Generate TypeScript types from your database
One command turns your tables into types. Your editor then rejects a wrong column or a wrong value before you run anything.
Generate the file#
npx @aurabase/gen --url https://my-app.aurabase.cloud --key "$AURABASE_SERVICE_ROLE_KEY" --out src/types/database.types.ts
Schema introspection (GET /v1/db/schema) requires a service_role key (AURABASE_SERVICE_ROLE_KEY); passing an anon key is rejected with an explicit message. Without --url and --key, @aurabase/gen reads NEXT_PUBLIC_AURABASE_URL and AURABASE_SERVICE_ROLE_KEY from your environment and .env, .env.local, .env.development (or a local schema snapshot with --from-file).
On a project with two tables and two functions, it prints:
[aurabase-gen] Types written to src/types/database.types.ts (2 table(s), 2 function(s), 0 enum(s), 0 view(s)).
Run it again whenever the schema changes (or pass --check in CI to fail on schema drift). Add --schema <name> for a schema other than public, --type-name to rename the main type, and --numeric-as-string to keep numeric/decimal as string instead of number.
Use it with the 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!)
The generated type describes each table with Row, Insert and Update. Against a real file, the compiler gave these results:
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 // error: string is not assignable to number
await aura.from('todos').insert({ title: 1 }) // error: number is not assignable to string
await aura.from('todos').insert({ title: 'ok' }) // ok: the other columns have defaults
In Insert, a column with a default or a nullable column is optional. In Update, every column is optional.
Row types for your components#
import type { Tables, TablesInsert, TablesUpdate, Enums } from '../types/database.types'
type Todo = Tables<'todos'> // a row, as read
type NewTodo = TablesInsert<'todos'> // what insert() accepts
type TodoPatch = TablesUpdate<'todos'> // what update() accepts
Enums<'name'> gives the values of a database enum.
What is checked#
- A table that is not in the generated file is not rejected:
aura.from('anything')still compiles, and its rows are untyped. - Functions appear under
Functionswith typed arguments and return values:add(a int, b int) returns intgivesArgs: { a: number; b: number }andReturns: number, and aRETURNS TABLE (content text, dist float8)function givesReturns: { content: string; dist: number }[]. A function that returns an anonymous composite type still shows asRecord<string, unknown>. - Filters,
insert()andupdate()payloads, enums and relationship embeds are checked. The column list inside theselect('a, b')string is used to type the result but a misspelled name there is only caught at run time (COLUMN_NOT_FOUND, with a « Perhaps you meant … » hint). - The Types button of Studio and
npx @aurabase/genproduce the same file. - The file reflects the schema at the time you generated it. A column added later is unknown to the types until you run the tool again.
- Schema introspection requires
AURABASE_SERVICE_ROLE_KEY(run it locally or in CI; never commit aservice_rolekey or expose it in client code).