Quickstart

Get TrailBase up and running in 5 minutes

Get your TrailBase backend server running and create your first API in under 5 minutes.

Install TrailBase

Linux & MacOS

curl -sSL https://trailbase.io/install.sh | bash

iwr https://trailbase.io/install.ps1 | iex

docker run -p 4000:4000 trailbase/trailbase /app/trail run

The install script downloads the latest release binary and adds it to your PATH. For more installation options, see the Installation Guide.

Start the Server

Run TrailBase with a single command:

trail run

On first start, TrailBase will:

• Create a ./traildepot directory for data and configuration
• Initialize a SQLite database
• Create an admin user with credentials printed to the terminal
• Start the server on http://localhost:4000

Save the admin credentials displayed in the terminal - you’ll need them to access the dashboard.

Access the Admin Dashboard

Open http://localhost:4000/_/admin/ in your browser and log in with the credentials from the previous step.

The admin dashboard lets you:

• Create and manage database tables
• Configure Record APIs with access rules
• Manage users and authentication
• View logs and monitor your server

Create Your First Table

Let’s create a simple “posts” table for a blog:

1. Navigate to Tables

   In the admin dashboard, go to Schema → Tables and click Create Table.

2. Define the Schema

   Create a table with the following columns:

   CREATE TABLE posts (
     id BLOB PRIMARY KEY DEFAULT (uuid_v7()) NOT NULL,
     created INTEGER DEFAULT (unixepoch()) NOT NULL,
     updated INTEGER DEFAULT (unixepoch()) NOT NULL,
     
     title TEXT NOT NULL,
     content TEXT NOT NULL,
     author_id BLOB REFERENCES _user(id),
     published INTEGER DEFAULT 0 NOT NULL
   ) STRICT;
   

   Click Execute to create the table.

3. Configure the API

   Go to APIs → Record APIs and click Create API:

   • Table: posts
   • Name: posts
   • Read Access: Public (for now)
   • Create Access: Authenticated
   • Update/Delete Access: Owner only

   Click Save.

Test Your API

Your posts API is now live! Test it with curl:

List all posts

curl http://localhost:4000/api/records/v1/posts

Create a post (requires authentication)

First, create a user and get an auth token:

# Register a new user
curl -X POST http://localhost:4000/api/auth/v1/register \
  -H "Content-Type: application/json" \
  -d '{"email":"[e-mail]","password":"secretpassword"}'

# Login to get a token
curl -X POST http://localhost:4000/api/auth/v1/login \
  -H "Content-Type: application/json" \
  -d '{"email":"[e-mail]","password":"secretpassword"}'

Then create a post using the auth token:

curl -X POST http://localhost:4000/api/records/v1/posts \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN_HERE" \
  -d '{
    "title": "My First Post",
    "content": "Hello from TrailBase!",
    "published": 1
  }'

Query posts

# Get a specific post
curl http://localhost:4000/api/records/v1/posts/POST_ID_HERE

# Filter published posts
curl "http://localhost:4000/api/records/v1/posts?published[eq]=1"

# Search by title
curl "http://localhost:4000/api/records/v1/posts?title[like]=%First%"

Use a Client SDK

Instead of raw HTTP requests, use one of TrailBase’s client libraries:

TypeScript

npm install trailbase

import { TrailBase } from 'trailbase';

const client = new TrailBase('http://localhost:4000');

// Login
await client.login('[e-mail]', 'secretpassword');

// Create a post
const post = await client.createRecord('posts', {
  title: 'My First Post',
  content: 'Hello from TrailBase!',
  published: 1
});

// List posts
const posts = await client.listRecords('posts', {
  filter: { published: { eq: 1 } }
});

Python

pip install trailbase

from trailbase import TrailBase

client = TrailBase('http://localhost:4000')

# Login
client.login('[e-mail]', 'secretpassword')

# Create a post
post = client.create_record('posts', {
    'title': 'My First Post',
    'content': 'Hello from TrailBase!',
    'published': 1
})

# List posts
posts = client.list_records('posts', filter={'published': {'eq': 1}})

Dart

flutter pub add trailbase

import 'package:trailbase/trailbase.dart';

final client = TrailBase('http://localhost:4000');

// Login
await client.login('[e-mail]', 'secretpassword');

// Create a post
final post = await client.createRecord('posts', {
  'title': 'My First Post',
  'content': 'Hello from TrailBase!',
  'published': 1
});

// List posts
final posts = await client.listRecords('posts',
  filter: {'published': {'eq': 1}}
);

Enable Realtime Subscriptions

Subscribe to live updates on your posts table:

const unsubscribe = await client.subscribe('posts', {
  onCreate: (record) => console.log('New post:', record),
  onUpdate: (record) => console.log('Updated:', record),
  onDelete: (id) => console.log('Deleted:', id)
});

Any changes to the posts table will trigger your callbacks in realtime!

Next Steps

Build Your First App

Complete tutorial building a full application

Database Setup

Learn about schema design and migrations

Authentication

Add user auth with OAuth providers

API Reference

Explore the complete REST API