Quick start
From zero to a queryable API: dedicated Postgres database, row-level security, realtime and TypeScript type generation included — no credit card required.
Prompt for your coding agent
Set up Aurabase in this app by following this page: https://aurabase.cloud/en/docs/getting-started.md
Documentation: read https://aurabase.cloud/llms.txt first. Every docs page is also available as Markdown: add .md to its URL, for example (the same works for every page): https://aurabase.cloud/en/docs/getting-started.md
Client: install @aurabase/aurabase-js and create the client with createClient(NEXT_PUBLIC_AURABASE_URL, NEXT_PUBLIC_AURABASE_ANON_KEY). Keep AURABASE_SERVICE_ROLE_KEY on the server: never put it in client code.
Project access: to read the schema and run SQL, start the Aurabase MCP server over stdio (82 tools with a project key):
npx -y -p @aurabase/mcp-server aurabase-mcp --url https://<slug>.aurabase.cloud --project-id <project-id> --service-role-key aura_sk_…
The project id is in Studio › Settings › General. The service role key is shown once when the project is created; regenerate it in Studio › Settings › Connection if you lost it.Quickstart#
Install the SDK, create the client and read your first rows.
1. Install the SDK#
Add the SDK to your project. The Rust tab installs the aurabase crate; the cURL tab checks that your project URL responds.
pnpm add @aurabase/aurabase-js
2. Create the client#
Create the client with your project URL and anon key, both in Studio › Settings › Connection. Keep the service role key on the server.
import { createClient } from '@aurabase/aurabase-js'
const aura = createClient(
process.env.NEXT_PUBLIC_AURABASE_URL!,
process.env.NEXT_PUBLIC_AURABASE_ANON_KEY!,
)
3. Query the database#
Read up to 10 rows from todos. The table is created in the "Create a table" section below; until it exists, error is set.
// `todos` is created in "Create a table" below
const { data, error } = await aura
.from('todos')
.select('id, title, done')
.limit(10)
console.log(data, error)
Prerequisites#
We assume that Node.js ≥ 20 is installed and a POSIX terminal is within range. No local database is required: Aurabase provisions a dedicated Postgres database for each project.
Are you coming from Supabase or Firebase? Most concepts are transposable. See the migration guide.
Installing the SDK#
The official SDK exposes a typed client for CRUD, auth, realtime and storage. It works the same way in Next.js, React, Node, Bun or Deno.
# Recommended
pnpm add @aurabase/aurabase-js
The package name includes the @aurabase/ scope. The package aurabase-js without a scope is not maintained by Aurabase: do not install it.
The SDK directly includes @aurabase/aurabase-js/ssr (createServerClient) export for Next.js (App Router, Server Actions, Middleware), Remix, Nuxt and SvelteKit with automatic session cookie management and anti-truncation chunking.
Create a project#
Create a project from the Studio. When it becomes active, the Studio shows a Copy your keys now panel with a ready-to-use .env.local (copy it or download it): the service_role key appears there once, only its hash is kept afterwards. Settings › Connection later shows the project URL and the public anon key; if you lost the service_role key, regenerate it there (the previous one is revoked). NEXT_PUBLIC_AURABASE_URL and NEXT_PUBLIC_AURABASE_ANON_KEY can be published on the client side; AURABASE_SERVICE_ROLE_KEY stays strictly on the server side.
NEXT_PUBLIC_AURABASE_URL=https://<slug>.aurabase.cloud
NEXT_PUBLIC_AURABASE_ANON_KEY=aura_anon_…
AURABASE_SERVICE_ROLE_KEY=aura_sk_…
| Schema | Access | Contains |
|---|---|---|
project_{uuid} | You | Your application tables |
project_{uuid}_auth | System | users, sessions, oauth_accounts, mfa |
project_{uuid}_storage | System | buckets, objects, rls_policies |
project_{uuid}_platform | System | functions, jobs, cron_jobs, api_keys |
The whole path also works from the CLI (see CLI for the installation): aura projects create waits until the project is ready and prints the URL and the keys once.
aura login
aura projects create todos-app --json > project.json # waits until the project is active
aura link --project-id "$(jq -r .id project.json)"
export NEXT_PUBLIC_AURABASE_URL="$(jq -r .url project.json)"
export AURABASE_SERVICE_ROLE_KEY="$(jq -r .service_role_key project.json)"
aura db raw "create table todos (id bigint generated always as identity primary key, title text not null, done boolean not null default false, user_id uuid not null default auth.uid(), created_at timestamptz not null default now())"
aura db raw "create policy todos_own_read on todos for select to aura_authenticated using (auth.uid() = user_id)"
aura db raw "create policy todos_own_insert on todos for insert to aura_authenticated with check (auth.uid() = user_id)"
aura db table realtime todos on
aura db raw "select count(*) from todos" --as authenticated --user <a user id> # see what that user sees
Never include AURABASE_SERVICE_ROLE_KEY in a client bundle. It bypasses all RLS policies, and the API refuses it from a browser (401 SECRET_KEY_IN_BROWSER). Reserve it for server calls (route handlers, server actions, jobs).
Create a table#
Open Database in the Studio, click SQL Editor (the link at the bottom of the tables panel) and run this script. Row-level security is enabled on every table: the first two policies let each signed-in user read and create their own rows, the third one is an example that lets visitors read the table so you can see your first rows without signing in. Policies target the aura_authenticated role (aura_anon for visitors).
create table todos (
id bigint generated always as identity primary key,
title text not null,
done boolean not null default false,
user_id uuid not null default auth.uid(),
created_at timestamptz not null default now()
);
create policy "todos_own_read" on todos for select to aura_authenticated using (auth.uid() = user_id);
create policy "todos_own_insert" on todos for insert to aura_authenticated with check (auth.uid() = user_id);
-- Example only: any visitor can read every todo. Drop it before production:
-- drop policy "todos_public_read" on todos;
create policy "todos_public_read" on todos for select to aura_anon using (true);
Then generate the TypeScript types of your schema (the command reads .env.local):
npx @aurabase/gen --out lib/aurabase.types.ts
First call#
Create a reusable Aurabase client by reading keys from environment variables, then query your first table. The paths below are relative to the root of your app: if your project uses a src/ directory, put lib/, components/ and app/ inside it, so that the @/ import alias resolves.
import { createClient } from '@aurabase/aurabase-js'
import type { Database } from './aurabase.types'
export const aura = createClient<Database>(
process.env.NEXT_PUBLIC_AURABASE_URL!,
process.env.NEXT_PUBLIC_AURABASE_ANON_KEY!,
)
Then, in a route handler or a server component:
import { aura } from '@/lib/aurabase'
export async function GET() {
const { data, error } = await aura
.from('todos')
.select('id, title, done')
.order('created_at', { ascending: false })
.limit(10)
if (error) throw error
return Response.json(data)
}
This returns the rows of the table, including without a signed-in user, thanks to the example policy todos_public_read. Without it (once you dropped it, as you should before production) a visitor gets []: the other policies only open rows to aura_authenticated, so sign a user in first with aura.auth.signInWithPassword({ email, password }) (see Ready-made sign-in pages for Next.js). Regenerate the Database types with npx @aurabase/gen after each schema change.
To insert a first row, sign a user up and in, then insert. The user_id column defaults to auth.uid():
import { aura } from '../lib/aurabase'
async function main() {
const email = 'you@example.com'
const password = 'a-strong-password'
await aura.auth.signUp({ email, password })
await aura.auth.signInWithPassword({ email, password })
const { data, error } = await aura.from('todos').insert({ title: 'First todo' }).select()
console.log(data, error)
}
main().catch((err) => {
console.error(err)
process.exit(1)
})
Run it with tsx, which resolves the extensionless import and reads .env.local:
pnpm add -D tsx
pnpm approve-builds # pnpm 10+: allow esbuild's install script, then run:
pnpm exec tsx --env-file=.env.local scripts/first-row.ts
With npm 11 or later, npx tsx fails with « You installed esbuild for another platform » because esbuild's install script is blocked by default. Use pnpm as above, or skip tsx and run the script with Node's built-in type stripping (Node 22.6+) after writing the two imports with their extension ('../lib/aurabase.ts', './aurabase.types.ts'): node --env-file=.env.local --experimental-strip-types scripts/first-row.ts.
For the users of your project, signUp followed by signInWithPassword works immediately: email confirmation is off until you turn it on in Studio › Authentication › Configuration (it needs a mail server). Anyone can then sign up with any address, so turn it on before production.
The service_role key has no signed-in user, so auth.uid() is NULL and an insert that relies on the default fails with NOT_NULL_VIOLATION. From a server, pass user_id explicitly.
Connect realtime#
Three auto-negotiated transports: WebSocket, SSE, NATS. Customer chooses the best one based on the network — no configuration necessary.
Enable realtime on the table once, with the CLI:
aura db table realtime todos on
or with the HTTP API, from a server (values from .env.local):
curl -X PUT "$NEXT_PUBLIC_AURABASE_URL/v1/db/schema/tables/todos/realtime" \
-H "apikey: $AURABASE_SERVICE_ROLE_KEY" \
-H "Content-Type: application/json" \
-d '{"enabled": true}'
Then subscribe to changes. A signed-in user receives the rows that its RLS policies let it read, including when the channel was opened before sign-in (it is re-authenticated automatically); a refused subscription reports CHANNEL_ERROR with the reason.
'use client'
import { aura } from '@/lib/aurabase'
import { useEffect } from 'react'
export function LiveTodos() {
useEffect(() => {
const channel = aura.realtime
.channel('todos')
.on('postgres_changes', { event: '*', schema: 'public', table: 'todos' }, (change) =>
console.log(change.eventType, change.new),
)
.subscribe((status, err) => {
// In development React StrictMode mounts, unmounts and re-mounts the component:
// the first CLOSED comes from that clean-up and is expected.
if (status === 'SUBSCRIBED') console.log('realtime connected')
if (status === 'CHANNEL_ERROR') console.error('realtime refused:', err?.message)
})
return () => {
void channel.unsubscribe()
}
}, [])
return null
}
Subscriptions are multiplexed over a single TCP connection. Open as many as you need — zero additional network costs.