@deebeetech/sqleasy-engine 0.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 DeeBee Tech
+
+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,70 @@
+<p align="center">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/deebee-tech/sqleasy-engine/main/assets/sqleasy-engine-lockup-dark.svg">
+    <img alt="SQLEasy Engine" src="https://raw.githubusercontent.com/deebee-tech/sqleasy-engine/main/assets/sqleasy-engine-lockup-light.svg" width="482">
+  </picture>
+</p>
+
+**A thin, opt-in executor for [`@deebeetech/sqleasy`](https://github.com/deebee-tech/sqleasy).**
+
+SQLEasy builds dialect-correct SQL and hands you `{ sql, params }`. It deliberately does not run
+anything. This package runs it: one small `run` / `transaction` / `explain` / `close` surface per
+dialect, and — crucially — **you load only the driver you import.**
+
+```bash
+npm install @deebeetech/sqleasy-engine @libsql/client   # only the driver(s) you use
+```
+
+Each dialect lives at its own subpath, so importing one pulls in only its driver:
+
+| Import                                | Driver (optional peer) | Factory                  |
+| ------------------------------------- | ---------------------- | ------------------------ |
+| `@deebeetech/sqleasy-engine/sqlite`   | `@libsql/client`       | `createSqliteExecutor`   |
+| `@deebeetech/sqleasy-engine/postgres` | `pg`                   | `createPostgresExecutor` |
+| `@deebeetech/sqleasy-engine/mysql`    | `mysql2`               | `createMysqlExecutor`    |
+| `@deebeetech/sqleasy-engine/mssql`    | `mssql`                | `createMssqlExecutor`    |
+
+```typescript
+import { createSqliteExecutor } from '@deebeetech/sqleasy-engine/sqlite';
+
+const db = createSqliteExecutor({ file: './app.db' });
+
+// One statement — hand it a builder's parsePrepared() output.
+const { rows } = await db.run({ sql: 'SELECT * FROM "users" WHERE "id" = ?;', params: [1] });
+
+// A whole batch as one atomic transaction — hand it a MultiBuilder's preparedStatements().
+// It commits on success and rolls back on any error; each statement runs as its own prepared
+// statement, in order.
+await db.transaction(multi.preparedStatements());
+
+await db.close();
+```
+
+The drivers are **optional peer dependencies** — install `pg`, `mysql2`, `mssql`, or `@libsql/client`
+yourself, only for the dialects you actually use. Nothing is loaded for a dialect you never import.
+
+## Why a transaction runs statement by statement
+
+SQLEasy's `MultiBuilder.parse()` renders a batch as one string for display — but placeholder
+numbering restarts per statement, so that string is not a runnable parameterized call on
+Postgres/MySQL/SQLite. `preparedStatements()` returns each statement's own `{ sql, params }`; this
+engine opens a real driver-level transaction and runs them in order. That is the correct way to
+execute a SQLEasy batch, and this package does it for you.
+
+## Status
+
+All four dialect executors — **SQLite/libSQL, Postgres, MySQL, SQL Server** — implement the full
+`run` / `transaction` / `explain` / `close` surface. The Postgres/MySQL/MSSQL executors also expose a
+`…FromPool` variant so you can share a pool you already manage.
+
+Tested: SQLite runs against real in-memory libSQL (params, atomic commit, rollback, explain). The
+others verify their transaction orchestration (BEGIN → per-statement → COMMIT/ROLLBACK + connection
+release) against a recording fake driver, their EXPLAIN parsers against real plan output, and carry
+real-database integration blocks gated on a connection env var (`DATABASE_URL`, `MYSQL_URL`,
+`MSSQL_CONNECTION_STRING`) for CI. Optional schema introspection is next.
+
+Part of the [DeeBee](https://github.com/deebee-tech) ecosystem.
+
+## License
+
+MIT © DeeBee Tech

package/dist/index.d.cts

@@ -0,0 +1,70 @@
+//#region src/index.d.ts
+/**
+ * Core, driver-agnostic types for the SQLEasy engine.
+ *
+ * This entry point pulls in NO database driver — importing it is free. Pick a dialect executor from
+ * its own subpath (`@deebeetech/sqleasy-engine/sqlite`, `/postgres`, …); each one imports only its
+ * own driver, so you install and load just the drivers you use.
+ */
+/** A single result-set row, keyed by column name. */
+type Row = Record<string, unknown>;
+/**
+ * A prepared statement and its ordered bound parameters — exactly the shape SQLEasy's
+ * `parsePrepared()` and `MultiBuilder.preparedStatements()` return.
+ *
+ * Structural on purpose: the engine accepts any `{ sql, params }`, so it never depends on the
+ * builder. `params` is optional/empty for SQL that carries its own values (e.g. SQLEasy's MSSQL
+ * `sp_executesql`, whose `params` is always `[]`).
+ */
+type PreparedSql = {
+  sql: string;
+  params?: readonly unknown[];
+};
+/** The outcome of executing one statement. */
+type QueryResult<T = Row> = {
+  rows: T[];
+  /** Rows returned (SELECT) or affected (INSERT/UPDATE/DELETE). */
+  rowCount: number;
+};
+/**
+ * The planner's estimate for a statement, obtained WITHOUT executing it. `cost` is in the dialect's
+ * own units and is NOT comparable across dialects — gate on `rows`/`fullScan` when you need one rule
+ * for all four. Best-effort: a backend supplies only what its planner exposes (SQLite has no
+ * numbers at all, only the plan shape).
+ */
+type ExplainEstimate = {
+  /** Planner cost in the dialect's own units. Absent when the backend reports none (SQLite). */
+  cost?: number;
+  /** Estimated rows the plan produces. Absent when the backend reports none (SQLite). */
+  rows?: number;
+  /** The plan reads a whole table instead of seeking an index — the portable "this will hurt" signal. */
+  fullScan: boolean;
+  /** A short raw-plan excerpt, for display and debugging. */
+  plan: string;
+};
+/**
+ * Executes prepared SQL against one database.
+ *
+ * Obtain one from a dialect subpath (`createSqliteExecutor`, `createPostgresExecutor`, …). Pick the
+ * executor whose dialect matches the SQL you built, so placeholders and quoting line up — the engine
+ * runs what it is given verbatim and does not rewrite dialects.
+ */
+type DbExecutor = {
+  /** Run one prepared statement and return its rows. */
+  run<T = Row>(prepared: PreparedSql): Promise<QueryResult<T>>;
+  /**
+   * Run several prepared statements as ONE atomic transaction: commit on success, roll back on any
+   * error. This is how you execute a SQLEasy `MultiBuilder` — pass `multi.preparedStatements()`.
+   * Statements run in order, each as its own prepared statement (never concatenated into one string,
+   * which would misbind: placeholder numbering restarts per statement), and each statement's result
+   * is returned in the same order.
+   */
+  transaction(statements: readonly PreparedSql[]): Promise<QueryResult[]>;
+  /** Ask the planner what a statement would cost WITHOUT running it. Best-effort per backend. */
+  explain(prepared: PreparedSql): Promise<ExplainEstimate>;
+  /** Close the underlying connection/pool. */
+  close(): Promise<void>;
+};
+//#endregion
+export { DbExecutor, ExplainEstimate, PreparedSql, QueryResult, Row };
+//# sourceMappingURL=index.d.cts.map

package/dist/index.d.mts

@@ -0,0 +1,70 @@
+//#region src/index.d.ts
+/**
+ * Core, driver-agnostic types for the SQLEasy engine.
+ *
+ * This entry point pulls in NO database driver — importing it is free. Pick a dialect executor from
+ * its own subpath (`@deebeetech/sqleasy-engine/sqlite`, `/postgres`, …); each one imports only its
+ * own driver, so you install and load just the drivers you use.
+ */
+/** A single result-set row, keyed by column name. */
+type Row = Record<string, unknown>;
+/**
+ * A prepared statement and its ordered bound parameters — exactly the shape SQLEasy's
+ * `parsePrepared()` and `MultiBuilder.preparedStatements()` return.
+ *
+ * Structural on purpose: the engine accepts any `{ sql, params }`, so it never depends on the
+ * builder. `params` is optional/empty for SQL that carries its own values (e.g. SQLEasy's MSSQL
+ * `sp_executesql`, whose `params` is always `[]`).
+ */
+type PreparedSql = {
+  sql: string;
+  params?: readonly unknown[];
+};
+/** The outcome of executing one statement. */
+type QueryResult<T = Row> = {
+  rows: T[];
+  /** Rows returned (SELECT) or affected (INSERT/UPDATE/DELETE). */
+  rowCount: number;
+};
+/**
+ * The planner's estimate for a statement, obtained WITHOUT executing it. `cost` is in the dialect's
+ * own units and is NOT comparable across dialects — gate on `rows`/`fullScan` when you need one rule
+ * for all four. Best-effort: a backend supplies only what its planner exposes (SQLite has no
+ * numbers at all, only the plan shape).
+ */
+type ExplainEstimate = {
+  /** Planner cost in the dialect's own units. Absent when the backend reports none (SQLite). */
+  cost?: number;
+  /** Estimated rows the plan produces. Absent when the backend reports none (SQLite). */
+  rows?: number;
+  /** The plan reads a whole table instead of seeking an index — the portable "this will hurt" signal. */
+  fullScan: boolean;
+  /** A short raw-plan excerpt, for display and debugging. */
+  plan: string;
+};
+/**
+ * Executes prepared SQL against one database.
+ *
+ * Obtain one from a dialect subpath (`createSqliteExecutor`, `createPostgresExecutor`, …). Pick the
+ * executor whose dialect matches the SQL you built, so placeholders and quoting line up — the engine
+ * runs what it is given verbatim and does not rewrite dialects.
+ */
+type DbExecutor = {
+  /** Run one prepared statement and return its rows. */
+  run<T = Row>(prepared: PreparedSql): Promise<QueryResult<T>>;
+  /**
+   * Run several prepared statements as ONE atomic transaction: commit on success, roll back on any
+   * error. This is how you execute a SQLEasy `MultiBuilder` — pass `multi.preparedStatements()`.
+   * Statements run in order, each as its own prepared statement (never concatenated into one string,
+   * which would misbind: placeholder numbering restarts per statement), and each statement's result
+   * is returned in the same order.
+   */
+  transaction(statements: readonly PreparedSql[]): Promise<QueryResult[]>;
+  /** Ask the planner what a statement would cost WITHOUT running it. Best-effort per backend. */
+  explain(prepared: PreparedSql): Promise<ExplainEstimate>;
+  /** Close the underlying connection/pool. */
+  close(): Promise<void>;
+};
+//#endregion
+export { DbExecutor, ExplainEstimate, PreparedSql, QueryResult, Row };
+//# sourceMappingURL=index.d.mts.map

package/dist/index.mjs

@@ -0,0 +1 @@
+export {};

package/dist/introspection/index.cjs

@@ -0,0 +1,419 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+//#region src/introspection/build-schema.ts
+/** Stitch flat catalog rows into per-table column/FK/index lists. Shared by every dialect reader. */
+function buildSchema(tables, columns, fks, indexColumns = [], rowCounts = []) {
+	const colMap = /* @__PURE__ */ new Map();
+	for (const c of columns) {
+		const key = `${c.schema}.${c.table}`;
+		const list = colMap.get(key) ?? [];
+		list.push({
+			name: c.name,
+			dataType: c.dataType,
+			nullable: c.nullable,
+			isPrimaryKey: c.isPrimaryKey,
+			defaultValue: c.defaultValue
+		});
+		colMap.set(key, list);
+	}
+	const fkMap = /* @__PURE__ */ new Map();
+	for (const fk of fks) {
+		const key = `${fk.schema}.${fk.table}`;
+		const list = fkMap.get(key) ?? [];
+		list.push({
+			columnName: fk.columnName,
+			referencedTable: fk.referencedTable,
+			referencedColumn: fk.referencedColumn,
+			referencedSchema: fk.referencedSchema
+		});
+		fkMap.set(key, list);
+	}
+	const idxMap = /* @__PURE__ */ new Map();
+	for (const r of indexColumns) {
+		const key = `${r.schema}.${r.table}`;
+		const byName = idxMap.get(key) ?? /* @__PURE__ */ new Map();
+		const idx = byName.get(r.indexName) ?? {
+			unique: r.unique,
+			cols: []
+		};
+		idx.cols.push({
+			name: r.columnName,
+			ordinal: r.ordinal
+		});
+		byName.set(r.indexName, idx);
+		idxMap.set(key, byName);
+	}
+	const indexesFor = (key) => [...idxMap.get(key)?.entries() ?? []].map(([name, i]) => ({
+		name,
+		unique: i.unique,
+		columns: i.cols.sort((a, b) => a.ordinal - b.ordinal).map((c) => c.name)
+	}));
+	const rowCountMap = new Map(rowCounts.map((r) => [`${r.schema}.${r.table}`, r.count]));
+	return { tables: tables.map((t) => {
+		const key = `${t.schema}.${t.name}`;
+		return {
+			schema: t.schema,
+			name: t.name,
+			type: t.isView ? "view" : "table",
+			columns: colMap.get(key) ?? [],
+			foreignKeys: fkMap.get(key) ?? [],
+			indexes: indexesFor(key),
+			approxRowCount: rowCountMap.get(key)
+		};
+	}) };
+}
+//#endregion
+//#region src/introspection/mssql.ts
+/** SQL Server catalog reader (INFORMATION_SCHEMA + sys catalog). Pass an executor connected to a
+* SQL Server database (`createMssqlExecutor`). */
+async function introspectMssql(executor, schema) {
+	const target = schema || "dbo";
+	const tables = await executor.run({
+		sql: `SELECT TABLE_NAME AS table_name, TABLE_TYPE AS table_type
+       FROM INFORMATION_SCHEMA.TABLES
+       WHERE TABLE_SCHEMA = @p0 AND TABLE_TYPE IN ('BASE TABLE', 'VIEW')
+       ORDER BY TABLE_TYPE, TABLE_NAME`,
+		params: [target]
+	});
+	const columns = await executor.run({
+		sql: `SELECT TABLE_NAME AS table_name, COLUMN_NAME AS column_name, DATA_TYPE AS data_type,
+              IS_NULLABLE AS is_nullable, COLUMN_DEFAULT AS column_default
+       FROM INFORMATION_SCHEMA.COLUMNS
+       WHERE TABLE_SCHEMA = @p0
+       ORDER BY TABLE_NAME, ORDINAL_POSITION`,
+		params: [target]
+	});
+	const pks = await executor.run({
+		sql: `SELECT kcu.TABLE_NAME AS table_name, kcu.COLUMN_NAME AS column_name
+       FROM INFORMATION_SCHEMA.TABLE_CONSTRAINTS tc
+       JOIN INFORMATION_SCHEMA.KEY_COLUMN_USAGE kcu
+         ON tc.CONSTRAINT_NAME = kcu.CONSTRAINT_NAME AND tc.TABLE_SCHEMA = kcu.TABLE_SCHEMA
+       WHERE tc.CONSTRAINT_TYPE = 'PRIMARY KEY' AND tc.TABLE_SCHEMA = @p0`,
+		params: [target]
+	});
+	const fks = await executor.run({
+		sql: `SELECT t1.name AS table_name, c1.name AS column_name,
+              s2.name AS referenced_schema, t2.name AS referenced_table, c2.name AS referenced_column
+       FROM sys.foreign_key_columns fkc
+       JOIN sys.objects t1 ON fkc.parent_object_id = t1.object_id
+       JOIN sys.columns c1 ON fkc.parent_object_id = c1.object_id AND fkc.parent_column_id = c1.column_id
+       JOIN sys.objects t2 ON fkc.referenced_object_id = t2.object_id
+       JOIN sys.columns c2 ON fkc.referenced_object_id = c2.object_id AND fkc.referenced_column_id = c2.column_id
+       JOIN sys.schemas s1 ON t1.schema_id = s1.schema_id
+       JOIN sys.schemas s2 ON t2.schema_id = s2.schema_id
+       WHERE s1.name = @p0`,
+		params: [target]
+	});
+	const indexes = await executor.run({
+		sql: `SELECT t.name AS table_name, i.name AS index_name, i.is_unique AS is_unique,
+              c.name AS column_name, ic.key_ordinal AS ordinal
+       FROM sys.indexes i
+       JOIN sys.tables t ON t.object_id = i.object_id
+       JOIN sys.schemas s ON s.schema_id = t.schema_id
+       JOIN sys.index_columns ic ON ic.object_id = i.object_id AND ic.index_id = i.index_id
+       JOIN sys.columns c ON c.object_id = ic.object_id AND c.column_id = ic.column_id
+       WHERE s.name = @p0 AND i.type > 0 AND ic.is_included_column = 0
+       ORDER BY t.name, i.name, ic.key_ordinal`,
+		params: [target]
+	});
+	const rowCounts = await executor.run({
+		sql: `SELECT t.name AS table_name, SUM(p.rows) AS n
+       FROM sys.tables t
+       JOIN sys.schemas s ON s.schema_id = t.schema_id
+       JOIN sys.partitions p ON p.object_id = t.object_id AND p.index_id IN (0, 1)
+       WHERE s.name = @p0
+       GROUP BY t.name`,
+		params: [target]
+	});
+	const pkSet = new Set(pks.rows.map((p) => `${p.table_name}.${p.column_name}`));
+	return buildSchema(tables.rows.map((t) => ({
+		schema: target,
+		name: t.table_name,
+		isView: t.table_type === "VIEW"
+	})), columns.rows.map((c) => ({
+		schema: target,
+		table: c.table_name,
+		name: c.column_name,
+		dataType: c.data_type,
+		nullable: c.is_nullable === "YES",
+		isPrimaryKey: pkSet.has(`${c.table_name}.${c.column_name}`),
+		defaultValue: c.column_default ?? void 0
+	})), fks.rows.map((fk) => ({
+		schema: target,
+		table: fk.table_name,
+		columnName: fk.column_name,
+		referencedTable: fk.referenced_table,
+		referencedColumn: fk.referenced_column,
+		referencedSchema: fk.referenced_schema
+	})), indexes.rows.map((r) => ({
+		schema: target,
+		table: r.table_name,
+		indexName: r.index_name,
+		unique: Boolean(r.is_unique),
+		columnName: r.column_name,
+		ordinal: Number(r.ordinal)
+	})), rowCounts.rows.map((r) => ({
+		schema: target,
+		table: r.table_name,
+		count: Number(r.n)
+	})));
+}
+//#endregion
+//#region src/introspection/mysql.ts
+/** MySQL / MariaDB catalog reader (information_schema). Pass an executor connected to a MySQL
+* database (`createMysqlExecutor`). */
+async function introspectMysql(executor, schema) {
+	let target = schema;
+	if (!target) target = (await executor.run({ sql: "SELECT DATABASE() AS db" })).rows[0]?.db ?? "";
+	const tables = await executor.run({
+		sql: `SELECT TABLE_NAME AS table_name, TABLE_TYPE AS table_type
+       FROM information_schema.tables
+       WHERE table_schema = ? AND table_type IN ('BASE TABLE', 'VIEW')
+       ORDER BY table_type, table_name`,
+		params: [target]
+	});
+	const columns = await executor.run({
+		sql: `SELECT TABLE_NAME AS table_name, COLUMN_NAME AS column_name, DATA_TYPE AS data_type,
+              IS_NULLABLE AS is_nullable, COLUMN_DEFAULT AS column_default, COLUMN_KEY AS column_key
+       FROM information_schema.columns
+       WHERE table_schema = ?
+       ORDER BY table_name, ordinal_position`,
+		params: [target]
+	});
+	const fks = await executor.run({
+		sql: `SELECT TABLE_NAME AS table_name, COLUMN_NAME AS column_name,
+              REFERENCED_TABLE_SCHEMA AS referenced_table_schema,
+              REFERENCED_TABLE_NAME AS referenced_table_name,
+              REFERENCED_COLUMN_NAME AS referenced_column_name
+       FROM information_schema.key_column_usage
+       WHERE table_schema = ? AND referenced_table_name IS NOT NULL`,
+		params: [target]
+	});
+	const indexes = await executor.run({
+		sql: `SELECT TABLE_NAME AS table_name, INDEX_NAME AS index_name, NON_UNIQUE AS non_unique,
+              COLUMN_NAME AS column_name, SEQ_IN_INDEX AS seq
+       FROM information_schema.statistics
+       WHERE table_schema = ?
+       ORDER BY table_name, index_name, seq`,
+		params: [target]
+	});
+	const rowCounts = await executor.run({
+		sql: `SELECT TABLE_NAME AS table_name, TABLE_ROWS AS n
+       FROM information_schema.tables
+       WHERE table_schema = ? AND table_type = 'BASE TABLE'`,
+		params: [target]
+	});
+	return buildSchema(tables.rows.map((t) => ({
+		schema: target,
+		name: t.table_name,
+		isView: t.table_type === "VIEW"
+	})), columns.rows.map((c) => ({
+		schema: target,
+		table: c.table_name,
+		name: c.column_name,
+		dataType: c.data_type,
+		nullable: c.is_nullable === "YES",
+		isPrimaryKey: c.column_key === "PRI",
+		defaultValue: c.column_default ?? void 0
+	})), fks.rows.map((fk) => ({
+		schema: target,
+		table: fk.table_name,
+		columnName: fk.column_name,
+		referencedTable: fk.referenced_table_name,
+		referencedColumn: fk.referenced_column_name,
+		referencedSchema: fk.referenced_table_schema
+	})), indexes.rows.filter((r) => r.column_name != null).map((r) => ({
+		schema: target,
+		table: r.table_name,
+		indexName: r.index_name,
+		unique: r.non_unique === 0,
+		columnName: r.column_name,
+		ordinal: Number(r.seq)
+	})), rowCounts.rows.map((r) => ({
+		schema: target,
+		table: r.table_name,
+		count: Number(r.n ?? 0)
+	})));
+}
+//#endregion
+//#region src/introspection/postgres.ts
+/** Postgres catalog reader (information_schema + pg_catalog). Pass an executor connected to a
+* Postgres database (`createPostgresExecutor`). */
+async function introspectPostgres(executor, schema) {
+	const target = schema || "public";
+	const tables = await executor.run({
+		sql: `SELECT table_name, table_type
+       FROM information_schema.tables
+       WHERE table_schema = $1 AND table_type IN ('BASE TABLE', 'VIEW')
+       ORDER BY table_type, table_name`,
+		params: [target]
+	});
+	const columns = await executor.run({
+		sql: `SELECT table_name, column_name, data_type, is_nullable, column_default
+       FROM information_schema.columns
+       WHERE table_schema = $1
+       ORDER BY table_name, ordinal_position`,
+		params: [target]
+	});
+	const pks = await executor.run({
+		sql: `SELECT kcu.table_name, kcu.column_name
+       FROM information_schema.table_constraints tc
+       JOIN information_schema.key_column_usage kcu
+         ON tc.constraint_name = kcu.constraint_name AND tc.table_schema = kcu.table_schema
+       WHERE tc.constraint_type = 'PRIMARY KEY' AND tc.table_schema = $1`,
+		params: [target]
+	});
+	const fks = await executor.run({
+		sql: `SELECT kcu.table_name, kcu.column_name,
+              ccu.table_schema AS referenced_table_schema,
+              ccu.table_name AS referenced_table_name,
+              ccu.column_name AS referenced_column_name
+       FROM information_schema.table_constraints tc
+       JOIN information_schema.key_column_usage kcu
+         ON tc.constraint_name = kcu.constraint_name AND tc.table_schema = kcu.table_schema
+       JOIN information_schema.constraint_column_usage ccu
+         ON tc.constraint_name = ccu.constraint_name AND tc.table_schema = ccu.table_schema
+       WHERE tc.constraint_type = 'FOREIGN KEY' AND tc.table_schema = $1`,
+		params: [target]
+	});
+	const indexes = await executor.run({
+		sql: `SELECT t.relname AS table_name, i.relname AS index_name, ix.indisunique AS is_unique,
+              a.attname AS column_name, k.ord AS ordinal
+       FROM pg_index ix
+       JOIN pg_class i ON i.oid = ix.indexrelid
+       JOIN pg_class t ON t.oid = ix.indrelid
+       JOIN pg_namespace n ON n.oid = t.relnamespace
+       JOIN LATERAL unnest(string_to_array(ix.indkey::text, ' ')::int[]) WITH ORDINALITY AS k(attnum, ord)
+         ON true
+       JOIN pg_attribute a ON a.attrelid = t.oid AND a.attnum = k.attnum
+       WHERE n.nspname = $1 AND t.relkind = 'r' AND k.attnum > 0
+       ORDER BY table_name, index_name, ordinal`,
+		params: [target]
+	});
+	const rowCounts = await executor.run({
+		sql: `SELECT c.relname AS table_name, c.reltuples::bigint AS n
+       FROM pg_class c JOIN pg_namespace n ON n.oid = c.relnamespace
+       WHERE n.nspname = $1 AND c.relkind = 'r'`,
+		params: [target]
+	});
+	const pkSet = new Set(pks.rows.map((p) => `${p.table_name}.${p.column_name}`));
+	return buildSchema(tables.rows.map((t) => ({
+		schema: target,
+		name: t.table_name,
+		isView: t.table_type === "VIEW"
+	})), columns.rows.map((c) => ({
+		schema: target,
+		table: c.table_name,
+		name: c.column_name,
+		dataType: c.data_type,
+		nullable: c.is_nullable === "YES",
+		isPrimaryKey: pkSet.has(`${c.table_name}.${c.column_name}`),
+		defaultValue: c.column_default ?? void 0
+	})), fks.rows.map((fk) => ({
+		schema: target,
+		table: fk.table_name,
+		columnName: fk.column_name,
+		referencedTable: fk.referenced_table_name,
+		referencedColumn: fk.referenced_column_name,
+		referencedSchema: fk.referenced_table_schema
+	})), indexes.rows.map((r) => ({
+		schema: target,
+		table: r.table_name,
+		indexName: r.index_name,
+		unique: r.is_unique,
+		columnName: r.column_name,
+		ordinal: Number(r.ordinal)
+	})), rowCounts.rows.map((r) => ({
+		schema: target,
+		table: r.table_name,
+		count: Number(r.n)
+	})).filter((r) => r.count >= 0));
+}
+//#endregion
+//#region src/introspection/sqlite.ts
+/** SQLite catalog reader (sqlite_master + pragma table-valued functions). Also serves libsql/turso —
+* they are all SQLite engines with the same catalog. Pass an executor from `createSqliteExecutor`. */
+async function introspectSqlite(executor) {
+	const tables = await executor.run({ sql: `SELECT name, type FROM sqlite_master
+       WHERE type IN ('table', 'view') AND name NOT LIKE 'sqlite_%'
+       ORDER BY type, name` });
+	const columns = [];
+	const fks = [];
+	const indexColumns = [];
+	for (const t of tables.rows) {
+		const cols = await executor.run({
+			sql: "SELECT name, type, \"notnull\", dflt_value, pk FROM pragma_table_info(?)",
+			params: [t.name]
+		});
+		for (const c of cols.rows) columns.push({
+			schema: "main",
+			table: t.name,
+			name: c.name,
+			dataType: c.type || "TEXT",
+			nullable: c.notnull === 0 && c.pk === 0,
+			isPrimaryKey: c.pk > 0,
+			defaultValue: c.dflt_value ?? void 0
+		});
+		const fkRows = await executor.run({
+			sql: "SELECT \"from\", \"table\", \"to\" FROM pragma_foreign_key_list(?)",
+			params: [t.name]
+		});
+		for (const fk of fkRows.rows) fks.push({
+			schema: "main",
+			table: t.name,
+			columnName: fk.from,
+			referencedTable: fk.table,
+			referencedColumn: fk.to
+		});
+		const idxList = await executor.run({
+			sql: "SELECT name, \"unique\" FROM pragma_index_list(?)",
+			params: [t.name]
+		});
+		for (const idx of idxList.rows) {
+			const idxCols = await executor.run({
+				sql: "SELECT seqno, name FROM pragma_index_info(?)",
+				params: [idx.name]
+			});
+			for (const ic of idxCols.rows) {
+				if (ic.name == null) continue;
+				indexColumns.push({
+					schema: "main",
+					table: t.name,
+					indexName: idx.name,
+					unique: idx.unique === 1,
+					columnName: ic.name,
+					ordinal: ic.seqno
+				});
+			}
+		}
+	}
+	return buildSchema(tables.rows.map((t) => ({
+		schema: "main",
+		name: t.name,
+		isView: t.type === "view"
+	})), columns, fks, indexColumns);
+}
+//#endregion
+//#region src/introspection/index.ts
+/**
+* Read a database's catalog as a {@link SchemaData}, through a supplied {@link DbExecutor}. Choose
+* the `dialect` matching the executor you built — the reader runs that dialect's catalog queries.
+* `schema` scopes the namespace, defaulting per dialect (postgres `public`, mysql the current
+* database, mssql `dbo`, sqlite `main` — sqlite ignores it).
+*/
+function introspectSchema(executor, dialect, schema) {
+	switch (dialect) {
+		case "postgres": return introspectPostgres(executor, schema);
+		case "mysql": return introspectMysql(executor, schema);
+		case "mssql": return introspectMssql(executor, schema);
+		case "sqlite": return introspectSqlite(executor);
+	}
+}
+//#endregion
+exports.buildSchema = buildSchema;
+exports.introspectMssql = introspectMssql;
+exports.introspectMysql = introspectMysql;
+exports.introspectPostgres = introspectPostgres;
+exports.introspectSchema = introspectSchema;
+exports.introspectSqlite = introspectSqlite;
+
+//# sourceMappingURL=index.cjs.map