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.
Lire les lignes#
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#
// 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
400avecAll object keys must match. Remplissez les clés manquantes avecnull. update()etdelete()sans filtre sont refusés par le client avec le code erreurUNFILTERED_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#
// 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#
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 :
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():
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_toest requis pour l'appeler. Sans lui, personne ne peut exécuter la fonction. Un rôle qui n'est pas listé obtient403 permission denied for function.authenticatedetaura_authenticatedsont tous deux acceptés. Cela vaut aussi pour les fonctions que vous créez avecdb.sql()ou une migration sur les projets créés après ce changement (le privilègeEXECUTEpar défaut dePUBLICest révoqué) : ajoutez vous-mêmegrant 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()renvoie404 Could not find the function. - Fonctions via SQL (
db.sql()) :CREATE FUNCTION/CREATE OR REPLACE FUNCTIONest autorisé en modeSECURITY INVOKER(par défaut) ;SECURITY DEFINERest rejeté sur/rawet doit être créé viacreateFunction(POST /v1/db/{project_id}/functions) ou CLI/migrations avecgrant_execute_toexplicite.
Exécuter SQL à partir d'un serveur#
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 lerange()demandé.meta.has_morevauttruequand d'autres lignes correspondent ; demandezcount: 'exact'pour obtenir aussimeta.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 ;offsetralentit à mesure qu'on avance. - Nombres au-delà de 2^53 en JavaScript. Un
bigintsupé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. Unnumericest renvoyé comme nombre JSON quand il est exactement représentable, et comme chaîne décimale exacte sinon (valeurs longues comme12345678901234567890.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). Utilisezcount: 'exact'quand le nombre compte.- Une colonne
vectorrevient sous forme de chaîne, par exemple"[0.1,0.2,0.3]": analysez-la avecJSON.parsepour obtenir unnumber[]. - 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'écrivezwith (security_invoker = false)explicitement que si vous voulez vraiment que la vue contourne RLS. db.sql()rejoue un429après le délaiRetry-After(une requête refusée n'a jamais été exécutée)./rawest limité par projet ; pour les chargements en masse, utilisezinsert()typé avec un tableau.