// @ozaco/db

SQLite

A SQLite driver for the `DB` protocol, over `better-sqlite3` or `bun:sqlite`.

import from@ozaco/db/impl/sqlite

@ozaco/db/impl/sqlite provides SqliteDB, a concrete implementation of the DB protocol backed by a synchronous SQLite client. Install it with a SqliteConfig — a database URL and your SchemaDef — and the effect scope gains a QueryBuilder you reach with useDatabase().

On install the driver strips a leading file: from the URL, builds the Drizzle table objects from your schema, opens the connection, and runs applyMigrations against the sqlite dialect so tables and columns are created before the first query. The connection is torn down through the protocol’s close action.

The raw executor adapts to both better-sqlite3 and bun:sqlite: statements that return no rows (DDL, INSERT, transaction control) are routed through run while row-returning statements use all, so the same driver works across both runtimes. SQLite errors are classified into DbErrorCode tags.

// on this page

Plugin Configuration

Plugin

const

SqliteDB

The installable SQLite implementation of the `DB` protocol.

signature

const SqliteDB: Plugin<QueryBuilder, [SqliteConfig], DBActions>

// DBActions:
SqliteDB.actions.close(): Future<void>

Built from DB.implement({ name: 'sqlite', version: '0.0.1', setup }). Its context is the QueryBuilder; its setup argument is a SqliteConfig. Pass it to install from @ozaco/std/plugin, then run queries via the returned builder or useDatabase().

Migrations run automatically during setup, so no separate migrate step is needed for the additive changes applyMigrations supports.

example

import { defineSchema } from '@ozaco/db'
import { SqliteDB } from '@ozaco/db/impl/sqlite'
import { install } from '@ozaco/std/plugin'

function* main() {
  const db = yield* install(SqliteDB, {
    url: 'file:app.db',
    schema: defineSchema({ users }),
  })

  yield* db.insert(users).values({ email: 'a@b.co' }).execute()
  return yield* db.from(users).all()
}

Configuration

iface

SqliteConfig

Install options: a database URL and the schema to migrate against.

signature

interface SqliteConfig {
  readonly url: string
  readonly schema: SchemaDef
}

url accepts a file:-prefixed path or a bare path (the prefix is stripped); use :memory: for an in-memory database. schema is a SchemaDef from defineSchema — the driver builds its tables and runs migrations from it on install.

example

import { defineSchema } from '@ozaco/db'
import type { SqliteConfig } from '@ozaco/db/impl/sqlite'

const config: SqliteConfig = {
  url: 'file:app.db',
  schema: defineSchema({ users }),
}