Zum Inhalt springen
Aurabase-Logo
Aurabasis

Fragen Sie Ihre Datenbank mit dem JavaScript SDK ab

Die alltäglichen Abläufe von aura.db, die Regeln, die unsichere Aufrufe ablehnen, und wie man eine Tabelle mit Sicherheit auf Zeilenebene schützt.

Anleitung9 Min. gelesenEbene MittelstufeÜberarbeitet am 12.10.2026

Diese Seite wurde automatisch übersetzt. Maßgeblich ist die englische Version.

Zeilen lesen#

read.tstypescript
const { data, error } = await aura
  .from('todos')
  .select('id, title, done')
  .eq('done', false)
  .order('created_at', { ascending: false })
  .limit(20)

aura.from('todos') ist das in dieser Dokumentation verwendete Formular (es ist eine Abkürzung für aura.db.from('todos'), derselbe Aufruf). Jeder Aufruf gibt { data, error } zurück und löst nie aus, siehe Clientoptionen und Fehler.

Filterkette: eq, neq, gt, gte, lt, lte, like, ilike, in, is und die anderen, die in der Datenbankreferenz aufgeführt sind. Verwenden Sie für eine Seite mit Zeilen range(from, to).

Einfügen, aktualisieren und löschen#

write.tstypescript
// Fügen Sie eine Zeile oder ein Array von Zeilen ein und erhalten Sie sie zurück
const { data } = await aura.from('todos').insert({ title: 'Write the docs' }).select()

// Upsert
await aura.from('todos').upsert({ id, title: 'Renamed' }).select()

// Für das Aktualisieren und Löschen ist ein Filter erforderlich
await aura.from('todos').update({ done: true }).eq('id', id)
await aura.from('todos').delete().eq('id', id)

Ein Schreibvorgang gibt nichts zurück (data ist null), es sei denn, Sie verketten .select(): Durch das Einfügen von 10.000 Zeilen werden keine 10.000 Zeilen zurückgesendet. Mit .select() kommen die Zeilen zurück, und ein PATCH oder POST, das mit keiner Zeile übereinstimmt, gibt den Grund in meta.hint an.

Zwei Regeln schützen Sie vor Fehlern:

  • Eine Batch-Einfügung benötigt in jeder Zeile die gleichen Schlüssel. Zeilen mit unterschiedlichen Schlüsseln geben 400 mit All object keys must match zurück. Füllen Sie die fehlenden Schlüssel mit null aus.
  • update() und delete() ohne Filter werden vom Client mit dem Fehlercode UNFILTERED_MUTATION abgelehnt, bevor eine Anfrage gesendet wird. Um jede Zeile absichtlich zu ändern, führen Sie SQL von einem Server aus.

Eine Reihe, viele Reihen zählen#

count.tstypescript
// Genau eine Zeile: ein Fehler, wenn keine oder mehrere vorhanden sind
const one = await aura.from('todos').select('*').eq('id', id).single()
// → error.status 406, wenn der Filter mit null oder mehreren Zeilen übereinstimmt

// Null oder eine Zeile: Daten sind null, wenn nichts übereinstimmt
const maybe = await aura.from('todos').select('*').eq('id', id).maybeSingle()

// Zeilen und ihre Summe
const page = await aura.from('todos').select('*', { count: 'exact' }).range(0, 9)
// page.count ist die Gesamtzahl, unabhängig vom Bereich

// Nur die Summe, keine Zeilen
const { count } = await aura.from('todos').select('*', { count: 'exact', head: true })

count: 'exact' zählt jede passende Zeile. 'planned' und 'estimated' sind bei sehr großen Tabellen und ungefähren Werten schneller.

Schützen Sie einen Tisch#

RLS ist standardmäßig über Aurabase aktiviert. Fügen Sie Richtlinien hinzu, um den Zugriff zu gewähren

Tabellen, die über Aurabase (db.sql(), Migrationen, Studio oder die Tabellen-API) erstellt wurden, erhalten automatisch ENABLE und FORCE ROW LEVEL SECURITY (es sei denn, Sie schließen DISABLE ROW LEVEL SECURITY explizit in Ihren DDL-Stapel ein). Da noch keine Richtlinien vorliegen, sehen anon- und authenticated-Anrufer []. Tabellen, die über eine direkte Postgres-Verbindung erstellt wurden, benötigen explizit enable row level security. Fügen Sie die benötigten Richtlinien hinzu:

SQLsql
create policy todos_own_read on todos
  for select to aura_authenticated
  using (auth.uid() = owner);

Die kanonischen Datenbankrollen sind aura_anon, aura_authenticated und aura_service_role (Gruppenaliase anon, authenticated, service_role werden ihnen auch auf verwalteten Clustern zugeordnet). auth.uid() ist NULL für den öffentlichen Schlüssel und eine Benutzer-ID für einen angemeldeten Benutzer. Siehe Sicherheit auf Zeilenebene.

Ein service_role-Schlüssel umgeht RLS von Natur aus: Behalten Sie ihn auf Ihrem Server.

SQL-Funktionen und RPC#

Erstellen Sie eine Funktion von einem Server und rufen Sie sie dann von überall mit rpc() auf:

server/setup.tstypescript
await admin.db.createFunction({
  name: 'add',
  args: [
    { name: 'a', data_type: 'int', mode: 'IN' },
    { name: 'b', data_type: 'int', mode: 'IN' },
  ],
  returns: 'int',
  language: 'sql',
  body: 'SELECT a + b',
  grant_execute_to: ['anon', 'authenticated'],
})
client.tstypescript
const { data } = await aura.rpc('add', { a: 1, b: 2 }) // → 3
  • Zum Aufruf ist grant_execute_to erforderlich. Ohne sie kann niemand die Funktion ausführen. Eine Rolle, die nicht aufgeführt ist, erhält 403 permission denied for function. Es werden sowohl authenticated als auch aura_authenticated akzeptiert. Dies gilt auch für Funktionen, die Sie mit db.sql() erstellen, oder für eine Migration von Projekten, die nach dieser Änderung erstellt wurden (die Standardberechtigung EXECUTE von PUBLIC wird widerrufen): Fügen Sie grant execute on function hello(text) to aura_authenticated; selbst hinzu.
  • Eine neue Funktion ist nach einigen Sekunden aufrufbar. Bis die API ihr Schema neu lädt, gibt rpc() 404 Could not find the function zurück.
  • Funktionen über SQL (db.sql()): CREATE FUNCTION / CREATE OR REPLACE FUNCTION ist im SECURITY INVOKER-Modus zulässig (Standard); SECURITY DEFINER wird auf /raw abgelehnt und muss über createFunction (POST /v1/db/{project_id}/functions) oder CLI/Migrationen mit explizitem grant_execute_to erstellt werden.

Führen Sie SQL von einem Server aus#

server/migrate.tstypescript
import { createAdminClient } from '@aurabase/aurabase-js'

const admin = createAdminClient(process.env.NEXT_PUBLIC_AURABASE_URL!, process.env.AURABASE_SERVICE_ROLE_KEY!)

await admin.db.sql(`
  create table if not exists todos (
    id uuid primary key default gen_random_uuid(),
    title text not null,
    done boolean not null default false,
    owner uuid,
    created_at timestamptz not null default now()
  )
`)

db.sql() benötigt einen service_role-Schlüssel. Es lehnt einen DELETE ohne WHERE ab und liest keine Systemkataloge wie pg_class oder pg_roles. Um Ihre Tabellen aufzulisten, verwenden Sie admin.db.schema().

Paginierung, Zeilenanfang und genaue Zahlen

  • Ein Lesevorgang gibt höchstens 1.000 Zeilen zurück – der Standardwert und die harte Obergrenze, unabhängig davon, nach limit() oder range() Sie fragen. meta.has_more ist true, wenn mehr Zeilen übereinstimmen; Fragen Sie nach count: 'exact', um auch meta.total zu erhalten.
  • Blättern Sie durch eine große Tabelle mit Keyset-Paginierung, die auf der millionsten Seite dasselbe kostet: aura.from('events').select('id,label').limit(1000).after('id', lastId) (es ist .order('id').gt('id', lastId)). .cursor() ist nur für MongoDB verfügbar; offset wird langsamer, je tiefer Sie gehen.
  • Zahlen über 2^53 von JavaScript hinaus. Ein bigint über 9.007.199.254.740.991 verliert seine letzten Ziffern, wenn es als JS-Nummer geparst wird: Erstellen Sie den Client mit { parseBigIntAsString: true }, um diese Werte als Zeichenfolgen zu empfangen. Ein numeric wird als JSON-Zahl zurückgegeben, wenn er genau darstellbar ist, andernfalls als exakte Dezimalzeichenfolge (lange Werte wie 12345678901234567890.123456789).
  • count: 'planned' und 'estimated' sind nur Schätzungen. Sie stammen aus den Statistiken von PostgreSQL, die für eine Tabelle, die gerade geladen wurde, leer sind (eine Tabelle mit 60 Zeilen kann 430 melden). Verwenden Sie count: 'exact', wenn es auf die Zahl ankommt.
  • Eine vector-Spalte wird als Zeichenfolge zurückgegeben, beispielsweise "[0.1,0.2,0.3]": Analysieren Sie sie mit JSON.parse, um eine number[] zu erhalten.
  • Eine Ansicht liest mit Ihren Berechtigungen. Von Ihnen erstellte Ansichten (SQL, Migration) erhalten security_invoker = true, sodass die Richtlinien der zugrunde liegenden Tabellen für den Leser gelten. Schreiben Sie with (security_invoker = false) nur dann explizit, wenn Sie wirklich möchten, dass die Ansicht RLS umgeht.
  • db.sql() wiederholt einen 429 nach der Retry-After-Verzögerung (eine abgelehnte Anfrage wurde nie ausgeführt). /raw ist pro Projekt begrenzt; Verwenden Sie für Massenladungen den Typ insert() mit einem Array.