Vai al contenuto
Logo Aurabase
aurabase

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.

Tutorial5 min lettoLivello principianteRevisionato il 21 ott 2026

Questa pagina è stata tradotta automaticamente. Fa fede la versione inglese.

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.

bash
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.

typescript
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.

typescript
// `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.

Informazioni

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.

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

Suggerimento

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.

.env.localbash
NEXT_PUBLIC_AURABASE_URL=https://<slug>.aurabase.cloud
NEXT_PUBLIC_AURABASE_ANON_KEY=aura_anon_…
AURABASE_SERVICE_ROLE_KEY=aura_sk_…
SchemaAccessoContiene
project_{uuid}TuLe tue tabelle applicative
project_{uuid}_authSistemausers, sessions, oauth_accounts, mfa
project_{uuid}_storageSistemabuckets, objects, rls_policies
project_{uuid}_platformSistemafunctions, jobs, cron_jobs, api_keys
Preferisci il terminale?

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.

terminalbash
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
Chiave del ruolo del servizio

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

todos.sqlsql
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):

terminalbash
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.

lib/aurabase.tstypescript
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:

app/api/todos/route.tstypescript
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)
}
Suggerimento

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():

scripts/first-row.tstypescript
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:

terminalbash
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
npm 11 blocca lo script di installazione di esbuild

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.

La conferma via email è disattivata per impostazione predefinita

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.

Attenzione

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:

terminalbash
aura db table realtime todos on

o con l'API HTTP, da un server (valori da .env.local):

terminalbash
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.

components/LiveTodos.tsxtypescript
'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
}
Suggerimento

Gli abbonamenti vengono multiplexati su una singola connessione TCP. Aprine quanti ne hai bisogno: zero costi di rete aggiuntivi.

Per andare oltre#