Snel beginnen
Van nul tot een doorzoekbare API: speciale Postgres-database, beveiliging op rijniveau, realtime en TypeScript-typegeneratie inbegrepen - geen creditcard vereist.
Prompt voor je codeeragent
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.Snelstart#
Installeer de SDK, maak de client en lees uw eerste rijen.
1. Installeer de SDK#
Voeg de SDK toe aan uw project. Op het tabblad Rust wordt de krat aurabase geïnstalleerd; het tabblad cURL controleert of uw project-URL reageert.
pnpm add @aurabase/aurabase-js
2. Maak de klant aan#
Maak de client aan met uw project-URL en anon-sleutel, beide in Studio › Instellingen › Verbinding. Bewaar de servicerolsleutel op de server.
import { createClient } from '@aurabase/aurabase-js'
const aura = createClient(
process.env.NEXT_PUBLIC_AURABASE_URL!,
process.env.NEXT_PUBLIC_AURABASE_ANON_KEY!,
)
3. Voer een query uit op de database#
Lees maximaal 10 rijen vanaf todos. De tabel wordt gemaakt in het gedeelte 'Een tabel maken' hieronder; totdat deze bestaat, wordt error ingesteld.
// `todos` wordt aangemaakt in "Een tabel maken" hieronder
const { data, error } = await aura
.from('todos')
.select('id, title, done')
.limit(10)
console.log(data, error)
Vereisten#
We gaan ervan uit dat Node.js ≥ 20 is geïnstalleerd en dat er een POSIX-terminal binnen bereik is. Er is geen lokale database vereist: Aurabase voorziet in een speciale Postgres database voor elk project.
Kom je uit Supabase of Firebase? De meeste concepten zijn transponeerbaar. Zie de migratiehandleiding.
De SDK installeren#
De officiële SDK stelt een getypte client beschikbaar voor CRUD, auth, realtime en opslag. Het werkt op dezelfde manier in Next.js, React, Node, Bun of Deno.
# Aanbevolen
pnpm add @aurabase/aurabase-js
De pakketnaam omvat het bereik @aurabase/. Het pakket aurabase-js zonder scope wordt niet onderhouden door Aurabase: installeer het niet.
De SDK omvat rechtstreeks @aurabase/aurabase-js/ssr (createServerClient) export voor Next.js (App Router, Server Actions, Middleware), Remix, Nuxt en SvelteKit met automatisch sessiecookiebeheer en anti-truncatie chunking.
Maak een project#
Maak een project vanuit de Studio. Wanneer deze actief wordt, toont de Studio een Kopieer nu uw sleutels paneel met een kant-en-klare .env.local (kopieer deze of download deze): de service_role sleutel verschijnt daar één keer, alleen de hash wordt daarna bewaard. Instellingen › Verbinding toont later de project-URL en de openbare anon-sleutel; als u de service_role-sleutel bent kwijtgeraakt, genereer deze dan daar opnieuw (de vorige wordt ingetrokken). NEXT_PUBLIC_AURABASE_URL en NEXT_PUBLIC_AURABASE_ANON_KEY kunnen aan de clientzijde worden gepubliceerd; AURABASE_SERVICE_ROLE_KEY blijft strikt aan de serverkant.
NEXT_PUBLIC_AURABASE_URL=https://<slug>.aurabase.cloud
NEXT_PUBLIC_AURABASE_ANON_KEY=aura_anon_…
AURABASE_SERVICE_ROLE_KEY=aura_sk_…
| Schema | Toegang | Bevat |
|---|---|---|
project_{uuid} | Jij | Uw toepassingstabellen |
project_{uuid}_auth | Systeem | users, sessions, oauth_accounts, mfa |
project_{uuid}_storage | Systeem | buckets, objects, rls_policies |
project_{uuid}_platform | Systeem | functions, jobs, cron_jobs, api_keys |
Het hele pad werkt ook vanuit de CLI (zie CLI voor de installatie): aura projects create wacht tot het project klaar is en drukt de URL en de sleutels één keer af.
aura login
aura projects create todos-app --json > project.json # wacht totdat het project actief is
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> # zien wat die gebruiker ziet
Neem AURABASE_SERVICE_ROLE_KEY nooit op in een clientbundel. Het omzeilt alle RLS-beleidsregels en de API weigert dit vanuit een browser (401 SECRET_KEY_IN_BROWSER). Reserveer het voor serveroproepen (routehandlers, serveracties, taken).
Maak een tabel#
Open Database in de Studio, klik op SQL Editor (de link onderaan het tabellenpaneel) en voer dit script uit. Beveiliging op rijniveau is ingeschakeld voor elke tabel: met de eerste twee beleidsregels kan elke aangemelde gebruiker zijn eigen rijen lezen en maken, de derde is een voorbeeld waarmee bezoekers de tabel kunnen lezen, zodat u uw eerste rijen kunt zien zonder in te loggen. Het beleid is gericht op de rol aura_authenticated (aura_anon voor bezoekers).
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);
-- Slechts een voorbeeld: elke bezoeker kan elke taak lezen. Laat het vallen vóór productie:
-- verwijder beleid "todos_public_read" op taken;
create policy "todos_public_read" on todos for select to aura_anon using (true);
Genereer vervolgens de TypeScript-typen van uw schema (de opdracht luidt .env.local):
npx @aurabase/gen --out lib/aurabase.types.ts
Eerste oproep#
Maak een herbruikbare Aurabase-client door sleutels uit omgevingsvariabelen te lezen en voer vervolgens een query uit op uw eerste tabel. De onderstaande paden zijn relatief ten opzichte van de hoofdmap van uw app: als uw project een map src/ gebruikt, plaatst u lib/, components/ en app/ erin, zodat de importalias @/ wordt opgelost.
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!,
)
Vervolgens in een route-handler of een servercomponent:
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)
}
Dit retourneert de rijen van de tabel, ook zonder een aangemelde gebruiker, dankzij het voorbeeldbeleid todos_public_read. Zonder dit (zodra je het hebt laten vallen, zoals je zou moeten doen vóór de productie) krijgt een bezoeker []: het andere beleid opent alleen rijen naar aura_authenticated, dus meld een gebruiker eerst aan met aura.auth.signInWithPassword({ email, password }) (zie Kant-en-klare inlogpagina's voor Next.js). Genereer de typen Database opnieuw met npx @aurabase/gen na elke schemawijziging.
Als u een eerste rij wilt invoegen, meldt u zich aan en meldt u zich aan, waarna u deze invoegt. De kolom user_id is standaard ingesteld op 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)
})
Voer het uit met tsx, wat de import zonder extensie oplost en .env.local leest:
pnpm add -D tsx
pnpm approve-builds # pnpm 10+: sta het installatiescript van esbuild toe en voer vervolgens uit:
pnpm exec tsx --env-file=.env.local scripts/first-row.ts
Met npm 11 of hoger mislukt npx tsx met "U hebt esbuild voor een ander platform geïnstalleerd" omdat het installatiescript van esbuild standaard wordt geblokkeerd. Gebruik pnpm zoals hierboven, of sla tsx over en voer het script uit met Node's ingebouwde type stripping (Node 22.6+) na het schrijven van de twee imports met hun extensie ('../lib/aurabase.ts', './aurabase.types.ts'): node --env-file=.env.local --experimental-strip-types scripts/first-row.ts.
Voor de gebruikers van uw project werkt signUp gevolgd door signInWithPassword onmiddellijk: e-mailbevestiging is uitgeschakeld totdat u het inschakelt in Studio › Authenticatie › Configuratie (er is een mailserver voor nodig). Iedereen kan zich dan met elk adres aanmelden, dus schakel dit vóór productie in.
De sleutel service_role heeft geen aangemelde gebruiker, dus auth.uid() is NULL en een invoeging die afhankelijk is van de standaardwaarde mislukt met NOT_NULL_VIOLATION. Geef vanaf een server user_id expliciet door.
Maak realtime verbinding#
Drie automatisch onderhandelde transporten: WebSocket, SSE, NATS. De klant kiest de beste op basis van het netwerk – geen configuratie nodig.
Schakel eenmalig realtime op tafel in, met de CLI:
aura db table realtime todos on
of met de HTTP API, vanaf een server (waarden van .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}'
Abonneer u dan op wijzigingen. Een ingelogde gebruiker ontvangt de rijen die zijn RLS-beleid hem laat lezen, inclusief wanneer het kanaal werd geopend vóór het inloggen (het wordt automatisch opnieuw geverifieerd); een geweigerd abonnement meldt CHANNEL_ERROR met de reden.
'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 ontwikkeling koppelt, ontkoppelt en hermonteert React StrictMode de component:
// de eerste GESLOTEN komt van die opruiming en wordt verwacht.
if (status === 'SUBSCRIBED') console.log('realtime connected')
if (status === 'CHANNEL_ERROR') console.error('realtime refused:', err?.message)
})
return () => {
void channel.unsubscribe()
}
}, [])
return null
}
Abonnementen worden gemultiplext via een enkele TCP-verbinding. Open er zoveel als u nodig heeft, zonder extra netwerkkosten.