Vai al contenuto
Logo Aurabase
aurabase

Genera tipi TypeScript dal tuo database

Un comando trasforma le tue tabelle in tipi. Il tuo editor quindi rifiuta una colonna sbagliata o un valore sbagliato prima di eseguire qualsiasi cosa.

Guida pratica4 min lettoLivello principianteRevisionato il 12 ott 2026

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

Generare il file#

terminalbash
npx @aurabase/gen --url https://my-app.aurabase.cloud --key "$AURABASE_SERVICE_ROLE_KEY" --out src/types/database.types.ts

L'introspezione dello schema (GET /v1/db/schema) richiede una chiave service_role (AURABASE_SERVICE_ROLE_KEY); il passaggio di una chiave anon viene rifiutato con un messaggio esplicito. Senza --url e --key, @aurabase/gen legge NEXT_PUBLIC_AURABASE_URL e AURABASE_SERVICE_ROLE_KEY dall'ambiente e .env, .env.local, .env.development (o uno snapshot dello schema locale con --from-file).

In un progetto con due tabelle e due funzioni, stampa:

text
[aurabase-gen] Types written to src/types/database.types.ts (2 table(s), 2 function(s), 0 enum(s), 0 view(s)).

Eseguilo di nuovo ogni volta che lo schema cambia (o passa --check in CI per fallire in caso di deriva dello schema). Aggiungere --schema <name> per uno schema diverso da public, --type-name per rinominare il tipo principale e --numeric-as-string per mantenere numeric/decimal come string invece di number.

Usalo con il cliente#

src/lib/aurabase.tstypescript
import { createClient } from '@aurabase/aurabase-js'
import type { Database } from '../types/database.types'

export const aura = createClient<Database>(process.env.NEXT_PUBLIC_AURABASE_URL!, process.env.NEXT_PUBLIC_AURABASE_ANON_KEY!)

Il tipo generato descrive ciascuna tabella con Row, Insert e Update. Rispetto a un file reale, il compilatore ha fornito questi risultati:

checked.tstypescript
const { data } = await aura.from('todos').select('id, title, done')
const title: string | undefined = data?.[0]?.title   // ok

const wrong: number | undefined = data?.[0]?.title   // errore: la stringa non è assegnabile al numero
await aura.from('todos').insert({ title: 1 })         // errore: il numero non è assegnabile alla stringa
await aura.from('todos').insert({ title: 'ok' })      // ok: le altre colonne hanno valori predefiniti

In Insert, una colonna con una colonna predefinita o nullable è facoltativa. In Update, ogni colonna è facoltativa.

Tipi di riga per i tuoi componenti#

Todo.tsxtypescript
import type { Tables, TablesInsert, TablesUpdate, Enums } from '../types/database.types'

type Todo = Tables<'todos'>             // una riga, come letto
type NewTodo = TablesInsert<'todos'>    // cosa accetta insert()
type TodoPatch = TablesUpdate<'todos'>  // cosa accetta update()

Enums<'name'> fornisce i valori di un'enumerazione del database.

Cosa viene controllato#

  • Una tabella che non è nel file generato è non rifiutata: aura.from('anything') viene comunque compilato e le sue righe non sono tipizzate.
  • Le funzioni vengono visualizzate sotto Functions con argomenti digitati e valori restituiti: add(a int, b int) returns int restituisce Args: { a: number; b: number } e Returns: number e una funzione RETURNS TABLE (content text, dist float8) restituisce Returns: { content: string; dist: number }[]. Una funzione che restituisce un tipo composito anonimo viene ancora visualizzata come Record<string, unknown>.
  • Vengono controllati i filtri, i payload insert() e update(), le enumerazioni e gli incorporamenti di relazioni. L'elenco di colonne all'interno della stringa select('a, b') viene utilizzato per digitare il risultato, ma un nome errato viene rilevato solo in fase di esecuzione (COLUMN_NOT_FOUND, con un suggerimento « Forse intendevi ... »).
  • Il pulsante dei tipi di Studio e npx @aurabase/gen produce lo stesso file.
  • Il file riflette lo schema nel momento in cui lo hai generato. Una colonna aggiunta successivamente risulta sconosciuta ai tipi finché non si esegue nuovamente lo strumento.
  • L'introspezione dello schema richiede AURABASE_SERVICE_ROLE_KEY (eseguirlo localmente o in CI; non eseguire mai il commit di una chiave service_role né esporla nel codice client).