Configuration

Configure vibecode-db with a single truth source (dbSpec) and a per‑environment adapter factory. This page lays out what is required vs optional, then shows concise adapter wiring.

1) The essentials

1// db/spec.ts
2import type { DBSpec } from '@vibecode-db/client'
3import { db } from './schema' // built with defineSchema(...)
4
5export const dbSpec: DBSpec<typeof db.zodBundle.shape> = {
6  schema: db.zodBundle,    // REQUIRED
7  relations: db.relations, // REQUIRED if your schema declares FKs/relations
8  seed: {                  // OPTIONAL (handy for local/dev/demo)
9    users: [{ id: 1, name: 'Ada',  email: 'ada@example.com' }],
10    todos: [{ id: 't1', title: 'Wire the UI', completed: false, user_id: 1 }],
11  },
12  // meta: { /* OPTIONAL: adapter‑specific metadata you want to pass through */ }
13}

Use dbSpec with the adapter for your target runtime:

1createClient({
2  dbSpec,
3  adapter: (ctx) => new SomeAdapter(ctx, /* options */),
4})

2) Database options (required vs optional)

Option	Required	Description	Example
`schema`	✅	Zod bundle auto‑generated from the vibecode‑db schema DSL. Used for runtime validation + TS inference.	`db.zodBundle`
`relations`	✅	Relation graph inferred from your DSL. Required when you define FKs/relations (recommended by default).	`db.relations`
`seed`	◻️	Initial rows per table to bootstrap UI/dev. Consumed by adapters that support seeding.	`{ users: [...], todos: [...] }`
`meta`	◻️	Free‑form metadata for adapters; shape is adapter‑defined.	`{ region: "eu-west-1" }`

*If your schema has no relations at all, relations can be omitted — but keeping it is future‑proof and harmless.

3) Adapter options (concise)

Web — `@vibecode-db/sqlite-web`

1import { SQLiteAdapter } from '@vibecode-db/sqlite-web'
2
3adapter: (ctx) => new SQLiteAdapter(ctx, {
4  wasm: { wasmUrl: '/sql-wasm.wasm' }, // ensure this asset is served
5  migrations,                          // string[] of SQL statements
6  // persistence: 'opfs' | 'idb',      // optional persistence strategy
7})

Expo / React Native — `@vibecode-db/sqlite-expo`

1import { SQLiteAdapter } from '@vibecode-db/sqlite-expo'
2
3adapter: (ctx) => new SQLiteAdapter(ctx, {
4  native: { dbName: 'vibecode.db' },
5  migrations,                 // string[]
6  // enableForeignKeys: true, // optional
7})

Supabase — remote Postgres (same API surface)

1adapter: (ctx) => new SupabaseAdapter(ctx, {
2  url: process.env.NEXT_PUBLIC_SUPABASE_URL!,
3  key: process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY!,
4})

We intentionally don’t document sqlite-core here (tooling‑only).

4) Environment variables (Supabase example)

1# .env
2NEXT_PUBLIC_SUPABASE_URL=https://your-project.supabase.co
3NEXT_PUBLIC_SUPABASE_ANON_KEY=your-public-anon-key

5) Query execution order (important)

In v1.x, .select(...) executes the query. Chain filters/modifiers before .select(...) and use nested projections for relations.

1const rows = await db
2  .from('todos')
3  .where({ user_id: 1 })
4  .select('id, title, users(name)')

You’re configured

You now know the minimal contract: dbSpec (schema + relations [+ optional seed/meta]) + adapter options per environment. Continue to Defining Your Schema for modeling patterns, or jump to Adapters for runtime‑specific guidance (WASM assets, persistence, Expo notes).