Aller au contenu
Logo Aurabase
aurabase

Interrogez votre base de données avec le SDK JavaScript

Les flux quotidiens de aura.db, les règles qui refusent les appels dangereux et comment protéger une table avec une sécurité au niveau des lignes.

Guide pratique9 min de lectureNiveau intermédiaireRévisé le 12 oct. 2026

Cette page a été traduite automatiquement. La version anglaise fait foi.

Lire les lignes#

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') est le formulaire utilisé tout au long de cette documentation (c'est un raccourci pour aura.db.from('todos'), le même appel). Chaque appel revient { data, error } et ne jette jamais, tu vois options et erreurs du client.

Chaîne de filtres : eq, neq, gt, gte, lt, lte, like, ilike, in, is, et les autres répertoriés dans le référence de base de données. Pour une page de lignes, utilisez range(from, to).

Insérer, mettre à jour et supprimer#

write.tstypescript
// Insérez une ligne ou un tableau de lignes et récupérez-les
const { data } = await aura.from('todos').insert({ title: 'Write the docs' }).select()

// Insérer
await aura.from('todos').upsert({ id, title: 'Renamed' }).select()

// La mise à jour et la suppression nécessitent un filtre
await aura.from('todos').update({ done: true }).eq('id', id)
await aura.from('todos').delete().eq('id', id)

Une écriture ne renvoie rien (data est null) sauf si vous enchaînez .select(): l'insertion de 10 000 lignes ne renvoie pas 10 000 lignes. Avec .select() les lignes reviennent, et un PATCH ou POST qui ne correspond à aucune ligne indique pourquoi dans meta.hint.

Deux règles vous protègent des erreurs :

  • Une insertion par lots nécessite les mêmes clés dans chaque ligne. Les lignes avec des clés différentes renvoient 400 avec All object keys must match. Remplissez les clés manquantes avec null.
  • update() et delete() sans filtre sont refusés par le client avec le code erreur UNFILTERED_MUTATION, avant l'envoi de toute requête. Pour modifier volontairement chaque ligne, exécutez SQL à partir d'un serveur.

Une ligne, plusieurs lignes, ça compte#

count.tstypescript
// Exactement une ligne : une erreur s'il n'y en a pas ou plusieurs
const one = await aura.from('todos').select('*').eq('id', id).single()
// → error.status 406 lorsque le filtre correspond à zéro ou plusieurs lignes

// Zéro ou une ligne : les données sont nulles lorsque rien ne correspond
const maybe = await aura.from('todos').select('*').eq('id', id).maybeSingle()

// Lignes et leur total
const page = await aura.from('todos').select('*', { count: 'exact' }).range(0, 9)
// page.count est le total, quelle que soit la plage

// Le total uniquement, pas de lignes
const { count } = await aura.from('todos').select('*', { count: 'exact', head: true })

count: 'exact' compte chaque ligne correspondante. 'planned' et 'estimated' sont plus rapides sur de très grandes tables et approximatives.

Protéger une table#

RLS est activé par défaut via Aurabase, ajoutez des stratégies pour accorder l'accès

Les tables créées via Aurabase (db.sql(), migrations, Studio ou l'API de table) obtiennent automatiquement ENABLE et FORCE ROW LEVEL SECURITY (sauf si vous incluez explicitement DISABLE ROW LEVEL SECURITY dans votre lot DDL). Sans politique pour le moment, les appelants anon et authenticated voient []. Les tables créées via une connexion directe Postgres nécessitent explicitement enable row level security. Ajoutez les politiques dont vous avez besoin :

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

Les rôles de base de données canoniques sont aura_anon, aura_authenticated et aura_service_role (les alias de groupe anon, authenticated, service_role leur correspondent également sur les clusters gérés). auth.uid() est NULL pour la clé publique et un identifiant utilisateur pour un utilisateur connecté. Voir Sécurité au niveau des lignes.

Une clé service_role contourne RLS de par sa conception : conservez-la sur votre serveur.

Fonctions SQL et rpc#

Créez une fonction depuis un serveur, puis appelez-la de n'importe où avec 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 est requis pour l'appeler. Sans lui, personne ne peut exécuter la fonction. Un rôle qui n'est pas listé obtient 403 permission denied for function. authenticated et aura_authenticated sont tous deux acceptés. Cela vaut aussi pour les fonctions que vous créez avec db.sql() ou une migration sur les projets créés après ce changement (le privilège EXECUTE par défaut de PUBLIC est révoqué) : ajoutez vous-même grant execute on function hello(text) to aura_authenticated;.
  • Une nouvelle fonction est appelable après quelques secondes. Jusqu'à ce que l'API recharge son schéma, rpc() renvoie 404 Could not find the function.
  • Fonctions via SQL (db.sql()) : CREATE FUNCTION / CREATE OR REPLACE FUNCTION est autorisé en mode SECURITY INVOKER (par défaut) ; SECURITY DEFINER est rejeté sur /raw et doit être créé via createFunction (POST /v1/db/{project_id}/functions) ou CLI/migrations avec grant_execute_to explicite.

Exécuter SQL à partir d'un serveur#

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() nécessite une clé service_role. Il refuse un DELETE sans un WHERE et ne lit pas les catalogues système tels que pg_class ou pg_roles. Pour lister vos tables, utilisez admin.db.schema().

Pagination, plafond de lignes et nombres exacts

  • Une lecture renvoie au plus 1 000 lignes — la valeur par défaut et le plafond strict, quel que soit le limit() ou le range() demandé. meta.has_more vaut true quand d'autres lignes correspondent ; demandez count: 'exact' pour obtenir aussi meta.total.
  • Parcourez une grande table par pagination keyset (sur la dernière clé lue), qui coûte pareil à la millionième page : aura.from('events').select('id,label').limit(1000).after('id', lastId) (c'est .order('id').gt('id', lastId)). .cursor() ne concerne que MongoDB ; offset ralentit à mesure qu'on avance.
  • Nombres au-delà de 2^53 en JavaScript. Un bigint supérieur à 9 007 199 254 740 991 perd ses derniers chiffres lorsqu'il est lu comme un nombre JS : créez le client avec { parseBigIntAsString: true } pour recevoir ces valeurs sous forme de chaînes. Un numeric est renvoyé comme nombre JSON quand il est exactement représentable, et comme chaîne décimale exacte sinon (valeurs longues comme 12345678901234567890.123456789).
  • count: 'planned' et 'estimated' ne sont que des estimations. Elles viennent des statistiques de PostgreSQL, vides sur une table qui vient d'être chargée (une table de 60 lignes peut en annoncer 430). Utilisez count: 'exact' quand le nombre compte.
  • Une colonne vector revient sous forme de chaîne, par exemple "[0.1,0.2,0.3]" : analysez-la avec JSON.parse pour obtenir un number[].
  • Une vue lit avec vos privilèges. Les vues que vous créez (SQL, migration) reçoivent security_invoker = true : les policies des tables sous-jacentes s'appliquent donc au lecteur. N'écrivez with (security_invoker = false) explicitement que si vous voulez vraiment que la vue contourne RLS.
  • db.sql() rejoue un 429 après le délai Retry-After (une requête refusée n'a jamais été exécutée). /raw est limité par projet ; pour les chargements en masse, utilisez insert() typé avec un tableau.