Core Concepts — Adapters

Adapters bind the same vibecode‑db query API to different runtimes (Web WASM, Expo/React Native, Supabase). You keep one schema, one DBSpec, and one fluent query surface—only the adapter wiring changes.

What an adapter does

• Initializes storage/runtime for the target environment.
• Reads your DBSpec (schema + relations [+ optional seed, meta]).
• Prepares tables (SQLite) via your migrations array (string[] of SQL).
• Executes queries while preserving types and Zod validation from the schema.

We don’t document internal cores here. Focus on your adapter choice and its options.

The contract

• You provide dbSpec and an adapter factory:
  createClient({ dbSpec, adapter: (ctx) => new Adapter(ctx, options) })
• The query builder is identical across adapters.
  Chain filters/modifiers first, then call .select(...) to execute.
  Use nested projection strings for relations (e.g., 'id, title, users(name)').

1// environment file (pattern only)
2export const db = createClient({
3  dbSpec,
4  adapter: (ctx) => new Adapter(ctx, { /* runtime-specific options */ }),
5})

Picking an adapter

• Web (SQLite, WASM): runs entirely in the browser; can persist via OPFS/IndexedDB.
• Expo / React Native (SQLite): runs on-device; persists by default; optional resetOnStart.
• Supabase (bundled in @vibecode-db/client): remote Postgres with RLS/auth; same API surface.

Each environment gets its own guide with exact options. This page stays conceptual.

Migration & seeding

• SQLite adapters expect a migrations string[] (DDL) on startup.
• Seeding is optional boot data per table—handy for demos/tests.

Where to next

For concrete wiring and options, see the dedicated Adapters section:

• Supabase — credentials/env, RLS/auth notes
• SQLite — Web (WASM asset & persistence) and Expo (on-device persistence, dbName, resetOnStart)

One schema, one fluent API—swap adapters to change where your data lives.