Vai al contenuto
Logo Aurabase
aurabase

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.

Guida pratica9 min lettoLivello intermedioRevisionato il 12 ott 2026

Questa pagina è stata tradotta automaticamente. Fa fede la versione inglese.

Leggi righe#

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

write.tstypescript
// 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 400 con All object keys must match. Compila le chiavi mancanti con null.
  • update() e delete() senza filtro vengono rifiutati dal client con il codice di errore UNFILTERED_MUTATION, prima che venga inviata qualsiasi richiesta. Per modificare ogni riga di proposito, esegui SQL da un server.

Una riga, molte righe, conta#

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

RLS è abilitato per impostazione predefinita tramite Aurabase, aggiungi policy per concedere l'accesso

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:

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

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 è necessario per chiamarlo. Senza di esso, nessuno può eseguire la funzione. Un ruolo non elencato ottiene 403 permission denied for function. Sono accettati sia authenticated che aura_authenticated. Ciò vale anche per le funzioni create con db.sql() o per una migrazione su progetti creati dopo questa modifica (il privilegio predefinito EXECUTE di PUBLIC è revocato): aggiungi grant 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() restituisce 404 Could not find the function.
  • Funzioni tramite SQL (db.sql()): CREATE FUNCTION / CREATE OR REPLACE FUNCTION è consentito in modalità SECURITY INVOKER (predefinita); SECURITY DEFINER viene rifiutato su /raw e deve essere creato tramite createFunction (POST /v1/db/{project_id}/functions) o CLI/migrazioni con grant_execute_to esplicito.

Esegui SQL da un 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() 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() o range() richiesto. meta.has_more è true quando più righe corrispondono; chiedi count: 'exact' per ottenere anche meta.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; offset diventa più lento più vai in profondità.
  • Numeri oltre 2^53 di JavaScript. Un bigint superiore 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. Un numeric viene restituito come numero JSON quando è esattamente rappresentabile e come una stringa decimale esatta altrimenti (valori lunghi come 12345678901234567890.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). Usa count: 'exact' quando il numero conta.
  • Una colonna vector ritorna come una stringa come "[0.1,0.2,0.3]": analizzala con JSON.parse per ottenere un number[].
  • 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. Scrivi with (security_invoker = false) esplicitamente solo se vuoi veramente che la vista ignori RLS.
  • db.sql() riprova un 429 dopo il ritardo Retry-After (una richiesta rifiutata non è mai stata eseguita). /raw è limitato per progetto; per carichi di massa utilizzare insert() digitato con un array.