@mark1russell7/docker-sqlite 0.1.0 → 0.2.0

package/README.md

@@ -1,1057 +1,1089 @@
-# @mark1russell7/docker-sqlite
-
-[![npm version](https://img.shields.io/npm/v/@mark1russell7/docker-sqlite.svg)](https://www.npmjs.com/package/@mark1russell7/docker-sqlite)
-[![License: MIT](https://img.shields.io/npm/l/@mark1russell7/docker-sqlite.svg)](./LICENSE)
-[![Node.js](https://img.shields.io/badge/Node.js-%3E%3D22-green.svg)](https://nodejs.org/)
-[![Part of client](https://img.shields.io/badge/part%20of-client-1f3fbf)](https://mark1russell7.github.io/client/)
-
-> Reusable SQLite setup with TypeScript utilities for connection management, queries, and migrations using sql.js (SQLite compiled to WASM).
-
-```bash
-npm install @mark1russell7/docker-sqlite
-```
-
-```typescript
-import { withConnection, execute, query } from "@mark1russell7/docker-sqlite";
-
-const rows = await withConnection({ dbPath: "./data/app.db" }, (db) => {
-  execute(db, "CREATE TABLE IF NOT EXISTS notes (id INTEGER PRIMARY KEY, text TEXT)");
-  execute(db, "INSERT INTO notes (text) VALUES (?)", ["hello"]);
-  return query(db, "SELECT text FROM notes").rows;
-});
-console.log(rows); // [{ text: "hello" }] (one more row on each run)
-```
-
-The file is saved only when the database changed, and calls for one file run one at a time. The package is the database layer of `db.*` and `logs.*` in the [client monorepo](https://github.com/mark1russell7/client) (see [the client site](https://mark1russell7.github.io/client/)).
-
-## Overview
-
-`@mark1russell7/docker-sqlite` provides a complete SQLite development environment with:
-
-- **Portable SQLite via WASM** - Uses sql.js for cross-platform compatibility without native dependencies
-- **Type-safe utilities** - Connection management, query execution, and migration system with full TypeScript support
-- **Auto-save functionality** - Changes automatically persisted to file with managed connections
-- **Migration system** - Version-controlled schema migrations with up/down support
-- **Docker integration** - Optional web UI for database browsing via docker-compose
-- **Zero native dependencies** - Works in Node.js, browsers, and edge environments
-
-## Table of Contents
-
-- [Architecture](#architecture)
-- [Installation](#installation)
-- [Docker Setup](#docker-setup)
-- [TypeScript API](#typescript-api)
-- [Migration System](#migration-system)
-- [Configuration](#configuration)
-- [Integration](#integration)
-- [Examples](#examples)
-- [API Reference](#api-reference)
-
-## Architecture
-
-```mermaid
-graph TB
-    subgraph "Application Layer"
-        A[Your Application]
-    end
-
-    subgraph "docker-sqlite Library"
-        B[Connection Manager]
-        C[Query Utilities]
-        D[Migration System]
-
-        B --> C
-        B --> D
-    end
-
-    subgraph "SQLite Engine"
-        E[sql.js<br/>WASM]
-    end
-
-    subgraph "Storage"
-        F[(File System<br/>*.db files)]
-        G[(In-Memory)]
-    end
-
-    subgraph "Docker Environment (Optional)"
-        H[sqlite-web Container<br/>Web UI]
-        I[Volume: ./data]
-    end
-
-    A --> B
-    B --> E
-    E --> F
-    E --> G
-    H --> I
-    I -.-> F
-
-    style A fill:#3178c6,color:#fff
-    style B fill:#3178c6,color:#fff
-    style E fill:#003b57,color:#fff
-    style H fill:#0db7ed,color:#fff
-```
-
-### Library Architecture
-
-```
-┌─────────────────────────────────────────────────────────────┐
-│  Application                                                │
-│  ┌───────────────────────────────────────────────────────┐  │
-│  │  await withConnection({ dbPath: './app.db' }, (db) => │  │
-│  │    runMigrations(db, migrations);                     │  │
-│  │    execute(db, 'INSERT INTO users ...');              │  │
-│  │    const { rows } = query(db, 'SELECT * FROM users'); │  │
-│  │  });                                                   │  │
-│  └───────────────────────────────────────────────────────┘  │
-└────────────────────────┬────────────────────────────────────┘
-                         │
-                         ▼
-┌─────────────────────────────────────────────────────────────┐
-│  @mark1russell7/docker-sqlite                               │
-├─────────────────────────────────────────────────────────────┤
-│                                                             │
-│  ┌────────────────────────────────────────────────────┐    │
-│  │  Connection (connect.ts)                           │    │
-│  │  ┌──────────────────────────────────────────────┐  │    │
-│  │  │  withConnection(config, callback)            │  │    │
-│  │  │  ├─ Load db file (or create in-memory)      │  │    │
-│  │  │  ├─ Execute callback with db instance       │  │    │
-│  │  │  └─ Auto-save and close on completion       │  │    │
-│  │  │                                              │  │    │
-│  │  │  createConnection(config)                    │  │    │
-│  │  │  └─ Manual connection management             │  │    │
-│  │  └──────────────────────────────────────────────┘  │    │
-│  └────────────────────────────────────────────────────┘    │
-│                                                             │
-│  ┌────────────────────────────────────────────────────┐    │
-│  │  Query (query.ts)                                  │    │
-│  │  ┌──────────────────────────────────────────────┐  │    │
-│  │  │  query(db, sql, params?)                     │  │    │
-│  │  │  └─ Execute SELECT, return {rows, columns}  │  │    │
-│  │  │                                              │  │    │
-│  │  │  execute(db, sql, params?)                   │  │    │
-│  │  │  └─ Execute INSERT/UPDATE/DELETE            │  │    │
-│  │  │                                              │  │    │
-│  │  │  execMultiple(db, statements)                │  │    │
-│  │  │  └─ Execute multiple statements              │  │    │
-│  │  │                                              │  │    │
-│  │  │  tableExists(db, tableName)                  │  │    │
-│  │  │  lastInsertRowId(db)                         │  │    │
-│  │  └──────────────────────────────────────────────┘  │    │
-│  └────────────────────────────────────────────────────┘    │
-│                                                             │
-│  ┌────────────────────────────────────────────────────┐    │
-│  │  Migration (migrate.ts)                            │    │
-│  │  ┌──────────────────────────────────────────────┐  │    │
-│  │  │  runMigrations(db, migrations)               │  │    │
-│  │  │  └─ Apply pending migrations in order        │  │    │
-│  │  │                                              │  │    │
-│  │  │  rollbackMigration(db, migrations)           │  │    │
-│  │  │  └─ Rollback last migration                  │  │    │
-│  │  │                                              │  │    │
-│  │  │  getMigrationStatus(db, migrations)          │  │    │
-│  │  │  └─ Get current version and status           │  │    │
-│  │  │                                              │  │    │
-│  │  │  createMigration(...)                        │  │    │
-│  │  │  └─ Helper to create migration objects       │  │    │
-│  │  └──────────────────────────────────────────────┘  │    │
-│  └────────────────────────────────────────────────────┘    │
-│                                                             │
-└────────────────────────┬────────────────────────────────────┘
-                         │
-                         ▼
-                  ┌─────────────────┐
-                  │    sql.js       │
-                  │ (SQLite in WASM)│
-                  └────────┬────────┘
-                           │
-                ┌──────────┴──────────┐
-                ▼                     ▼
-         ┌─────────────┐      ┌─────────────┐
-         │ File System │      │  In-Memory  │
-         │   *.db      │      │   Database  │
-         └─────────────┘      └─────────────┘
-```
-
-### Data Flow Diagram
-
-```mermaid
-sequenceDiagram
-    participant App as Application
-    participant Lib as docker-sqlite
-    participant SQL as sql.js (WASM)
-    participant FS as File System
-
-    App->>Lib: withConnection({ dbPath: './app.db' }, callback)
-    Lib->>FS: Read database file
-    alt File exists
-        FS-->>Lib: File buffer
-    else File doesn't exist
-        FS-->>Lib: ENOENT error
-        Note over Lib: Create new database
-    end
-
-    Lib->>SQL: new Database(buffer)
-    SQL-->>Lib: Database instance
-
-    Lib->>App: callback(db)
-
-    App->>Lib: execute(db, 'INSERT ...')
-    Lib->>SQL: db.run(sql, params)
-    SQL-->>Lib: Success
-
-    App->>Lib: query(db, 'SELECT ...')
-    Lib->>SQL: db.prepare(sql).step()
-    SQL-->>Lib: Result rows
-    Lib-->>App: { rows, columns }
-
-    App-->>Lib: callback complete
-
-    Lib->>SQL: db.export()
-    SQL-->>Lib: Binary data
-    Lib->>FS: Write database file
-    FS-->>Lib: Success
-
-    Lib->>SQL: db.close()
-    Lib-->>App: Return callback result
-```
-
-## Installation
-
-```bash
-npm install @mark1russell7/docker-sqlite
-```
-
-### Requirements
-
-- **Node.js**: >= 22
-- **Docker** (optional): For web UI to browse database
-- **Docker Compose** (optional): For orchestration
-
-## Docker Setup
-
-The package includes an optional Docker Compose configuration that provides a web-based SQLite browser.
-
-### Quick Start
-
-```bash
-# Start SQLite Web UI
-docker compose up -d
-
-# Open http://localhost:8080 to browse your database
-
-# Stop container
-docker compose down
-```
-
-### Environment Variables
-
-Configure the SQLite web viewer using environment variables:
-
-| Variable | Default | Description |
-|----------|---------|-------------|
-| `SQLITE_CONTAINER_NAME` | `sqlite-web` | Name of the Docker container |
-| `SQLITE_PORT` | `8080` | Host port for web UI |
-| `SQLITE_DB_PATH` | `./data` | Path to database directory on host |
-| `SQLITE_DB_NAME` | `cli.db` | Database filename to open |
-
-#### Example: Custom Configuration
-
-Create a `.env` file:
-
-```env
-SQLITE_CONTAINER_NAME=myapp-sqlite-ui
-SQLITE_PORT=8090
-SQLITE_DB_PATH=./database
-SQLITE_DB_NAME=myapp.db
-```
-
-Then run:
-
-```bash
-docker compose up -d
-```
-
-### Container Features
-
-- **Web-based UI**: Browse and query SQLite databases via browser
-- **Auto-restart**: Container restarts unless explicitly stopped
-- **Volume mounting**: Live view of database changes
-- **Health checks**: Monitors UI availability every 30s
-- **Read-write mode**: Can modify database through UI
-
-### Web UI Usage
-
-Once running, navigate to `http://localhost:8080` to:
-
-- Browse tables and schema
-- Execute SQL queries
-- View indexes and constraints
-- Export data as CSV/JSON
-- Modify records directly
-
-## TypeScript API
-
-### Connection Management
-
-#### `withConnection<T>(config, callback): Promise<T>`
-
-Execute a callback with an auto-managed SQLite connection. The database is automatically loaded, saved, and closed.
-
-```typescript
-import { withConnection, query, execute } from '@mark1russell7/docker-sqlite';
-
-const users = await withConnection(
-  { dbPath: './data/app.db' },
-  (db) => {
-    execute(db, 'INSERT INTO users (name) VALUES (?)', ['Alice']);
-    return query(db, 'SELECT * FROM users');
-  }
-);
-
-console.log(users.rows);
-```
-
-**Parameters:**
-- `config.dbPath`: Path to database file (use `':memory:'` for in-memory database)
-- `callback`: Function receiving `Database` instance
-
-**Returns:** Result of the callback function
-
-**Behavior:**
-- Saves the database after the callback completes, only when its content changed. A read does not write the file, so a read-only file can be read, and a read cannot write an old copy over the changes of another process.
-- Makes the database file only when the callback changes the database. A query of a missing file does not make an empty file.
-- Calls for one file run one at a time in this process. On Windows, two spellings of one path (case) share one queue.
-- Closes database connection in finally block
-- Creates parent directories as needed
-
----
-
-#### `createConnection(config): Promise<{db, save}>`
-
-Create a manually-managed connection. Caller must handle saving and closing.
-
-```typescript
-import { createConnection, execute } from '@mark1russell7/docker-sqlite';
-
-const { db, save } = await createConnection({ dbPath: './data/app.db' });
-
-try {
-  execute(db, 'INSERT INTO logs (message) VALUES (?)', ['Started']);
-  await save(); // Explicitly save changes
-} finally {
-  db.close();
-}
-```
-
-### Query Operations
-
-#### `query<T>(db, sql, params?): QueryResult<T>`
-
-Execute a SELECT query and return typed results.
-
-```typescript
-import { query } from '@mark1russell7/docker-sqlite';
-
-interface User {
-  id: number;
-  name: string;
-  email: string;
-}
-
-const result = query<User>(
-  db,
-  'SELECT * FROM users WHERE age > ?',
-  [21]
-);
-
-console.log(result.columns); // ['id', 'name', 'email']
-console.log(result.rows);    // Array of User objects
-```
-
-**Parameters:**
-- `db`: Database instance
-- `sql`: SQL SELECT statement
-- `params?`: Optional parameter values
-
-**Returns:**
-```typescript
-{
-  columns: string[];  // Column names
-  rows: T[];          // Result rows as typed objects
-}
-```
-
----
-
-#### `execute(db, sql, params?): ExecuteResult`
-
-Execute an INSERT, UPDATE, or DELETE statement.
-
-```typescript
-import { execute, lastInsertRowId } from '@mark1russell7/docker-sqlite';
-
-const result = execute(
-  db,
-  'INSERT INTO users (name, email) VALUES (?, ?)',
-  ['Bob', 'bob@example.com']
-);
-
-console.log(result.changes);     // 1
-console.log(lastInsertRowId(db)); // New row ID
-```
-
-SQL with several statements runs completely when there are no parameters, and `changes` counts the rows of all statements. With parameters, several statements are an error: parameters bind to one statement.
-
-**Returns:**
-```typescript
-{
-  changes: number;  // Number of rows affected
-}
-```
-
----
-
-#### `execMultiple(db, sql): void`
-
-Execute multiple SQL statements at once. Useful for schema setup and batch operations.
-
-```typescript
-import { execMultiple } from '@mark1russell7/docker-sqlite';
-
-execMultiple(db, `
-  CREATE TABLE IF NOT EXISTS users (
-    id INTEGER PRIMARY KEY AUTOINCREMENT,
-    name TEXT NOT NULL,
-    email TEXT UNIQUE
-  );
-
-  CREATE INDEX IF NOT EXISTS idx_users_email ON users(email);
-
-  CREATE TABLE IF NOT EXISTS posts (
-    id INTEGER PRIMARY KEY,
-    user_id INTEGER,
-    title TEXT,
-    FOREIGN KEY (user_id) REFERENCES users(id)
-  );
-`);
-```
-
----
-
-#### `tableExists(db, tableName): boolean`
-
-Check if a table exists in the database.
-
-```typescript
-import { tableExists } from '@mark1russell7/docker-sqlite';
-
-if (!tableExists(db, 'users')) {
-  execute(db, 'CREATE TABLE users (id INTEGER PRIMARY KEY, name TEXT)');
-}
-```
-
----
-
-#### `lastInsertRowId(db): number`
-
-Get the row ID of the last inserted row.
-
-```typescript
-import { execute, lastInsertRowId } from '@mark1russell7/docker-sqlite';
-
-execute(db, 'INSERT INTO users (name) VALUES (?)', ['Alice']);
-const userId = lastInsertRowId(db);
-console.log(`Created user with ID: ${userId}`);
-```
-
-## Migration System
-
-The package includes a complete migration system for versioned schema management.
-
-### Migration Structure
-
-```typescript
-interface Migration {
-  version: number;        // Unique version number (sequential)
-  description: string;    // Human-readable description
-  up: string;            // SQL to apply migration
-  down?: string;         // SQL to rollback migration (optional)
-}
-```
-
-### `runMigrations(db, migrations): Migration[]`
-
-Apply all pending migrations in order.
-
-```typescript
-import { withConnection, runMigrations } from '@mark1russell7/docker-sqlite';
-
-const migrations = [
-  {
-    version: 1,
-    description: 'Create users table',
-    up: `
-      CREATE TABLE users (
-        id INTEGER PRIMARY KEY AUTOINCREMENT,
-        name TEXT NOT NULL,
-        email TEXT UNIQUE
-      )
-    `,
-    down: 'DROP TABLE users'
-  },
-  {
-    version: 2,
-    description: 'Add created_at column',
-    up: 'ALTER TABLE users ADD COLUMN created_at TEXT DEFAULT CURRENT_TIMESTAMP',
-    down: 'ALTER TABLE users DROP COLUMN created_at'
-  },
-  {
-    version: 3,
-    description: 'Create posts table',
-    up: `
-      CREATE TABLE posts (
-        id INTEGER PRIMARY KEY,
-        user_id INTEGER,
-        title TEXT NOT NULL,
-        content TEXT,
-        FOREIGN KEY (user_id) REFERENCES users(id)
-      )
-    `
-  }
-];
-
-await withConnection({ dbPath: './data/app.db' }, (db) => {
-  const applied = runMigrations(db, migrations);
-  console.log(`Applied ${applied.length} migrations`);
-  applied.forEach(m => console.log(`  ✓ ${m.description}`));
-});
-```
-
-**Behavior:**
-- Creates `_migrations` table automatically to track applied migrations
-- Applies only pending migrations in version order
-- Records each migration with timestamp
-- Skips already-applied migrations
-- Throws error if migration fails (doesn't continue)
-
-**Returns:** Array of applied migrations
-
----
-
-### `getMigrationStatus(db, migrations): MigrationStatus`
-
-Get the current migration status.
-
-```typescript
-import { getMigrationStatus } from '@mark1russell7/docker-sqlite';
-
-const status = getMigrationStatus(db, migrations);
-
-console.log(`Current version: ${status.currentVersion}`);
-console.log(`Applied migrations: ${status.appliedMigrations.join(', ')}`);
-console.log(`Pending migrations: ${status.pendingMigrations.length}`);
-
-status.pendingMigrations.forEach(m => {
-  console.log(`  - v${m.version}: ${m.description}`);
-});
-```
-
-**Returns:**
-```typescript
-{
-  currentVersion: number;           // Latest applied version (0 if none)
-  appliedMigrations: number[];      // Array of applied version numbers
-  pendingMigrations: Migration[];   // Migrations not yet applied
-}
-```
-
----
-
-### `rollbackMigration(db, migrations): Migration | null`
-
-Rollback the last applied migration.
-
-```typescript
-import { rollbackMigration } from '@mark1russell7/docker-sqlite';
-
-const rolled = rollbackMigration(db, migrations);
-
-if (rolled) {
-  console.log(`Rolled back: v${rolled.version} - ${rolled.description}`);
-} else {
-  console.log('No migrations to rollback');
-}
-```
-
-**Requirements:**
-- Migration must have a `down` script
-- Migration must be the current version
-
-**Returns:** The rolled-back migration, or `null` if none
-
----
-
-### `createMigration(version, description, up, down?): Migration`
-
-Helper function to create a migration object.
-
-```typescript
-import { createMigration } from '@mark1russell7/docker-sqlite';
-
-const migration = createMigration(
-  1,
-  'Initial schema',
-  'CREATE TABLE users (id INTEGER PRIMARY KEY)',
-  'DROP TABLE users'
-);
-```
-
-## Configuration
-
-### Database Paths
-
-```typescript
-// In-memory database (no persistence)
-await withConnection({ dbPath: ':memory:' }, (db) => {
-  // Data is lost after connection closes
-});
-
-// Relative path
-await withConnection({ dbPath: './data/app.db' }, (db) => {
-  // Saved to ./data/app.db
-});
-
-// Absolute path
-await withConnection({ dbPath: '/var/lib/myapp/app.db' }, (db) => {
-  // Saved to /var/lib/myapp/app.db
-});
-
-// Default (in-memory)
-await withConnection({}, (db) => {
-  // No persistence
-});
-```
-
-### Common Patterns
-
-#### CLI Logging Database
-
-The package includes a reference schema for CLI logging in `schema/logs.sql`:
-
-```typescript
-import { withConnection, execMultiple } from '@mark1russell7/docker-sqlite';
-import { readFile } from 'node:fs/promises';
-
-const schema = await readFile('./node_modules/@mark1russell7/docker-sqlite/schema/logs.sql', 'utf-8');
-
-await withConnection({ dbPath: './cli-logs.db' }, (db) => {
-  execMultiple(db, schema);
-
-  execute(db, `
-    INSERT INTO logs (level, message, command, session_id)
-    VALUES (?, ?, ?, ?)
-  `, ['info', 'Command started', 'lib.refresh', sessionId]);
-});
-```
-
-#### Testing Pattern
-
-```typescript
-import { describe, it } from 'node:test';
-import assert from 'node:assert';
-import { withConnection, query, execute } from '@mark1russell7/docker-sqlite';
-
-describe('User repository', () => {
-  it('should create and retrieve user', async () => {
-    await withConnection({ dbPath: ':memory:' }, (db) => {
-      // Setup schema
-      execute(db, 'CREATE TABLE users (id INTEGER PRIMARY KEY, name TEXT)');
-
-      // Test
-      execute(db, 'INSERT INTO users (name) VALUES (?)', ['Alice']);
-      const result = query(db, 'SELECT * FROM users WHERE name = ?', ['Alice']);
-
-      assert.strictEqual(result.rows.length, 1);
-      assert.strictEqual(result.rows[0].name, 'Alice');
-    });
-  });
-});
-```
-
-#### Migration-based Setup
-
-```typescript
-import { withConnection, runMigrations, getMigrationStatus } from '@mark1russell7/docker-sqlite';
-
-const migrations = [
-  {
-    version: 1,
-    description: 'Initial schema',
-    up: `
-      CREATE TABLE users (id INTEGER PRIMARY KEY, name TEXT);
-      CREATE TABLE posts (id INTEGER PRIMARY KEY, user_id INTEGER);
-    `
-  }
-];
-
-async function initDatabase(dbPath: string) {
-  await withConnection({ dbPath }, (db) => {
-    const status = getMigrationStatus(db, migrations);
-
-    if (status.pendingMigrations.length > 0) {
-      console.log(`Applying ${status.pendingMigrations.length} migration(s)...`);
-      runMigrations(db, migrations);
-      console.log('Database up to date!');
-    } else {
-      console.log(`Database already at version ${status.currentVersion}`);
-    }
-  });
-}
-
-await initDatabase('./data/app.db');
-```
-
-## Integration
-
-### Environment Configuration
-
-Create a `.env` file for your application:
-
-```env
-# SQLite database path
-SQLITE_DB_PATH=./data/app.db
-
-# Docker Web UI settings (optional)
-SQLITE_CONTAINER_NAME=myapp-sqlite-ui
-SQLITE_PORT=8080
-```
-
-Load in your application:
-
-```typescript
-import 'dotenv/config';
-import { withConnection } from '@mark1russell7/docker-sqlite';
-
-const dbPath = process.env.SQLITE_DB_PATH || './app.db';
-
-await withConnection({ dbPath }, (db) => {
-  // Your database operations
-});
-```
-
-### npm Scripts
-
-Add to your `package.json`:
-
-```json
-{
-  "scripts": {
-    "db:ui": "docker compose -f node_modules/@mark1russell7/docker-sqlite/docker-compose.yml up -d",
-    "db:ui:stop": "docker compose -f node_modules/@mark1russell7/docker-sqlite/docker-compose.yml down",
-    "db:migrate": "tsx scripts/migrate.ts",
-    "db:rollback": "tsx scripts/rollback.ts"
-  }
-}
-```
-
-### Ecosystem Integration
-
-This package integrates with the broader Mark Russell ecosystem:
-
-- **@mark1russell7/cue**: TypeScript configuration inheritance
-- **client-sqlite**: MCP client procedures for SQLite operations
-- **bundle-dev**: Development bundle including database tooling
-
-## Examples
-
-### Complete Application with Migrations
-
-```typescript
-import { withConnection, runMigrations, query, execute } from '@mark1russell7/docker-sqlite';
-
-// Define schema migrations
-const migrations = [
-  {
-    version: 1,
-    description: 'Create users table',
-    up: `
-      CREATE TABLE users (
-        id INTEGER PRIMARY KEY AUTOINCREMENT,
-        username TEXT UNIQUE NOT NULL,
-        email TEXT UNIQUE NOT NULL,
-        created_at TEXT DEFAULT CURRENT_TIMESTAMP
-      );
-      CREATE INDEX idx_users_email ON users(email);
-    `,
-    down: 'DROP TABLE users'
-  },
-  {
-    version: 2,
-    description: 'Create posts table',
-    up: `
-      CREATE TABLE posts (
-        id INTEGER PRIMARY KEY AUTOINCREMENT,
-        user_id INTEGER NOT NULL,
-        title TEXT NOT NULL,
-        content TEXT,
-        created_at TEXT DEFAULT CURRENT_TIMESTAMP,
-        FOREIGN KEY (user_id) REFERENCES users(id) ON DELETE CASCADE
-      );
-      CREATE INDEX idx_posts_user ON posts(user_id);
-    `,
-    down: 'DROP TABLE posts'
-  }
-];
-
-// Application setup
-async function setupDatabase(dbPath: string) {
-  await withConnection({ dbPath }, (db) => {
-    // Apply migrations
-    const applied = runMigrations(db, migrations);
-    if (applied.length > 0) {
-      console.log(`Applied ${applied.length} migration(s)`);
-    }
-  });
-}
-
-// User operations
-interface User {
-  id: number;
-  username: string;
-  email: string;
-  created_at: string;
-}
-
-async function createUser(dbPath: string, username: string, email: string): Promise<number> {
-  return withConnection({ dbPath }, (db) => {
-    execute(db, 'INSERT INTO users (username, email) VALUES (?, ?)', [username, email]);
-    return lastInsertRowId(db);
-  });
-}
-
-async function getUsers(dbPath: string): Promise<User[]> {
-  return withConnection({ dbPath }, (db) => {
-    const result = query<User>(db, 'SELECT * FROM users ORDER BY created_at DESC');
-    return result.rows;
-  });
-}
-
-// Usage
-const dbPath = './data/myapp.db';
-
-await setupDatabase(dbPath);
-const userId = await createUser(dbPath, 'alice', 'alice@example.com');
-const users = await getUsers(dbPath);
-
-console.log(`Created user ID: ${userId}`);
-console.log(`Total users: ${users.length}`);
-```
-
-### Transaction Pattern (Manual Connection)
-
-```typescript
-import { createConnection, execute } from '@mark1russell7/docker-sqlite';
-
-async function transferCredits(fromUserId: number, toUserId: number, amount: number) {
-  const { db, save } = await createConnection({ dbPath: './data/app.db' });
-
-  try {
-    // Start transaction
-    execute(db, 'BEGIN TRANSACTION');
-
-    // Deduct from sender
-    execute(db, 'UPDATE users SET credits = credits - ? WHERE id = ?', [amount, fromUserId]);
-
-    // Check sender balance
-    const result = query(db, 'SELECT credits FROM users WHERE id = ?', [fromUserId]);
-    if (result.rows[0].credits < 0) {
-      throw new Error('Insufficient credits');
-    }
-
-    // Add to receiver
-    execute(db, 'UPDATE users SET credits = credits + ? WHERE id = ?', [amount, toUserId]);
-
-    // Commit
-    execute(db, 'COMMIT');
-    await save();
-
-    console.log(`Transferred ${amount} credits from user ${fromUserId} to ${toUserId}`);
-  } catch (error) {
-    // Rollback on error
-    execute(db, 'ROLLBACK');
-    throw error;
-  } finally {
-    db.close();
-  }
-}
-```
-
-### Query Builder Pattern
-
-```typescript
-import { withConnection, query } from '@mark1russell7/docker-sqlite';
-
-interface QueryBuilder {
-  select(columns: string[]): this;
-  from(table: string): this;
-  where(condition: string, params: unknown[]): this;
-  orderBy(column: string, direction?: 'ASC' | 'DESC'): this;
-  limit(limit: number): this;
-  execute<T>(): QueryResult<T>;
-}
-
-class SQLiteQueryBuilder implements QueryBuilder {
-  private parts: {
-    select: string[];
-    from: string;
-    where: { condition: string; params: unknown[] }[];
-    orderBy?: string;
-    limit?: number;
-  } = { select: ['*'], from: '', where: [] };
-
-  constructor(private db: Database) {}
-
-  select(columns: string[]): this {
-    this.parts.select = columns;
-    return this;
-  }
-
-  from(table: string): this {
-    this.parts.from = table;
-    return this;
-  }
-
-  where(condition: string, params: unknown[]): this {
-    this.parts.where.push({ condition, params });
-    return this;
-  }
-
-  orderBy(column: string, direction: 'ASC' | 'DESC' = 'ASC'): this {
-    this.parts.orderBy = `${column} ${direction}`;
-    return this;
-  }
-
-  limit(limit: number): this {
-    this.parts.limit = limit;
-    return this;
-  }
-
-  execute<T>(): QueryResult<T> {
-    let sql = `SELECT ${this.parts.select.join(', ')} FROM ${this.parts.from}`;
-    const params: unknown[] = [];
-
-    if (this.parts.where.length > 0) {
-      sql += ' WHERE ' + this.parts.where.map(w => w.condition).join(' AND ');
-      this.parts.where.forEach(w => params.push(...w.params));
-    }
-
-    if (this.parts.orderBy) {
-      sql += ` ORDER BY ${this.parts.orderBy}`;
-    }
-
-    if (this.parts.limit) {
-      sql += ` LIMIT ${this.parts.limit}`;
-    }
-
-    return query<T>(this.db, sql, params);
-  }
-}
-
-// Usage
-await withConnection({ dbPath: './data/app.db' }, (db) => {
-  const builder = new SQLiteQueryBuilder(db);
-
-  const result = builder
-    .select(['id', 'username', 'email'])
-    .from('users')
-    .where('created_at > ?', ['2024-01-01'])
-    .where('email LIKE ?', ['%@example.com'])
-    .orderBy('created_at', 'DESC')
-    .limit(10)
-    .execute<User>();
-
-  console.log(result.rows);
-});
-```
-
-## API Reference
-
-### Types
-
-```typescript
-interface ConnectionConfig {
-  dbPath: string;  // Path to database file, or ':memory:' for in-memory
-}
-
-type ConnectionCallback<T> = (db: Database) => T | Promise<T>;
-
-interface QueryResult<T = Record<string, unknown>> {
-  columns: string[];  // Column names
-  rows: T[];          // Result rows as typed objects
-}
-
-interface ExecuteResult {
-  changes: number;  // Number of rows affected
-}
-
-interface Migration {
-  version: number;        // Unique version number (sequential)
-  description: string;    // Human-readable description
-  up: string;            // SQL to apply migration
-  down?: string;         // SQL to rollback migration (optional)
-}
-
-interface MigrationStatus {
-  currentVersion: number;           // Latest applied version (0 if none)
-  appliedMigrations: number[];      // Array of applied version numbers
-  pendingMigrations: Migration[];   // Migrations not yet applied
-}
-```
-
-### Functions
-
-All functions are fully documented with JSDoc and include TypeScript type definitions. Import from the package root:
-
-```typescript
-import {
-  // Connection
-  withConnection,
-  createConnection,
-
-  // Query
-  query,
-  execute,
-  execMultiple,
-  tableExists,
-  lastInsertRowId,
-
-  // Migration
-  runMigrations,
-  rollbackMigration,
-  getMigrationStatus,
-  createMigration,
-
-  // Types
-  type ConnectionConfig,
-  type QueryResult,
-  type Migration,
-  type MigrationStatus,
-  type Database,
-  // ... etc
-} from '@mark1russell7/docker-sqlite';
-```
-
-## License
-
-MIT
-
-## Contributing
-
-Issues and pull requests are welcome at the package repository.
-
-## Related Packages
-
-- [@mark1russell7/docker-mongo](../mongo) - MongoDB Docker setup with similar API
-- [@mark1russell7/cue](https://github.com/mark1russell7/cue) - Shared TypeScript configuration
-- [sql.js](https://github.com/sql-js/sql.js) - SQLite compiled to JavaScript/WASM
+# @mark1russell7/docker-sqlite
+
+[![npm version](https://img.shields.io/npm/v/@mark1russell7/docker-sqlite.svg)](https://www.npmjs.com/package/@mark1russell7/docker-sqlite)
+[![License: MIT](https://img.shields.io/npm/l/@mark1russell7/docker-sqlite.svg)](./LICENSE)
+[![Node.js](https://img.shields.io/badge/Node.js-%3E%3D22-green.svg)](https://nodejs.org/)
+[![Part of client](https://img.shields.io/badge/part%20of-client-1f3fbf)](https://mark1russell7.github.io/client/)
+
+> Reusable SQLite setup with TypeScript utilities for connection management, queries, and migrations using sql.js (SQLite compiled to WASM).
+
+```bash
+npm install @mark1russell7/docker-sqlite
+```
+
+```typescript
+import { withConnection, execute, query } from "@mark1russell7/docker-sqlite";
+
+const rows = await withConnection({ dbPath: "./data/app.db" }, (db) => {
+  execute(db, "CREATE TABLE IF NOT EXISTS notes (id INTEGER PRIMARY KEY, text TEXT)");
+  execute(db, "INSERT INTO notes (text) VALUES (?)", ["hello"]);
+  return query(db, "SELECT text FROM notes").rows;
+});
+console.log(rows); // [{ text: "hello" }] (one more row on each run)
+```
+
+The file is saved only when the database changed, and calls for one file run one at a time. The package is the database layer of `db.*` and `logs.*` in the [client monorepo](https://github.com/mark1russell7/client) (see [the client site](https://mark1russell7.github.io/client/)).
+
+## Overview
+
+`@mark1russell7/docker-sqlite` provides a complete SQLite development environment with:
+
+- **Portable SQLite via WASM** - Uses sql.js for cross-platform compatibility without native dependencies
+- **Type-safe utilities** - Connection management, query execution, and migration system with full TypeScript support
+- **Auto-save functionality** - Changes automatically persisted to file with managed connections
+- **Migration system** - Version-controlled schema migrations with up/down support
+- **Docker integration** - Optional web UI for database browsing via docker-compose
+- **Zero native dependencies** - Works in Node.js, browsers, and edge environments
+
+## Table of Contents
+
+- [Architecture](#architecture)
+- [Installation](#installation)
+- [Docker Setup](#docker-setup)
+- [TypeScript API](#typescript-api)
+- [Migration System](#migration-system)
+- [Configuration](#configuration)
+- [Integration](#integration)
+- [Examples](#examples)
+- [API Reference](#api-reference)
+
+## Architecture
+
+```mermaid
+graph TB
+    subgraph "Application Layer"
+        A[Your Application]
+    end
+
+    subgraph "docker-sqlite Library"
+        B[Connection Manager]
+        C[Query Utilities]
+        D[Migration System]
+
+        B --> C
+        B --> D
+    end
+
+    subgraph "SQLite Engine"
+        E[sql.js<br/>WASM]
+    end
+
+    subgraph "Storage"
+        F[(File System<br/>*.db files)]
+        G[(In-Memory)]
+    end
+
+    subgraph "Docker Environment (Optional)"
+        H[sqlite-web Container<br/>Web UI]
+        I[Volume: ./data]
+    end
+
+    A --> B
+    B --> E
+    E --> F
+    E --> G
+    H --> I
+    I -.-> F
+
+    style A fill:#3178c6,color:#fff
+    style B fill:#3178c6,color:#fff
+    style E fill:#003b57,color:#fff
+    style H fill:#0db7ed,color:#fff
+```
+
+### Library Architecture
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│  Application                                                │
+│  ┌───────────────────────────────────────────────────────┐  │
+│  │  await withConnection({ dbPath: './app.db' }, (db) => │  │
+│  │    runMigrations(db, migrations);                     │  │
+│  │    execute(db, 'INSERT INTO users ...');              │  │
+│  │    const { rows } = query(db, 'SELECT * FROM users'); │  │
+│  │  });                                                   │  │
+│  └───────────────────────────────────────────────────────┘  │
+└────────────────────────┬────────────────────────────────────┘
+                         │
+                         ▼
+┌─────────────────────────────────────────────────────────────┐
+│  @mark1russell7/docker-sqlite                               │
+├─────────────────────────────────────────────────────────────┤
+│                                                             │
+│  ┌────────────────────────────────────────────────────┐    │
+│  │  Connection (connect.ts)                           │    │
+│  │  ┌──────────────────────────────────────────────┐  │    │
+│  │  │  withConnection(config, callback)            │  │    │
+│  │  │  ├─ Load db file (or create in-memory)      │  │    │
+│  │  │  ├─ Execute callback with db instance       │  │    │
+│  │  │  └─ Auto-save and close on completion       │  │    │
+│  │  │                                              │  │    │
+│  │  │  createConnection(config)                    │  │    │
+│  │  │  └─ Manual connection management             │  │    │
+│  │  └──────────────────────────────────────────────┘  │    │
+│  └────────────────────────────────────────────────────┘    │
+│                                                             │
+│  ┌────────────────────────────────────────────────────┐    │
+│  │  Query (query.ts)                                  │    │
+│  │  ┌──────────────────────────────────────────────┐  │    │
+│  │  │  query(db, sql, params?)                     │  │    │
+│  │  │  └─ Execute SELECT, return {rows, columns}  │  │    │
+│  │  │                                              │  │    │
+│  │  │  execute(db, sql, params?)                   │  │    │
+│  │  │  └─ Execute INSERT/UPDATE/DELETE            │  │    │
+│  │  │                                              │  │    │
+│  │  │  execMultiple(db, statements)                │  │    │
+│  │  │  └─ Execute multiple statements              │  │    │
+│  │  │                                              │  │    │
+│  │  │  tableExists(db, tableName)                  │  │    │
+│  │  │  lastInsertRowId(db)                         │  │    │
+│  │  └──────────────────────────────────────────────┘  │    │
+│  └────────────────────────────────────────────────────┘    │
+│                                                             │
+│  ┌────────────────────────────────────────────────────┐    │
+│  │  Migration (migrate.ts)                            │    │
+│  │  ┌──────────────────────────────────────────────┐  │    │
+│  │  │  runMigrations(db, migrations)               │  │    │
+│  │  │  └─ Apply pending migrations in order        │  │    │
+│  │  │                                              │  │    │
+│  │  │  rollbackMigration(db, migrations)           │  │    │
+│  │  │  └─ Rollback last migration                  │  │    │
+│  │  │                                              │  │    │
+│  │  │  getMigrationStatus(db, migrations)          │  │    │
+│  │  │  └─ Get current version and status           │  │    │
+│  │  │                                              │  │    │
+│  │  │  createMigration(...)                        │  │    │
+│  │  │  └─ Helper to create migration objects       │  │    │
+│  │  └──────────────────────────────────────────────┘  │    │
+│  └────────────────────────────────────────────────────┘    │
+│                                                             │
+└────────────────────────┬────────────────────────────────────┘
+                         │
+                         ▼
+                  ┌─────────────────┐
+                  │    sql.js       │
+                  │ (SQLite in WASM)│
+                  └────────┬────────┘
+                           │
+                ┌──────────┴──────────┐
+                ▼                     ▼
+         ┌─────────────┐      ┌─────────────┐
+         │ File System │      │  In-Memory  │
+         │   *.db      │      │   Database  │
+         └─────────────┘      └─────────────┘
+```
+
+### Data Flow Diagram
+
+```mermaid
+sequenceDiagram
+    participant App as Application
+    participant Lib as docker-sqlite
+    participant SQL as sql.js (WASM)
+    participant FS as File System
+
+    App->>Lib: withConnection({ dbPath: './app.db' }, callback)
+    Lib->>FS: Read database file
+    alt File exists
+        FS-->>Lib: File buffer
+    else File doesn't exist
+        FS-->>Lib: ENOENT error
+        Note over Lib: Create new database
+    end
+
+    Lib->>SQL: new Database(buffer)
+    SQL-->>Lib: Database instance
+
+    Lib->>App: callback(db)
+
+    App->>Lib: execute(db, 'INSERT ...')
+    Lib->>SQL: db.run(sql, params)
+    SQL-->>Lib: Success
+
+    App->>Lib: query(db, 'SELECT ...')
+    Lib->>SQL: db.prepare(sql).step()
+    SQL-->>Lib: Result rows
+    Lib-->>App: { rows, columns }
+
+    App-->>Lib: callback complete
+
+    Lib->>SQL: db.export()
+    SQL-->>Lib: Binary data
+    Lib->>FS: Write database file
+    FS-->>Lib: Success
+
+    Lib->>SQL: db.close()
+    Lib-->>App: Return callback result
+```
+
+## Installation
+
+```bash
+npm install @mark1russell7/docker-sqlite
+```
+
+### Requirements
+
+- **Node.js**: >= 22
+- **Docker** (optional): For web UI to browse database
+- **Docker Compose** (optional): For orchestration
+
+## Docker Setup
+
+The package includes an optional Docker Compose configuration that provides a web-based SQLite browser.
+
+### Quick Start
+
+```bash
+# Start SQLite Web UI
+docker compose up -d
+
+# Open http://localhost:8080 to browse your database
+
+# Stop container
+docker compose down
+```
+
+### Environment Variables
+
+Configure the SQLite web viewer using environment variables:
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `SQLITE_CONTAINER_NAME` | `sqlite-web` | Name of the Docker container |
+| `SQLITE_PORT` | `8080` | Host port for web UI |
+| `SQLITE_DB_PATH` | `./data` | Path to database directory on host |
+| `SQLITE_DB_NAME` | `cli.db` | Database filename to open |
+
+#### Example: Custom Configuration
+
+Create a `.env` file:
+
+```env
+SQLITE_CONTAINER_NAME=myapp-sqlite-ui
+SQLITE_PORT=8090
+SQLITE_DB_PATH=./database
+SQLITE_DB_NAME=myapp.db
+```
+
+Then run:
+
+```bash
+docker compose up -d
+```
+
+### Container Features
+
+- **Web-based UI**: Browse and query SQLite databases via browser
+- **Auto-restart**: Container restarts unless explicitly stopped
+- **Volume mounting**: Live view of database changes
+- **Health checks**: Monitors UI availability every 30s
+- **Read-write mode**: Can modify database through UI
+
+### Web UI Usage
+
+Once running, navigate to `http://localhost:8080` to:
+
+- Browse tables and schema
+- Execute SQL queries
+- View indexes and constraints
+- Export data as CSV/JSON
+- Modify records directly
+
+## TypeScript API
+
+### Connection Management
+
+#### `withConnection<T>(config, callback): Promise<T>`
+
+Execute a callback with an auto-managed SQLite connection. The database is automatically loaded, saved, and closed.
+
+```typescript
+import { withConnection, query, execute } from '@mark1russell7/docker-sqlite';
+
+const users = await withConnection(
+  { dbPath: './data/app.db' },
+  (db) => {
+    execute(db, 'INSERT INTO users (name) VALUES (?)', ['Alice']);
+    return query(db, 'SELECT * FROM users');
+  }
+);
+
+console.log(users.rows);
+```
+
+**Parameters:**
+- `config.dbPath`: Path to database file (use `':memory:'` for in-memory database)
+- `callback`: Function receiving `Database` instance
+
+**Returns:** Result of the callback function
+
+**Behavior:**
+- Saves the database after the callback completes, only when its content changed. A read does not write the file, so a read-only file can be read, and a read cannot write an old copy over the changes of another process.
+- Makes the database file only when the callback changes the database. A query of a missing file does not make an empty file.
+- Calls for one file run one at a time in this process. On Windows, two spellings of one path (case) share one queue.
+- Writes a temporary file, flushes it to the disk and renames it over the database file. A crash or a power loss during the save cannot leave a truncated database.
+- Closes database connection in finally block
+- Creates parent directories as needed
+
+---
+
+#### `createConnection(config): Promise<{db, save}>`
+
+Create a manually-managed connection. Caller must handle saving and closing.
+
+```typescript
+import { createConnection, execute } from '@mark1russell7/docker-sqlite';
+
+const { db, save } = await createConnection({ dbPath: './data/app.db' });
+
+try {
+  execute(db, 'INSERT INTO logs (message) VALUES (?)', ['Started']);
+  await save(); // Explicitly save changes
+} finally {
+  db.close();
+}
+```
+
+**Behavior:**
+- `save()` writes the file only when the database changed, with the same atomic save as `withConnection`.
+- `save()` runs in the queue of the file: one call at a time with `withConnection` and the other saves of this process. In a `withConnection` callback for the same file, it runs at once.
+- `save()` throws a `DatabaseFileChangedError` (`code: "DATABASE_FILE_CHANGED"`) and writes nothing when the file changed after the connection loaded it or saved it last. Another connection or process wrote the file, and the old copy of this connection would replace those changes. After the error, close the connection, open a new one and make the change again.
+
+```typescript
+import { createConnection, DatabaseFileChangedError, execute } from '@mark1russell7/docker-sqlite';
+
+async function addLog(message: string): Promise<void> {
+  const { db, save } = await createConnection({ dbPath: './data/app.db' });
+  try {
+    execute(db, 'INSERT INTO logs (message) VALUES (?)', [message]);
+    await save();
+  } catch (error) {
+    if (error instanceof DatabaseFileChangedError) {
+      return addLog(message); // The file changed: load it again and repeat the change
+    }
+    throw error;
+  } finally {
+    db.close();
+  }
+}
+```
+
+### Query Operations
+
+#### `query<T>(db, sql, params?): QueryResult<T>`
+
+Execute a SELECT query and return typed results.
+
+```typescript
+import { query } from '@mark1russell7/docker-sqlite';
+
+interface User {
+  id: number;
+  name: string;
+  email: string;
+}
+
+const result = query<User>(
+  db,
+  'SELECT * FROM users WHERE age > ?',
+  [21]
+);
+
+console.log(result.columns); // ['id', 'name', 'email']
+console.log(result.rows);    // Array of User objects
+```
+
+**Parameters:**
+- `db`: Database instance
+- `sql`: SQL SELECT statement
+- `params?`: Optional parameter values
+
+**Returns:**
+```typescript
+{
+  columns: string[];  // Column names
+  rows: T[];          // Result rows as typed objects
+}
+```
+
+`columns` has the column names also when there are no rows.
+
+---
+
+#### `execute(db, sql, params?): ExecuteResult`
+
+Execute an INSERT, UPDATE, or DELETE statement.
+
+```typescript
+import { execute, lastInsertRowId } from '@mark1russell7/docker-sqlite';
+
+const result = execute(
+  db,
+  'INSERT INTO users (name, email) VALUES (?, ?)',
+  ['Bob', 'bob@example.com']
+);
+
+console.log(result.changes);     // 1
+console.log(lastInsertRowId(db)); // New row ID
+```
+
+SQL with several statements runs completely when there are no parameters, and `changes` counts the rows of all statements. With parameters, several statements are an error: parameters bind to one statement.
+
+**Returns:**
+```typescript
+{
+  changes: number;  // Number of rows affected
+}
+```
+
+---
+
+#### `execMultiple(db, sql): void`
+
+Execute multiple SQL statements at once. Useful for schema setup and batch operations.
+
+```typescript
+import { execMultiple } from '@mark1russell7/docker-sqlite';
+
+execMultiple(db, `
+  CREATE TABLE IF NOT EXISTS users (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    name TEXT NOT NULL,
+    email TEXT UNIQUE
+  );
+
+  CREATE INDEX IF NOT EXISTS idx_users_email ON users(email);
+
+  CREATE TABLE IF NOT EXISTS posts (
+    id INTEGER PRIMARY KEY,
+    user_id INTEGER,
+    title TEXT,
+    FOREIGN KEY (user_id) REFERENCES users(id)
+  );
+`);
+```
+
+---
+
+#### `tableExists(db, tableName): boolean`
+
+Check if a table exists in the database.
+
+```typescript
+import { tableExists } from '@mark1russell7/docker-sqlite';
+
+if (!tableExists(db, 'users')) {
+  execute(db, 'CREATE TABLE users (id INTEGER PRIMARY KEY, name TEXT)');
+}
+```
+
+---
+
+#### `lastInsertRowId(db): number`
+
+Get the row ID of the last inserted row.
+
+```typescript
+import { execute, lastInsertRowId } from '@mark1russell7/docker-sqlite';
+
+execute(db, 'INSERT INTO users (name) VALUES (?)', ['Alice']);
+const userId = lastInsertRowId(db);
+console.log(`Created user with ID: ${userId}`);
+```
+
+## Migration System
+
+The package includes a complete migration system for versioned schema management.
+
+### Migration Structure
+
+```typescript
+interface Migration {
+  version: number;        // Unique version number (sequential)
+  description: string;    // Human-readable description
+  up: string;            // SQL to apply migration
+  down?: string;         // SQL to rollback migration (optional)
+}
+```
+
+### `runMigrations(db, migrations): Migration[]`
+
+Apply all pending migrations in order.
+
+```typescript
+import { withConnection, runMigrations } from '@mark1russell7/docker-sqlite';
+
+const migrations = [
+  {
+    version: 1,
+    description: 'Create users table',
+    up: `
+      CREATE TABLE users (
+        id INTEGER PRIMARY KEY AUTOINCREMENT,
+        name TEXT NOT NULL,
+        email TEXT UNIQUE
+      )
+    `,
+    down: 'DROP TABLE users'
+  },
+  {
+    version: 2,
+    description: 'Add created_at column',
+    up: 'ALTER TABLE users ADD COLUMN created_at TEXT DEFAULT CURRENT_TIMESTAMP',
+    down: 'ALTER TABLE users DROP COLUMN created_at'
+  },
+  {
+    version: 3,
+    description: 'Create posts table',
+    up: `
+      CREATE TABLE posts (
+        id INTEGER PRIMARY KEY,
+        user_id INTEGER,
+        title TEXT NOT NULL,
+        content TEXT,
+        FOREIGN KEY (user_id) REFERENCES users(id)
+      )
+    `
+  }
+];
+
+await withConnection({ dbPath: './data/app.db' }, (db) => {
+  const applied = runMigrations(db, migrations);
+  console.log(`Applied ${applied.length} migrations`);
+  applied.forEach(m => console.log(`  ✓ ${m.description}`));
+});
+```
+
+**Behavior:**
+- Creates `_migrations` table automatically to track applied migrations
+- Applies only pending migrations in version order
+- Records each migration with timestamp
+- Skips already-applied migrations
+- Throws error if migration fails (doesn't continue)
+- Runs each migration and its record in a savepoint. A migration that fails leaves no change, so a corrected migration applies on the next run. In a transaction of the caller, the savepoint keeps that transaction open.
+- A migration whose SQL controls transactions itself (`BEGIN`, `COMMIT`, `END`, `ROLLBACK`, `SAVEPOINT`, `RELEASE`, `VACUUM`, `ATTACH`, `DETACH` or `PRAGMA`) runs without the savepoint: in a transaction, these statements fail or do nothing.
+
+**Returns:** Array of applied migrations
+
+---
+
+### `getMigrationStatus(db, migrations): MigrationStatus`
+
+Get the current migration status.
+
+```typescript
+import { getMigrationStatus } from '@mark1russell7/docker-sqlite';
+
+const status = getMigrationStatus(db, migrations);
+
+console.log(`Current version: ${status.currentVersion}`);
+console.log(`Applied migrations: ${status.appliedMigrations.join(', ')}`);
+console.log(`Pending migrations: ${status.pendingMigrations.length}`);
+
+status.pendingMigrations.forEach(m => {
+  console.log(`  - v${m.version}: ${m.description}`);
+});
+```
+
+**Returns:**
+```typescript
+{
+  currentVersion: number;           // Latest applied version (0 if none)
+  appliedMigrations: number[];      // Array of applied version numbers
+  pendingMigrations: Migration[];   // Migrations not yet applied
+}
+```
+
+---
+
+### `rollbackMigration(db, migrations): Migration | null`
+
+Rollback the last applied migration.
+
+```typescript
+import { rollbackMigration } from '@mark1russell7/docker-sqlite';
+
+const rolled = rollbackMigration(db, migrations);
+
+if (rolled) {
+  console.log(`Rolled back: v${rolled.version} - ${rolled.description}`);
+} else {
+  console.log('No migrations to rollback');
+}
+```
+
+**Requirements:**
+- Migration must have a `down` script
+- Migration must be the current version
+
+The `down` script and the removal of its record run in a savepoint, with the same rules as `runMigrations`.
+
+**Returns:** The rolled-back migration, or `null` if none
+
+---
+
+### `createMigration(version, description, up, down?): Migration`
+
+Helper function to create a migration object.
+
+```typescript
+import { createMigration } from '@mark1russell7/docker-sqlite';
+
+const migration = createMigration(
+  1,
+  'Initial schema',
+  'CREATE TABLE users (id INTEGER PRIMARY KEY)',
+  'DROP TABLE users'
+);
+```
+
+## Configuration
+
+### Database Paths
+
+```typescript
+// In-memory database (no persistence)
+await withConnection({ dbPath: ':memory:' }, (db) => {
+  // Data is lost after connection closes
+});
+
+// Relative path
+await withConnection({ dbPath: './data/app.db' }, (db) => {
+  // Saved to ./data/app.db
+});
+
+// Absolute path
+await withConnection({ dbPath: '/var/lib/myapp/app.db' }, (db) => {
+  // Saved to /var/lib/myapp/app.db
+});
+
+// Default (in-memory)
+await withConnection({}, (db) => {
+  // No persistence
+});
+```
+
+### Common Patterns
+
+#### CLI Logging Database
+
+The package includes a reference schema for CLI logging in `schema/logs.sql`:
+
+```typescript
+import { withConnection, execMultiple } from '@mark1russell7/docker-sqlite';
+import { readFile } from 'node:fs/promises';
+
+const schema = await readFile('./node_modules/@mark1russell7/docker-sqlite/schema/logs.sql', 'utf-8');
+
+await withConnection({ dbPath: './cli-logs.db' }, (db) => {
+  execMultiple(db, schema);
+
+  execute(db, `
+    INSERT INTO logs (level, message, command, session_id)
+    VALUES (?, ?, ?, ?)
+  `, ['info', 'Command started', 'lib.refresh', sessionId]);
+});
+```
+
+#### Testing Pattern
+
+```typescript
+import { describe, it } from 'node:test';
+import assert from 'node:assert';
+import { withConnection, query, execute } from '@mark1russell7/docker-sqlite';
+
+describe('User repository', () => {
+  it('should create and retrieve user', async () => {
+    await withConnection({ dbPath: ':memory:' }, (db) => {
+      // Setup schema
+      execute(db, 'CREATE TABLE users (id INTEGER PRIMARY KEY, name TEXT)');
+
+      // Test
+      execute(db, 'INSERT INTO users (name) VALUES (?)', ['Alice']);
+      const result = query(db, 'SELECT * FROM users WHERE name = ?', ['Alice']);
+
+      assert.strictEqual(result.rows.length, 1);
+      assert.strictEqual(result.rows[0].name, 'Alice');
+    });
+  });
+});
+```
+
+#### Migration-based Setup
+
+```typescript
+import { withConnection, runMigrations, getMigrationStatus } from '@mark1russell7/docker-sqlite';
+
+const migrations = [
+  {
+    version: 1,
+    description: 'Initial schema',
+    up: `
+      CREATE TABLE users (id INTEGER PRIMARY KEY, name TEXT);
+      CREATE TABLE posts (id INTEGER PRIMARY KEY, user_id INTEGER);
+    `
+  }
+];
+
+async function initDatabase(dbPath: string) {
+  await withConnection({ dbPath }, (db) => {
+    const status = getMigrationStatus(db, migrations);
+
+    if (status.pendingMigrations.length > 0) {
+      console.log(`Applying ${status.pendingMigrations.length} migration(s)...`);
+      runMigrations(db, migrations);
+      console.log('Database up to date!');
+    } else {
+      console.log(`Database already at version ${status.currentVersion}`);
+    }
+  });
+}
+
+await initDatabase('./data/app.db');
+```
+
+## Integration
+
+### Environment Configuration
+
+Create a `.env` file for your application:
+
+```env
+# SQLite database path
+SQLITE_DB_PATH=./data/app.db
+
+# Docker Web UI settings (optional)
+SQLITE_CONTAINER_NAME=myapp-sqlite-ui
+SQLITE_PORT=8080
+```
+
+Load in your application:
+
+```typescript
+import 'dotenv/config';
+import { withConnection } from '@mark1russell7/docker-sqlite';
+
+const dbPath = process.env.SQLITE_DB_PATH || './app.db';
+
+await withConnection({ dbPath }, (db) => {
+  // Your database operations
+});
+```
+
+### npm Scripts
+
+Add to your `package.json`:
+
+```json
+{
+  "scripts": {
+    "db:ui": "docker compose -f node_modules/@mark1russell7/docker-sqlite/docker-compose.yml up -d",
+    "db:ui:stop": "docker compose -f node_modules/@mark1russell7/docker-sqlite/docker-compose.yml down",
+    "db:migrate": "tsx scripts/migrate.ts",
+    "db:rollback": "tsx scripts/rollback.ts"
+  }
+}
+```
+
+### Ecosystem Integration
+
+This package integrates with the broader Mark Russell ecosystem:
+
+- **@mark1russell7/cue**: TypeScript configuration inheritance
+- **client-sqlite**: MCP client procedures for SQLite operations
+- **bundle-dev**: Development bundle including database tooling
+
+## Examples
+
+### Complete Application with Migrations
+
+```typescript
+import { withConnection, runMigrations, query, execute } from '@mark1russell7/docker-sqlite';
+
+// Define schema migrations
+const migrations = [
+  {
+    version: 1,
+    description: 'Create users table',
+    up: `
+      CREATE TABLE users (
+        id INTEGER PRIMARY KEY AUTOINCREMENT,
+        username TEXT UNIQUE NOT NULL,
+        email TEXT UNIQUE NOT NULL,
+        created_at TEXT DEFAULT CURRENT_TIMESTAMP
+      );
+      CREATE INDEX idx_users_email ON users(email);
+    `,
+    down: 'DROP TABLE users'
+  },
+  {
+    version: 2,
+    description: 'Create posts table',
+    up: `
+      CREATE TABLE posts (
+        id INTEGER PRIMARY KEY AUTOINCREMENT,
+        user_id INTEGER NOT NULL,
+        title TEXT NOT NULL,
+        content TEXT,
+        created_at TEXT DEFAULT CURRENT_TIMESTAMP,
+        FOREIGN KEY (user_id) REFERENCES users(id) ON DELETE CASCADE
+      );
+      CREATE INDEX idx_posts_user ON posts(user_id);
+    `,
+    down: 'DROP TABLE posts'
+  }
+];
+
+// Application setup
+async function setupDatabase(dbPath: string) {
+  await withConnection({ dbPath }, (db) => {
+    // Apply migrations
+    const applied = runMigrations(db, migrations);
+    if (applied.length > 0) {
+      console.log(`Applied ${applied.length} migration(s)`);
+    }
+  });
+}
+
+// User operations
+interface User {
+  id: number;
+  username: string;
+  email: string;
+  created_at: string;
+}
+
+async function createUser(dbPath: string, username: string, email: string): Promise<number> {
+  return withConnection({ dbPath }, (db) => {
+    execute(db, 'INSERT INTO users (username, email) VALUES (?, ?)', [username, email]);
+    return lastInsertRowId(db);
+  });
+}
+
+async function getUsers(dbPath: string): Promise<User[]> {
+  return withConnection({ dbPath }, (db) => {
+    const result = query<User>(db, 'SELECT * FROM users ORDER BY created_at DESC');
+    return result.rows;
+  });
+}
+
+// Usage
+const dbPath = './data/myapp.db';
+
+await setupDatabase(dbPath);
+const userId = await createUser(dbPath, 'alice', 'alice@example.com');
+const users = await getUsers(dbPath);
+
+console.log(`Created user ID: ${userId}`);
+console.log(`Total users: ${users.length}`);
+```
+
+### Transaction Pattern (Manual Connection)
+
+```typescript
+import { createConnection, execute } from '@mark1russell7/docker-sqlite';
+
+async function transferCredits(fromUserId: number, toUserId: number, amount: number) {
+  const { db, save } = await createConnection({ dbPath: './data/app.db' });
+
+  try {
+    // Start transaction
+    execute(db, 'BEGIN TRANSACTION');
+
+    // Deduct from sender
+    execute(db, 'UPDATE users SET credits = credits - ? WHERE id = ?', [amount, fromUserId]);
+
+    // Check sender balance
+    const result = query(db, 'SELECT credits FROM users WHERE id = ?', [fromUserId]);
+    if (result.rows[0].credits < 0) {
+      throw new Error('Insufficient credits');
+    }
+
+    // Add to receiver
+    execute(db, 'UPDATE users SET credits = credits + ? WHERE id = ?', [amount, toUserId]);
+
+    // Commit
+    execute(db, 'COMMIT');
+    await save();
+
+    console.log(`Transferred ${amount} credits from user ${fromUserId} to ${toUserId}`);
+  } catch (error) {
+    // Rollback on error
+    execute(db, 'ROLLBACK');
+    throw error;
+  } finally {
+    db.close();
+  }
+}
+```
+
+### Query Builder Pattern
+
+```typescript
+import { withConnection, query } from '@mark1russell7/docker-sqlite';
+
+interface QueryBuilder {
+  select(columns: string[]): this;
+  from(table: string): this;
+  where(condition: string, params: unknown[]): this;
+  orderBy(column: string, direction?: 'ASC' | 'DESC'): this;
+  limit(limit: number): this;
+  execute<T>(): QueryResult<T>;
+}
+
+class SQLiteQueryBuilder implements QueryBuilder {
+  private parts: {
+    select: string[];
+    from: string;
+    where: { condition: string; params: unknown[] }[];
+    orderBy?: string;
+    limit?: number;
+  } = { select: ['*'], from: '', where: [] };
+
+  constructor(private db: Database) {}
+
+  select(columns: string[]): this {
+    this.parts.select = columns;
+    return this;
+  }
+
+  from(table: string): this {
+    this.parts.from = table;
+    return this;
+  }
+
+  where(condition: string, params: unknown[]): this {
+    this.parts.where.push({ condition, params });
+    return this;
+  }
+
+  orderBy(column: string, direction: 'ASC' | 'DESC' = 'ASC'): this {
+    this.parts.orderBy = `${column} ${direction}`;
+    return this;
+  }
+
+  limit(limit: number): this {
+    this.parts.limit = limit;
+    return this;
+  }
+
+  execute<T>(): QueryResult<T> {
+    let sql = `SELECT ${this.parts.select.join(', ')} FROM ${this.parts.from}`;
+    const params: unknown[] = [];
+
+    if (this.parts.where.length > 0) {
+      sql += ' WHERE ' + this.parts.where.map(w => w.condition).join(' AND ');
+      this.parts.where.forEach(w => params.push(...w.params));
+    }
+
+    if (this.parts.orderBy) {
+      sql += ` ORDER BY ${this.parts.orderBy}`;
+    }
+
+    if (this.parts.limit) {
+      sql += ` LIMIT ${this.parts.limit}`;
+    }
+
+    return query<T>(this.db, sql, params);
+  }
+}
+
+// Usage
+await withConnection({ dbPath: './data/app.db' }, (db) => {
+  const builder = new SQLiteQueryBuilder(db);
+
+  const result = builder
+    .select(['id', 'username', 'email'])
+    .from('users')
+    .where('created_at > ?', ['2024-01-01'])
+    .where('email LIKE ?', ['%@example.com'])
+    .orderBy('created_at', 'DESC')
+    .limit(10)
+    .execute<User>();
+
+  console.log(result.rows);
+});
+```
+
+## API Reference
+
+### Types
+
+```typescript
+interface ConnectionConfig {
+  dbPath: string;  // Path to database file, or ':memory:' for in-memory
+}
+
+type ConnectionCallback<T> = (db: Database) => T | Promise<T>;
+
+interface QueryResult<T = Record<string, unknown>> {
+  columns: string[];  // Column names
+  rows: T[];          // Result rows as typed objects
+}
+
+interface ExecuteResult {
+  changes: number;  // Number of rows affected
+}
+
+interface Migration {
+  version: number;        // Unique version number (sequential)
+  description: string;    // Human-readable description
+  up: string;            // SQL to apply migration
+  down?: string;         // SQL to rollback migration (optional)
+}
+
+interface MigrationStatus {
+  currentVersion: number;           // Latest applied version (0 if none)
+  appliedMigrations: number[];      // Array of applied version numbers
+  pendingMigrations: Migration[];   // Migrations not yet applied
+}
+```
+
+### Functions
+
+All functions are fully documented with JSDoc and include TypeScript type definitions. Import from the package root:
+
+```typescript
+import {
+  // Connection
+  withConnection,
+  createConnection,
+  DatabaseFileChangedError,
+
+  // Query
+  query,
+  execute,
+  execMultiple,
+  tableExists,
+  lastInsertRowId,
+
+  // Migration
+  runMigrations,
+  rollbackMigration,
+  getMigrationStatus,
+  createMigration,
+
+  // Types
+  type ConnectionConfig,
+  type QueryResult,
+  type Migration,
+  type MigrationStatus,
+  type Database,
+  // ... etc
+} from '@mark1russell7/docker-sqlite';
+```
+
+## License
+
+MIT
+
+## Contributing
+
+Issues and pull requests are welcome at the package repository.
+
+## Related Packages
+
+- [@mark1russell7/docker-mongo](../mongo) - MongoDB Docker setup with similar API
+- [@mark1russell7/cue](https://github.com/mark1russell7/cue) - Shared TypeScript configuration
+- [sql.js](https://github.com/sql-js/sql.js) - SQLite compiled to JavaScript/WASM