Logo Aurabase
aurabasedocumenti
documenti›Guide›Query your database (SDK)

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.

9 min letto·Livello intermedio·Revisionato il 12 ott 2026
Questo testo inglese è stato generato automaticamente dall'originale francese e non è stato ancora rivisto.
Questa pagina è stata tradotta automaticamente. Fa fede la versione inglese.
#
Leggi

1. Leggi le 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') è una scorciatoia per aura.db.from('todos'). Ogni chiamata restituisce { data, error } e non genera mai un'eccezione, vedere opzioni ed errori 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).

#
Scrivi

2. 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)

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.
#
Risultati

3. Una riga, molte righe, contano

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.

#
Sicurezza

4. Proteggi un tavolo

Una tabella creata in SQL è aperta finché non abiliti RLS

La sicurezza a livello di riga è disattivata su una nuova tabella. Con la chiave pubblica chiunque può leggerlo e scriverlo. Abilitalo, quindi aggiungi le policy che ti servono:

SQLsql
alter table todos enable row level security;

create policy todos_own_read on todos
  for select to aura_authenticated
  using (auth.uid() = owner);

I ruoli del database sono aura_anon, aura_authenticated e aura_service_role. 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

5. 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.
  • 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.
  • La creazione di funzioni con SQL non elaborato (CREATE FUNCTION) è rifiutata: utilizzare createFunction.
#
Server

6. Eseguire SQL da un server

server/migrate.tstypescript
import { createAdminClient } from '@aurabase/aurabase-js'

const admin = createAdminClient(process.env.AURA_URL!, process.env.AURA_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().

Ultimo aggiornamento · 12 ott 2026