@mark1russell7/docker-sqlite 0.0.0-stage → 0.1.1

package/dist/migrate.js

@@ -0,0 +1,254 @@
+/**
+ * Migration utilities for SQLite
+ */
+import { query, execute, execMultiple } from "./query.js";
+/**
+ * Schema for tracking migrations
+ */
+const MIGRATIONS_TABLE_SQL = `
+  CREATE TABLE IF NOT EXISTS _migrations (
+    version INTEGER PRIMARY KEY,
+    description TEXT NOT NULL,
+    applied_at TEXT NOT NULL DEFAULT (datetime('now'))
+  )
+`;
+/**
+ * Ensure the migrations table exists
+ */
+function ensureMigrationsTable(db) {
+    execMultiple(db, MIGRATIONS_TABLE_SQL);
+}
+/** The name of the savepoint that holds one migration and its record. */
+const SAVEPOINT = "docker_sqlite_migration";
+/**
+ * The first words of the statements that control transactions, cannot run in a transaction
+ * (VACUUM, ATTACH) or can do nothing there (PRAGMA foreign_keys).
+ */
+const OUTSIDE_A_TRANSACTION = new Set([
+    "BEGIN",
+    "COMMIT",
+    "END",
+    "ROLLBACK",
+    "SAVEPOINT",
+    "RELEASE",
+    "VACUUM",
+    "ATTACH",
+    "DETACH",
+    "PRAGMA",
+]);
+/**
+ * The tokens of SQL text: the words in upper case, ";" for each semicolon, and "?" for each
+ * other token. Comments are skipped. A string or a quoted name is one "?" token, so a word in it
+ * is not a keyword.
+ */
+function* tokens(sql) {
+    const word = /[\p{L}_][\p{L}\p{N}_$]*/uy;
+    let i = 0;
+    while (i < sql.length) {
+        const c = sql[i];
+        if (/\s/.test(c)) {
+            i++;
+        }
+        else if (c === "-" && sql[i + 1] === "-") {
+            const end = sql.indexOf("\n", i);
+            i = end < 0 ? sql.length : end + 1;
+        }
+        else if (c === "/" && sql[i + 1] === "*") {
+            const end = sql.indexOf("*/", i + 2);
+            i = end < 0 ? sql.length : end + 2;
+        }
+        else if (c === "'" || c === '"' || c === "`" || c === "[") {
+            // A quote in the text is two quotes. A name in brackets cannot hold "]".
+            const close = c === "[" ? "]" : c;
+            let end = sql.indexOf(close, i + 1);
+            while (end >= 0 && close !== "]" && sql[end + 1] === close) {
+                end = sql.indexOf(close, end + 2);
+            }
+            i = end < 0 ? sql.length : end + 1;
+            yield "?";
+        }
+        else if (c === ";") {
+            i++;
+            yield ";";
+        }
+        else {
+            word.lastIndex = i;
+            const match = word.exec(sql);
+            if (match) {
+                i += match[0].length;
+                yield match[0].toUpperCase();
+            }
+            else {
+                i++;
+                yield "?";
+            }
+        }
+    }
+}
+/**
+ * The first word of each statement of `sql`, in upper case. The statements in the body of a
+ * trigger are part of the trigger: like sqlite3_complete(), the trigger ends at "; END ;".
+ */
+function statementKeywords(sql) {
+    const keywords = [];
+    let words = [];
+    let trigger = false;
+    let afterSemicolon = false;
+    let afterEnd = false;
+    for (const token of tokens(sql)) {
+        if (token === ";") {
+            if (!trigger || afterEnd) {
+                words = [];
+                trigger = false;
+                afterEnd = false;
+            }
+            else {
+                afterSemicolon = true;
+            }
+            continue;
+        }
+        if (words.length === 0) {
+            keywords.push(token);
+        }
+        if (words.length < 3) {
+            words.push(token);
+            const [first, second, third] = words;
+            trigger ||=
+                first === "CREATE" &&
+                    (second === "TRIGGER" || ((second === "TEMP" || second === "TEMPORARY") && third === "TRIGGER"));
+        }
+        afterEnd = trigger && afterSemicolon && token === "END";
+        afterSemicolon = false;
+    }
+    return keywords;
+}
+/**
+ * Run `work` in a savepoint: its changes stay only when it succeeds. Before, a migration that
+ * failed after its first statement kept the changes of those statements, and was not recorded:
+ * the next run ran it again and failed ("table already exists").
+ *
+ * A savepoint also works in a transaction of the caller, and keeps that transaction open. SQL
+ * that controls transactions itself (BEGIN, COMMIT, VACUUM, PRAGMA and the others in
+ * OUTSIDE_A_TRANSACTION) runs without a savepoint, as before: in a transaction it fails or does
+ * nothing.
+ */
+function atomically(db, sql, work) {
+    if (statementKeywords(sql).some((keyword) => OUTSIDE_A_TRANSACTION.has(keyword))) {
+        work();
+        return;
+    }
+    db.exec(`SAVEPOINT ${SAVEPOINT}`);
+    try {
+        work();
+        db.exec(`RELEASE ${SAVEPOINT}`);
+    }
+    catch (error) {
+        try {
+            db.exec(`ROLLBACK TO ${SAVEPOINT}`);
+            db.exec(`RELEASE ${SAVEPOINT}`);
+        }
+        catch {
+            // Some errors end the transaction (ON CONFLICT ROLLBACK): then the savepoint is gone
+        }
+        throw error;
+    }
+}
+/**
+ * Get the current migration status
+ */
+export function getMigrationStatus(db, migrations) {
+    ensureMigrationsTable(db);
+    const applied = query(db, "SELECT version FROM _migrations ORDER BY version");
+    const appliedVersions = new Set(applied.rows.map((r) => r.version));
+    const appliedMigrations = [...appliedVersions].sort((a, b) => a - b);
+    const currentVersion = appliedMigrations.length > 0
+        ? appliedMigrations[appliedMigrations.length - 1]
+        : 0;
+    const pendingMigrations = migrations
+        .filter((m) => !appliedVersions.has(m.version))
+        .sort((a, b) => a.version - b.version);
+    return {
+        currentVersion,
+        appliedMigrations,
+        pendingMigrations,
+    };
+}
+/**
+ * Run all pending migrations
+ *
+ * @example
+ * ```typescript
+ * const migrations: Migration[] = [
+ *   {
+ *     version: 1,
+ *     description: 'Create users table',
+ *     up: 'CREATE TABLE users (id INTEGER PRIMARY KEY, name TEXT)',
+ *     down: 'DROP TABLE users'
+ *   },
+ *   {
+ *     version: 2,
+ *     description: 'Add email column',
+ *     up: 'ALTER TABLE users ADD COLUMN email TEXT',
+ *   }
+ * ];
+ *
+ * const applied = runMigrations(db, migrations);
+ * console.log(`Applied ${applied.length} migrations`);
+ * ```
+ */
+export function runMigrations(db, migrations) {
+    const status = getMigrationStatus(db, migrations);
+    const applied = [];
+    for (const migration of status.pendingMigrations) {
+        try {
+            // Run the migration and record it as applied, in one savepoint
+            atomically(db, migration.up, () => {
+                execMultiple(db, migration.up);
+                execute(db, "INSERT INTO _migrations (version, description) VALUES (?, ?)", [migration.version, migration.description]);
+            });
+            applied.push(migration);
+        }
+        catch (error) {
+            throw new Error(`Failed to apply migration ${migration.version} (${migration.description}): ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+    return applied;
+}
+/**
+ * Rollback the last applied migration
+ */
+export function rollbackMigration(db, migrations) {
+    const status = getMigrationStatus(db, migrations);
+    if (status.currentVersion === 0) {
+        return null;
+    }
+    const migration = migrations.find((m) => m.version === status.currentVersion);
+    if (!migration) {
+        throw new Error(`Migration ${status.currentVersion} not found in migrations list`);
+    }
+    if (!migration.down) {
+        throw new Error(`Migration ${migration.version} (${migration.description}) has no down migration`);
+    }
+    const down = migration.down;
+    try {
+        atomically(db, down, () => {
+            execMultiple(db, down);
+            execute(db, "DELETE FROM _migrations WHERE version = ?", [migration.version]);
+        });
+        return migration;
+    }
+    catch (error) {
+        throw new Error(`Failed to rollback migration ${migration.version}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+}
+/**
+ * Create a migration from SQL strings
+ */
+export function createMigration(version, description, up, down) {
+    const migration = { version, description, up };
+    if (down !== undefined) {
+        migration.down = down;
+    }
+    return migration;
+}
+//# sourceMappingURL=migrate.js.map

package/dist/migrate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"migrate.js","sourceRoot":"","sources":["../src/migrate.ts"],"names":[],"mappings":"AAAA;;GAEG;AAIH,OAAO,EAAE,KAAK,EAAE,OAAO,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAE1D;;GAEG;AACH,MAAM,oBAAoB,GAAG;;;;;;CAM5B,CAAC;AAEF;;GAEG;AACH,SAAS,qBAAqB,CAAC,EAAY;IACzC,YAAY,CAAC,EAAE,EAAE,oBAAoB,CAAC,CAAC;AACzC,CAAC;AAED,yEAAyE;AACzE,MAAM,SAAS,GAAG,yBAAyB,CAAC;AAE5C;;;GAGG;AACH,MAAM,qBAAqB,GAAG,IAAI,GAAG,CAAC;IACpC,OAAO;IACP,QAAQ;IACR,KAAK;IACL,UAAU;IACV,WAAW;IACX,SAAS;IACT,QAAQ;IACR,QAAQ;IACR,QAAQ;IACR,QAAQ;CACT,CAAC,CAAC;AAEH;;;;GAIG;AACH,QAAQ,CAAC,CAAC,MAAM,CAAC,GAAW;IAC1B,MAAM,IAAI,GAAG,2BAA2B,CAAC;IACzC,IAAI,CAAC,GAAG,CAAC,CAAC;IACV,OAAO,CAAC,GAAG,GAAG,CAAC,MAAM,EAAE,CAAC;QACtB,MAAM,CAAC,GAAG,GAAG,CAAC,CAAC,CAAE,CAAC;QAClB,IAAI,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC;YACjB,CAAC,EAAE,CAAC;QACN,CAAC;aAAM,IAAI,CAAC,KAAK,GAAG,IAAI,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,KAAK,GAAG,EAAE,CAAC;YAC3C,MAAM,GAAG,GAAG,GAAG,CAAC,OAAO,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC;YACjC,CAAC,GAAG,GAAG,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,GAAG,GAAG,CAAC,CAAC;QACrC,CAAC;aAAM,IAAI,CAAC,KAAK,GAAG,IAAI,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,KAAK,GAAG,EAAE,CAAC;YAC3C,MAAM,GAAG,GAAG,GAAG,CAAC,OAAO,CAAC,IAAI,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;YACrC,CAAC,GAAG,GAAG,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,GAAG,GAAG,CAAC,CAAC;QACrC,CAAC;aAAM,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC,KAAK,GAAG,EAAE,CAAC;YAC5D,yEAAyE;YACzE,MAAM,KAAK,GAAG,CAAC,KAAK,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;YAClC,IAAI,GAAG,GAAG,GAAG,CAAC,OAAO,CAAC,KAAK,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;YACpC,OAAO,GAAG,IAAI,CAAC,IAAI,KAAK,KAAK,GAAG,IAAI,GAAG,CAAC,GAAG,GAAG,CAAC,CAAC,KAAK,KAAK,EAAE,CAAC;gBAC3D,GAAG,GAAG,GAAG,CAAC,OAAO,CAAC,KAAK,EAAE,GAAG,GAAG,CAAC,CAAC,CAAC;YACpC,CAAC;YACD,CAAC,GAAG,GAAG,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,GAAG,GAAG,CAAC,CAAC;YACnC,MAAM,GAAG,CAAC;QACZ,CAAC;aAAM,IAAI,CAAC,KAAK,GAAG,EAAE,CAAC;YACrB,CAAC,EAAE,CAAC;YACJ,MAAM,GAAG,CAAC;QACZ,CAAC;aAAM,CAAC;YACN,IAAI,CAAC,SAAS,GAAG,CAAC,CAAC;YACnB,MAAM,KAAK,GAAG,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;YAC7B,IAAI,KAAK,EAAE,CAAC;gBACV,CAAC,IAAI,KAAK,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC;gBACrB,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,WAAW,EAAE,CAAC;YAC/B,CAAC;iBAAM,CAAC;gBACN,CAAC,EAAE,CAAC;gBACJ,MAAM,GAAG,CAAC;YACZ,CAAC;QACH,CAAC;IACH,CAAC;AACH,CAAC;AAED;;;GAGG;AACH,SAAS,iBAAiB,CAAC,GAAW;IACpC,MAAM,QAAQ,GAAa,EAAE,CAAC;IAC9B,IAAI,KAAK,GAAa,EAAE,CAAC;IACzB,IAAI,OAAO,GAAG,KAAK,CAAC;IACpB,IAAI,cAAc,GAAG,KAAK,CAAC;IAC3B,IAAI,QAAQ,GAAG,KAAK,CAAC;IACrB,KAAK,MAAM,KAAK,IAAI,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC;QAChC,IAAI,KAAK,KAAK,GAAG,EAAE,CAAC;YAClB,IAAI,CAAC,OAAO,IAAI,QAAQ,EAAE,CAAC;gBACzB,KAAK,GAAG,EAAE,CAAC;gBACX,OAAO,GAAG,KAAK,CAAC;gBAChB,QAAQ,GAAG,KAAK,CAAC;YACnB,CAAC;iBAAM,CAAC;gBACN,cAAc,GAAG,IAAI,CAAC;YACxB,CAAC;YACD,SAAS;QACX,CAAC;QACD,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YACvB,QAAQ,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QACvB,CAAC;QACD,IAAI,KAAK,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YACrB,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;YAClB,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,CAAC,GAAG,KAAK,CAAC;YACrC,OAAO;gBACL,KAAK,KAAK,QAAQ;oBAClB,CAAC,MAAM,KAAK,SAAS,IAAI,CAAC,CAAC,MAAM,KAAK,MAAM,IAAI,MAAM,KAAK,WAAW,CAAC,IAAI,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC;QACrG,CAAC;QACD,QAAQ,GAAG,OAAO,IAAI,cAAc,IAAI,KAAK,KAAK,KAAK,CAAC;QACxD,cAAc,GAAG,KAAK,CAAC;IACzB,CAAC;IACD,OAAO,QAAQ,CAAC;AAClB,CAAC;AAED;;;;;;;;;GASG;AACH,SAAS,UAAU,CAAC,EAAY,EAAE,GAAW,EAAE,IAAgB;IAC7D,IAAI,iBAAiB,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,qBAAqB,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,EAAE,CAAC;QACjF,IAAI,EAAE,CAAC;QACP,OAAO;IACT,CAAC;IACD,EAAE,CAAC,IAAI,CAAC,aAAa,SAAS,EAAE,CAAC,CAAC;IAClC,IAAI,CAAC;QACH,IAAI,EAAE,CAAC;QACP,EAAE,CAAC,IAAI,CAAC,WAAW,SAAS,EAAE,CAAC,CAAC;IAClC,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,IAAI,CAAC;YACH,EAAE,CAAC,IAAI,CAAC,eAAe,SAAS,EAAE,CAAC,CAAC;YACpC,EAAE,CAAC,IAAI,CAAC,WAAW,SAAS,EAAE,CAAC,CAAC;QAClC,CAAC;QAAC,MAAM,CAAC;YACP,qFAAqF;QACvF,CAAC;QACD,MAAM,KAAK,CAAC;IACd,CAAC;AACH,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,kBAAkB,CAChC,EAAY,EACZ,UAAuB;IAEvB,qBAAqB,CAAC,EAAE,CAAC,CAAC;IAE1B,MAAM,OAAO,GAAG,KAAK,CACnB,EAAE,EACF,kDAAkD,CACnD,CAAC;IAEF,MAAM,eAAe,GAAG,IAAI,GAAG,CAAC,OAAO,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC;IACpE,MAAM,iBAAiB,GAAG,CAAC,GAAG,eAAe,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;IACrE,MAAM,cAAc,GAClB,iBAAiB,CAAC,MAAM,GAAG,CAAC;QAC1B,CAAC,CAAC,iBAAiB,CAAC,iBAAiB,CAAC,MAAM,GAAG,CAAC,CAAE;QAClD,CAAC,CAAC,CAAC,CAAC;IAER,MAAM,iBAAiB,GAAG,UAAU;SACjC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,eAAe,CAAC,GAAG,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC;SAC9C,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,GAAG,CAAC,CAAC,OAAO,CAAC,CAAC;IAEzC,OAAO;QACL,cAAc;QACd,iBAAiB;QACjB,iBAAiB;KAClB,CAAC;AACJ,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,MAAM,UAAU,aAAa,CAAC,EAAY,EAAE,UAAuB;IACjE,MAAM,MAAM,GAAG,kBAAkB,CAAC,EAAE,EAAE,UAAU,CAAC,CAAC;IAClD,MAAM,OAAO,GAAgB,EAAE,CAAC;IAEhC,KAAK,MAAM,SAAS,IAAI,MAAM,CAAC,iBAAiB,EAAE,CAAC;QACjD,IAAI,CAAC;YACH,+DAA+D;YAC/D,UAAU,CAAC,EAAE,EAAE,SAAS,CAAC,EAAE,EAAE,GAAG,EAAE;gBAChC,YAAY,CAAC,EAAE,EAAE,SAAS,CAAC,EAAE,CAAC,CAAC;gBAC/B,OAAO,CACL,EAAE,EACF,8DAA8D,EAC9D,CAAC,SAAS,CAAC,OAAO,EAAE,SAAS,CAAC,WAAW,CAAC,CAC3C,CAAC;YACJ,CAAC,CAAC,CAAC;YAEH,OAAO,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;QAC1B,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,MAAM,IAAI,KAAK,CACb,6BAA6B,SAAS,CAAC,OAAO,KAAK,SAAS,CAAC,WAAW,MAAM,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,CACvI,CAAC;QACJ,CAAC;IACH,CAAC;IAED,OAAO,OAAO,CAAC;AACjB,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,iBAAiB,CAC/B,EAAY,EACZ,UAAuB;IAEvB,MAAM,MAAM,GAAG,kBAAkB,CAAC,EAAE,EAAE,UAAU,CAAC,CAAC;IAElD,IAAI,MAAM,CAAC,cAAc,KAAK,CAAC,EAAE,CAAC;QAChC,OAAO,IAAI,CAAC;IACd,CAAC;IAED,MAAM,SAAS,GAAG,UAAU,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,KAAK,MAAM,CAAC,cAAc,CAAC,CAAC;IAE9E,IAAI,CAAC,SAAS,EAAE,CAAC;QACf,MAAM,IAAI,KAAK,CAAC,aAAa,MAAM,CAAC,cAAc,+BAA+B,CAAC,CAAC;IACrF,CAAC;IAED,IAAI,CAAC,SAAS,CAAC,IAAI,EAAE,CAAC;QACpB,MAAM,IAAI,KAAK,CACb,aAAa,SAAS,CAAC,OAAO,KAAK,SAAS,CAAC,WAAW,yBAAyB,CAClF,CAAC;IACJ,CAAC;IAED,MAAM,IAAI,GAAG,SAAS,CAAC,IAAI,CAAC;IAC5B,IAAI,CAAC;QACH,UAAU,CAAC,EAAE,EAAE,IAAI,EAAE,GAAG,EAAE;YACxB,YAAY,CAAC,EAAE,EAAE,IAAI,CAAC,CAAC;YACvB,OAAO,CAAC,EAAE,EAAE,2CAA2C,EAAE,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC,CAAC;QAChF,CAAC,CAAC,CAAC;QACH,OAAO,SAAS,CAAC;IACnB,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,IAAI,KAAK,CACb,gCAAgC,SAAS,CAAC,OAAO,KAAK,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,CAC/G,CAAC;IACJ,CAAC;AACH,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,eAAe,CAC7B,OAAe,EACf,WAAmB,EACnB,EAAU,EACV,IAAa;IAEb,MAAM,SAAS,GAAc,EAAE,OAAO,EAAE,WAAW,EAAE,EAAE,EAAE,CAAC;IAC1D,IAAI,IAAI,KAAK,SAAS,EAAE,CAAC;QACvB,SAAS,CAAC,IAAI,GAAG,IAAI,CAAC;IACxB,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC"}

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,CAmBhB;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,120 @@
+/**
+ * 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);
+        // The statement knows its columns before the first step. Before, the columns came from the
+        // first row, so a result with no rows had no columns.
+        const columns = stmt.getColumnNames();
+        const rows = [];
+        while (stmt.step()) {
+            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,80 @@
 {
+  "$schema": "https://json.schemastore.org/package",
   "name": "@mark1russell7/docker-sqlite",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.1",
+  "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"
+  ],
+  "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
+  },
+  "scripts": {
+    "build": "tsc -b",
+    "typecheck": "tsc --noEmit",
+    "clean": "rm -rf dist .tsbuildinfo",
+    "test": "vitest run"
+  }
 }

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);