Schnellstart
Von Null zu einer abfragbaren API: dedizierte Postgres-Datenbank, Sicherheit auf Zeilenebene, Echtzeit und TypeScript-Typgenerierung inklusive – keine Kreditkarte erforderlich.
Prompt für Ihren Coding-Agenten
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.Schnellstart#
Installieren Sie das SDK, erstellen Sie den Client und lesen Sie Ihre ersten Zeilen.
1. Installieren Sie das SDK#
Fügen Sie das SDK zu Ihrem Projekt hinzu. Auf der Registerkarte Rust wird die Kiste aurabase installiert. Auf der Registerkarte cURL wird überprüft, ob Ihre Projekt-URL antwortet.
pnpm add @aurabase/aurabase-js
2. Erstellen Sie den Client#
Erstellen Sie den Client mit Ihrer Projekt-URL und einem anonymen Schlüssel, beide in Studio › Einstellungen › Verbindung. Behalten Sie den Dienstrollenschlüssel auf dem Server.
import { createClient } from '@aurabase/aurabase-js'
const aura = createClient(
process.env.NEXT_PUBLIC_AURABASE_URL!,
process.env.NEXT_PUBLIC_AURABASE_ANON_KEY!,
)
3. Fragen Sie die Datenbank ab#
Lesen Sie bis zu 10 Zeilen aus todos. Die Tabelle wird im Abschnitt „Eine Tabelle erstellen“ unten erstellt. bis es existiert, wird error gesetzt.
// „todos“ wird unten im Abschnitt „Eine Tabelle erstellen“ erstellt
const { data, error } = await aura
.from('todos')
.select('id, title, done')
.limit(10)
console.log(data, error)
Voraussetzungen#
Wir gehen davon aus, dass Node.js ≥ 20 installiert ist und ein POSIX-Terminal in Reichweite ist. Es ist keine lokale Datenbank erforderlich: Aurabase stellt für jedes Projekt eine dedizierte Postgres-Datenbank bereit.
Kommen Sie von Supabase oder Firebase? Die meisten Konzepte sind übertragbar. Siehe die Migrationsleitfaden.
Installieren des SDK#
Das offizielle SDK stellt einen typisierten Client für CRUD, Authentifizierung, Echtzeit und Speicherung bereit. In Next.js, React, Node, Bun oder Deno funktioniert es genauso.
# Empfohlen
pnpm add @aurabase/aurabase-js
Der Paketname umfasst den Bereich @aurabase/. Das Paket aurabase-js ohne Gültigkeitsbereich wird von Aurabase nicht verwaltet: Installieren Sie es nicht.
Das SDK umfasst direkt den @aurabase/aurabase-js/ssr (createServerClient)-Export für Next.js (App Router, Serveraktionen, Middleware), Remix, Nuxt und SvelteKit mit automatischer Sitzungs-Cookie-Verwaltung und Anti-Truncation-Chunking.
Erstellen Sie ein Projekt#
Erstellen Sie ein Projekt aus dem Studio. Wenn es aktiv wird, zeigt das Studio ein Kopieren Sie Ihre Schlüssel jetzt-Panel mit einem gebrauchsfertigen .env.local (kopieren oder herunterladen): Der service_role-Schlüssel erscheint dort einmal, nur sein Hash wird danach behalten. Einstellungen › Verbindung zeigt später die Projekt-URL und den öffentlichen Anonymschlüssel an; Wenn Sie den Schlüssel service_role verloren haben, generieren Sie ihn dort neu (der vorherige wird widerrufen). NEXT_PUBLIC_AURABASE_URL und NEXT_PUBLIC_AURABASE_ANON_KEY können auf der Clientseite veröffentlicht werden; AURABASE_SERVICE_ROLE_KEY bleibt ausschließlich serverseitig.
NEXT_PUBLIC_AURABASE_URL=https://<slug>.aurabase.cloud
NEXT_PUBLIC_AURABASE_ANON_KEY=aura_anon_…
AURABASE_SERVICE_ROLE_KEY=aura_sk_…
| Schema | Zugang | Enthält |
|---|---|---|
project_{uuid} | Du | Ihre Anwendungstabellen |
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 |
Der gesamte Pfad funktioniert auch von der CLI aus (siehe CLI für die Installation): aura projects create wartet, bis das Projekt fertig ist und gibt die URL und die Schlüssel einmal aus.
aura login
aura projects create todos-app --json > project.json # wartet bis das Projekt aktiv ist
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> # Sehen Sie, was dieser Benutzer sieht
Schließen Sie AURABASE_SERVICE_ROLE_KEY niemals in ein Client-Bundle ein. Es umgeht alle RLS-Richtlinien und die API lehnt es von einem Browser ab (401 SECRET_KEY_IN_BROWSER). Reservieren Sie es für Serveraufrufe (Routenhandler, Serveraktionen, Jobs).
Erstellen Sie eine Tabelle#
Öffnen Sie die -Datenbank im Studio, klicken Sie auf SQL Editor (den Link unten im Tabellenbereich) und führen Sie dieses Skript aus. Sicherheit auf Zeilenebene ist für jede Tabelle aktiviert: Mit den ersten beiden Richtlinien kann jeder angemeldete Benutzer seine eigenen Zeilen lesen und erstellen. Die dritte Richtlinie ist ein -Beispiel, mit dem Besucher die Tabelle lesen können, sodass Sie Ihre ersten Zeilen sehen können, ohne sich anzumelden. Richtlinien zielen auf die Rolle aura_authenticated ab (aura_anon für Besucher).
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);
-- Nur ein Beispiel: Jeder Besucher kann alle Aufgaben lesen. Lassen Sie es vor der Produktion fallen:
-- Richtlinie „todos_public_read“ auf Todos löschen;
create policy "todos_public_read" on todos for select to aura_anon using (true);
Generieren Sie dann die TypeScript-Typen Ihres Schemas (der Befehl lautet .env.local):
npx @aurabase/gen --out lib/aurabase.types.ts
Erster Anruf#
Erstellen Sie einen wiederverwendbaren Aurabase-Client, indem Sie Schlüssel aus Umgebungsvariablen lesen und dann Ihre erste Tabelle abfragen. Die folgenden Pfade beziehen sich auf das Stammverzeichnis Ihrer App: Wenn Ihr Projekt ein src/-Verzeichnis verwendet, fügen Sie lib/, components/ und app/ darin ein, damit der Importalias @/ aufgelöst wird.
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!,
)
Dann in einem Routenhandler oder einer Serverkomponente:
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)
}
Dadurch werden dank der Beispielrichtlinie todos_public_read die Zeilen der Tabelle zurückgegeben, auch ohne angemeldeten Benutzer. Ohne sie (sobald Sie sie gelöscht haben, wie Sie es vor der Produktion tun sollten) erhält ein Besucher []: Die anderen Richtlinien öffnen nur Zeilen für aura_authenticated, also melden Sie einen Benutzer zuerst mit aura.auth.signInWithPassword({ email, password }) an (siehe Fertige Anmeldeseiten für Next.js). Generieren Sie die Database-Typen mit npx @aurabase/gen nach jeder Schemaänderung neu.
Um eine erste Zeile einzufügen, melden Sie einen Benutzer an und fügen Sie ihn dann ein. Die Spalte user_id ist standardmäßig 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)
})
Führen Sie es mit tsx aus, wodurch der erweiterungslose Import aufgelöst wird und .env.local lautet:
pnpm add -D tsx
pnpm approve-builds # pnpm 10+: Erlauben Sie das Installationsskript von esbuild und führen Sie dann Folgendes aus:
pnpm exec tsx --env-file=.env.local scripts/first-row.ts
Mit npm 11 oder höher schlägt npx tsx mit „Sie haben esbuild für eine andere Plattform installiert“ fehl, da das Installationsskript von esbuild standardmäßig blockiert ist. Verwenden Sie pnpm wie oben oder überspringen Sie tsx und führen Sie das Skript mit der integrierten Typentfernung von Node (Node 22.6+) aus, nachdem Sie die beiden Importe mit ihrer Erweiterung ('../lib/aurabase.ts', './aurabase.types.ts') geschrieben haben: node --env-file=.env.local --experimental-strip-types scripts/first-row.ts.
Für die Benutzer Ihres Projekts funktioniert signUp gefolgt von signInWithPassword sofort: Die E-Mail-Bestätigung ist aus, bis Sie sie in Studio › Authentifizierung › Konfiguration aktivieren (es ist ein Mailserver erforderlich). Jeder kann sich dann mit einer beliebigen Adresse anmelden, also schalten Sie es vor der Produktion ein.
Der Schlüssel service_role hat keinen angemeldeten Benutzer, daher ist auth.uid() NULL und eine Einfügung, die auf dem Standardwert basiert, schlägt mit NOT_NULL_VIOLATION fehl. Übergeben Sie von einem Server aus explizit user_id.
Verbinden Sie sich in Echtzeit#
Drei automatisch ausgehandelte Transporte: WebSocket, SSE, NATS. Der Kunde wählt basierend auf dem Netzwerk das beste aus – keine Konfiguration erforderlich.
Aktivieren Sie einmal Echtzeit für die Tabelle mit der CLI:
aura db table realtime todos on
oder mit der HTTP-API von einem Server (Werte aus .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}'
Dann abonnieren Sie Änderungen. Ein angemeldeter Benutzer erhält die Zeilen, die er aufgrund seiner RLS-Richtlinien lesen kann, auch wenn der Kanal vor der Anmeldung geöffnet wurde (er wird automatisch erneut authentifiziert); Ein abgelehntes Abonnement meldet CHANNEL_ERROR mit dem Grund.
'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 der Entwicklung React StrictMode mountet, unmountet und remountet die Komponente:
// Das erste GESCHLOSSEN stammt aus dieser Aufräumaktion und wird erwartet.
if (status === 'SUBSCRIBED') console.log('realtime connected')
if (status === 'CHANNEL_ERROR') console.error('realtime refused:', err?.message)
})
return () => {
void channel.unsubscribe()
}
}, [])
return null
}
Abonnements werden über eine einzige TCP-Verbindung gemultiplext. Öffnen Sie so viele, wie Sie benötigen – keine zusätzlichen Netzwerkkosten.