Interroga il tuo database con l'SDK JavaScript
I flussi quotidiani di aura.db, le regole che rifiutano le chiamate non sicure e come proteggere una tabella con sicurezza a livello di riga.
Leggi righe#
const { data, error } = await aura
.from('todos')
.select('id, title, done')
.eq('done', false)
.order('created_at', { ascending: false })
.limit(20)
aura.from('todos') è il formato utilizzato in tutta questa documentazione (è una scorciatoia per aura.db.from('todos'), la stessa chiamata). Ogni chiamata ritorna { data, error } e non lancia mai, vedi opzioni ed errori del client.
Catena di filtri: eq, neq, gt, gte, lt, lte, like, ilike, in, is e gli altri elencati nella riferimento database. Per una pagina di righe, utilizzare range(from, to).
Inserisci, aggiorna ed elimina#
// Inserisci una riga o una serie di righe e recuperale
const { data } = await aura.from('todos').insert({ title: 'Write the docs' }).select()
// Upsert
await aura.from('todos').upsert({ id, title: 'Renamed' }).select()
// Aggiorna ed elimina necessitano di un filtro
await aura.from('todos').update({ done: true }).eq('id', id)
await aura.from('todos').delete().eq('id', id)
Una scrittura non restituisce nulla (data è null) a meno che non si concatena .select(): l'inserimento di 10.000 righe non restituisce 10.000 righe. Con .select() le righe ritornano e un PATCH o POST che non corrispondeva a nessuna riga indica il motivo in meta.hint.
Due regole ti proteggono dagli errori:
- Un inserimento batch richiede le stesse chiavi in ogni riga. Righe con chiavi diverse restituiscono
400conAll object keys must match. Compila le chiavi mancanti connull. update()edelete()senza filtro vengono rifiutati dal client con il codice di erroreUNFILTERED_MUTATION, prima che venga inviata qualsiasi richiesta. Per modificare ogni riga di proposito, esegui SQL da un server.
Una riga, molte righe, conta#
// Esattamente una riga: un errore se non ce ne sono o ce ne sono più
const one = await aura.from('todos').select('*').eq('id', id).single()
// → error.status 406 quando il filtro corrisponde a zero o più righe
// Zero o una riga: i dati sono nulli quando non corrisponde nulla
const maybe = await aura.from('todos').select('*').eq('id', id).maybeSingle()
// Righe e loro totale
const page = await aura.from('todos').select('*', { count: 'exact' }).range(0, 9)
// page.count è il totale, qualunque sia l'intervallo
// Solo il totale, senza righe
const { count } = await aura.from('todos').select('*', { count: 'exact', head: true })
count: 'exact' conta ogni riga corrispondente. 'planned' e 'estimated' sono più veloci su tabelle molto grandi e approssimative.
Proteggi un tavolo#
Le tabelle create tramite Aurabase (db.sql(), migrazioni, Studio o l'API della tabella) ottengono automaticamente ENABLE e FORCE ROW LEVEL SECURITY (a meno che non includi esplicitamente DISABLE ROW LEVEL SECURITY nel batch DDL). Senza ancora policy, i chiamanti anon e authenticated vedono []. Le tabelle create tramite una connessione diretta Postgres richiedono enable row level security esplicitamente. Aggiungi le policy di cui hai bisogno:
create policy todos_own_read on todos
for select to aura_authenticated
using (auth.uid() = owner);
I ruoli canonici del database sono aura_anon, aura_authenticated e aura_service_role (anche gli alias di gruppo anon, authenticated, service_role vengono mappati a questi sui cluster gestiti). auth.uid() è NULL per la chiave pubblica e un ID utente per un utente che ha effettuato l'accesso. Vedere Sicurezza a livello di riga.
Una chiave service_role bypassa RLS in base alla progettazione: tienila sul tuo server.
Funzioni SQL e rpc#
Crea una funzione da un server, quindi chiamala da qualsiasi luogo con 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_toè necessario per chiamarlo. Senza di esso, nessuno può eseguire la funzione. Un ruolo non elencato ottiene403 permission denied for function. Sono accettati siaauthenticatedcheaura_authenticated. Ciò vale anche per le funzioni create condb.sql()o per una migrazione su progetti creati dopo questa modifica (il privilegio predefinitoEXECUTEdiPUBLICè revocato): aggiungigrant execute on function hello(text) to aura_authenticated;tu stesso.- Una nuova funzione è richiamabile dopo alcuni secondi. Fino a quando l'API non ricarica il proprio schema,
rpc()restituisce404 Could not find the function. - Funzioni tramite SQL (
db.sql()):CREATE FUNCTION/CREATE OR REPLACE FUNCTIONè consentito in modalitàSECURITY INVOKER(predefinita);SECURITY DEFINERviene rifiutato su/rawe deve essere creato tramitecreateFunction(POST /v1/db/{project_id}/functions) o CLI/migrazioni congrant_execute_toesplicito.
Esegui SQL da un 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() necessita di una chiave service_role. Rifiuta un DELETE senza un WHERE e non legge i cataloghi di sistema come pg_class o pg_roles. Per elencare le tue tabelle, usa admin.db.schema().
Impaginazione, limite di riga e numeri esatti
- Una lettura restituisce al massimo 1.000 righe: il valore predefinito e il limite massimo, qualunque sia
limit()orange()richiesto.meta.has_moreètruequando più righe corrispondono; chiedicount: 'exact'per ottenere anchemeta.total. - Pagina attraverso una grande tabella con impaginazione keyset, che costa lo stesso sulla milionesima pagina:
aura.from('events').select('id,label').limit(1000).after('id', lastId)(è.order('id').gt('id', lastId))..cursor()è solo MongoDB;offsetdiventa più lento più vai in profondità. - Numeri oltre 2^53 di JavaScript. Un
bigintsuperiore a 9.007.199.254.740.991 perde le sue ultime cifre quando viene analizzato come numero JS: crea il client con{ parseBigIntAsString: true }per ricevere tali valori come stringhe. Unnumericviene restituito come numero JSON quando è esattamente rappresentabile e come una stringa decimale esatta altrimenti (valori lunghi come12345678901234567890.123456789). count: 'planned'e'estimated'sono solo stime. Provengono dalle statistiche di PostgreSQL, che sono vuote su una tabella appena caricata (una tabella a 60 righe può riportarne 430). Usacount: 'exact'quando il numero conta.- Una colonna
vectorritorna come una stringa come"[0.1,0.2,0.3]": analizzala conJSON.parseper ottenere unnumber[]. - Una vista legge con i tuoi privilegi. Le viste create (SQL, migrazione) ottengono
security_invoker = true, quindi le politiche delle tabelle sottostanti si applicano al lettore. Scriviwith (security_invoker = false)esplicitamente solo se vuoi veramente che la vista ignori RLS. db.sql()riprova un429dopo il ritardoRetry-After(una richiesta rifiutata non è mai stata eseguita)./rawè limitato per progetto; per carichi di massa utilizzareinsert()digitato con un array.