Adapters — Overview

Adapters are how vibecode-db talks to storage backends using the same client API.
This page merges “Packages” and “Adapters” into one high-level overview focused on how to choose and wire adapters without duplicating package docs.

Execution rule: In v1.0, .select(projection) executes the query — chain filters/modifiers before calling it. Writes (insert, update, delete) execute immediately.

What an adapter does

An adapter is a small class you pass to createClient that receives your DBSpec and knows how to:

• Execute reads/writes for the fluent chain (from() … where() … select() / insert|update|delete).
• Validate payloads via the Zod bundle derived from your schema.
• Optionally bootstrap seed data (policy is adapter-specific).

DBSpec (inputs): schema (required), relations (recommended), optional seed, meta.

Where these live (one-line mapping)

• SQLite Web (WASM) → @vibecode-db/sqlite-web (depends on @vibecode-db/sqlite-core → @vibecode-db/client)
• SQLite Expo (React Native) → @vibecode-db/sqlite-expo (depends on @vibecode-db/sqlite-core → @vibecode-db/client)
• Supabase (Postgres over HTTP) → bundled adapter in @vibecode-db/client

No separate “packages” page needed — you install the adapter package that matches your runtime, then use the same client surface.

Quick wiring examples

SQLite Web (browser, WASM)

1import { createClient } from '@vibecode-db/client'
2import { SQLiteWebAdapter } from '@vibecode-db/sqlite-web'
3import { db } from './schema' // defineSchema(...)
4
5export const vibecode = createClient({
6  dbSpec: { schema: db.zodBundle, relations: db.relations },
7  adapter: (ctx) => new SQLiteWebAdapter(ctx, {
8    // Example options:
9    // wasm: { wasmUrl: '/sql-wasm.wasm' },
10  }),
11})

SQLite Expo (React Native)

1import { createClient } from '@vibecode-db/client'
2import { SQLiteExpoAdapter } from '@vibecode-db/sqlite-expo'
3import { db } from './schema'
4
5export const vibecode = createClient({
6  dbSpec: { schema: db.zodBundle, relations: db.relations },
7  adapter: (ctx) => new SQLiteExpoAdapter(ctx, {
8    dbName: 'vibecode.db',
9    resetOnStart: false, // persists by default with expo-sqlite; toggle for dev resets
10  }),
11})

Supabase (remote Postgres, RLS/auth)

1import { createClient } from '@vibecode-db/client'
2import { SupabaseAdapter } from '@vibecode-db/client/adapters/supabase'
3import { db } from './schema'
4
5export const vibecode = createClient({
6  dbSpec: { schema: db.zodBundle, relations: db.relations },
7  adapter: (ctx) => new SupabaseAdapter(ctx, {
8    url: process.env.NEXT_PUBLIC_SUPABASE_URL!,
9    key: process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY!,
10  }),
11})

When to use which

Seed & persistence (high level)

• Seed — optional dbSpec.seed can be applied by adapters (commonly “insert-if-empty” on first run).
• Persistence — Web (not supported), Expo (on-device by default; resetOnStart for dev), Supabase (remote/Postgres).

Summary

Choose where your data lives — Web, mobile, or cloud — by selecting a single adapter. Your queries and types stay the same, so you can move between local SQLite and Supabase without rewriting your front end.