Générez des types TypeScript à partir de votre base de données
Une commande transforme vos tables en types. Votre éditeur rejette alors une mauvaise colonne ou une mauvaise valeur avant d'exécuter quoi que ce soit.
Générer le fichier#
npx @aurabase/gen --url https://my-app.aurabase.cloud --key "$AURABASE_SERVICE_ROLE_KEY" --out src/types/database.types.ts
L'introspection de schéma (GET /v1/db/schema) nécessite une clé service_role (AURABASE_SERVICE_ROLE_KEY) ; le passage d'une clé anon est rejeté avec un message explicite. Sans --url et --key, @aurabase/gen lit NEXT_PUBLIC_AURABASE_URL et AURABASE_SERVICE_ROLE_KEY à partir de votre environnement et .env, .env.local, .env.development (ou un instantané de schéma local avec --from-file).
Sur un projet avec deux tables et deux fonctions, il imprime :
[aurabase-gen] Types written to src/types/database.types.ts (2 table(s), 2 function(s), 0 enum(s), 0 view(s)).
Réexécutez-le chaque fois que le schéma change (ou transmettez --check dans CI pour échouer en cas de dérive du schéma). Ajoutez --schema <name> pour un schéma autre que public, --type-name pour renommer le type principal et --numeric-as-string pour conserver numeric/decimal comme string au lieu de number.
Utilisez-le avec le client#
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!)
Le type généré décrit chaque table avec Row, Insert et Update. Sur un fichier réel, le compilateur a donné ces résultats :
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 // erreur : la chaîne n'est pas attribuable au numéro
await aura.from('todos').insert({ title: 1 }) // erreur : le numéro ne peut pas être attribué à la chaîne
await aura.from('todos').insert({ title: 'ok' }) // ok : les autres colonnes ont des valeurs par défaut
Dans Insert, une colonne avec une colonne par défaut ou nullable est facultative. Dans Update, chaque colonne est facultative.
Types de lignes pour vos composants#
import type { Tables, TablesInsert, TablesUpdate, Enums } from '../types/database.types'
type Todo = Tables<'todos'> // une ligne, comme lu
type NewTodo = TablesInsert<'todos'> // ce que insert() accepte
type TodoPatch = TablesUpdate<'todos'> // ce que update() accepte
Enums<'name'> donne les valeurs d'une énumération de base de données.
Ce qui est vérifié#
- Une table qui ne figure pas dans le fichier généré est et non rejetée :
aura.from('anything')est toujours compilée et ses lignes ne sont pas typées. - Les fonctions apparaissent sous
Functionsavec des arguments et des valeurs de retour typés :add(a int, b int) returns intdonneArgs: { a: number; b: number }etReturns: number, et une fonctionRETURNS TABLE (content text, dist float8)donneReturns: { content: string; dist: number }[]. Une fonction qui renvoie un type composite anonyme reste typéeRecord<string, unknown>. - Les filtres, les charges de
insert()etupdate(), les enums et les jointures imbriquées sont vérifiés. La liste de colonnes dans la chaîneselect('a, b')sert à typer le résultat, mais un nom mal orthographié n'y est détecté qu'à l'exécution (COLUMN_NOT_FOUND, avec un indice « Perhaps you meant … »). - Le bouton Types du Studio et
npx @aurabase/genproduisent le même fichier. - Le fichier reflète le schéma au moment où vous l'avez généré. Une colonne ajoutée ultérieurement est inconnue des types jusqu'à ce que vous exécutiez à nouveau l'outil.
- L'introspection de schéma nécessite
AURABASE_SERVICE_ROLE_KEY(exécutez-la localement ou dans CI ; ne validez jamais une cléservice_roleet ne l'exposez jamais dans le code client).