narai-primitives 2.0.0-rc.1

package/dist/connectors/db/lib/drivers/postgresql.js

@@ -0,0 +1,294 @@
+/**
+ * drivers/postgresql.ts — PostgreSQL driver via the `pg` package.
+ *
+ * Design:
+ *  - The driver owns a `pg.Pool` lazily created on the first `connect()`
+ *    call and cached for the lifetime of the driver instance. Each
+ *    `connect()` call checks out a client from the pool; `close()`
+ *    releases it back. The pool itself is destroyed by `shutdown()`,
+ *    which connection.ts is expected to call at process teardown.
+ *  - connection.ts calls `driver.connect(envConfig)` per
+ *    `getConnection()` invocation, so the lazy-pool + per-call checkout
+ *    gives us real pooling: N calls reuse M < N underlying sockets.
+ *  - Read-only: every `executeReadAsync` runs inside a `BEGIN READ ONLY`
+ *    transaction with a server-side `statement_timeout`.
+ *  - The native `pg` module is loaded with a dynamic `import()` so this
+ *    file compiles even when the package is not installed. On a missing
+ *    install, `connect()` throws a helpful `npm install pg @types/pg` hint.
+ */
+import { performance } from "node:perf_hooks";
+import { Column, DatabaseDriver, Table, } from "./base.js";
+import { classifySqlKeywords } from "../policy.js";
+export class PostgresDriver extends DatabaseDriver {
+    _pgModule = null;
+    _pool = null;
+    _schema = null;
+    _poolPromise = null;
+    async _loadPg() {
+        if (this._pgModule !== null)
+            return this._pgModule;
+        try {
+            const mod = (await import("pg"));
+            this._pgModule =
+                "Pool" in mod
+                    ? mod
+                    : mod.default;
+            return this._pgModule;
+        }
+        catch (e) {
+            throw new Error(`Driver 'postgresql' requires 'pg' — run: npm install pg @types/pg (${e.message})`);
+        }
+    }
+    /**
+     * Build the pool on first call; subsequent callers receive the cached
+     * instance (or await the in-flight creation promise to avoid racing
+     * two `new Pool()` calls on concurrent connects).
+     */
+    _ensurePool(envConfig) {
+        if (this._pool !== null)
+            return Promise.resolve(this._pool);
+        if (this._poolPromise !== null)
+            return this._poolPromise;
+        this._poolPromise = this._loadPg().then((pg) => {
+            const host = typeof envConfig["host"] === "string" ? envConfig["host"] : "localhost";
+            const port = typeof envConfig["port"] === "number" ? envConfig["port"] : 5432;
+            const database = typeof envConfig["database"] === "string" ? envConfig["database"] : "";
+            const user = typeof envConfig["user"] === "string" ? envConfig["user"] : undefined;
+            const password = typeof envConfig["password"] === "string"
+                ? envConfig["password"]
+                : undefined;
+            const ssl = envConfig["ssl"] === true
+                ? { rejectUnauthorized: false }
+                : typeof envConfig["ssl"] === "object" && envConfig["ssl"] !== null
+                    ? envConfig["ssl"]
+                    : undefined;
+            this._schema =
+                typeof envConfig["schema"] === "string" &&
+                    envConfig["schema"].length > 0
+                    ? envConfig["schema"]
+                    : null;
+            const poolConfig = {
+                host,
+                port,
+                database,
+                max: typeof envConfig["pool_max"] === "number"
+                    ? envConfig["pool_max"]
+                    : 10,
+                idleTimeoutMillis: 30_000,
+            };
+            if (user !== undefined)
+                poolConfig["user"] = user;
+            if (password !== undefined)
+                poolConfig["password"] = password;
+            if (ssl !== undefined)
+                poolConfig["ssl"] = ssl;
+            const pool = new pg.Pool(poolConfig);
+            this._pool = pool;
+            return pool;
+        });
+        return this._poolPromise;
+    }
+    /**
+     * Check out a client from the pool. connection.ts tracks one handle per
+     * `getConnection()` call; `close()` releases the client back to the pool.
+     */
+    connect(envConfig) {
+        return this._ensurePool(envConfig).then(async (pool) => {
+            const client = await pool.connect();
+            return { client, schema: this._schema };
+        });
+    }
+    executeRead(_conn, _query, _params = null, _maxRows = 1000, _timeoutMs = 30_000) {
+        return {
+            status: "error",
+            error_code: "SYNC_UNSUPPORTED",
+            error: "PostgresDriver.executeRead is async — call executeReadAsync() instead.",
+            execution_time_ms: 0,
+        };
+    }
+    async executeReadAsync(conn, query, params = null, maxRows = 1000, timeoutMs = 30_000) {
+        const handle = (await conn);
+        const start = performance.now();
+        try {
+            await handle.client.query(`SET statement_timeout = ${Math.max(1, timeoutMs)}`);
+            await handle.client.query("BEGIN READ ONLY");
+            if (handle.schema !== null) {
+                const safe = handle.schema.replace(/"/g, '""');
+                await handle.client.query(`SET LOCAL search_path TO "${safe}"`);
+            }
+            // G-LIMIT-WRAP: wrap as a subquery so bounded semantics hold even
+            // when the outer query has a trailing `-- limit` comment, a CTE
+            // with its own LIMIT, a FOR UPDATE clause, or a LIMIT on an inner
+            // SELECT that the old substring check mistook for the bound.
+            const inner = query.trim().replace(/;\s*$/, "");
+            const limited = `SELECT * FROM (${inner}) AS _limited LIMIT ${maxRows + 1}`;
+            const result = await handle.client.query(limited, params ?? []);
+            await handle.client.query("COMMIT");
+            let truncated = false;
+            let rows = result.rows;
+            if (rows.length > maxRows) {
+                truncated = true;
+                rows = rows.slice(0, maxRows);
+            }
+            return {
+                status: "success",
+                rows,
+                row_count: rows.length,
+                columns: result.fields.map((f) => f.name),
+                execution_time_ms: roundTo2(performance.now() - start),
+                truncated,
+            };
+        }
+        catch (e) {
+            try {
+                await handle.client.query("ROLLBACK");
+            }
+            catch {
+                /* best-effort */
+            }
+            return {
+                status: "error",
+                error_code: "SQL_ERROR",
+                error: e.message,
+                execution_time_ms: roundTo2(performance.now() - start),
+            };
+        }
+    }
+    getSchema(_conn, _schemaName = "", _tableFilter = null) {
+        return [];
+    }
+    async getSchemaAsync(conn, schemaName = "", tableFilter = null) {
+        const handle = (await conn);
+        const ns = schemaName.length > 0 ? schemaName : (handle.schema ?? "public");
+        try {
+            const tableParams = [ns];
+            let tableSql = "SELECT table_name FROM information_schema.tables " +
+                "WHERE table_schema = $1 AND table_type = 'BASE TABLE'";
+            if (tableFilter !== null && tableFilter !== undefined) {
+                tableSql += " AND table_name LIKE $2 ESCAPE '!'";
+                tableParams.push(tableFilter.replace(/[!_%]/g, "!$&"));
+            }
+            tableSql += " ORDER BY table_name";
+            const tablesResult = await handle.client.query(tableSql, tableParams);
+            const tableNames = tablesResult.rows.map((r) => String(r["table_name"]));
+            if (tableNames.length === 0)
+                return [];
+            // G-SCHEMA-BATCH: fold per-table queries into two set-based queries
+            // using PostgreSQL's `= ANY($N::text[])`. For N tables we drop from
+            // 2N+1 round-trips (tables + N columns + N PKs) to 3.
+            const colsResult = await handle.client.query("SELECT table_name, column_name, data_type, is_nullable, column_default, ordinal_position " +
+                "FROM information_schema.columns " +
+                "WHERE table_schema = $1 AND table_name = ANY($2::text[]) " +
+                "ORDER BY table_name, ordinal_position", [ns, tableNames]);
+            const pkResult = await handle.client.query("SELECT c.relname AS table_name, a.attname AS column_name " +
+                "FROM pg_index i " +
+                "JOIN pg_class c ON c.oid = i.indrelid " +
+                "JOIN pg_namespace nsp ON nsp.oid = c.relnamespace " +
+                "JOIN pg_attribute a ON a.attrelid = i.indrelid AND a.attnum = ANY(i.indkey) " +
+                "WHERE nsp.nspname = $1 AND c.relname = ANY($2::text[]) AND i.indisprimary", [ns, tableNames]);
+            const pksByTable = new Map();
+            for (const r of pkResult.rows) {
+                const t = String(r["table_name"]);
+                let set = pksByTable.get(t);
+                if (set === undefined) {
+                    set = new Set();
+                    pksByTable.set(t, set);
+                }
+                set.add(String(r["column_name"]));
+            }
+            const colsByTable = new Map();
+            for (const r of colsResult.rows) {
+                const t = String(r["table_name"]);
+                let list = colsByTable.get(t);
+                if (list === undefined) {
+                    list = [];
+                    colsByTable.set(t, list);
+                }
+                const name = String(r["column_name"]);
+                list.push(new Column({
+                    name,
+                    data_type: String(r["data_type"]),
+                    nullable: String(r["is_nullable"]).toUpperCase() === "YES",
+                    is_primary_key: pksByTable.get(t)?.has(name) ?? false,
+                    default: r["column_default"] === null
+                        ? null
+                        : String(r["column_default"]),
+                }));
+            }
+            const out = [];
+            for (const tableName of tableNames) {
+                out.push(new Table({
+                    name: tableName,
+                    schema: ns,
+                    columns: colsByTable.get(tableName) ?? [],
+                }));
+            }
+            return out;
+        }
+        catch {
+            return [];
+        }
+    }
+    /**
+     * Release the checked-out client back to the pool. Does NOT destroy
+     * the pool — use {@link shutdown} for that.
+     */
+    close(conn) {
+        Promise.resolve(conn)
+            .then((h) => h.client.release())
+            .catch((e) => {
+            // G-CLOSE-LOG: surface release errors on stderr instead of
+            // swallowing them. close() is called from sync cleanup paths
+            // so we cannot await; keep it fire-and-forget but at least
+            // give an operator something to grep for in a misbehaving run.
+            process.stderr.write(`[postgresql] release error (best-effort): ${e instanceof Error ? e.message : String(e)}\n`);
+        });
+    }
+    classifyOperation(query) {
+        return classifySqlKeywords(query);
+    }
+    async closeAsync(conn) {
+        const handle = (await conn);
+        try {
+            handle.client.release();
+        }
+        catch {
+            /* best-effort */
+        }
+    }
+    /**
+     * Per-driver health check. Runs `SELECT 1` on the given handle. Caller
+     * still owns the handle and is responsible for {@link close}-ing it.
+     */
+    async healthCheck(conn) {
+        try {
+            const handle = (await conn);
+            const r = await handle.client.query("SELECT 1");
+            return r.rowCount !== null && r.rowCount >= 0;
+        }
+        catch {
+            return false;
+        }
+    }
+    /**
+     * Drain and destroy the pool. connection.ts's `shutdownAll()` fans out
+     * to each driver instance; this is where we actually close sockets.
+     */
+    async shutdown() {
+        const pool = this._pool;
+        this._pool = null;
+        this._poolPromise = null;
+        if (pool !== null) {
+            try {
+                await pool.end();
+            }
+            catch {
+                /* best-effort */
+            }
+        }
+    }
+}
+function roundTo2(n) {
+    return Math.round(n * 100) / 100;
+}
+//# sourceMappingURL=postgresql.js.map

package/dist/connectors/db/lib/drivers/postgresql.js.map

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

package/dist/connectors/db/lib/drivers/register.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Dynamic-import and register the driver backing a given name (or alias).
+ * Throws if `name` is not a recognized driver key; callers should propagate
+ * this through to the CLI where it surfaces as a validation error.
+ */
+export declare function ensureDriver(name: string): Promise<void>;
+/**
+ * Load and register every shipped driver. Used by tests that want the
+ * full registry available and by explicit library consumers. Prefer
+ * `ensureDriver(name)` in production code paths so only the drivers
+ * actually in use get pulled into memory.
+ */
+export declare function registerAll(): Promise<void>;
+/** Test helper — drop the loaded-driver memo so dynamic imports re-run. */
+export declare function _resetLoadedDrivers(): void;
+//# sourceMappingURL=register.d.ts.map

package/dist/connectors/db/lib/drivers/register.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"register.d.ts","sourceRoot":"","sources":["../../../../../src/connectors/db/lib/drivers/register.ts"],"names":[],"mappings":"AA+CA;;;;GAIG;AACH,wBAAsB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAuD9D;AAED;;;;;GAKG;AACH,wBAAsB,WAAW,IAAI,OAAO,CAAC,IAAI,CAAC,CAGjD;AAED,2EAA2E;AAC3E,wBAAgB,mBAAmB,IAAI,IAAI,CAE1C"}

package/dist/connectors/db/lib/drivers/register.js

@@ -0,0 +1,111 @@
+/**
+ * drivers/register.ts — Lazy driver loader.
+ *
+ * Replaces the v1 eager `registerAll()` (which pulled every optional Phase E
+ * dep into memory on `import "./lib"`) with an alias-aware `ensureDriver(name)`
+ * that dynamic-imports the requested driver module on demand. Idempotent —
+ * a second call for the same driver is a no-op.
+ *
+ * Call sites:
+ *  - `connection.getConnection(envName)` awaits `ensureDriver(driverName)`
+ *    before the factory lookup.
+ *  - Tests that want every driver wired up can `await registerAll()`, which
+ *    resolves all of them in parallel.
+ *
+ * Heavy optional deps (`pg`, `mysql2`, `mssql`, `mongodb`,
+ * `@aws-sdk/client-dynamodb`) therefore only load when a config references
+ * the corresponding driver name.
+ */
+import { listDriverFactories, registerDriverFactory } from "../connection.js";
+const ALIASES = {
+    sqlite: "sqlite",
+    postgresql: "postgresql",
+    postgres: "postgresql",
+    mysql: "mysql",
+    sqlserver: "sqlserver",
+    mssql: "sqlserver",
+    mongodb: "mongodb",
+    mongo: "mongodb",
+    dynamodb: "dynamodb",
+    dynamo: "dynamodb",
+    oracle: "oracle",
+    oracledb: "oracle",
+    oci: "oracle",
+};
+const _loaded = new Set();
+/**
+ * Dynamic-import and register the driver backing a given name (or alias).
+ * Throws if `name` is not a recognized driver key; callers should propagate
+ * this through to the CLI where it surfaces as a validation error.
+ */
+export async function ensureDriver(name) {
+    // If a factory is already registered (including test-only mock drivers),
+    // leave it alone — the caller's factory wins.
+    if (listDriverFactories().includes(name))
+        return;
+    const key = ALIASES[name];
+    if (key === undefined) {
+        throw new Error(`unknown driver: '${name}' (valid: ${Object.keys(ALIASES).sort().join(", ")})`);
+    }
+    if (_loaded.has(key))
+        return;
+    switch (key) {
+        case "sqlite": {
+            const m = await import("./sqlite.js");
+            registerDriverFactory("sqlite", () => new m.SQLiteDriver());
+            break;
+        }
+        case "postgresql": {
+            const m = await import("./postgresql.js");
+            registerDriverFactory("postgresql", () => new m.PostgresDriver());
+            registerDriverFactory("postgres", () => new m.PostgresDriver());
+            break;
+        }
+        case "mysql": {
+            const m = await import("./mysql.js");
+            registerDriverFactory("mysql", () => new m.MysqlDriver());
+            break;
+        }
+        case "sqlserver": {
+            const m = await import("./sqlserver.js");
+            registerDriverFactory("sqlserver", () => new m.SqlServerDriver());
+            registerDriverFactory("mssql", () => new m.SqlServerDriver());
+            break;
+        }
+        case "mongodb": {
+            const m = await import("./mongodb.js");
+            registerDriverFactory("mongodb", () => new m.MongoDriver());
+            registerDriverFactory("mongo", () => new m.MongoDriver());
+            break;
+        }
+        case "dynamodb": {
+            const m = await import("./dynamodb.js");
+            registerDriverFactory("dynamodb", () => new m.DynamoDriver());
+            registerDriverFactory("dynamo", () => new m.DynamoDriver());
+            break;
+        }
+        case "oracle": {
+            const m = await import("./oracle.js");
+            registerDriverFactory("oracle", () => new m.OracleDriver());
+            registerDriverFactory("oracledb", () => new m.OracleDriver());
+            registerDriverFactory("oci", () => new m.OracleDriver());
+            break;
+        }
+    }
+    _loaded.add(key);
+}
+/**
+ * Load and register every shipped driver. Used by tests that want the
+ * full registry available and by explicit library consumers. Prefer
+ * `ensureDriver(name)` in production code paths so only the drivers
+ * actually in use get pulled into memory.
+ */
+export async function registerAll() {
+    const unique = [...new Set(Object.values(ALIASES))];
+    await Promise.all(unique.map((k) => ensureDriver(k)));
+}
+/** Test helper — drop the loaded-driver memo so dynamic imports re-run. */
+export function _resetLoadedDrivers() {
+    _loaded.clear();
+}
+//# sourceMappingURL=register.js.map

package/dist/connectors/db/lib/drivers/register.js.map

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

package/dist/connectors/db/lib/drivers/sqlite.d.ts

@@ -0,0 +1,11 @@
+import Database from "better-sqlite3";
+import { DatabaseDriver, Table, type ExecuteReadResult } from "./base.js";
+import { type OperationType } from "../policy.js";
+export declare class SQLiteDriver extends DatabaseDriver {
+    connect(envConfig: Record<string, unknown>): Database.Database;
+    executeRead(conn: unknown, query: string, params?: unknown[] | null, maxRows?: number, _timeoutMs?: number): ExecuteReadResult;
+    getSchema(conn: unknown, schemaName?: string, tableFilter?: string | null): Table[];
+    close(conn: unknown): void;
+    classifyOperation(query: string): OperationType;
+}
+//# sourceMappingURL=sqlite.d.ts.map

package/dist/connectors/db/lib/drivers/sqlite.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sqlite.d.ts","sourceRoot":"","sources":["../../../../../src/connectors/db/lib/drivers/sqlite.ts"],"names":[],"mappings":"AAmBA,OAAO,QAAQ,MAAM,gBAAgB,CAAC;AACtC,OAAO,EAEL,cAAc,EACd,KAAK,EACL,KAAK,iBAAiB,EACvB,MAAM,WAAW,CAAC;AACnB,OAAO,EAAuB,KAAK,aAAa,EAAE,MAAM,cAAc,CAAC;AAEvE,qBAAa,YAAa,SAAQ,cAAc;IACrC,OAAO,CAAC,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,QAAQ,CAAC,QAAQ;IAQ9D,WAAW,CAClB,IAAI,EAAE,OAAO,EACb,KAAK,EAAE,MAAM,EACb,MAAM,GAAE,OAAO,EAAE,GAAG,IAAW,EAC/B,OAAO,GAAE,MAAa,EACtB,UAAU,GAAE,MAAc,GACzB,iBAAiB;IAoEX,SAAS,CAChB,IAAI,EAAE,OAAO,EACb,UAAU,GAAE,MAAW,EACvB,WAAW,GAAE,MAAM,GAAG,IAAW,GAChC,KAAK,EAAE;IAoDD,KAAK,CAAC,IAAI,EAAE,OAAO,GAAG,IAAI;IAI1B,iBAAiB,CAAC,KAAK,EAAE,MAAM,GAAG,aAAa;CAGzD"}

package/dist/connectors/db/lib/drivers/sqlite.js

@@ -0,0 +1,147 @@
+/**
+ * drivers/sqlite.ts — SQLite driver, used for fast unit tests and
+ * local/embedded databases.
+ *
+ * Mirrors `drivers/sqlite.py`. The Python implementation uses stdlib
+ * `sqlite3`; here we use `better-sqlite3` because it provides a synchronous
+ * API that matches Python's ergonomics (no Promise wrapping needed for
+ * single-shot queries inside the policy/query pipeline).
+ *
+ * Behaviour parity:
+ *  - `connect({database})` opens the path; `:memory:` is an in-memory DB.
+ *  - `executeRead` fetches `max_rows + 1` rows so we can detect truncation
+ *    without reading the whole result set.
+ *  - On error: returns `{status: "error", error_code: "SQL_ERROR", error,
+ *    execution_time_ms}` — never raises.
+ *  - `getSchema(conn, schema?, tableFilter?)` reads `sqlite_master` and
+ *    `PRAGMA table_info(<name>)`, mirroring Python's queries verbatim.
+ */
+import { performance } from "node:perf_hooks";
+import Database from "better-sqlite3";
+import { Column, DatabaseDriver, Table, } from "./base.js";
+import { classifySqlKeywords } from "../policy.js";
+export class SQLiteDriver extends DatabaseDriver {
+    connect(envConfig) {
+        const dbPath = typeof envConfig["database"] === "string"
+            ? envConfig["database"]
+            : ":memory:";
+        return new Database(dbPath);
+    }
+    executeRead(conn, query, params = null, maxRows = 1000, _timeoutMs = 30000) {
+        const db = conn;
+        const start = performance.now();
+        try {
+            const stmt = db.prepare(query);
+            // better-sqlite3 exposes `stmt.reader` as `true` for row-returning
+            // statements (SELECT / PRAGMA / EXPLAIN) and `false` for writes
+            // (INSERT/UPDATE/DELETE). `.iterate()` only works for readers; writes
+            // must go through `.run()`. When the plugin config opts into
+            // `write: allow` or `delete: allow`, the policy gate routes the
+            // statement through this method — so dispatch on `stmt.reader`.
+            if (stmt.reader === false) {
+                stmt.run(...(params ?? []));
+                const elapsed = performance.now() - start;
+                return {
+                    status: "success",
+                    rows: [],
+                    row_count: 0,
+                    columns: [],
+                    execution_time_ms: roundTo2(elapsed),
+                    truncated: false,
+                };
+            }
+            const iter = stmt.iterate(...(params ?? []));
+            const rowsRaw = [];
+            // Fetch one extra row to detect truncation.
+            let truncated = false;
+            for (const row of iter) {
+                if (rowsRaw.length >= maxRows) {
+                    truncated = true;
+                    // We need to break the iterator cleanly so SQLite can release
+                    // its statement state. better-sqlite3's iterate() honours
+                    // `return()` to close the underlying stmt.
+                    if (typeof iter.return === "function")
+                        iter.return();
+                    break;
+                }
+                rowsRaw.push(row);
+            }
+            // Columns: `stmt.columns()` returns ColumnDefinition[] with `name`.
+            let columns = [];
+            try {
+                columns = stmt.columns().map((c) => c.name);
+            }
+            catch {
+                // Non-SELECT statements have no columns; mirror Python's
+                // `cursor.description` being None.
+                columns = [];
+            }
+            const elapsed = performance.now() - start;
+            return {
+                status: "success",
+                rows: rowsRaw,
+                row_count: rowsRaw.length,
+                columns,
+                execution_time_ms: roundTo2(elapsed),
+                truncated,
+            };
+        }
+        catch (e) {
+            const elapsed = performance.now() - start;
+            return {
+                status: "error",
+                error_code: "SQL_ERROR",
+                error: e.message,
+                execution_time_ms: roundTo2(elapsed),
+            };
+        }
+    }
+    getSchema(conn, schemaName = "", tableFilter = null) {
+        const db = conn;
+        try {
+            let cursor;
+            let baseQuery = "SELECT name FROM sqlite_master WHERE type='table' AND name NOT LIKE 'sqlite_%'";
+            if (tableFilter !== null && tableFilter !== undefined) {
+                baseQuery += " AND name LIKE ?";
+                cursor = db.prepare(baseQuery).all(tableFilter);
+            }
+            else {
+                cursor = db.prepare(baseQuery).all();
+            }
+            const tables = [];
+            for (const row of cursor) {
+                const tableName = row.name;
+                // PRAGMA table_info returns rows shaped like:
+                //   {cid, name, type, notnull, dflt_value, pk}
+                const colCursor = db
+                    .prepare(`PRAGMA table_info(${tableName})`)
+                    .all();
+                const columns = [];
+                for (const colRow of colCursor) {
+                    columns.push(new Column({
+                        name: colRow.name,
+                        data_type: colRow.type,
+                        nullable: !colRow.notnull,
+                        is_primary_key: Boolean(colRow.pk),
+                        default: colRow.dflt_value,
+                    }));
+                }
+                tables.push(new Table({ name: tableName, schema: schemaName, columns }));
+            }
+            return tables;
+        }
+        catch {
+            return [];
+        }
+    }
+    close(conn) {
+        conn.close();
+    }
+    classifyOperation(query) {
+        return classifySqlKeywords(query);
+    }
+}
+function roundTo2(n) {
+    return Math.round(n * 100) / 100;
+}
+//# sourceMappingURL=sqlite.js.map

package/dist/connectors/db/lib/drivers/sqlite.js.map

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