@mark1russell7/docker-sqlite 0.0.0-stage → 0.1.0

package/dist/query.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Query helper utilities for SQLite
+ */
+import type { Database } from "sql.js";
+import type { QueryResult, ExecuteResult } from "./types.js";
+/**
+ * Execute a SELECT query and return results
+ *
+ * @example
+ * ```typescript
+ * const result = query(db, 'SELECT * FROM users WHERE age > ?', [21]);
+ * console.log(result.columns); // ['id', 'name', 'age']
+ * console.log(result.rows);    // [{ id: 1, name: 'Alice', age: 25 }, ...]
+ * ```
+ */
+export declare function query<T = Record<string, unknown>>(db: Database, sql: string, params?: unknown[]): QueryResult<T>;
+/**
+ * Execute an INSERT, UPDATE, DELETE, or other statement
+ *
+ * @example
+ * ```typescript
+ * const result = execute(db, 'INSERT INTO users (name, age) VALUES (?, ?)', ['Bob', 30]);
+ * console.log(result.changes); // 1
+ * ```
+ */
+export declare function execute(db: Database, sql: string, params?: unknown[]): ExecuteResult;
+/**
+ * True when `sql` holds more than one statement. Nothing runs: the function only prepares the
+ * first statement and examines the SQL after it.
+ */
+export declare function hasSeveralStatements(db: Database, sql: string): boolean;
+/**
+ * Execute multiple statements (for schema setup, etc.)
+ *
+ * @example
+ * ```typescript
+ * execMultiple(db, `
+ *   CREATE TABLE IF NOT EXISTS users (id INTEGER PRIMARY KEY, name TEXT);
+ *   CREATE TABLE IF NOT EXISTS posts (id INTEGER PRIMARY KEY, user_id INTEGER);
+ * `);
+ * ```
+ */
+export declare function execMultiple(db: Database, sql: string): void;
+/**
+ * Get the last inserted row ID
+ */
+export declare function lastInsertRowId(db: Database): number;
+/**
+ * Check if a table exists
+ */
+export declare function tableExists(db: Database, tableName: string): boolean;
+//# sourceMappingURL=query.d.ts.map

package/dist/query.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"query.d.ts","sourceRoot":"","sources":["../src/query.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,QAAQ,CAAC;AACvC,OAAO,KAAK,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAE7D;;;;;;;;;GASG;AACH,wBAAgB,KAAK,CAAC,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC/C,EAAE,EAAE,QAAQ,EACZ,GAAG,EAAE,MAAM,EACX,MAAM,GAAE,OAAO,EAAO,GACrB,WAAW,CAAC,CAAC,CAAC,CAoBhB;AAED;;;;;;;;GAQG;AACH,wBAAgB,OAAO,CACrB,EAAE,EAAE,QAAQ,EACZ,GAAG,EAAE,MAAM,EACX,MAAM,GAAE,OAAO,EAAO,GACrB,aAAa,CAiBf;AAiBD;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,EAAE,EAAE,QAAQ,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAiBvE;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,YAAY,CAAC,EAAE,EAAE,QAAQ,EAAE,GAAG,EAAE,MAAM,GAAG,IAAI,CAE5D;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,EAAE,EAAE,QAAQ,GAAG,MAAM,CAGpD;AAED;;GAEG;AACH,wBAAgB,WAAW,CAAC,EAAE,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAOpE"}

package/dist/query.js

@@ -0,0 +1,121 @@
+/**
+ * Query helper utilities for SQLite
+ */
+/**
+ * Execute a SELECT query and return results
+ *
+ * @example
+ * ```typescript
+ * const result = query(db, 'SELECT * FROM users WHERE age > ?', [21]);
+ * console.log(result.columns); // ['id', 'name', 'age']
+ * console.log(result.rows);    // [{ id: 1, name: 'Alice', age: 25 }, ...]
+ * ```
+ */
+export function query(db, sql, params = []) {
+    const stmt = db.prepare(sql);
+    try {
+        stmt.bind(params);
+        const rows = [];
+        let columns = [];
+        while (stmt.step()) {
+            if (columns.length === 0) {
+                columns = stmt.getColumnNames();
+            }
+            rows.push(stmt.getAsObject());
+        }
+        return { columns, rows };
+    }
+    finally {
+        stmt.free();
+    }
+}
+/**
+ * Execute an INSERT, UPDATE, DELETE, or other statement
+ *
+ * @example
+ * ```typescript
+ * const result = execute(db, 'INSERT INTO users (name, age) VALUES (?, ?)', ['Bob', 30]);
+ * console.log(result.changes); // 1
+ * ```
+ */
+export function execute(db, sql, params = []) {
+    // With parameters, sql.js runs only the first statement. Before, the other statements were
+    // ignored and the call reported success. Now several statements run with no parameters, and
+    // are an error with parameters.
+    if (hasSeveralStatements(db, sql)) {
+        if (params.length > 0) {
+            throw new Error("execute() binds parameters to one statement, and the SQL has several. Send one statement per call.");
+        }
+        const before = totalChanges(db);
+        db.exec(sql);
+        return { changes: totalChanges(db) - before };
+    }
+    db.run(sql, params);
+    const changes = db.getRowsModified();
+    return { changes };
+}
+/** The number of rows that the statements of this connection changed. */
+function totalChanges(db) {
+    const result = db.exec("SELECT total_changes()");
+    return Number(result[0]?.values[0]?.[0] ?? 0);
+}
+/** True when the text holds SQL other than spaces, ";" and comments. */
+function holdsStatement(sql) {
+    return sql
+        .replace(/--[^\n]*/g, "")
+        .replace(/\/\*[\s\S]*?\*\//g, "")
+        .replace(/[\s;]/g, "")
+        .length > 0;
+}
+/**
+ * True when `sql` holds more than one statement. Nothing runs: the function only prepares the
+ * first statement and examines the SQL after it.
+ */
+export function hasSeveralStatements(db, sql) {
+    const iterator = db.iterateStatements(sql);
+    const first = iterator.next();
+    if (first.done) {
+        return false;
+    }
+    const rest = iterator.getRemainingSQL();
+    // Read the iterator to its end: this frees the statement and the copy of the SQL. A later
+    // statement can fail to prepare (its table does not exist yet), and that also ends it.
+    try {
+        while (!iterator.next().done) {
+            // Prepare only
+        }
+    }
+    catch {
+        // The iterator ended
+    }
+    return holdsStatement(rest);
+}
+/**
+ * Execute multiple statements (for schema setup, etc.)
+ *
+ * @example
+ * ```typescript
+ * execMultiple(db, `
+ *   CREATE TABLE IF NOT EXISTS users (id INTEGER PRIMARY KEY, name TEXT);
+ *   CREATE TABLE IF NOT EXISTS posts (id INTEGER PRIMARY KEY, user_id INTEGER);
+ * `);
+ * ```
+ */
+export function execMultiple(db, sql) {
+    db.exec(sql);
+}
+/**
+ * Get the last inserted row ID
+ */
+export function lastInsertRowId(db) {
+    const result = query(db, "SELECT last_insert_rowid() as id");
+    return result.rows[0]?.id ?? 0;
+}
+/**
+ * Check if a table exists
+ */
+export function tableExists(db, tableName) {
+    const result = query(db, "SELECT name FROM sqlite_master WHERE type='table' AND name=?", [tableName]);
+    return result.rows.length > 0;
+}
+//# sourceMappingURL=query.js.map

package/dist/query.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"query.js","sourceRoot":"","sources":["../src/query.ts"],"names":[],"mappings":"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"}

package/dist/types.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Type definitions for docker-sqlite
+ */
+import type { Database } from "sql.js";
+/**
+ * Configuration for SQLite connection
+ */
+export interface ConnectionConfig {
+    /** Path to the SQLite database file. Use ":memory:" for in-memory database */
+    dbPath: string;
+}
+/**
+ * Callback function for withConnection
+ */
+export type ConnectionCallback<T> = (db: Database) => T | Promise<T>;
+/**
+ * Result of a query operation
+ */
+export interface QueryResult<T = Record<string, unknown>> {
+    /** Column names */
+    columns: string[];
+    /** Row values */
+    rows: T[];
+}
+/**
+ * Result of an execute operation (INSERT, UPDATE, DELETE)
+ */
+export interface ExecuteResult {
+    /** Number of rows affected */
+    changes: number;
+}
+/**
+ * Migration definition
+ */
+export interface Migration {
+    /** Migration version (must be unique and sequential) */
+    version: number;
+    /** Description of the migration */
+    description: string;
+    /** SQL to apply the migration */
+    up: string;
+    /** SQL to revert the migration (optional) */
+    down?: string;
+}
+/**
+ * Migration status
+ */
+export interface MigrationStatus {
+    /** Current version (0 if no migrations applied) */
+    currentVersion: number;
+    /** List of applied migrations */
+    appliedMigrations: number[];
+    /** List of pending migrations */
+    pendingMigrations: Migration[];
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,QAAQ,CAAC;AAEvC;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,8EAA8E;IAC9E,MAAM,EAAE,MAAM,CAAC;CAChB;AAED;;GAEG;AACH,MAAM,MAAM,kBAAkB,CAAC,CAAC,IAAI,CAAC,EAAE,EAAE,QAAQ,KAAK,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;AAErE;;GAEG;AACH,MAAM,WAAW,WAAW,CAAC,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IACtD,mBAAmB;IACnB,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,iBAAiB;IACjB,IAAI,EAAE,CAAC,EAAE,CAAC;CACX;AAED;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,8BAA8B;IAC9B,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;GAEG;AACH,MAAM,WAAW,SAAS;IACxB,wDAAwD;IACxD,OAAO,EAAE,MAAM,CAAC;IAChB,mCAAmC;IACnC,WAAW,EAAE,MAAM,CAAC;IACpB,iCAAiC;IACjC,EAAE,EAAE,MAAM,CAAC;IACX,6CAA6C;IAC7C,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,mDAAmD;IACnD,cAAc,EAAE,MAAM,CAAC;IACvB,iCAAiC;IACjC,iBAAiB,EAAE,MAAM,EAAE,CAAC;IAC5B,iCAAiC;IACjC,iBAAiB,EAAE,SAAS,EAAE,CAAC;CAChC"}

package/dist/types.js

@@ -0,0 +1,5 @@
+/**
+ * Type definitions for docker-sqlite
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;GAEG"}

package/docker-compose.yml

@@ -0,0 +1,31 @@
+# SQLite Docker Compose Configuration
+#
+# Provides a web UI for browsing SQLite databases.
+#
+# Environment variables (with defaults):
+#   SQLITE_CONTAINER_NAME - Container name (default: sqlite-web)
+#   SQLITE_PORT           - Host port for web UI (default: 8080)
+#   SQLITE_DB_PATH        - Path to database directory (default: ./data)
+#   SQLITE_DB_NAME        - Database filename (default: cli.db)
+#
+# Usage:
+#   docker compose up -d
+#   docker compose down
+#   Open http://localhost:8080 to browse the database
+
+services:
+  sqlite-web:
+    image: coleifer/sqlite-web
+    container_name: ${SQLITE_CONTAINER_NAME:-sqlite-web}
+    ports:
+      # Loopback only: the sqlite-web UI has full read/write access and no authentication
+      - "127.0.0.1:${SQLITE_PORT:-8080}:8080"
+    volumes:
+      - ${SQLITE_DB_PATH:-./data}:/data:rw
+    command: sqlite_web -H 0.0.0.0 /data/${SQLITE_DB_NAME:-cli.db}
+    restart: unless-stopped
+    healthcheck:
+      test: ["CMD", "wget", "-q", "--spider", "http://localhost:8080/"]
+      interval: 30s
+      timeout: 10s
+      retries: 3

package/package.json

@@ -1,6 +1,86 @@
-{
-  "name": "@mark1russell7/docker-sqlite",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+{
+  "$schema": "https://json.schemastore.org/package",
+  "name": "@mark1russell7/docker-sqlite",
+  "version": "0.1.0",
+  "description": "SQLite for Node.js with no native build: sql.js (SQLite in WebAssembly) with safe file access (one call at a time per file, atomic saves, no write on read), queries, migrations and an optional Docker Compose web UI.",
+  "keywords": [
+    "sqlite",
+    "sqlite3",
+    "sql.js",
+    "wasm",
+    "webassembly",
+    "database",
+    "migrations",
+    "schema-migrations",
+    "query",
+    "embedded-database",
+    "docker",
+    "docker-compose",
+    "sqlite-web",
+    "typescript",
+    "node"
+  ],
+  "homepage": "https://github.com/mark1russell7/docker-sqlite#readme",
+  "bugs": {
+    "url": "https://github.com/mark1russell7/docker-sqlite/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mark1russell7/docker-sqlite.git"
+  },
+  "license": "MIT",
+  "author": "Mark Russell (https://github.com/mark1russell7)",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./docker-compose.yml": "./docker-compose.yml",
+    "./schema/*": "./schema/*",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "src",
+    "!dist/**/*.test.*",
+    "!src/**/*.test.ts",
+    "schema",
+    "docker-compose.yml",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc -b",
+    "typecheck": "tsc --noEmit",
+    "clean": "rm -rf dist .tsbuildinfo",
+    "prepare": "npm run build",
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "@types/sql.js": "^1.4.11",
+    "sql.js": "^1.11.0"
+  },
+  "devDependencies": {
+    "@mark1russell7/cue": "github:mark1russell7/cue#main",
+    "@types/node": "^22.0.0",
+    "typescript": "^5.9.3",
+    "vitest": "^4.1.11"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "sideEffects": false,
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "pnpm": {
+    "onlyBuiltDependencies": [
+      "@mark1russell7/cue"
+    ]
+  }
+}

package/schema/logs.sql

@@ -0,0 +1,21 @@
+-- Log table schema for CLI logging
+-- This is a reference schema, not applied automatically
+
+CREATE TABLE IF NOT EXISTS logs (
+  id INTEGER PRIMARY KEY AUTOINCREMENT,
+  timestamp TEXT NOT NULL DEFAULT (datetime('now')),
+  level TEXT NOT NULL CHECK (level IN ('trace', 'debug', 'info', 'warn', 'error')),
+  message TEXT NOT NULL,
+  data TEXT,           -- JSON serialized additional data
+  session_id TEXT,     -- Groups logs by CLI session
+  command TEXT,        -- CLI command that generated the log (e.g., 'lib.refresh')
+  context TEXT,        -- Additional context (e.g., package name)
+  error_stack TEXT,    -- Stack trace if error
+  created_at TEXT NOT NULL DEFAULT (datetime('now'))
+);
+
+-- Indexes for common queries
+CREATE INDEX IF NOT EXISTS idx_logs_session ON logs(session_id);
+CREATE INDEX IF NOT EXISTS idx_logs_level ON logs(level);
+CREATE INDEX IF NOT EXISTS idx_logs_timestamp ON logs(timestamp);
+CREATE INDEX IF NOT EXISTS idx_logs_command ON logs(command);

package/src/connect.ts

@@ -0,0 +1,194 @@
+/**
+ * Connection utilities for SQLite using sql.js
+ */
+
+import initSqlJs, { type Database } from "sql.js";
+import { readFile, writeFile, mkdir, rename, unlink } from "node:fs/promises";
+import { dirname, resolve } from "node:path";
+import type { ConnectionConfig, ConnectionCallback } from "./types.js";
+
+let sqlPromise: Promise<Awaited<ReturnType<typeof initSqlJs>>> | null = null;
+
+/**
+ * Initialize sql.js (cached)
+ */
+async function getSql(): Promise<Awaited<ReturnType<typeof initSqlJs>>> {
+  if (!sqlPromise) {
+    sqlPromise = initSqlJs();
+  }
+  return sqlPromise;
+}
+
+/** A database and the bytes of its file when it was loaded (null: there was no file). */
+interface LoadedDatabase {
+  db: Database;
+  original: Uint8Array | null;
+}
+
+/**
+ * Load a database from a file path or create a new one
+ */
+async function loadDatabase(dbPath: string): Promise<LoadedDatabase> {
+  const SQL = await getSql();
+
+  if (dbPath === ":memory:") {
+    return { db: new SQL.Database(), original: null };
+  }
+
+  try {
+    const buffer = await readFile(dbPath);
+    // sql.js keeps the array that it gets and writes into it: give it a copy, so `original`
+    // keeps the bytes of the file
+    return { db: new SQL.Database(new Uint8Array(buffer)), original: buffer };
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") {
+      // File doesn't exist, create new database
+      return { db: new SQL.Database(), original: null };
+    }
+    throw error;
+  }
+}
+
+/**
+ * Save a database to a file path, when its content changed.
+ *
+ * A database that did not change is not written. Before, each call wrote the file, also a
+ * read: a read failed on a read-only file (EPERM), a read wrote an old copy over the rows of
+ * another process, and a query of a missing file made an empty file. The export of a
+ * database that did not change has the bytes of its file, and an empty new database exports
+ * no bytes.
+ *
+ * Writes a temporary file and renames it over the database, so a crash during the write
+ * cannot leave a truncated database (the rename replaces the file in one step).
+ */
+async function saveDatabase(db: Database, dbPath: string, original: Uint8Array | null): Promise<Uint8Array | null> {
+  if (dbPath === ":memory:") {
+    return null;
+  }
+
+  const data = db.export();
+  const unchanged = original
+    ? Buffer.compare(Buffer.from(data), Buffer.from(original)) === 0
+    : data.length === 0;
+  if (unchanged) {
+    return original;
+  }
+  const buffer = Buffer.from(data);
+
+  // Ensure directory exists
+  await mkdir(dirname(dbPath), { recursive: true });
+
+  const tempPath = `${dbPath}.${process.pid}.${Date.now()}.tmp`;
+  await writeFile(tempPath, buffer);
+  try {
+    await rename(tempPath, dbPath);
+  } catch {
+    // For example, the file is held open on Windows: fall back to a direct write
+    await unlink(tempPath).catch(() => {});
+    await writeFile(dbPath, buffer);
+  }
+  return data;
+}
+
+/**
+ * The calls that wait for each database file. Each call reads the whole file, changes it in
+ * memory and writes it back, so two calls at once lost the changes of one of them
+ * (50 concurrent inserts kept 1 row). Calls for the same file now run one at a time in this
+ * process. (Other processes that write the same file are not coordinated.)
+ */
+const fileQueues = new Map<string, Promise<unknown>>();
+
+/**
+ * The queue key of a file. Windows file names do not depend on case, so the key is in lower
+ * case there. Before, two spellings of one file had two queues, and their calls ran at once.
+ */
+export function fileQueueKey(dbPath: string, platform: NodeJS.Platform = process.platform): string {
+  const path = resolve(dbPath);
+  return platform === "win32" ? path.toLowerCase() : path;
+}
+
+async function inFileQueue<T>(dbPath: string, task: () => Promise<T>): Promise<T> {
+  if (dbPath === ":memory:") {
+    return task();
+  }
+  const key = fileQueueKey(dbPath);
+  const previous = fileQueues.get(key) ?? Promise.resolve();
+  const run = previous.then(task, task);
+  const tail = run.then(
+    () => undefined,
+    () => undefined
+  );
+  fileQueues.set(key, tail);
+  try {
+    return await run;
+  } finally {
+    if (fileQueues.get(key) === tail) {
+      fileQueues.delete(key);
+    }
+  }
+}
+
+/**
+ * Execute a callback with a SQLite connection, ensuring proper cleanup and persistence.
+ *
+ * @example
+ * ```typescript
+ * const result = await withConnection(
+ *   { dbPath: './data/app.db' },
+ *   async (db) => {
+ *     const stmt = db.prepare('SELECT * FROM users WHERE id = ?');
+ *     stmt.bind([1]);
+ *     const rows = [];
+ *     while (stmt.step()) {
+ *       rows.push(stmt.getAsObject());
+ *     }
+ *     stmt.free();
+ *     return rows;
+ *   }
+ * );
+ * ```
+ */
+export async function withConnection<T>(
+  config: ConnectionConfig,
+  fn: ConnectionCallback<T>
+): Promise<T> {
+  return inFileQueue(config.dbPath, async () => {
+    const { db, original } = await loadDatabase(config.dbPath);
+
+    try {
+      const result = await fn(db);
+      // Save changes back to file (only when there are changes)
+      await saveDatabase(db, config.dbPath, original);
+      return result;
+    } finally {
+      db.close();
+    }
+  });
+}
+
+/**
+ * Create a SQLite database that can be manually managed.
+ * Caller is responsible for calling db.close() and saving if needed.
+ *
+ * @example
+ * ```typescript
+ * const { db, save } = await createConnection({ dbPath: './data/app.db' });
+ * try {
+ *   db.run('INSERT INTO users (name) VALUES (?)', ['Alice']);
+ *   await save();
+ * } finally {
+ *   db.close();
+ * }
+ * ```
+ */
+export async function createConnection(
+  config: ConnectionConfig
+): Promise<{ db: Database; save: () => Promise<void> }> {
+  const { db, original } = await loadDatabase(config.dbPath);
+  // The bytes of the file after the last save, to compare the next save with
+  let saved = original;
+  const save = async (): Promise<void> => {
+    saved = await saveDatabase(db, config.dbPath, saved);
+  };
+  return { db, save };
+}

package/src/index.ts

@@ -0,0 +1,61 @@
+/**
+ * docker-sqlite - Reusable SQLite Docker setup with TypeScript utilities
+ *
+ * @example
+ * ```typescript
+ * import { withConnection, query, execute, runMigrations } from 'docker-sqlite';
+ *
+ * // Define migrations
+ * const migrations = [
+ *   {
+ *     version: 1,
+ *     description: 'Create users table',
+ *     up: 'CREATE TABLE users (id INTEGER PRIMARY KEY, name TEXT, email TEXT)',
+ *     down: 'DROP TABLE users'
+ *   }
+ * ];
+ *
+ * // Run with auto-save
+ * await withConnection({ dbPath: './data/app.db' }, (db) => {
+ *   runMigrations(db, migrations);
+ *
+ *   execute(db, 'INSERT INTO users (name, email) VALUES (?, ?)', ['Alice', 'alice@example.com']);
+ *
+ *   const result = query(db, 'SELECT * FROM users');
+ *   console.log(result.rows);
+ * });
+ * ```
+ */
+
+// Types
+export type {
+  ConnectionConfig,
+  ConnectionCallback,
+  QueryResult,
+  ExecuteResult,
+  Migration,
+  MigrationStatus,
+} from "./types.js";
+
+// Connection utilities
+export { withConnection, createConnection } from "./connect.js";
+
+// Query utilities
+export {
+  query,
+  execute,
+  execMultiple,
+  lastInsertRowId,
+  tableExists,
+} from "./query.js";
+
+// Migration utilities
+export {
+  getMigrationStatus,
+  runMigrations,
+  rollbackMigration,
+  createMigration,
+} from "./migrate.js";
+
+// Re-export sql.js Database type for convenience
+export type { Database } from "sql.js";