Naar de inhoud springen
Aurabase-logo
aurabasis

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.

Handleiding9 min lezenNiveau tussenproductHerzien op 12 okt 2026

Deze pagina is automatisch vertaald. De Engelse versie is gezaghebbend.

Rijen lezen#

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') 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#

write.tstypescript
// 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 400 met All object keys must match. Vul de ontbrekende sleutels met null.
  • update() en delete() zonder filter worden geweigerd door de client met de foutcode UNFILTERED_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#

count.tstypescript
// 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#

RLS is standaard ingeschakeld via Aurabase. Voeg beleid toe om toegang te verlenen

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:

SQLsql
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():

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
  • grant_execute_to is vereist om het aan te roepen. Zonder dit kan niemand de functie uitvoeren. Een rol die niet in de lijst staat, krijgt 403 permission denied for function. Zowel authenticated als aura_authenticated worden geaccepteerd. Dit geldt ook voor functies die u maakt met db.sql() of voor een migratie van projecten die na deze wijziging zijn gemaakt (het standaardrecht EXECUTE van PUBLIC is ingetrokken): voeg zelf grant 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 FUNCTION is toegestaan in de SECURITY INVOKER-modus (standaard); SECURITY DEFINER wordt afgewezen op /raw en moet worden gemaakt via createFunction (POST /v1/db/{project_id}/functions) of CLI/migraties met expliciete grant_execute_to.

Voer SQL uit vanaf een server#

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() 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() of range() waar u om vraagt. meta.has_more is true als er meer rijen overeenkomen; vraag om count: 'exact' om ook meta.total te 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; offset wordt langzamer naarmate je dieper gaat.
  • Getallen boven JavaScript's 2^53. Een bigint boven 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. Een numeric wordt geretourneerd als een JSON-nummer wanneer het exact kan worden weergegeven, en anders als een exacte decimale tekenreeks (lange waarden zoals 12345678901234567890.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). Gebruik count: 'exact' als het nummer ertoe doet.
  • Een kolom vector komt terug als een tekenreeks, zoals "[0.1,0.2,0.3]": parseer deze met JSON.parse om een number[] 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. Schrijf with (security_invoker = false) alleen expliciet als u echt wilt dat de weergave RLS overslaat.
  • db.sql() probeert opnieuw een 429 na de Retry-After vertraging (een geweigerd verzoek is nooit uitgevoerd). /raw is beperkt per project; gebruik voor bulkladingen het getypte insert() met een array.