Voer een query uit op uw database met de JavaScript SDK
De dagelijkse stromen van aura.db, de regels die onveilige oproepen weigeren en hoe u een tabel kunt beschermen met beveiliging op rijniveau.
Rijen lezen#
const { data, error } = await aura
.from('todos')
.select('id, title, done')
.eq('done', false)
.order('created_at', { ascending: false })
.limit(20)
aura.from('todos') is de vorm die in deze documentatie wordt gebruikt (het is een snelkoppeling voor aura.db.from('todos'), dezelfde aanroep). Elke oproep retourneert { data, error } en gooit nooit, zie clientopties en fouten.
Filterketen: eq, neq, gt, gte, lt, lte, like, ilike, in, is, en de anderen vermeld in de databasereferentie. Gebruik voor een pagina met rijen range(from, to).
Invoegen, bijwerken en verwijderen#
// Voeg één rij in, of een reeks rijen, en haal ze terug
const { data } = await aura.from('todos').insert({ title: 'Write the docs' }).select()
// Bovenste
await aura.from('todos').upsert({ id, title: 'Renamed' }).select()
// Bijwerken en verwijderen hebben een filter nodig
await aura.from('todos').update({ done: true }).eq('id', id)
await aura.from('todos').delete().eq('id', id)
Een schrijfbewerking retourneert niets (data is null) tenzij u .select() aan elkaar koppelt: het invoegen van 10.000 rijen stuurt geen 10.000 rijen terug. Met .select() komen de rijen terug, en een PATCH of POST die met geen enkele rij overeenkomt, zegt waarom in meta.hint.
Twee regels beschermen u tegen fouten:
- Voor een batchinvoeging zijn in elke rij dezelfde sleutels nodig. Rijen met verschillende sleutels retourneren
400metAll object keys must match. Vul de ontbrekende sleutels metnull. update()endelete()zonder filter worden geweigerd door de client met de foutcodeUNFILTERED_MUTATION, voordat er een verzoek wordt verzonden. Om elke rij expres te wijzigen, voert u SQL uit vanaf een server.
Eén rij, veel rijen, telt#
// Precies één rij: een fout als er geen of meerdere zijn
const one = await aura.from('todos').select('*').eq('id', id).single()
// → error.status 406 wanneer het filter overeenkomt met nul of meerdere rijen
// Nul of één rij: gegevens zijn nul als er niets overeenkomt
const maybe = await aura.from('todos').select('*').eq('id', id).maybeSingle()
// Rijen en hun totaal
const page = await aura.from('todos').select('*', { count: 'exact' }).range(0, 9)
// page.count is het totaal, ongeacht het bereik
// Alleen het totaal, geen rijen
const { count } = await aura.from('todos').select('*', { count: 'exact', head: true })
count: 'exact' telt elke overeenkomende rij. 'planned' en 'estimated' zijn sneller op zeer grote tafels en bij benadering.
Bescherm een tafel#
Tabellen die zijn gemaakt via Aurabase (db.sql(), migraties, Studio of de tabel-API) krijgen automatisch ENABLE en FORCE ROW LEVEL SECURITY (tenzij u expliciet DISABLE ROW LEVEL SECURITY opneemt in uw DDL-batch). Als er nog geen beleid is, zien anon- en authenticated-bellers []. Tabellen die via een directe Postgres-verbinding zijn gemaakt, hebben expliciet enable row level security nodig. Voeg het beleid toe dat u nodig heeft:
create policy todos_own_read on todos
for select to aura_authenticated
using (auth.uid() = owner);
De canonieke databaserollen zijn aura_anon, aura_authenticated en aura_service_role (groepaliassen anon, authenticated, service_role worden ook hieraan toegewezen op beheerde clusters). auth.uid() is NULL voor de openbare sleutel en een gebruikers-ID voor een aangemelde gebruiker. Zie Beveiliging op rijniveau.
Een service_role sleutel omzeilt RLS door zijn ontwerp: bewaar hem op uw server.
SQL-functies en rpc#
Maak een functie vanaf een server en roep deze vervolgens overal aan met rpc():
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
grant_execute_tois vereist om het aan te roepen. Zonder dit kan niemand de functie uitvoeren. Een rol die niet in de lijst staat, krijgt403 permission denied for function. Zowelauthenticatedalsaura_authenticatedworden geaccepteerd. Dit geldt ook voor functies die u maakt metdb.sql()of voor een migratie van projecten die na deze wijziging zijn gemaakt (het standaardrechtEXECUTEvanPUBLICis ingetrokken): voeg zelfgrant execute on function hello(text) to aura_authenticated;toe.- Na enkele seconden kan een nieuwe functie worden opgeroepen. Totdat de API zijn schema opnieuw laadt, retourneert
rpc()404 Could not find the function. - Functies via SQL (
db.sql()):CREATE FUNCTION/CREATE OR REPLACE FUNCTIONis toegestaan in deSECURITY INVOKER-modus (standaard);SECURITY DEFINERwordt afgewezen op/rawen moet worden gemaakt viacreateFunction(POST /v1/db/{project_id}/functions) of CLI/migraties met explicietegrant_execute_to.
Voer SQL uit vanaf een server#
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() heeft een service_role sleutel nodig. Het weigert een DELETE zonder een WHERE en leest geen systeemcatalogi zoals pg_class of pg_roles. Gebruik admin.db.schema() om uw tabellen weer te geven.
Paginering, rijkap en exacte cijfers
- Een lezing retourneert maximaal 1.000 rijen — de standaard en het harde plafond, ongeacht
limit()ofrange()waar u om vraagt.meta.has_moreistrueals er meer rijen overeenkomen; vraag omcount: 'exact'om ookmeta.totalte krijgen. - Blader door een grote tabel met sleutelsetpaginering, wat hetzelfde kost op de miljoenste pagina:
aura.from('events').select('id,label').limit(1000).after('id', lastId)(het is.order('id').gt('id', lastId))..cursor()is alleen geschikt voor MongoDB;offsetwordt langzamer naarmate je dieper gaat. - Getallen boven JavaScript's 2^53. Een
bigintboven 9.007.199.254.740.991 verliest zijn laatste cijfers wanneer deze wordt geparseerd als een JS-nummer: maak de client aan met{ parseBigIntAsString: true }om deze waarden als tekenreeksen te ontvangen. Eennumericwordt geretourneerd als een JSON-nummer wanneer het exact kan worden weergegeven, en anders als een exacte decimale tekenreeks (lange waarden zoals12345678901234567890.123456789). count: 'planned'en'estimated'zijn slechts schattingen. Ze komen uit de statistieken van PostgreSQL, die leeg zijn in een tabel die zojuist is geladen (een tabel met 60 rijen kan 430 rijen rapporteren). Gebruikcount: 'exact'als het nummer ertoe doet.- Een kolom
vectorkomt terug als een tekenreeks, zoals"[0.1,0.2,0.3]": parseer deze metJSON.parseom eennumber[]te verkrijgen. - Een weergave leest met uw rechten. Views die u maakt (SQL, migratie) krijgen
security_invoker = true, dus het beleid van de onderliggende tabellen is van toepassing op de lezer. Schrijfwith (security_invoker = false)alleen expliciet als u echt wilt dat de weergave RLS overslaat. db.sql()probeert opnieuw een429na deRetry-Aftervertraging (een geweigerd verzoek is nooit uitgevoerd)./rawis beperkt per project; gebruik voor bulkladingen het getypteinsert()met een array.