bunderstack 0.1.0 → 0.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bunderstack",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Batteries-included backend framework for Bun: CRUD APIs, auth, file storage, realtime, tRPC, email, and validated env from a single Drizzle schema and config object.",
   "keywords": [
     "backend",
@@ -33,8 +33,11 @@
   "exports": {
     ".": "./src/index.ts",
     "./access": "./src/access.ts",
+    "./provision": "./src/provision.ts",
     "./schema": "./src/schema-export.ts",
+    "./schema/pg": "./src/schema-export-pg.ts",
     "./typeid": "./src/typeid.ts",
+    "./typeid/pg": "./src/typeid-pg.ts",
     "./env": "./src/env.ts",
     "./trpc": "./src/trpc.ts"
   },
@@ -45,25 +48,42 @@
     "db:migrate": "drizzle-kit migrate"
   },
   "dependencies": {
-    "@libsql/client": "^0.14.0",
     "@trpc/server": "^11.0.0",
     "better-auth": "^1.0.0",
-    "drizzle-orm": "^0.45.0",
     "hono": "^4.0.0",
     "superjson": "^2.2.0",
     "zod": "^4.4.3"
   },
+  "devDependencies": {
+    "@electric-sql/pglite": ">=0.3.0",
+    "@libsql/client": ">=0.14.0",
+    "drizzle-kit": "^0.30.0",
+    "drizzle-orm": "^0.45.0"
+  },
   "peerDependencies": {
+    "@electric-sql/pglite": ">=0.3.0",
+    "@libsql/client": ">=0.14.0",
     "drizzle-kit": "^0.30.0",
+    "drizzle-orm": "^0.45.0",
     "nodemailer": "^6",
+    "postgres": ">=3.4.0",
     "typescript": "^5"
   },
   "peerDependenciesMeta": {
+    "@electric-sql/pglite": {
+      "optional": true
+    },
+    "@libsql/client": {
+      "optional": true
+    },
     "drizzle-kit": {
       "optional": true
     },
     "nodemailer": {
       "optional": true
+    },
+    "postgres": {
+      "optional": true
     }
   }
 }

package/src/auth.ts

@@ -1,20 +1,18 @@
-import type { LibSQLDatabase } from 'drizzle-orm/libsql'
-
 // src/auth.ts
 import { betterAuth } from 'better-auth'
 import { drizzleAdapter } from 'better-auth/adapters/drizzle'
 
 import type { BetterAuthConfig } from './config'
 import type { AuthSessionResolver } from './access'
+import type { AnyDb, Dialect } from './dialect'
 import type { EmailFacade } from './email'
 
-export function createAuth(
-  db: LibSQLDatabase<Record<string, unknown>>,
-  cfg: BetterAuthConfig,
-) {
+export function createAuth(db: AnyDb, cfg: BetterAuthConfig, dialect: Dialect) {
   return betterAuth({
     ...cfg,
-    database: drizzleAdapter(db, { provider: 'sqlite' }),
+    database: drizzleAdapter(db as Parameters<typeof drizzleAdapter>[0], {
+      provider: dialect === 'pg' ? 'pg' : 'sqlite',
+    }),
   })
 }
 

package/src/config.ts

@@ -24,7 +24,11 @@ export const BunderstackOptionsSchema = z.object({
   schema: z.record(z.string(), z.unknown()),
   access: z.record(z.string(), z.any()).optional(),
   database: z
-    .object({ url: z.string().optional(), authToken: z.string().optional() })
+    .object({
+      url: z.string().optional(),
+      authToken: z.string().optional(),
+      migrations: z.string().optional(),
+    })
     .optional(),
   auth: z.record(z.string(), z.unknown()).optional(),
   // Loose: bucket access/scope hold functions that can't survive strict zod
@@ -99,7 +103,7 @@ export type BunderstackConfig<
 }
 
 export type ResolvedConfig = {
-  database: { url: string; authToken?: string }
+  database: { url: string; authToken?: string; migrations: string }
   auth: BetterAuthConfig
   storage: ResolvedStorageBuckets
   realtime?:
@@ -125,6 +129,7 @@ export function resolveConfig<TSchema extends Record<string, unknown>>(
     database: {
       url: parsed.database?.url ?? resolvedEnv.DATABASE_URL,
       authToken: parsed.database?.authToken ?? resolvedEnv.DATABASE_AUTH_TOKEN,
+      migrations: parsed.database?.migrations ?? './migrations',
     },
     auth: (() => {
       const authInput = options.auth ?? {}

package/src/crud.ts

@@ -1,8 +1,7 @@
-import type { LibSQLDatabase } from 'drizzle-orm/libsql'
-
 import { eq, getTableColumns, getTableName, isTable } from 'drizzle-orm'
 import { Hono } from 'hono'
 
+import type { AnyDb } from './dialect'
 import type { RealtimeBroker } from './realtime/index'
 
 import {
@@ -61,7 +60,7 @@ async function enforce(
 
 export function buildCrudRouter<TSchema extends Record<string, unknown>>(
   schema: TSchema,
-  db: LibSQLDatabase<TSchema>,
+  db: AnyDb,
   options: CrudRouterOptions,
 ): Hono {
   const router = new Hono()

package/src/db.ts

@@ -1,10 +1,103 @@
-import { createClient } from '@libsql/client'
-import { drizzle } from 'drizzle-orm/libsql'
+// src/db.ts — dialect/driver dispatch. Every driver module loads via dynamic
+// import so the driver packages stay optional peers; the ignore comments keep
+// bundlers (vite/nitro, webpack) from resolving them at build time.
+import type { LibSQLDatabase } from 'drizzle-orm/libsql'
+import type { PgDatabase, PgQueryResultHKT, PgTable } from 'drizzle-orm/pg-core'
 
-export function createDb<TSchema extends Record<string, unknown>>(
+import { mkdir } from 'node:fs/promises'
+
+import type { Dialect } from './dialect'
+
+export type Driver = 'libsql' | 'pglite' | 'bun-sql' | 'postgres-js'
+
+/** Per-dialect public db type, computed from the schema's table brands. */
+export type DbFor<TSchema extends Record<string, unknown>> = [
+  Extract<TSchema[keyof TSchema], PgTable>,
+] extends [never]
+  ? LibSQLDatabase<TSchema>
+  : PgDatabase<PgQueryResultHKT, TSchema>
+
+const PG_SERVER_RE = /^postgres(ql)?:\/\//
+const LIBSQL_REMOTE_RE = /^(libsql|wss?|https?):\/\//
+
+/** Exported for testing the missing-package error wrapping in isolation. */
+export async function importDriver<T>(specifier: string, hint: string): Promise<T> {
+  try {
+    return (await import(
+      /* @vite-ignore */ /* webpackIgnore: true */ specifier
+    )) as T
+  } catch (cause) {
+    throw new Error(`[bunderstack] ${hint}`, { cause })
+  }
+}
+
+export async function createDb<TSchema extends Record<string, unknown>>(
   schema: TSchema,
-  cfg: { url: string; authToken?: string },
-) {
-  const client = createClient({ url: cfg.url, authToken: cfg.authToken })
-  return drizzle(client, { schema })
+  cfg: { url: string; authToken?: string; dialect: Dialect },
+): Promise<{ db: DbFor<TSchema>; driver: Driver }> {
+  if (cfg.dialect === 'sqlite') {
+    if (PG_SERVER_RE.test(cfg.url)) {
+      throw new Error(
+        '[bunderstack] DATABASE_URL is a Postgres URL but the schema uses sqliteTable. ' +
+          'Define the schema with drizzle-orm/pg-core, or point DATABASE_URL at a SQLite database.',
+      )
+    }
+    const { drizzle } = await importDriver<typeof import('drizzle-orm/libsql')>(
+      'drizzle-orm/libsql',
+      'SQLite support requires @libsql/client, which is not installed.\n' +
+        '  Run `bun add @libsql/client`.',
+    )
+    const db = drizzle({
+      connection: { url: cfg.url, authToken: cfg.authToken },
+      schema,
+    })
+    return { db: db as unknown as DbFor<TSchema>, driver: 'libsql' }
+  }
+
+  if (LIBSQL_REMOTE_RE.test(cfg.url)) {
+    throw new Error(
+      '[bunderstack] DATABASE_URL looks like a libsql/Turso URL but the schema uses pgTable. ' +
+        'Set DATABASE_URL=postgres://… (or leave it unset for local PGlite).',
+    )
+  }
+
+  if (PG_SERVER_RE.test(cfg.url)) {
+    if (typeof Bun !== 'undefined') {
+      const { drizzle } = await import(
+        /* @vite-ignore */ /* webpackIgnore: true */ 'drizzle-orm/bun-sql'
+      )
+      return {
+        db: drizzle(cfg.url, { schema }) as unknown as DbFor<TSchema>,
+        driver: 'bun-sql',
+      }
+    }
+    const { drizzle } = await importDriver<
+      typeof import('drizzle-orm/postgres-js')
+    >(
+      'drizzle-orm/postgres-js',
+      'Postgres on Node requires the `postgres` driver, which is not installed.\n' +
+        '  Run `npm install postgres`. (Under Bun the built-in Bun.sql is used instead.)',
+    )
+    return {
+      db: drizzle(cfg.url, { schema }) as unknown as DbFor<TSchema>,
+      driver: 'postgres-js',
+    }
+  }
+
+  // Local PGlite: `file:<dir>`, a bare path, `:memory:`, or `memory://`.
+  const raw = cfg.url.startsWith('file:') ? cfg.url.slice('file:'.length) : cfg.url
+  const dataDir = raw === ':memory:' ? 'memory://' : raw
+  if (!dataDir.startsWith('memory://')) {
+    await mkdir(dataDir, { recursive: true })
+  }
+  const { drizzle } = await importDriver<typeof import('drizzle-orm/pglite')>(
+    'drizzle-orm/pglite',
+    'Local Postgres development requires PGlite, which is not installed.\n' +
+      '  Run `bun add -d @electric-sql/pglite` — bunderstack runs an embedded Postgres in ./data.pglite.\n' +
+      '  In production set DATABASE_URL=postgres://… (PGlite is not needed there).',
+  )
+  return {
+    db: drizzle(dataDir, { schema }) as unknown as DbFor<TSchema>,
+    driver: 'pglite',
+  }
 }

package/src/dialect.ts

@@ -0,0 +1,38 @@
+// src/dialect.ts — schema-driven dialect detection. Imports only dialect-core
+// drizzle entrypoints (no drivers), safe in every module graph.
+import { is } from 'drizzle-orm'
+import { PgTable } from 'drizzle-orm/pg-core'
+import { SQLiteTable } from 'drizzle-orm/sqlite-core'
+
+export type Dialect = 'sqlite' | 'pg'
+
+/**
+ * Minimal structural view of a drizzle db shared by both dialects. Internal
+ * modules run dynamic tables (Record<string, unknown> schemas) where drizzle's
+ * generics add no safety, so they accept this instead of a per-dialect union.
+ * The public surface (`app.db`, tRPC ctx) keeps full per-dialect typing via
+ * `DbFor` in db.ts.
+ */
+export type AnyDb = {
+  select: (...args: any[]) => any
+  insert: (...args: any[]) => any
+  update: (...args: any[]) => any
+  delete: (...args: any[]) => any
+}
+
+/** Classify a schema by its table brands. Mixed dialects are a config error. */
+export function detectDialect(schema: Record<string, unknown>): Dialect {
+  let pgKey: string | undefined
+  let sqliteKey: string | undefined
+  for (const [key, value] of Object.entries(schema)) {
+    if (is(value, PgTable)) pgKey ??= key
+    else if (is(value, SQLiteTable)) sqliteKey ??= key
+  }
+  if (pgKey !== undefined && sqliteKey !== undefined) {
+    throw new Error(
+      `[bunderstack] schema mixes dialects: "${pgKey}" is a Postgres table while "${sqliteKey}" is a SQLite table. ` +
+        'Define every table with the same dialect (drizzle-orm/pg-core or drizzle-orm/sqlite-core).',
+    )
+  }
+  return pgKey !== undefined ? 'pg' : 'sqlite'
+}

package/src/env.ts

@@ -49,6 +49,8 @@ export type ValidateEnvOptions = {
   emailProvider?: string
   /** Value source; defaults to process.env. Tests pass this explicitly. */
   source?: Record<string, string | undefined>
+  /** Dialect-aware DATABASE_URL fallback; createBunderstack passes it. */
+  defaultDatabaseUrl?: string
 }
 
 const DEV_AUTH_SECRET = 'dev-secret-change-in-prod'
@@ -96,7 +98,8 @@ export function validateEnv<TEnv extends EnvConfigInput | undefined>(
 
   const base: BaseEnv = {
     NODE_ENV: source.NODE_ENV,
-    DATABASE_URL: source.DATABASE_URL ?? 'file:./data.db',
+    DATABASE_URL:
+      source.DATABASE_URL ?? options.defaultDatabaseUrl ?? 'file:./data.db',
     DATABASE_AUTH_TOKEN: source.DATABASE_AUTH_TOKEN,
     AUTH_SECRET: source.AUTH_SECRET ?? DEV_AUTH_SECRET,
     REDIS_URL: source.REDIS_URL,

package/src/idempotency.ts

@@ -1,9 +1,9 @@
-import type { LibSQLDatabase } from 'drizzle-orm/libsql'
-
 import { and, eq, lt } from 'drizzle-orm'
 import { createHash } from 'node:crypto'
 
-import { bunderstackIdempotency } from './internal-tables'
+import type { AnyDb } from './dialect'
+
+import { idempotencyTableFor } from './internal-tables'
 
 export type IdempotencyConfig = {
   ttlMs?: number
@@ -21,34 +21,28 @@ export type IdempotencyLookup =
   | { type: 'proceed' }
 
 export async function lookupIdempotency(
-  db: LibSQLDatabase<Record<string, unknown>>,
+  db: AnyDb,
   tableName: string,
   key: string,
   body: string,
   config: IdempotencyConfig,
 ): Promise<IdempotencyLookup> {
+  const t = idempotencyTableFor(db)
   const now = Date.now()
 
   // TTL sweep: drop expired rows before reading.
-  await db
-    .delete(bunderstackIdempotency)
-    .where(lt(bunderstackIdempotency.expiresAt, now))
+  await db.delete(t).where(lt(t.expiresAt, now))
 
   const bodyHash = hashBody(body)
   const rows = await db
     .select({
-      bodyHash: bunderstackIdempotency.bodyHash,
-      status: bunderstackIdempotency.status,
-      response: bunderstackIdempotency.response,
-      expiresAt: bunderstackIdempotency.expiresAt,
+      bodyHash: t.bodyHash,
+      status: t.status,
+      response: t.response,
+      expiresAt: t.expiresAt,
     })
-    .from(bunderstackIdempotency)
-    .where(
-      and(
-        eq(bunderstackIdempotency.key, key),
-        eq(bunderstackIdempotency.tableName, tableName),
-      ),
-    )
+    .from(t)
+    .where(and(eq(t.key, key), eq(t.tableName, tableName)))
     .limit(1)
 
   const row = rows[0]
@@ -64,7 +58,7 @@ export async function lookupIdempotency(
 }
 
 export async function storeIdempotency(
-  db: LibSQLDatabase<Record<string, unknown>>,
+  db: AnyDb,
   tableName: string,
   key: string,
   body: string,
@@ -72,13 +66,14 @@ export async function storeIdempotency(
   response: unknown,
   config: IdempotencyConfig,
 ): Promise<void> {
+  const t = idempotencyTableFor(db)
   const ttlMs = config.ttlMs ?? DEFAULT_TTL_MS
   const expiresAt = Date.now() + ttlMs
   const bodyHash = hashBody(body)
   const responseText = JSON.stringify(response)
 
   await db
-    .insert(bunderstackIdempotency)
+    .insert(t)
     .values({
       key,
       tableName,
@@ -88,7 +83,7 @@ export async function storeIdempotency(
       expiresAt,
     })
     .onConflictDoUpdate({
-      target: [bunderstackIdempotency.key, bunderstackIdempotency.tableName],
+      target: [t.key, t.tableName],
       set: { bodyHash, status, response: responseText, expiresAt },
     })
 }

package/src/index.ts

@@ -1,18 +1,19 @@
 // src/index.ts
 import type { AnyRouter } from '@trpc/server'
-import type { LibSQLDatabase } from 'drizzle-orm/libsql'
 import type { Hono as HonoType } from 'hono'
 
 import { fetchRequestHandler } from '@trpc/server/adapters/fetch'
 
 import type { StorageAdapter } from './storage/index'
 import type { TableAccessInput } from './access'
+import type { DbFor } from './db'
 import type { StorageConfigInput } from './storage/buckets'
 
 import { resolveAccessUser, validateAndResolveAccess } from './access'
 import { createAuth, toAuthSessionResolver, withEmailAuthDefaults } from './auth'
 import { resolveConfig, type BunderstackConfig } from './config'
 import { resolveRealtimeRedisUrl } from './config'
+import { detectDialect } from './dialect'
 import { createEmail, emailProviderTag, type EmailFacade } from './email'
 import { validateEnv, type EnvConfigInput, type ValidatedEnv } from './env'
 import { createTRPC, type BunderstackTRPC } from './trpc'
@@ -20,7 +21,10 @@ import { buildCrudRouter } from './crud'
 import { createDb } from './db'
 import { buildHandler } from './handler'
 import { withInternalTables } from './internal-tables'
-import { provisionSchema } from './provision'
+import {
+  PROVISION_INTERNALS,
+  type WithProvisionInternals,
+} from './provision-internals'
 import { createRealtimeBroker, buildRealtimeRouter } from './realtime/index'
 import { createRedisRealtimeBroker } from './realtime/redis'
 import { deleteFileWithDerivatives } from './storage/delete'
@@ -70,7 +74,7 @@ export type BunderstackApp<
   TRouter = undefined,
 > = {
   handler: (req: Request) => Promise<Response>
-  db: LibSQLDatabase<TSchema>
+  db: DbFor<TSchema>
   auth: AuthInstance
   storage: StorageFacade
   router: HonoType
@@ -80,8 +84,6 @@ export type BunderstackApp<
   env: ValidatedEnv<TEnv>
   /** Email facade; always present — send() throws when email isn't configured. */
   email: EmailFacade
-  /** Push the merged schema (user + internal tables) to the database. */
-  provision: (options?: { force?: boolean }) => Promise<void>
   /**
    * Type-only carrier for client inference (`createClient<typeof app>()`).
    * Never assigned at runtime.
@@ -110,7 +112,7 @@ export function createBunderstack<
     /** Builder callback receiving the pre-wired `t` instance. */
     trpc: (t: BunderstackTRPC<TSchema, ValidatedEnv<TEnv>>) => TRouter
   },
-): BunderstackApp<TSchema, TAccess, BucketNamesOf<TStorage>, TEnv, TRouter>
+): Promise<BunderstackApp<TSchema, TAccess, BucketNamesOf<TStorage>, TEnv, TRouter>>
 export function createBunderstack<
   TSchema extends Record<string, unknown>,
   const TAccess extends Record<string, TableAccessInput> | undefined =
@@ -123,8 +125,8 @@ export function createBunderstack<
     /** Prebuilt tRPC router (escape hatch for multi-file setups). */
     trpc?: TRouter
   },
-): BunderstackApp<TSchema, TAccess, BucketNamesOf<TStorage>, TEnv, TRouter>
-export function createBunderstack<
+): Promise<BunderstackApp<TSchema, TAccess, BucketNamesOf<TStorage>, TEnv, TRouter>>
+export async function createBunderstack<
   TSchema extends Record<string, unknown>,
   const TAccess extends Record<string, TableAccessInput> | undefined =
     undefined,
@@ -136,17 +138,16 @@ export function createBunderstack<
       | AnyRouter
       | ((t: BunderstackTRPC<TSchema, ValidatedEnv<TEnv>>) => AnyRouter)
   },
-): BunderstackApp<
-  TSchema,
-  TAccess,
-  BucketNamesOf<TStorage>,
-  TEnv,
-  AnyRouter | undefined
+): Promise<
+  BunderstackApp<TSchema, TAccess, BucketNamesOf<TStorage>, TEnv, AnyRouter | undefined>
 > {
+  const dialect = detectDialect(options.schema)
   // Env is validated FIRST: the app refuses to boot on missing/invalid vars,
   // and everything downstream (config, email, trpc ctx) consumes the result.
   const env = validateEnv(options.env, {
     emailProvider: emailProviderTag(options.email),
+    defaultDatabaseUrl:
+      dialect === 'pg' ? 'file:./data.pglite' : 'file:./data.db',
   })
   const config = resolveConfig(options, env)
   const email = createEmail(options.email, { env })
@@ -154,17 +155,21 @@ export function createBunderstack<
   // schema used for the db client + provisioning. CRUD/access stay on the USER
   // schema so internal tables never get a CRUD route.
   const mergedSchema = withInternalTables(options.schema)
-  const db = createDb(mergedSchema, config.database)
+  const { db, driver } = await createDb(mergedSchema, {
+    ...config.database,
+    dialect,
+  })
   // `db` is typed with the merged schema (user tables + internal tables) so the
   // storage/idempotency code can query the internal tables. The public surface
-  // and CRUD only expose the USER schema. TS can widen `LibSQLDatabase<merged>`
-  // to `LibSQLDatabase<Record<string, unknown>>` on its own (storage/auth pass
-  // `db` directly), but it can't *narrow* a generic schema view, so this single
-  // intentional cast produces the user-facing db type. See `app.db` / crud below.
-  const userDb = db as unknown as LibSQLDatabase<TSchema>
+  // and CRUD only expose the USER schema. TS can widen the merged-schema db type
+  // on its own (storage/auth pass `db` directly), but it can't *narrow* a
+  // generic schema view, so this single intentional cast produces the
+  // user-facing, per-dialect db type. See `app.db` / crud below.
+  const userDb = db as unknown as DbFor<TSchema>
   const auth = createAuth(
     db,
     withEmailAuthDefaults(config.auth, email, Boolean(options.email)),
+    dialect,
   )
   // Internal routers consume the narrow AuthSessionResolver contract, not the
   // raw better-auth instance. app.auth still exposes `auth` unchanged.
@@ -297,11 +302,18 @@ export function createBunderstack<
     env,
     email,
     trpcRouter,
-    provision: (opts) =>
-      provisionSchema(db, mergedSchema, {
-        force: opts?.force,
-        databaseUrl: config.database.url,
-      }),
+  }
+
+  // Hidden handle for the optional `bunderstack/provision` entry. Kept off the
+  // public type so provisioning stays opt-in (and drizzle-kit out of this
+  // module graph).
+  ;(app as WithProvisionInternals)[PROVISION_INTERNALS] = {
+    db,
+    schema: mergedSchema,
+    databaseUrl: config.database.url,
+    migrationsFolder: config.database.migrations,
+    dialect,
+    driver,
   }
 
   return app
@@ -314,7 +326,6 @@ export type {
   BunderstackConfig,
   ResolvedConfig,
 } from './config'
-export { provisionSchema } from './provision'
 export { validateEnv, createClientEnv, BunderstackEnvError } from './env'
 export type { EnvConfigInput, BaseEnv, ValidatedEnv } from './env'
 export { createEmail } from './email'
@@ -353,16 +364,3 @@ export type {
 } from './storage/buckets'
 // StorageFacade is declared+exported inline above.
 export type { TransformSpec } from './storage/thumbnails'
-
-// Re-export drizzle builders so consumers share bunderstack's drizzle-orm instance
-// and avoid type incompatibilities from duplicate installs.
-export {
-  sqliteTable,
-  integer,
-  text,
-  real,
-  blob,
-  numeric,
-  foreignKey,
-} from 'drizzle-orm/sqlite-core'
-export { eq, and, or, not, gt, gte, lt, lte, desc, asc, sql } from 'drizzle-orm'

package/src/internal-tables-pg.ts

@@ -0,0 +1,45 @@
+// src/internal-tables-pg.ts — Postgres twins of the internal tables. Same
+// table/column names and row shapes as the sqlite originals; timestamps stay
+// integer milliseconds (bigint mode:number) so shared code never branches.
+import {
+  bigint,
+  index,
+  integer,
+  pgTable,
+  primaryKey,
+  text,
+} from 'drizzle-orm/pg-core'
+
+export const bunderstackFilesPg = pgTable(
+  'bunderstack_file_meta',
+  {
+    fileId: text('file_id').primaryKey(),
+    bucket: text('bucket').notNull(),
+    ownerId: text('owner_id'),
+    scopeJson: text('scope_json'),
+    status: text('status').notNull(),
+    filename: text('filename'),
+    contentType: text('content_type'),
+    size: bigint('size', { mode: 'number' }),
+    createdAt: bigint('created_at', { mode: 'number' }).notNull(),
+    confirmedAt: bigint('confirmed_at', { mode: 'number' }),
+  },
+  (t) => [
+    index('bfm_owner').on(t.ownerId),
+    index('bfm_scope').on(t.bucket, t.scopeJson),
+    index('bfm_sweep').on(t.status, t.createdAt),
+  ],
+)
+
+export const bunderstackIdempotencyPg = pgTable(
+  '_bunderstack_idempotency',
+  {
+    key: text('key').notNull(),
+    tableName: text('table_name').notNull(),
+    bodyHash: text('body_hash').notNull(),
+    status: integer('status').notNull(),
+    response: text('response').notNull(),
+    expiresAt: bigint('expires_at', { mode: 'number' }).notNull(),
+  },
+  (t) => [primaryKey({ columns: [t.key, t.tableName] })],
+)

package/src/internal-tables.ts

@@ -1,4 +1,5 @@
-import { getTableName, isTable } from 'drizzle-orm'
+import { getTableName, is, isTable } from 'drizzle-orm'
+import { PgDatabase } from 'drizzle-orm/pg-core'
 import {
   index,
   integer,
@@ -7,6 +8,12 @@ import {
   text,
 } from 'drizzle-orm/sqlite-core'
 
+import { detectDialect } from './dialect'
+import {
+  bunderstackFilesPg,
+  bunderstackIdempotencyPg,
+} from './internal-tables-pg'
+
 export const bunderstackFiles = sqliteTable(
   'bunderstack_file_meta',
   {
@@ -51,11 +58,30 @@ export const INTERNAL_TABLE_NAMES: ReadonlySet<string> = new Set([
   '_bunderstack_idempotency',
 ])
 
-const INTERNAL_TABLE_BY_NAME = new Map<string, (typeof INTERNAL_TABLES)[keyof typeof INTERNAL_TABLES]>([
-  [getTableName(bunderstackFiles), bunderstackFiles],
-  [getTableName(bunderstackIdempotency), bunderstackIdempotency],
+export const INTERNAL_TABLES_PG = {
+  bunderstackFiles: bunderstackFilesPg,
+  bunderstackIdempotency: bunderstackIdempotencyPg,
+} as const
+
+// Both dialect twins count as "ours" for the re-export identity check.
+const INTERNAL_TABLE_CANDIDATES = new Map<string, readonly unknown[]>([
+  [getTableName(bunderstackFiles), [bunderstackFiles, bunderstackFilesPg]],
+  [
+    getTableName(bunderstackIdempotency),
+    [bunderstackIdempotency, bunderstackIdempotencyPg],
+  ],
 ])
 
+/** Internal file-meta table matching the db's dialect. */
+export function filesTableFor(db: unknown) {
+  return is(db, PgDatabase) ? bunderstackFilesPg : bunderstackFiles
+}
+
+/** Internal idempotency table matching the db's dialect. */
+export function idempotencyTableFor(db: unknown) {
+  return is(db, PgDatabase) ? bunderstackIdempotencyPg : bunderstackIdempotency
+}
+
 export function withInternalTables<TSchema extends Record<string, unknown>>(
   schema: TSchema,
 ): TSchema & typeof INTERNAL_TABLES {
@@ -66,9 +92,9 @@ export function withInternalTables<TSchema extends Record<string, unknown>>(
     const name = getTableName(value)
     if (!INTERNAL_TABLE_NAMES.has(name)) continue
 
-    const internal = INTERNAL_TABLE_BY_NAME.get(name)
-    if (internal === value) {
-      // Re-exported from bunderstack/schema — already in user schema.
+    const candidates = INTERNAL_TABLE_CANDIDATES.get(name)
+    if (candidates?.includes(value)) {
+      // Re-exported from bunderstack/schema(-pg) — already in user schema.
       continue
     }
 
@@ -77,7 +103,9 @@ export function withInternalTables<TSchema extends Record<string, unknown>>(
     )
   }
 
-  for (const [key, table] of Object.entries(INTERNAL_TABLES)) {
+  const internal =
+    detectDialect(schema) === 'pg' ? INTERNAL_TABLES_PG : INTERNAL_TABLES
+  for (const [key, table] of Object.entries(internal)) {
     if (!(key in merged)) {
       ;(merged as Record<string, unknown>)[key] = table
     }

package/src/list-query.ts

@@ -1,5 +1,3 @@
-import type { LibSQLDatabase } from 'drizzle-orm/libsql'
-
 import {
   and,
   asc,
@@ -7,14 +5,18 @@ import {
   eq,
   getTableColumns,
   gt,
+  ilike,
   inArray,
+  is,
   like,
   lt,
   or,
   sql,
   type SQL,
 } from 'drizzle-orm'
+import { PgTable } from 'drizzle-orm/pg-core'
 
+import type { AnyDb } from './dialect'
 import type { ResolvedTableAccess, SortOrder } from './access'
 
 import { ErrorCode, ListQueryError } from './errors'
@@ -180,9 +182,12 @@ function buildSearchWhere(
   if (!q || !searchableColumns?.length) return undefined
   const columns = getTableColumns(table)
   const pattern = `%${q.replace(/[%_\\]/g, (ch) => `\\${ch}`)}%`
+  // LIKE is case-insensitive in SQLite but case-sensitive in Postgres; use
+  // ilike there so search behaves identically across dialects.
+  const likeOp = is(table, PgTable) ? ilike : like
   const conditions = searchableColumns
     .filter((name) => name in columns)
-    .map((name) => like(columns[name]!, pattern))
+    .map((name) => likeOp(columns[name]!, pattern))
   return conditions.length ? or(...conditions) : undefined
 }
 
@@ -325,7 +330,7 @@ function buildOrderBy(
 }
 
 export async function executeList<T extends Record<string, unknown>>(
-  db: LibSQLDatabase<Record<string, unknown>>,
+  db: AnyDb,
   table: Parameters<typeof getTableColumns>[0],
   access: ResolvedTableAccess,
   params: ParsedListParams,

package/src/provision-internals.ts

@@ -0,0 +1,28 @@
+// src/provision-internals.ts
+import type { AnyDb, Dialect } from './dialect'
+import type { Driver } from './db'
+
+/**
+ * Hidden handle connecting `createBunderstack()` to the optional
+ * `bunderstack/provision` entry. Lives in its own module so the main entry
+ * never imports provision code (and its drizzle-kit reference).
+ */
+export const PROVISION_INTERNALS: unique symbol = Symbol.for(
+  'bunderstack.provision-internals',
+)
+
+export interface ProvisionInternals {
+  /** Runtime db typed over the MERGED schema (user + internal tables). */
+  db: AnyDb
+  /** Merged schema used for push. */
+  schema: Record<string, unknown>
+  databaseUrl: string
+  /** Resolved migrations folder (config `database.migrations`). */
+  migrationsFolder: string
+  dialect: Dialect
+  driver: Driver
+}
+
+export interface WithProvisionInternals {
+  [PROVISION_INTERNALS]?: ProvisionInternals
+}

package/src/provision.ts

@@ -1,9 +1,25 @@
-import type { LibSQLDatabase } from 'drizzle-orm/libsql'
+// src/provision.ts
+import { access, mkdir } from 'node:fs/promises'
+import { dirname, join } from 'node:path'
 
-import { mkdir } from 'node:fs/promises'
-import { dirname } from 'node:path'
+import type { AnyDb, Dialect } from './dialect'
 
-async function ensureSqliteFileParent(url: string): Promise<void> {
+import { detectDialect } from './dialect'
+import {
+  PROVISION_INTERNALS,
+  type WithProvisionInternals,
+} from './provision-internals'
+
+/** Create the local backing directory for file-based urls, per dialect. */
+async function ensureLocalDataDir(url: string, dialect: Dialect): Promise<void> {
+  if (dialect === 'pg') {
+    // PGlite data dir: `file:<dir>` or a bare path; server/memory urls need nothing.
+    if (/^postgres(ql)?:\/\//.test(url)) return
+    const raw = url.startsWith('file:') ? url.slice('file:'.length) : url
+    if (raw === ':memory:' || raw.startsWith('memory://')) return
+    await mkdir(raw, { recursive: true })
+    return
+  }
   const match = /^file:(.+)$/.exec(url)
   if (!match) return
   const filePath = match[1]!
@@ -11,22 +27,50 @@ async function ensureSqliteFileParent(url: string): Promise<void> {
   await mkdir(dirname(filePath), { recursive: true })
 }
 
+async function exists(path: string): Promise<boolean> {
+  try {
+    await access(path)
+    return true
+  } catch {
+    return false
+  }
+}
+
+const DRIZZLE_KIT_HINT =
+  '[bunderstack] Schema push requires drizzle-kit, which is not installed.\n' +
+  '  Development: run `bun add -d drizzle-kit` — provision() will push schema changes to the database on startup.\n' +
+  '  Production: generate migrations locally with `bunx drizzle-kit generate` and commit the folder — provision() applies them without drizzle-kit.'
+
 /** Push the merged schema to the database via drizzle-kit/api. */
 export async function provisionSchema<TSchema extends Record<string, unknown>>(
-  db: LibSQLDatabase<TSchema>,
+  db: AnyDb,
   schema: TSchema,
   options?: { force?: boolean; databaseUrl?: string },
 ): Promise<void> {
+  const dialect = detectDialect(schema)
   if (options?.databaseUrl) {
-    await ensureSqliteFileParent(options.databaseUrl)
+    await ensureLocalDataDir(options.databaseUrl, dialect)
   }
 
-  const { pushSQLiteSchema } = await import('drizzle-kit/api')
-  const result = await pushSQLiteSchema(schema, db)
+  let kit: typeof import('drizzle-kit/api')
+  try {
+    // Ignore comments keep bundlers (vite/nitro, webpack) from resolving
+    // drizzle-kit at build time — this branch only runs in development.
+    kit = await import(
+      /* @vite-ignore */ /* webpackIgnore: true */ 'drizzle-kit/api'
+    )
+  } catch (cause) {
+    throw new Error(DRIZZLE_KIT_HINT, { cause })
+  }
+
+  const result =
+    dialect === 'pg'
+      ? await kit.pushSchema(schema, db as never)
+      : await kit.pushSQLiteSchema(schema, db as never)
 
   if (result.hasDataLoss && !options?.force) {
     throw new Error(
-      '[bunderstack] Schema push would cause data loss. Run `bunx drizzle-kit push` or call app.provision({ force: true }).',
+      '[bunderstack] Schema push would cause data loss. Run `bunx drizzle-kit push` or call provision(app, { force: true }).',
     )
   }
 
@@ -44,3 +88,50 @@ export async function provisionSchema<TSchema extends Record<string, unknown>>(
     `[bunderstack] provisioned ${result.statementsToExecute.length} schema change(s)`,
   )
 }
+
+const MIGRATOR_MODULES = {
+  libsql: 'drizzle-orm/libsql/migrator',
+  pglite: 'drizzle-orm/pglite/migrator',
+  'bun-sql': 'drizzle-orm/bun-sql/migrator',
+  'postgres-js': 'drizzle-orm/postgres-js/migrator',
+} as const
+
+/**
+ * Provision the database for a Bunderstack app.
+ *
+ * The migrations folder is the mode switch:
+ * - `<migrations>/meta/_journal.json` exists → apply committed migrations via
+ *   drizzle-orm's migrator. Pure runtime; drizzle-kit is never imported, so a
+ *   fresh clone deploys with `bun install --production`.
+ * - No migrations → development: push the schema straight to the database via
+ *   drizzle-kit (install it with `bun add -d drizzle-kit`).
+ *
+ * Once you run `bunx drizzle-kit generate` for the first time, provision stops
+ * pushing and every schema change goes through an explicit `generate`.
+ */
+export async function provision(
+  app: object,
+  options?: { force?: boolean },
+): Promise<void> {
+  const internals = (app as WithProvisionInternals)[PROVISION_INTERNALS]
+  if (!internals) {
+    throw new Error(
+      '[bunderstack] provision() expects the app returned by createBunderstack().',
+    )
+  }
+
+  const { db, schema, databaseUrl, migrationsFolder, dialect, driver } =
+    internals
+  const journal = join(migrationsFolder, 'meta', '_journal.json')
+
+  if (await exists(journal)) {
+    await ensureLocalDataDir(databaseUrl, dialect)
+    const { migrate } = (await import(
+      /* @vite-ignore */ /* webpackIgnore: true */ MIGRATOR_MODULES[driver]
+    )) as { migrate: (db: never, cfg: { migrationsFolder: string }) => Promise<void> }
+    await migrate(db as never, { migrationsFolder })
+    return
+  }
+
+  await provisionSchema(db, schema, { force: options?.force, databaseUrl })
+}

package/src/schema-export-pg.ts

@@ -0,0 +1,6 @@
+// src/schema-export-pg.ts — pg twins under the same names bunderstack/schema
+// uses, so `export * from 'bunderstack/schema/pg'` mirrors the sqlite setup.
+export {
+  bunderstackFilesPg as bunderstackFiles,
+  bunderstackIdempotencyPg as bunderstackIdempotency,
+} from './internal-tables-pg'

package/src/storage/delete.ts

@@ -1,6 +1,5 @@
 // src/storage/delete.ts
-import type { LibSQLDatabase } from 'drizzle-orm/libsql'
-
+import type { AnyDb } from '../dialect'
 import type { StorageAdapter } from './index'
 
 import { deleteFileMetaRow } from './file-meta'
@@ -14,7 +13,7 @@ import { deleteFileMetaRow } from './file-meta'
  */
 export async function deleteFileWithDerivatives(
   adapter: StorageAdapter,
-  db: LibSQLDatabase<Record<string, unknown>>,
+  db: AnyDb,
   fileId: string,
 ): Promise<void> {
   if (adapter.list) {

package/src/storage/file-meta.ts

@@ -27,21 +27,20 @@
  * See docs/plans/2026-06-28-multi-bucket-storage-design.md §6 for full rationale.
  */
 
-import type { LibSQLDatabase } from 'drizzle-orm/libsql'
-
 import { eq, and, lt, sql } from 'drizzle-orm'
 
+import type { AnyDb } from '../dialect'
 import type { ScopeMap } from '../access'
 
 import { rowMatchesScope } from '../access'
-import { bunderstackFiles } from '../internal-tables'
+import { bunderstackFiles, filesTableFor } from '../internal-tables'
 
 export type FileMetaRow = typeof bunderstackFiles.$inferSelect
 
 // ─── CRUD ─────────────────────────────────────────────────────────────────────
 
 export async function insertPendingFile(
-  db: LibSQLDatabase<Record<string, unknown>>,
+  db: AnyDb,
   input: {
     fileId: string
     bucket: string
@@ -51,7 +50,8 @@ export async function insertPendingFile(
     contentType: string | null
   },
 ): Promise<void> {
-  await db.insert(bunderstackFiles).values({
+  const files = filesTableFor(db)
+  await db.insert(files).values({
     fileId: input.fileId,
     bucket: input.bucket,
     ownerId: input.ownerId,
@@ -66,7 +66,7 @@ export async function insertPendingFile(
 }
 
 export async function insertReadyFile(
-  db: LibSQLDatabase<Record<string, unknown>>,
+  db: AnyDb,
   input: {
     fileId: string
     bucket: string
@@ -77,8 +77,9 @@ export async function insertReadyFile(
     size: number | null
   },
 ): Promise<void> {
+  const files = filesTableFor(db)
   const now = Date.now()
-  await db.insert(bunderstackFiles).values({
+  await db.insert(files).values({
     fileId: input.fileId,
     bucket: input.bucket,
     ownerId: input.ownerId,
@@ -93,79 +94,76 @@ export async function insertReadyFile(
 }
 
 export async function markFileReady(
-  db: LibSQLDatabase<Record<string, unknown>>,
+  db: AnyDb,
   fileId: string,
   patch: { size: number | null; contentType: string | null },
 ): Promise<void> {
+  const files = filesTableFor(db)
   await db
-    .update(bunderstackFiles)
+    .update(files)
     .set({
       status: 'ready',
       confirmedAt: Date.now(),
       size: patch.size,
       contentType: patch.contentType,
     })
-    .where(eq(bunderstackFiles.fileId, fileId))
+    .where(eq(files.fileId, fileId))
 }
 
 export async function getFileMeta(
-  db: LibSQLDatabase<Record<string, unknown>>,
+  db: AnyDb,
   fileId: string,
 ): Promise<FileMetaRow | null> {
+  const files = filesTableFor(db)
   const rows = await db
     .select()
-    .from(bunderstackFiles)
-    .where(eq(bunderstackFiles.fileId, fileId))
+    .from(files)
+    .where(eq(files.fileId, fileId))
     .limit(1)
-  return rows[0] ?? null
+  return (rows[0] as FileMetaRow | undefined) ?? null
 }
 
 export async function deleteFileMetaRow(
-  db: LibSQLDatabase<Record<string, unknown>>,
+  db: AnyDb,
   fileId: string,
 ): Promise<void> {
-  await db.delete(bunderstackFiles).where(eq(bunderstackFiles.fileId, fileId))
+  const files = filesTableFor(db)
+  await db.delete(files).where(eq(files.fileId, fileId))
 }
 
 // ─── Sweep ────────────────────────────────────────────────────────────────────
 
 export async function listStalePendingFiles(
-  db: LibSQLDatabase<Record<string, unknown>>,
+  db: AnyDb,
   olderThanMs: number,
 ): Promise<FileMetaRow[]> {
+  const files = filesTableFor(db)
   return db
     .select()
-    .from(bunderstackFiles)
-    .where(
-      and(
-        eq(bunderstackFiles.status, 'pending'),
-        lt(bunderstackFiles.createdAt, olderThanMs),
-      ),
-    )
+    .from(files)
+    .where(and(eq(files.status, 'pending'), lt(files.createdAt, olderThanMs)))
 }
 
 // ─── Quota ────────────────────────────────────────────────────────────────────
 
 export async function sumReadySize(
-  db: LibSQLDatabase<Record<string, unknown>>,
+  db: AnyDb,
   q: { bucket: string; ownerId?: string; scopeJson?: string },
 ): Promise<number> {
-  const conditions = [
-    eq(bunderstackFiles.status, 'ready'),
-    eq(bunderstackFiles.bucket, q.bucket),
-  ]
+  const files = filesTableFor(db)
+  const conditions = [eq(files.status, 'ready'), eq(files.bucket, q.bucket)]
   if (q.ownerId !== undefined) {
-    conditions.push(eq(bunderstackFiles.ownerId, q.ownerId))
+    conditions.push(eq(files.ownerId, q.ownerId))
   }
   if (q.scopeJson !== undefined) {
-    conditions.push(eq(bunderstackFiles.scopeJson, q.scopeJson))
+    conditions.push(eq(files.scopeJson, q.scopeJson))
   }
 
   const rows = await db
     .select({
-      total: sql<number>`coalesce(sum(${bunderstackFiles.size}), 0)`,
+      total: sql<number>`coalesce(sum(${files.size}), 0)`,
     })
-    .from(bunderstackFiles)
+    .from(files)
     .where(and(...conditions))
 
   const raw = rows[0]?.total ?? 0

package/src/storage/router.ts

@@ -1,4 +1,3 @@
-import type { LibSQLDatabase } from 'drizzle-orm/libsql'
 // src/storage/router.ts
 import type { Context } from 'hono'
 
@@ -11,6 +10,7 @@ import type {
   AuthSessionResolver,
   OperationRule,
 } from '../access'
+import type { AnyDb } from '../dialect'
 import type { BucketStorageRegistry } from './registry'
 
 import { checkAccess, resolveSession } from '../access'
@@ -35,7 +35,7 @@ import {
 
 export interface BucketStorageRouterOptions {
   registry: BucketStorageRegistry
-  db: LibSQLDatabase<Record<string, unknown>>
+  db: AnyDb
   auth: AuthSessionResolver | undefined
   /** Default presign TTL (seconds) for PUT/GET URLs. */
   presignExpiresSec?: number
@@ -511,7 +511,7 @@ export function buildBucketStorageRouter(
  * dimension (perUser uses ownerId; perScope uses scopeJson).
  */
 async function quotaExceeded(
-  db: LibSQLDatabase<Record<string, unknown>>,
+  db: AnyDb,
   bucket: string,
   quota: { perUserBytes?: number; perScopeBytes?: number },
   ownerId: string | undefined,

package/src/storage/sweep.ts

@@ -1,6 +1,5 @@
 // src/storage/sweep.ts
-import type { LibSQLDatabase } from 'drizzle-orm/libsql'
-
+import type { AnyDb } from '../dialect'
 import type { BucketStorageRegistry } from './registry'
 
 import { deleteFileMetaRow, listStalePendingFiles } from './file-meta'
@@ -12,7 +11,7 @@ import { deleteFileMetaRow, listStalePendingFiles } from './file-meta'
  */
 export async function sweepOrphans(
   registry: BucketStorageRegistry,
-  db: LibSQLDatabase<Record<string, unknown>>,
+  db: AnyDb,
   olderThanMs: number,
 ): Promise<number> {
   const cutoff = Date.now() - olderThanMs

package/src/trpc.ts

@@ -1,17 +1,16 @@
 // src/trpc.ts — pre-wired tRPC instance for bunderstack endpoints.
-import type { LibSQLDatabase } from 'drizzle-orm/libsql'
-
 import { initTRPC, TRPCError } from '@trpc/server'
 import superjson from 'superjson'
 
 import type { AccessUser } from './access'
+import type { DbFor } from './db'
 import type { EmailFacade } from './email'
 
 export type TRPCContext<
   TSchema extends Record<string, unknown>,
   TEnvResult = Record<string, unknown>,
 > = {
-  db: LibSQLDatabase<TSchema>
+  db: DbFor<TSchema>
   user: AccessUser | null
   env: TEnvResult
   email: EmailFacade

package/src/typeid-pg.ts

@@ -0,0 +1,24 @@
+// src/typeid-pg.ts — Postgres twin of the typeid column builder. The codec
+// (generate/parse/encode/decode) is dialect-neutral and lives in ./typeid;
+// only the drizzle customType wrapper differs.
+import { customType } from 'drizzle-orm/pg-core'
+
+import { isValidPrefix, type TypeId } from './typeid'
+
+/**
+ * Drizzle column builder for a branded TypeID text value (Postgres). Stores a
+ * plain `text` column so drizzle-kit migrations and `$inferSelect` work
+ * unchanged.
+ *
+ *   id: typeid('post').primaryKey().$defaultFn(() => generate('post'))
+ */
+export function typeid<P extends string>(prefix: P) {
+  if (!isValidPrefix(prefix))
+    throw new Error(`Invalid typeid prefix: "${prefix}"`)
+  return customType<{ data: TypeId<P>; driverData: string }>({
+    dataType: () => 'text',
+  })()
+}
+
+export { generate, parse, asTypeId, encode, decode } from './typeid'
+export type { TypeId } from './typeid'