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.
Zeilen lesen#
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#
// 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
400mitAll object keys must matchzurück. Füllen Sie die fehlenden Schlüssel mitnullaus. update()unddelete()ohne Filter werden vom Client mit dem FehlercodeUNFILTERED_MUTATIONabgelehnt, 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#
// 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#
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:
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:
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'],
})
const { data } = await aura.rpc('add', { a: 1, b: 2 }) // → 3
- Zum Aufruf ist
grant_execute_toerforderlich. Ohne sie kann niemand die Funktion ausführen. Eine Rolle, die nicht aufgeführt ist, erhält403 permission denied for function. Es werden sowohlauthenticatedals auchaura_authenticatedakzeptiert. Dies gilt auch für Funktionen, die Sie mitdb.sql()erstellen, oder für eine Migration von Projekten, die nach dieser Änderung erstellt wurden (die StandardberechtigungEXECUTEvonPUBLICwird widerrufen): Fügen Siegrant 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 functionzurück. - Funktionen über SQL (
db.sql()):CREATE FUNCTION/CREATE OR REPLACE FUNCTIONist imSECURITY INVOKER-Modus zulässig (Standard);SECURITY DEFINERwird auf/rawabgelehnt und muss übercreateFunction(POST /v1/db/{project_id}/functions) oder CLI/Migrationen mit explizitemgrant_execute_toerstellt werden.
Führen Sie SQL von einem Server aus#
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()oderrange()Sie fragen.meta.has_moreisttrue, wenn mehr Zeilen übereinstimmen; Fragen Sie nachcount: 'exact', um auchmeta.totalzu 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;offsetwird 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. Einnumericwird als JSON-Zahl zurückgegeben, wenn er genau darstellbar ist, andernfalls als exakte Dezimalzeichenfolge (lange Werte wie12345678901234567890.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 Siecount: '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 mitJSON.parse, um einenumber[]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 Siewith (security_invoker = false)nur dann explizit, wenn Sie wirklich möchten, dass die Ansicht RLS umgeht. db.sql()wiederholt einen429nach derRetry-After-Verzögerung (eine abgelehnte Anfrage wurde nie ausgeführt)./rawist pro Projekt begrenzt; Verwenden Sie für Massenladungen den Typinsert()mit einem Array.