Démarrage rapide
De zéro à une API interrogeable : base de données Postgres dédiée, sécurité au niveau des lignes, génération de type TypeScript en temps réel incluse – aucune carte de crédit requise.
Prompt pour votre agent de code
Configure Aurabase dans cette application en suivant cette page : https://aurabase.cloud/en/docs/getting-started.md
Documentation : lis d'abord https://aurabase.cloud/llms.txt. Chaque page de la documentation est aussi disponible en Markdown : ajoute .md à son URL, par exemple (cela marche pour toutes les pages) : https://aurabase.cloud/en/docs/getting-started.md
Client: install @aurabase/aurabase-js and create the client with createClient(NEXT_PUBLIC_AURABASE_URL, NEXT_PUBLIC_AURABASE_ANON_KEY). Keep AURABASE_SERVICE_ROLE_KEY on the server: never put it in client code.
Project access: to read the schema and run SQL, start the Aurabase MCP server over stdio (82 tools with a project key):
npx -y -p @aurabase/mcp-server aurabase-mcp --url https://<slug>.aurabase.cloud --project-id <project-id> --service-role-key aura_sk_…
The project id is in Studio › Settings › General. The service role key is shown once when the project is created; regenerate it in Studio › Settings › Connection if you lost it.Démarrage rapide#
Installez le SDK, créez le client et lisez vos premières lignes.
1. Installez le SDK#
Ajoutez le SDK à votre projet. L'onglet Rust installe la caisse aurabase ; l'onglet cURL vérifie que l'URL de votre projet répond.
pnpm add @aurabase/aurabase-js
2. Créez le client#
Créez le client avec l'URL de votre projet et la clé anonyme, tous deux dans Studio > Paramètres > Connexion. Conservez la clé de rôle de service sur le serveur.
import { createClient } from '@aurabase/aurabase-js'
const aura = createClient(
process.env.NEXT_PUBLIC_AURABASE_URL!,
process.env.NEXT_PUBLIC_AURABASE_ANON_KEY!,
)
3. Interrogez la base de données#
Lisez jusqu'à 10 lignes à partir de todos. Le tableau est créé dans la section « Créer un tableau » ci-dessous ; jusqu'à ce qu'il existe, error est défini.
// `todos` est créé dans "Créer un tableau" ci-dessous
const { data, error } = await aura
.from('todos')
.select('id, title, done')
.limit(10)
console.log(data, error)
Conditions préalables#
Nous supposons que Node.js ≥ 20 est installé et qu'un terminal POSIX est à portée. Aucune base de données locale n'est requise : Aurabase fournit une base de données Postgres dédiée pour chaque projet.
Venez-vous de Supabase ou Firebase? La plupart des concepts sont transposables. Voir le guide de migration.
Installation du SDK#
Le SDK officiel expose un client typé pour CRUD, l'authentification, le temps réel et le stockage. Cela fonctionne de la même manière dans Next.js, React, Node, Bun ou Deno.
# Recommandé
pnpm add @aurabase/aurabase-js
Le nom du package inclut la portée @aurabase/. Le package aurabase-js sans scope n'est pas maintenu par Aurabase: ne l'installez pas.
Le SDK inclut directement l'export @aurabase/aurabase-js/ssr (createServerClient) pour Next.js (App Router, Server Actions, Middleware), Remix, Nuxt et SvelteKit avec gestion automatique des cookies de session et chunking anti-troncation.
Créer un projet#
Créez un projet depuis le Studio. Lorsqu'il devient actif, le Studio affiche un panneau Copiez vos clés maintenant avec un .env.local prêt à l'emploi (copiez-le ou téléchargez-le) : la clé service_role y apparaît une fois, seul son hachage est conservé par la suite. Paramètres › Connexion affiche plus tard l'URL du projet et la clé publique anonyme ; si vous avez perdu la clé service_role, régénérez-la là (la précédente est révoquée). NEXT_PUBLIC_AURABASE_URL et NEXT_PUBLIC_AURABASE_ANON_KEY peuvent être publiés côté client ; AURABASE_SERVICE_ROLE_KEY reste strictement côté serveur.
NEXT_PUBLIC_AURABASE_URL=https://<slug>.aurabase.cloud
NEXT_PUBLIC_AURABASE_ANON_KEY=aura_anon_…
AURABASE_SERVICE_ROLE_KEY=aura_sk_…
| Schéma | Accès | Contient |
|---|---|---|
project_{uuid} | Vous | Vos tableaux d'application |
project_{uuid}_auth | Système | users, sessions, oauth_accounts, mfa |
project_{uuid}_storage | Système | buckets, objects, rls_policies |
project_{uuid}_platform | Système | functions, jobs, cron_jobs, api_keys |
L'ensemble du chemin fonctionne également depuis la CLI (voir CLI pour l'installation) : aura projects create attend que le projet soit prêt et imprime une fois l'URL et les clés.
aura login
aura projects create todos-app --json > project.json # attend que le projet soit actif
aura link --project-id "$(jq -r .id project.json)"
export NEXT_PUBLIC_AURABASE_URL="$(jq -r .url project.json)"
export AURABASE_SERVICE_ROLE_KEY="$(jq -r .service_role_key project.json)"
aura db raw "create table todos (id bigint generated always as identity primary key, title text not null, done boolean not null default false, user_id uuid not null default auth.uid(), created_at timestamptz not null default now())"
aura db raw "create policy todos_own_read on todos for select to aura_authenticated using (auth.uid() = user_id)"
aura db raw "create policy todos_own_insert on todos for insert to aura_authenticated with check (auth.uid() = user_id)"
aura db table realtime todos on
aura db raw "select count(*) from todos" --as authenticated --user <a user id> # voir ce que cet utilisateur voit
N'incluez jamais AURABASE_SERVICE_ROLE_KEY dans un ensemble client. Il contourne toutes les politiques RLS et l'API le refuse depuis un navigateur (401 SECRET_KEY_IN_BROWSER). Réservez-le pour les appels du serveur (gestionnaires de routes, actions du serveur, travaux).
Créer un tableau#
Ouvrir Base de données dans le Studio, cliquez sur Éditeur SQL (le lien en bas du panneau des tableaux) et exécutez ce script. La sécurité au niveau des lignes est activée sur chaque table : les deux premières stratégies permettent à chaque utilisateur connecté de lire et de créer ses propres lignes, la troisième est une exemple qui permet aux visiteurs de lire le tableau afin que vous puissiez voir vos premières lignes sans vous connecter. Les politiques ciblent le aura_authenticated rôle (aura_anon pour les visiteurs).
create table todos (
id bigint generated always as identity primary key,
title text not null,
done boolean not null default false,
user_id uuid not null default auth.uid(),
created_at timestamptz not null default now()
);
create policy "todos_own_read" on todos for select to aura_authenticated using (auth.uid() = user_id);
create policy "todos_own_insert" on todos for insert to aura_authenticated with check (auth.uid() = user_id);
-- Exemple uniquement : n'importe quel visiteur peut lire chaque tâche. Déposez-le avant la production :
-- déposez la politique "todos_public_read" sur todos ;
create policy "todos_public_read" on todos for select to aura_anon using (true);
Générez ensuite les types TypeScript de votre schéma (la commande lit .env.local) :
npx @aurabase/gen --out lib/aurabase.types.ts
Premier appel#
Créez un client Aurabase réutilisable en lisant les clés des variables d'environnement, puis interrogez votre première table. Les chemins ci-dessous sont relatifs à la racine de votre application : si votre projet utilise un répertoire src/, placez-y lib/, components/ et app/, afin que l'alias d'importation @/ soit résolu.
import { createClient } from '@aurabase/aurabase-js'
import type { Database } from './aurabase.types'
export const aura = createClient<Database>(
process.env.NEXT_PUBLIC_AURABASE_URL!,
process.env.NEXT_PUBLIC_AURABASE_ANON_KEY!,
)
Ensuite, dans un gestionnaire de route ou un composant serveur :
import { aura } from '@/lib/aurabase'
export async function GET() {
const { data, error } = await aura
.from('todos')
.select('id, title, done')
.order('created_at', { ascending: false })
.limit(10)
if (error) throw error
return Response.json(data)
}
Cela renvoie les lignes de la table, y compris sans utilisateur connecté, grâce à l'exemple de politique todos_public_read. Sans cela (une fois que vous l'avez déposé, comme vous devriez le faire avant la production), un visiteur obtient []: les autres politiques n'ouvrent que les lignes vers aura_authenticated, alors connectez-vous d'abord à un utilisateur avec aura.auth.signInWithPassword({ email, password }) (voir Pages de connexion prêtes à l'emploi pour Next.js). Régénérez les types Database avec npx @aurabase/gen après chaque modification de schéma.
Pour insérer une première ligne, inscrivez un utilisateur et insérez-le, puis insérez-le. La colonne user_id est par défaut auth.uid():
import { aura } from '../lib/aurabase'
async function main() {
const email = 'you@example.com'
const password = 'a-strong-password'
await aura.auth.signUp({ email, password })
await aura.auth.signInWithPassword({ email, password })
const { data, error } = await aura.from('todos').insert({ title: 'First todo' }).select()
console.log(data, error)
}
main().catch((err) => {
console.error(err)
process.exit(1)
})
Exécutez-le avec tsx, qui résout l'importation sans extension et lit .env.local:
pnpm add -D tsx
pnpm approve-builds # pnpm 10+ : autorisez le script d'installation d'esbuild, puis exécutez :
pnpm exec tsx --env-file=.env.local scripts/first-row.ts
Avec npm 11 ou plus récent, npx tsx échoue avec « You installed esbuild for another platform » car le script d'installation d'esbuild est bloqué par défaut. Utilisez pnpm comme ci-dessus, ou renoncez à tsx et exécutez le script avec le retrait de types intégré à Node (Node 22.6+), après avoir écrit les deux imports avec leur extension ('../lib/aurabase.ts', './aurabase.types.ts') : node --env-file=.env.local --experimental-strip-types scripts/first-row.ts.
Pour les utilisateurs de votre projet, signUp suivi de signInWithPassword fonctionne immédiatement : la confirmation par e-mail est désactivée jusqu'à ce que vous l'activiez dans Studio > Authentification > Configuration (il nécessite un serveur de messagerie). N’importe qui peut alors s’inscrire avec n’importe quelle adresse, alors activez-la avant la production.
La clé service_role n'a aucun utilisateur connecté, donc auth.uid() est NULL et une insertion qui s'appuie sur la valeur par défaut échoue avec NOT_NULL_VIOLATION. Depuis un serveur, transmettez explicitement user_id.
Connectez-vous en temps réel#
Trois transports auto-négociés : WebSocket, SSE, NATS. Le client choisit le meilleur en fonction du réseau – aucune configuration n'est nécessaire.
Activez le temps réel sur la table une fois, avec la CLI :
aura db table realtime todos on
ou avec l'API HTTP, depuis un serveur (valeurs de .env.local) :
curl -X PUT "$NEXT_PUBLIC_AURABASE_URL/v1/db/schema/tables/todos/realtime" \
-H "apikey: $AURABASE_SERVICE_ROLE_KEY" \
-H "Content-Type: application/json" \
-d '{"enabled": true}'
Alors abonnez-vous aux modifications. Un utilisateur connecté reçoit les lignes que ses stratégies RLS lui permettent de lire, y compris lorsque le canal a été ouvert avant la connexion (il est réauthentifié automatiquement) ; un abonnement refusé signale CHANNEL_ERROR avec le motif.
'use client'
import { aura } from '@/lib/aurabase'
import { useEffect } from 'react'
export function LiveTodos() {
useEffect(() => {
const channel = aura.realtime
.channel('todos')
.on('postgres_changes', { event: '*', schema: 'public', table: 'todos' }, (change) =>
console.log(change.eventType, change.new),
)
.subscribe((status, err) => {
// En développement, React StrictMode monte, démonte et remonte le composant :
// le premier FERMÉ vient de ce nettoyage et est attendu.
if (status === 'SUBSCRIBED') console.log('realtime connected')
if (status === 'CHANNEL_ERROR') console.error('realtime refused:', err?.message)
})
return () => {
void channel.unsubscribe()
}
}, [])
return null
}
Les abonnements sont multiplexés sur une seule connexion TCP. Ouvrez-en autant que vous le souhaitez – aucun coût de réseau supplémentaire.