Core Concepts — DBSpec

DBSpec is the single object that describes your database to vibecode‑db and its adapters. It bundles the generated schema and relations, plus optional seed and meta. Every environment receives the same DBSpec, so startup behavior is consistent across Web, Expo, and Supabase.

What DBSpec contains

• schema (required): the Zod bundle generated from your vibecode‑db schema DSL. Used for runtime validation and type inference.
• relations (required if you model FKs): relation graph inferred from your DSL. Enables nested reads and integrity hints.
• seed (optional): initial rows per table for demos, tests, or quick UIs.
• meta (optional): free‑form metadata for adapters (shape is adapter‑defined).

Minimal shape

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,
7  relations: db.relations,
8  // seed?: Record<string, unknown[]>
9  // meta?: Record<string, unknown>
10}

With seed data

1export const dbSpec: DBSpec<typeof db.zodBundle.shape> = {
2  schema: db.zodBundle,
3  relations: db.relations,
4  seed: {
5    users: [
6      { id: 1, name: 'Ada',  email: 'ada@example.com' },
7      { id: 2, name: 'Alan', email: 'alan@example.com' },
8    ],
9    todos: [
10      { id: 't1', title: 'Wire the UI', completed: false, user_id: 1, created_at: new Date(), updated_at: new Date() },
11    ],
12  },
13}

How adapters use DBSpec

• SQLite (Web/Expo): read schema/relations, run migrations you provide (DDL string[]), then serve queries locally (persistence depends on the adapter).
• Supabase: use the same client surface; credentials/options are adapter‑specific. DBSpec still provides validation/types and relation awareness.

Pattern

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

Tips

• Always include relations if you declare foreign keys; it’s future‑proof even when small.
• Keep seed small and deterministic; use it to showcase UI states.
• Treat meta as an escape hatch for adapter hints (e.g., region, logging).

Summary

DBSpec ties your schema outputs into a portable, adapter‑agnostic contract. Provide schema (+ relations when using FKs), add seed/meta if helpful, and pass it to createClient. One object, consistent behavior everywhere.