@humbdb/sqlite 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Humb contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,7 @@
+# @humbdb/sqlite
+
+SQLite driver for Humb. Implements the `DatabaseAdapter` contract from `@humbdb/driver-contract`.
+
+The whole connection is opened in read-only mode (`better-sqlite3`'s `readonly: true`) - the
+authoritative read-only backstop, equivalent to `@humbdb/postgres`'s `READ ONLY` transaction. See
+[`docs/product-specs/connect-and-inspect-sqlite.md`](../../../docs/product-specs/connect-and-inspect-sqlite.md).

package/dist/index.d.ts

@@ -0,0 +1,23 @@
+import { ConnectionTarget, DatabaseOverview, TableMetadata, RowPage } from '@humbdb/core';
+import { DatabaseAdapter, AdapterFactory } from '@humbdb/driver-contract';
+export { ReadOnlyViolationError, assertReadOnly } from '@humbdb/driver-contract';
+
+declare class SqliteAdapter implements DatabaseAdapter {
+    private readonly target;
+    readonly engine = "sqlite";
+    private db;
+    constructor(target: ConnectionTarget);
+    private getDb;
+    connect(): Promise<void>;
+    disconnect(): Promise<void>;
+    ping(): Promise<boolean>;
+    getVersion(): Promise<string>;
+    getOverview(): Promise<DatabaseOverview>;
+    getTable(schema: string, table: string): Promise<TableMetadata>;
+    getRows(schema: string, table: string, page: number, pageSize: number): Promise<RowPage>;
+    runReadOnlyQuery(sql: string): Promise<RowPage>;
+}
+/** Factory that creates {@link SqliteAdapter} instances for SQLite targets. */
+declare const sqliteAdapterFactory: AdapterFactory;
+
+export { SqliteAdapter, sqliteAdapterFactory };

package/dist/index.js

@@ -0,0 +1,113 @@
+// src/index.ts
+import { resolve } from "path";
+import { assertReadOnly, resolvePageRequest } from "@humbdb/driver-contract";
+import Database from "better-sqlite3";
+import { assertReadOnly as assertReadOnly2, ReadOnlyViolationError } from "@humbdb/driver-contract";
+var MAIN_SCHEMA = "main";
+function quoteIdent(name) {
+  return `"${name.replace(/"/g, '""')}"`;
+}
+function fetchIndexes(db, table) {
+  const indexList = db.pragma(`index_list(${quoteIdent(table)})`);
+  return indexList.map((index) => {
+    const indexInfo = db.pragma(`index_info(${quoteIdent(index.name)})`);
+    return {
+      name: index.name,
+      columns: indexInfo.map((column) => column.name),
+      unique: index.unique === 1,
+      primary: index.origin === "pk"
+    };
+  });
+}
+var SqliteAdapter = class {
+  constructor(target) {
+    this.target = target;
+  }
+  target;
+  engine = "sqlite";
+  db;
+  getDb() {
+    if (!this.db) {
+      throw new Error("SqliteAdapter is not connected. Call connect() first.");
+    }
+    return this.db;
+  }
+  async connect() {
+    this.db = new Database(resolve(this.target.raw), { readonly: true, fileMustExist: true });
+  }
+  async disconnect() {
+    this.db?.close();
+    this.db = void 0;
+  }
+  async ping() {
+    const row = this.getDb().prepare("SELECT 1 AS ok").get();
+    return row?.ok === 1;
+  }
+  async getVersion() {
+    const row = this.getDb().prepare("SELECT sqlite_version() AS version").get();
+    return `SQLite ${row.version}`;
+  }
+  async getOverview() {
+    const tables = this.getDb().prepare(
+      "SELECT name FROM sqlite_master WHERE type = 'table' AND name NOT LIKE 'sqlite_%' ORDER BY name"
+    ).all();
+    const schemas = [
+      { name: MAIN_SCHEMA, tables: tables.map((row) => row.name) }
+    ];
+    return { engine: "sqlite", schemas };
+  }
+  async getTable(schema, table) {
+    const db = this.getDb();
+    const tableInfo = db.pragma(`table_info(${quoteIdent(table)})`);
+    const foreignKeyList = db.pragma(
+      `foreign_key_list(${quoteIdent(table)})`
+    );
+    const foreignKeys = new Set(foreignKeyList.map((fk) => fk.from));
+    const columns = tableInfo.map((row) => ({
+      name: row.name,
+      // SQLite's declared column type is a free-form string (may even be empty) - "" reads
+      // awkwardly in the UI, so fall back to a neutral placeholder rather than an empty cell.
+      dataType: row.type || "any",
+      nullable: row.notnull === 0,
+      isPrimaryKey: row.pk > 0,
+      isForeignKey: foreignKeys.has(row.name)
+    }));
+    const indexes = fetchIndexes(db, table);
+    const { count } = db.prepare(`SELECT COUNT(*) AS count FROM ${quoteIdent(table)}`).get();
+    return { schema, name: table, columns, indexes, rowCount: count };
+  }
+  async getRows(schema, table, page, pageSize) {
+    const { page: safePage, pageSize: safePageSize, offset } = resolvePageRequest(page, pageSize);
+    const stmt = this.getDb().prepare(`SELECT * FROM ${quoteIdent(table)} LIMIT ? OFFSET ?`);
+    const rows = stmt.all(safePageSize, offset);
+    return {
+      columns: stmt.columns().map((column) => column.name),
+      rows,
+      page: safePage,
+      pageSize: safePageSize
+    };
+  }
+  async runReadOnlyQuery(sql) {
+    assertReadOnly(sql);
+    const stmt = this.getDb().prepare(sql);
+    const rows = stmt.all();
+    return {
+      columns: stmt.columns().map((column) => column.name),
+      rows,
+      page: 0,
+      pageSize: rows.length
+    };
+  }
+};
+var sqliteAdapterFactory = {
+  engine: "sqlite",
+  supports: (target) => target.engine === "sqlite",
+  create: (target) => new SqliteAdapter(target)
+};
+export {
+  ReadOnlyViolationError,
+  SqliteAdapter,
+  assertReadOnly2 as assertReadOnly,
+  sqliteAdapterFactory
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts"],"sourcesContent":["/**\n * SQLite driver for Humb.\n *\n * Implements the engine-agnostic {@link DatabaseAdapter} contract from `@humbdb/driver-contract`.\n * See ARCHITECTURE.md and docs/product-specs/connect-and-inspect-sqlite.md.\n */\nimport { resolve } from \"node:path\";\nimport type {\n  ColumnMetadata,\n  ConnectionTarget,\n  DatabaseOverview,\n  IndexMetadata,\n  RowPage,\n  SchemaMetadata,\n  TableMetadata\n} from \"@humbdb/core\";\nimport { assertReadOnly, resolvePageRequest } from \"@humbdb/driver-contract\";\nimport type { AdapterFactory, DatabaseAdapter } from \"@humbdb/driver-contract\";\nimport Database from \"better-sqlite3\";\n\nexport { assertReadOnly, ReadOnlyViolationError } from \"@humbdb/driver-contract\";\n\n/** SQLite has a single implicit namespace; the UI still expects a schema name, per the spec. */\nconst MAIN_SCHEMA = \"main\";\n\n/** Quote a SQL identifier safely (SQLite uses the standard `\"...\"` convention, like Postgres). */\nfunction quoteIdent(name: string): string {\n  return `\"${name.replace(/\"/g, '\"\"')}\"`;\n}\n\ninterface TableInfoRow {\n  cid: number;\n  name: string;\n  type: string;\n  notnull: number;\n  dflt_value: unknown;\n  pk: number;\n}\n\ninterface IndexListRow {\n  seq: number;\n  name: string;\n  unique: number;\n  origin: \"c\" | \"u\" | \"pk\";\n  partial: number;\n}\n\ninterface IndexInfoRow {\n  seqno: number;\n  cid: number;\n  name: string;\n}\n\ninterface ForeignKeyListRow {\n  id: number;\n  seq: number;\n  table: string;\n  from: string;\n  to: string | null;\n  on_update: string;\n  on_delete: string;\n  match: string;\n}\n\n/** Fetch index metadata for a table via SQLite's pragmas. */\nfunction fetchIndexes(db: Database.Database, table: string): IndexMetadata[] {\n  const indexList = db.pragma(`index_list(${quoteIdent(table)})`) as IndexListRow[];\n  return indexList.map((index) => {\n    const indexInfo = db.pragma(`index_info(${quoteIdent(index.name)})`) as IndexInfoRow[];\n    return {\n      name: index.name,\n      columns: indexInfo.map((column) => column.name),\n      unique: index.unique === 1,\n      primary: index.origin === \"pk\"\n    };\n  });\n}\n\nexport class SqliteAdapter implements DatabaseAdapter {\n  public readonly engine = \"sqlite\";\n  private db: Database.Database | undefined;\n\n  constructor(private readonly target: ConnectionTarget) {}\n\n  private getDb(): Database.Database {\n    if (!this.db) {\n      throw new Error(\"SqliteAdapter is not connected. Call connect() first.\");\n    }\n    return this.db;\n  }\n\n  async connect(): Promise<void> {\n    // The whole connection is opened read-only - the authoritative backstop, equivalent to\n    // @humbdb/postgres's READ ONLY transaction (see runReadOnlyQuery below and the product spec).\n    // SQLite itself refuses any write through this handle, regardless of what assertReadOnly's\n    // string scan misses.\n    this.db = new Database(resolve(this.target.raw), { readonly: true, fileMustExist: true });\n  }\n\n  async disconnect(): Promise<void> {\n    this.db?.close();\n    this.db = undefined;\n  }\n\n  async ping(): Promise<boolean> {\n    const row = this.getDb().prepare(\"SELECT 1 AS ok\").get() as { ok: number } | undefined;\n    return row?.ok === 1;\n  }\n\n  async getVersion(): Promise<string> {\n    const row = this.getDb().prepare(\"SELECT sqlite_version() AS version\").get() as {\n      version: string;\n    };\n    return `SQLite ${row.version}`;\n  }\n\n  async getOverview(): Promise<DatabaseOverview> {\n    const tables = this.getDb()\n      .prepare(\n        \"SELECT name FROM sqlite_master WHERE type = 'table' AND name NOT LIKE 'sqlite_%' ORDER BY name\"\n      )\n      .all() as Array<{ name: string }>;\n\n    const schemas: SchemaMetadata[] = [\n      { name: MAIN_SCHEMA, tables: tables.map((row) => row.name) }\n    ];\n\n    return { engine: \"sqlite\", schemas };\n  }\n\n  async getTable(schema: string, table: string): Promise<TableMetadata> {\n    const db = this.getDb();\n    const tableInfo = db.pragma(`table_info(${quoteIdent(table)})`) as TableInfoRow[];\n    const foreignKeyList = db.pragma(\n      `foreign_key_list(${quoteIdent(table)})`\n    ) as ForeignKeyListRow[];\n    const foreignKeys = new Set(foreignKeyList.map((fk) => fk.from));\n\n    const columns: ColumnMetadata[] = tableInfo.map((row) => ({\n      name: row.name,\n      // SQLite's declared column type is a free-form string (may even be empty) - \"\" reads\n      // awkwardly in the UI, so fall back to a neutral placeholder rather than an empty cell.\n      dataType: row.type || \"any\",\n      nullable: row.notnull === 0,\n      isPrimaryKey: row.pk > 0,\n      isForeignKey: foreignKeys.has(row.name)\n    }));\n\n    const indexes = fetchIndexes(db, table);\n\n    const { count } = db.prepare(`SELECT COUNT(*) AS count FROM ${quoteIdent(table)}`).get() as {\n      count: number;\n    };\n\n    return { schema, name: table, columns, indexes, rowCount: count };\n  }\n\n  async getRows(schema: string, table: string, page: number, pageSize: number): Promise<RowPage> {\n    const { page: safePage, pageSize: safePageSize, offset } = resolvePageRequest(page, pageSize);\n\n    const stmt = this.getDb().prepare(`SELECT * FROM ${quoteIdent(table)} LIMIT ? OFFSET ?`);\n    const rows = stmt.all(safePageSize, offset) as Array<Record<string, unknown>>;\n\n    return {\n      columns: stmt.columns().map((column) => column.name),\n      rows,\n      page: safePage,\n      pageSize: safePageSize\n    };\n  }\n\n  async runReadOnlyQuery(sql: string): Promise<RowPage> {\n    assertReadOnly(sql);\n\n    // assertReadOnly is a heuristic string check; the read-only connection opened in connect() is\n    // the authoritative guarantee - SQLite refuses any write through this handle regardless of\n    // what the string check missed (see connect()'s comment).\n    const stmt = this.getDb().prepare(sql);\n    const rows = stmt.all() as Array<Record<string, unknown>>;\n\n    return {\n      columns: stmt.columns().map((column) => column.name),\n      rows,\n      page: 0,\n      pageSize: rows.length\n    };\n  }\n}\n\n/** Factory that creates {@link SqliteAdapter} instances for SQLite targets. */\nexport const sqliteAdapterFactory: AdapterFactory = {\n  engine: \"sqlite\",\n  supports: (target) => target.engine === \"sqlite\",\n  create: (target) => new SqliteAdapter(target)\n};\n"],"mappings":"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","names":["assertReadOnly"]}

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "@humbdb/sqlite",
+  "version": "0.0.1",
+  "type": "module",
+  "description": "SQLite driver for Humb.",
+  "license": "MIT",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "better-sqlite3": "^11.10.0",
+    "@humbdb/core": "0.0.1",
+    "@humbdb/driver-contract": "0.0.1"
+  },
+  "devDependencies": {
+    "@types/better-sqlite3": "^7.6.13",
+    "@humbdb/config": "0.0.0"
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "clean": "rimraf dist .turbo"
+  }
+}