Avvio rapido
Da zero a un'API interrogabile: database dedicato Postgres, sicurezza a livello di riga, tempo reale e generazione di tipi TypeScript inclusi: non è richiesta la carta di credito.
Prompt per il tuo agente di codice
Set up Aurabase in this app by following this page: https://aurabase.cloud/en/docs/getting-started.md
Documentation: read https://aurabase.cloud/llms.txt first. Every docs page is also available as Markdown: add .md to its URL, for example (the same works for every page): 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.Avvio rapido#
Installa l'SDK, crea il client e leggi le prime righe.
1. Installa l'SDK#
Aggiungi l'SDK al tuo progetto. La scheda Rust installa il crate aurabase; la scheda cURL controlla che l'URL del tuo progetto risponda.
pnpm add @aurabase/aurabase-js
2. Creare il cliente#
Crea il client con l'URL del tuo progetto e la chiave anon, sia in Studio > Impostazioni > Connessione. Conserva la chiave del ruolo del servizio sul server.
import { createClient } from '@aurabase/aurabase-js'
const aura = createClient(
process.env.NEXT_PUBLIC_AURABASE_URL!,
process.env.NEXT_PUBLIC_AURABASE_ANON_KEY!,
)
3. Interrogare il database#
Leggi fino a 10 righe da todos. La tabella viene creata nella sezione "Crea una tabella" di seguito; finché non esiste, viene impostato error.
// `todos` viene creato in "Crea una tabella" di seguito
const { data, error } = await aura
.from('todos')
.select('id, title, done')
.limit(10)
console.log(data, error)
Prerequisiti#
Supponiamo che Node.js ≥ 20 sia installato e che un terminale POSIX sia nel raggio d'azione. Non è richiesto alcun database locale: Aurabase fornisce un database Postgres dedicato per ogni progetto.
Vieni da Supabase o Firebase? La maggior parte dei concetti sono trasponibili. Vedi il guida alla migrazione.
Installazione dell'SDK#
L'SDK ufficiale espone un client tipizzato per CRUD, autenticazione, tempo reale e archiviazione. Funziona allo stesso modo in Next.js, React, Node, Bun o Deno.
# Consigliato
pnpm add @aurabase/aurabase-js
Il nome del pacchetto include l'ambito @aurabase/. Il pacchetto aurabase-js senza ambito non è gestito da Aurabase: non installarlo.
L'SDK include direttamente l'esportazione di @aurabase/aurabase-js/ssr (createServerClient) per Next.js (App Router, Server Actions, Middleware), Remix, Nuxt e SvelteKit con gestione automatica dei cookie di sessione e Chunking anti-troncamento.
Crea un progetto#
Crea un progetto dallo Studio. Quando diventa attivo, lo Studio mostra un pannello Copia le tue chiavi adesso con un .env.local pronto all'uso (copialo o scaricalo): la chiave service_role appare lì una volta, in seguito viene mantenuto solo il suo hash. Impostazioni › Connessione successivamente mostra l'URL del progetto e la chiave anon pubblica; se hai perso la chiave service_role, rigenerala lì (la precedente viene revocata). NEXT_PUBLIC_AURABASE_URL e NEXT_PUBLIC_AURABASE_ANON_KEY possono essere pubblicati lato client; AURABASE_SERVICE_ROLE_KEY rimane strettamente sul lato server.
NEXT_PUBLIC_AURABASE_URL=https://<slug>.aurabase.cloud
NEXT_PUBLIC_AURABASE_ANON_KEY=aura_anon_…
AURABASE_SERVICE_ROLE_KEY=aura_sk_…
| Schema | Accesso | Contiene |
|---|---|---|
project_{uuid} | Tu | Le tue tabelle applicative |
project_{uuid}_auth | Sistema | users, sessions, oauth_accounts, mfa |
project_{uuid}_storage | Sistema | buckets, objects, rls_policies |
project_{uuid}_platform | Sistema | functions, jobs, cron_jobs, api_keys |
L'intero percorso funziona anche dalla CLI (vedi CLI per l'installazione): aura projects create attende finché il progetto è pronto e stampa l'URL e le chiavi una volta.
aura login
aura projects create todos-app --json > project.json # attende finché il progetto è attivo
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> # vedere cosa vede quell'utente
Non includere mai AURABASE_SERVICE_ROLE_KEY in un pacchetto client. Ignora tutte le policy RLS e l'API lo rifiuta da un browser (401 SECRET_KEY_IN_BROWSER). Prenotalo per le chiamate al server (gestori di percorsi, azioni del server, lavori).
Crea una tabella#
Apri Database in Studio, fai clic su Editor SQL (il collegamento nella parte inferiore del pannello delle tabelle) ed esegui questo script. La sicurezza a livello di riga è abilitata su ogni tabella: le prime due policy consentono a ciascun utente che ha effettuato l'accesso di leggere e creare le proprie righe, la terza è un esempio che consente ai visitatori di leggere la tabella in modo da poter vedere le prime righe senza effettuare l'accesso. Le policy hanno come target il ruolo aura_authenticated (aura_anon per i visitatori).
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);
-- Solo ad esempio: qualsiasi visitatore può leggere tutte le cose da fare. Rilascialo prima della produzione:
-- eliminare la policy "todos_public_read" su todos;
create policy "todos_public_read" on todos for select to aura_anon using (true);
Quindi genera i tipi TypeScript del tuo schema (il comando legge .env.local):
npx @aurabase/gen --out lib/aurabase.types.ts
Prima chiamata#
Crea un client Aurabase riutilizzabile leggendo le chiavi dalle variabili di ambiente, quindi esegui una query sulla prima tabella. I percorsi seguenti sono relativi alla root della tua app: se il tuo progetto utilizza una directory src/, inserisci lib/, components/ e app/ al suo interno, in modo che l'alias di importazione @/ si risolva.
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!,
)
Quindi, in un gestore di route o un componente server:
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)
}
Restituisce le righe della tabella, anche senza un utente registrato, grazie alla policy di esempio todos_public_read. Senza di esso (una volta rilasciato, come dovresti prima della produzione) un visitatore ottiene []: le altre policy aprono solo le righe a aura_authenticated, quindi accedi prima un utente con aura.auth.signInWithPassword({ email, password }) (vedi Pagine di accesso già pronte per Next.js). Rigenera i tipi Database con npx @aurabase/gen dopo ogni modifica dello schema.
Per inserire una prima riga, iscrivi un utente e accedi, quindi inserisci. La colonna user_id per impostazione predefinita è 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)
})
Eseguilo con tsx, che risolve l'importazione senza estensione e legge .env.local:
pnpm add -D tsx
pnpm approve-builds # pnpm 10+: consenti lo script di installazione di esbuild, quindi esegui:
pnpm exec tsx --env-file=.env.local scripts/first-row.ts
Con npm 11 o successivo, npx tsx fallisce con «Hai installato esbuild per un'altra piattaforma» perché lo script di installazione di esbuild è bloccato per impostazione predefinita. Utilizza pnpm come sopra oppure salta tsx ed esegui lo script con l'eliminazione dei tipi incorporata di Node (Node 22.6+) dopo aver scritto le due importazioni con la loro estensione ('../lib/aurabase.ts', './aurabase.types.ts'): node --env-file=.env.local --experimental-strip-types scripts/first-row.ts.
Per gli utenti del tuo progetto, signUp seguito da signInWithPassword funziona immediatamente: la conferma via email è disattivata finché non la attivi in Studio › Autenticazione › Configurazione (è necessario un server di posta). Chiunque può quindi registrarsi con qualsiasi indirizzo, quindi attivalo prima della produzione.
La chiave service_role non ha un utente che ha effettuato l'accesso, quindi auth.uid() è NULL e un inserimento che si basa sull'impostazione predefinita ha esito negativo con NOT_NULL_VIOLATION. Da un server, passare user_id in modo esplicito.
Connettiti in tempo reale#
Tre trasporti negoziati automaticamente: WebSocket, SSE, NATS. Il cliente sceglie quello migliore in base alla rete: non è necessaria alcuna configurazione.
Abilita il tempo reale sul tavolo una volta, con la CLI:
aura db table realtime todos on
o con l'API HTTP, da un server (valori da .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}'
Quindi iscriviti alle modifiche. Un utente che ha effettuato l'accesso riceve le righe che le sue policy RLS gli consentono di leggere, incluso quando il canale è stato aperto prima dell'accesso (viene ri-autenticato automaticamente); un abbonamento rifiutato segnala CHANNEL_ERROR con il motivo.
'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) => {
// In fase di sviluppo React StrictMode monta, smonta e rimonta il componente:
// il primo CHIUSO deriva da quella bonifica ed è previsto.
if (status === 'SUBSCRIBED') console.log('realtime connected')
if (status === 'CHANNEL_ERROR') console.error('realtime refused:', err?.message)
})
return () => {
void channel.unsubscribe()
}
}, [])
return null
}
Gli abbonamenti vengono multiplexati su una singola connessione TCP. Aprine quanti ne hai bisogno: zero costi di rete aggiuntivi.