turbine-orm 0.33.0 → 0.35.0

package/README.md

@@ -863,7 +863,7 @@ const db = await turbineMssql('mssql://sa:Passw0rd!@localhost:1433/app', SCHEMA)
 ```
 
 ```ts
-// PowDB — async; embedded (in-process) or networked. Schema is code-defined (no introspection).
+// PowDB — async; embedded (in-process) or networked. Schema is code-defined.
 import { turbinePowDB } from 'turbine-orm/powdb';
 import { schema } from './schema.js'; // defineSchema({...})
 
@@ -891,7 +891,7 @@ Everything is honest about what ports and what doesn't. Features marked **PG-onl
 
 **Engine notes:** SQLite uses `RETURNING` (≥ 3.35) just like Postgres. MySQL has no `RETURNING`, so writes re-`SELECT` the affected row and **`createMany` returns `[]`** (the rows ARE inserted — re-query if you need them). SQL Server returns rows via `OUTPUT`/`MERGE`; `DISTINCT ON` is Postgres-only. Only Postgres streams via a true cursor (constant memory); the other engines' `findManyStream` materializes the result then yields it in batches. Optimistic locking throws `OptimisticLockError` on all engines (on MySQL the conflict is detected from the version-checked UPDATE's affected-row count). The `turbine` CLI (`generate`, `migrate`) is currently PostgreSQL-only — point the engine factories at a hand-written or programmatically introspected `SCHEMA`.
 
-**PowDB** speaks its own non-SQL query language (PowQL), so it sits outside the SQL matrix above. Writes use a trailing **`returning`** keyword (upsert reselects by PK). PKs are server-assigned `auto` ints **or** client UUIDs. Nested relations load client-side (N+1, including many-to-many via the junction — no `json_agg`). Nested writes cover hasMany/hasOne/belongsTo; many-to-many nested writes are not supported. Transactions are single-writer: concurrent `$transaction` calls queue FIFO (bounded by `transactionQueueTimeoutMs`); nested/re-entrant transactions throw typed errors (no savepoints). Schema is code-first via `defineSchema` (no wire introspection) — `schemaDefToMetadata()` bridges it to any engine that needs runtime metadata. Embedded `syncMode: 'normal'` moves fsync off the commit path; the networked transport runs the same data over a socket. Cursor streaming and the Postgres-only trio (pgvector / LISTEN/NOTIFY / RLS session GUCs) throw `UnsupportedFeatureError`. Full details: **[turbineorm.dev/engines#powdb](https://turbineorm.dev/engines#powdb)**.
+**PowDB** speaks its own non-SQL query language (PowQL), so it sits outside the SQL matrix above. Writes use a trailing **`returning`** keyword (upsert reselects by PK). PKs are server-assigned `auto` ints **or** client UUIDs. Nested relations load client-side (N+1, including many-to-many via the junction — no `json_agg`). Nested writes cover hasMany/hasOne/belongsTo; many-to-many nested writes are not supported. Transactions are single-writer: concurrent `$transaction` calls queue FIFO (bounded by `transactionQueueTimeoutMs`); nested/re-entrant transactions throw typed errors (no savepoints). Schema is code-first via `defineSchema` — `schemaDefToMetadata()` bridges it to any engine that needs runtime metadata, and a programmatic `describe`-based introspector exists since 0.34 (relations excluded). JSON documents are first-class on engine 0.12+: `JsonFilter` where-filters, JSON-path `orderBy`/`groupBy`, doc-field expression indexes, and a lossless native wire (0.13+) that keeps JSON `null`, missing fields, and the string `"null"` distinct. Embedded `syncMode: 'normal'` moves fsync off the commit path; the networked transport runs the same data over a socket. Cursor streaming and the Postgres-only trio (pgvector / LISTEN/NOTIFY / RLS session GUCs) throw `UnsupportedFeatureError`. Full details: **[turbineorm.dev/engines#powdb](https://turbineorm.dev/engines#powdb)**.
 
 Full setup, signatures, and the complete support matrix: **[turbineorm.dev/engines](https://turbineorm.dev/engines)**.
 

package/dist/cjs/client.js

@@ -111,15 +111,27 @@ class TransactionClient {
     schema;
     middlewares;
     queryOptions;
+    sourcePool;
     tableCache = new Map();
     savepointCounter = 0;
     /** Active SQL dialect — owns savepoint keywords and raw-SQL placeholders. */
     dialect;
-    constructor(client, schema, middlewares, queryOptions) {
+    constructor(client, schema, middlewares, queryOptions, 
+    /**
+     * The parent pool this transaction runs on. Only its `readonly` and
+     * `capabilities` are read (both PowDB-only flags), so the transaction-scoped
+     * proxy pool built by {@link createTxPool} carries them through: without this
+     * a read-only client's `$transaction` writes bypass the E018 guard, and an
+     * older-engine client falls back to ALL_POWDB_CAPABILITIES inside the tx
+     * (emitting join PowQL a pre-0.13 engine rejects). Undefined / absent flags
+     * for a plain pg pool leave the proxy unchanged.
+     */
+    sourcePool) {
         this.client = client;
         this.schema = schema;
         this.middlewares = middlewares;
         this.queryOptions = queryOptions;
+        this.sourcePool = sourcePool;
         this.dialect = queryOptions?.dialect ?? dialect_js_1.postgresDialect;
         // Auto-create typed table accessors for all tables in the schema
         for (const tableName of Object.keys(schema.tables)) {
@@ -199,7 +211,7 @@ class TransactionClient {
         const client = this.client;
         // Return a minimal pool-compatible object that routes queries
         // through the transaction client
-        return {
+        const txPool = {
             query: async (textOrConfig, values) => {
                 try {
                     if (typeof textOrConfig === 'string') {
@@ -216,6 +228,14 @@ class TransactionClient {
             },
             connect: () => Promise.resolve(client),
         };
+        // Carry the parent pool's PowDB-only flags through so a transaction-scoped
+        // PowqlInterface reads the same read-only guard and capabilities it would
+        // outside the transaction (a plain pg pool has neither, so nothing changes).
+        if (this.sourcePool?.readonly !== undefined)
+            txPool.readonly = this.sourcePool.readonly;
+        if (this.sourcePool?.capabilities !== undefined)
+            txPool.capabilities = this.sourcePool.capabilities;
+        return txPool;
     }
 }
 exports.TransactionClient = TransactionClient;
@@ -884,8 +904,10 @@ class TurbineClient {
                     await client.query(cfg.sql, cfg.params);
                 }
             }
-            // Create the transaction client with typed table accessors
-            const tx = new TransactionClient(client, this.schema, this.middlewares, this.queryOptions);
+            // Create the transaction client with typed table accessors. Pass the
+            // parent pool so its read-only guard + PowDB capabilities flow into the
+            // transaction-scoped proxy pool (see TransactionClient.createTxPool).
+            const tx = new TransactionClient(client, this.schema, this.middlewares, this.queryOptions, this.pool);
             // Dynamically attach table accessors to tx
             for (const tableName of Object.keys(this.schema.tables)) {
                 const camelName = tableName.replace(/_([a-z])/g, (_, c) => c.toUpperCase());

package/dist/cjs/dialect.js

@@ -59,6 +59,7 @@ exports.postgresDialect = {
     supportsRLS: true,
     supportsAdvisoryLock: true,
     supportsLateralJoin: true,
+    explainQuery: { prefix: 'EXPLAIN' },
     paramPlaceholder(index) {
         return `$${index}`;
     },

package/dist/cjs/errors.js

@@ -6,7 +6,7 @@
  * All Turbine errors extend TurbineError which includes a `code` property.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.UnsupportedFeatureError = exports.OptimisticLockError = exports.PipelineError = exports.ExclusionConstraintError = exports.CheckConstraintError = exports.SerializationFailureError = exports.DeadlockError = exports.NotNullViolationError = exports.ForeignKeyError = exports.UniqueConstraintError = exports.CircularRelationError = exports.MigrationError = exports.RelationError = exports.ConnectionError = exports.ValidationError = exports.TimeoutError = exports.NotFoundError = exports.TurbineError = exports.TurbineErrorCode = void 0;
+exports.ReadOnlyError = exports.UnsupportedFeatureError = exports.OptimisticLockError = exports.PipelineError = exports.ExclusionConstraintError = exports.CheckConstraintError = exports.SerializationFailureError = exports.DeadlockError = exports.NotNullViolationError = exports.ForeignKeyError = exports.UniqueConstraintError = exports.CircularRelationError = exports.MigrationError = exports.RelationError = exports.ConnectionError = exports.ValidationError = exports.TimeoutError = exports.NotFoundError = exports.TurbineError = exports.TurbineErrorCode = void 0;
 exports.setErrorMessageMode = setErrorMessageMode;
 exports.getErrorMessageMode = getErrorMessageMode;
 exports.wrapPgError = wrapPgError;
@@ -29,6 +29,7 @@ exports.TurbineErrorCode = {
     OPTIMISTIC_LOCK: 'TURBINE_E015',
     EXCLUSION_VIOLATION: 'TURBINE_E016',
     UNSUPPORTED_FEATURE: 'TURBINE_E017',
+    READ_ONLY: 'TURBINE_E018',
 };
 /**
  * Prefix a human message with its stable error code so logs are greppable
@@ -503,6 +504,45 @@ class UnsupportedFeatureError extends TurbineError {
     }
 }
 exports.UnsupportedFeatureError = UnsupportedFeatureError;
+/**
+ * Thrown when a write or DDL statement is refused because the target is
+ * read-only. Two shapes reach here, both on PowDB:
+ *   - an embedded database opened read-only for snapshot serving refuses a write
+ *     with `readonly mode: statement requires a writer …`;
+ *   - a networked read-only role refuses a write with `permission denied: role
+ *     '<role>' cannot execute write statements` (translated by `wrapPowdbError`).
+ * It is also raised locally, before the wire, when a write is issued on a pool
+ * the caller marked read-only (fail-fast). The message carries the engine text
+ * plus a hint to route writes to a writable primary.
+ *
+ * NOT retryable: the same write against the same read-only target fails
+ * identically; route it to a writable primary instead.
+ */
+class ReadOnlyError extends TurbineError {
+    /**
+     * Why the write was refused. `'snapshot'`: the database itself is read-only
+     * (snapshot serving, an embedded `readonly: true` open, or the client-level
+     * fail-fast flag), so NOTHING can write here and writes must route to the
+     * primary. `'rbac'`: the database is writable but THIS connection's role may
+     * not write (per-connection permission), so re-authenticating may suffice.
+     */
+    reason;
+    /**
+     * @param detail human-readable description of the refused write (the engine
+     *   message, or a local fail-fast description). A "route writes to a writable
+     *   primary" hint is always appended.
+     * @param options optional driver `cause` to preserve when wrapping a refusal,
+     *   and the refusal `reason` (default `'snapshot'`).
+     */
+    constructor(detail, options) {
+        super(exports.TurbineErrorCode.READ_ONLY, `[turbine] ${detail} Route writes to a writable primary.`, {
+            cause: options?.cause,
+        });
+        this.name = 'ReadOnlyError';
+        this.reason = options?.reason ?? 'snapshot';
+    }
+}
+exports.ReadOnlyError = ReadOnlyError;
 /**
  * Parse column names out of a pg `detail` string like:
  *   "Key (email)=(foo@bar) already exists."

package/dist/cjs/index.js

@@ -34,8 +34,8 @@
  * ```
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.ColumnBuilder = exports.applyManyToManyRelations = exports.snakeToPascal = exports.snakeToCamel = exports.singularize = exports.pgTypeToTs = exports.pgArrayType = exports.normalizeKeyColumns = exports.isDateType = exports.camelToSnake = exports.validateChannel = exports.QueryInterface = exports.pipelineSupported = exports.executePipeline = exports.hasRelationFields = exports.executeNestedUpdate = exports.executeNestedCreate = exports.introspect = exports.generate = exports.wrapPgError = exports.ValidationError = exports.UnsupportedFeatureError = exports.UniqueConstraintError = exports.TurbineErrorCode = exports.TurbineError = exports.TimeoutError = exports.setErrorMessageMode = exports.SerializationFailureError = exports.RelationError = exports.PipelineError = exports.OptimisticLockError = exports.NotNullViolationError = exports.NotFoundError = exports.MigrationError = exports.getErrorMessageMode = exports.ForeignKeyError = exports.ExclusionConstraintError = exports.DeadlockError = exports.ConnectionError = exports.CircularRelationError = exports.CheckConstraintError = exports.postgresDialect = exports.withRetry = exports.TurbineClient = exports.TransactionClient = exports.yugabytedb = exports.timescale = exports.postgresql = exports.cockroachdb = exports.alloydb = void 0;
-exports.TypedSqlQuery = exports.buildTypedSql = exports.turbineHttp = exports.defineSeed = exports.schemaToSQLString = exports.schemaToSQL = exports.schemaPush = exports.schemaDiff = exports.schemaDefToMetadata = exports.table = exports.defineSchema = exports.column = void 0;
+exports.applyManyToManyRelations = exports.snakeToPascal = exports.snakeToCamel = exports.singularize = exports.pgTypeToTs = exports.pgArrayType = exports.normalizeKeyColumns = exports.isDateType = exports.camelToSnake = exports.validateChannel = exports.QueryInterface = exports.pipelineSupported = exports.executePipeline = exports.hasRelationFields = exports.executeNestedUpdate = exports.executeNestedCreate = exports.introspect = exports.generate = exports.wrapPgError = exports.ValidationError = exports.UnsupportedFeatureError = exports.UniqueConstraintError = exports.TurbineErrorCode = exports.TurbineError = exports.TimeoutError = exports.setErrorMessageMode = exports.SerializationFailureError = exports.RelationError = exports.ReadOnlyError = exports.PipelineError = exports.OptimisticLockError = exports.NotNullViolationError = exports.NotFoundError = exports.MigrationError = exports.getErrorMessageMode = exports.ForeignKeyError = exports.ExclusionConstraintError = exports.DeadlockError = exports.ConnectionError = exports.CircularRelationError = exports.CheckConstraintError = exports.postgresDialect = exports.withRetry = exports.TurbineClient = exports.TransactionClient = exports.yugabytedb = exports.timescale = exports.postgresql = exports.cockroachdb = exports.alloydb = void 0;
+exports.TypedSqlQuery = exports.buildTypedSql = exports.turbineHttp = exports.defineSeed = exports.schemaToSQLString = exports.schemaToSQL = exports.schemaPush = exports.schemaDiff = exports.schemaDefToMetadata = exports.table = exports.isDocFieldIndexDef = exports.defineSchema = exports.column = exports.ColumnBuilder = void 0;
 var index_js_1 = require("./adapters/index.js");
 Object.defineProperty(exports, "alloydb", { enumerable: true, get: function () { return index_js_1.alloydb; } });
 Object.defineProperty(exports, "cockroachdb", { enumerable: true, get: function () { return index_js_1.cockroachdb; } });
@@ -63,6 +63,7 @@ Object.defineProperty(exports, "NotFoundError", { enumerable: true, get: functio
 Object.defineProperty(exports, "NotNullViolationError", { enumerable: true, get: function () { return errors_js_1.NotNullViolationError; } });
 Object.defineProperty(exports, "OptimisticLockError", { enumerable: true, get: function () { return errors_js_1.OptimisticLockError; } });
 Object.defineProperty(exports, "PipelineError", { enumerable: true, get: function () { return errors_js_1.PipelineError; } });
+Object.defineProperty(exports, "ReadOnlyError", { enumerable: true, get: function () { return errors_js_1.ReadOnlyError; } });
 Object.defineProperty(exports, "RelationError", { enumerable: true, get: function () { return errors_js_1.RelationError; } });
 Object.defineProperty(exports, "SerializationFailureError", { enumerable: true, get: function () { return errors_js_1.SerializationFailureError; } });
 Object.defineProperty(exports, "setErrorMessageMode", { enumerable: true, get: function () { return errors_js_1.setErrorMessageMode; } });
@@ -110,6 +111,7 @@ Object.defineProperty(exports, "applyManyToManyRelations", { enumerable: true, g
 Object.defineProperty(exports, "ColumnBuilder", { enumerable: true, get: function () { return schema_builder_js_1.ColumnBuilder; } });
 Object.defineProperty(exports, "column", { enumerable: true, get: function () { return schema_builder_js_1.column; } });
 Object.defineProperty(exports, "defineSchema", { enumerable: true, get: function () { return schema_builder_js_1.defineSchema; } });
+Object.defineProperty(exports, "isDocFieldIndexDef", { enumerable: true, get: function () { return schema_builder_js_1.isDocFieldIndexDef; } });
 // Legacy compat (deprecated — use object format with defineSchema)
 Object.defineProperty(exports, "table", { enumerable: true, get: function () { return schema_builder_js_1.table; } });
 // Schema metadata bridge — defineSchema() → SchemaMetadata without a live DB

package/dist/cjs/mssql.js

@@ -483,6 +483,11 @@ exports.mssqlDialect = {
     supportsLateralJoin: false,
     // sp_getapplock / sp_releaseapplock exist (used by a future migrate adapter).
     supportsAdvisoryLock: true,
+    // No in-band EXPLAIN: SQL Server's SHOWPLAN is a session toggle
+    // (SET SHOWPLAN_ALL ON), not a statement prefix, so a compiled query cannot
+    // be explained in one round-trip. Override the inherited Postgres `EXPLAIN`
+    // to absent → QueryInterface.explain() throws E017.
+    explainQuery: undefined,
     // FOR JSON over zero rows is NULL → coalesced in the relation override.
     aggSupportsInlineOrderBy: false,
     jsonPathSupport: 'limited',

package/dist/cjs/mysql.js

@@ -384,6 +384,10 @@ exports.mysqlDialect = {
     supportsLateralJoin: false,
     // GET_LOCK / RELEASE_LOCK exist (used by a future migrate adapter).
     supportsAdvisoryLock: true,
+    // Plain `EXPLAIN` (one row of tabular plan columns) works on every supported
+    // MySQL 8.0.x; the readable `FORMAT=TREE` variant only exists from 8.0.16 and
+    // the engine floor here is 8.0.0. Plan text is a diagnostic, not a contract.
+    explainQuery: { prefix: 'EXPLAIN' },
     // JSON_ARRAYAGG has no inline ORDER BY argument → force the inner-subquery
     // rewrite for every ordered to-many relation.
     aggSupportsInlineOrderBy: false,

package/dist/cjs/optional-peer-import.cjs

@@ -119,4 +119,32 @@ async function importOptionalPeer(specifier, allowEsmFallback = true) {
         return esmCapableCopy(specifier, false);
     }
 }
+/**
+ * Merged namespace so callers can reach {@link peerPackageVersion} off the same
+ * default import (`importOptionalPeer.peerPackageVersion(...)`). Lives in this
+ * `.cts` file for the same reason the dynamic import does: a `.cts` compiles to
+ * CommonJS in BOTH build passes, so `require` / `require.resolve` are natively
+ * available and `import.meta` is never emitted (which would break the CJS build
+ * and crash CJS consumers, see `resolveEmbeddedVersion` in powdb.ts).
+ */
+(function (importOptionalPeer) {
+    /**
+     * Resolve an optional peer's declared `package.json` version WITHOUT loading
+     * the package itself (so an ESM-only peer never trips `require`). `require` is
+     * anchored on THIS module's location (inside the published `dist/`), so bare
+     * resolution walks up `node_modules` and finds the peer exactly where
+     * `import.meta.url` used to point, but it compiles under `module: CommonJS`
+     * too. Returns `null` when the peer / its package.json cannot be resolved.
+     */
+    function peerPackageVersion(specifier) {
+        try {
+            const pkg = require(`${specifier}/package.json`);
+            return typeof pkg.version === 'string' ? pkg.version : null;
+        }
+        catch {
+            return null;
+        }
+    }
+    importOptionalPeer.peerPackageVersion = peerPackageVersion;
+})(importOptionalPeer || (importOptionalPeer = {}));
 module.exports = importOptionalPeer;

package/dist/cjs/powdb-introspect.js

@@ -0,0 +1,222 @@
+"use strict";
+/**
+ * turbine-orm/powdb — `describe`-based introspection.
+ *
+ * PowDB exposes its catalog through two ordinary rows-returning statements
+ * (keywords since engine 0.10):
+ *   - `schema` → one row per type: `{ name, columns }` (columns = a count).
+ *   - `describe <T>` / `schema <T>` → one row per column:
+ *     `{ column, type, nullable, index }` where `type` is a PowQL type name
+ *     (`str`/`int`/`float`/`bool`/`json`/`datetime`/`uuid`/`bytes`), `nullable`
+ *     is `"true"`/`"false"`, and `index` is `"unique"` / `"index"` / `""`.
+ *
+ * {@link introspectPowdbDatabase} turns those into the same {@link SchemaMetadata}
+ * shape the SQL introspectors produce, so a code-first PowDB database can be
+ * introspected for bootstrap/verification. It is transport-agnostic: the caller
+ * supplies an `exec(powql)` that returns row objects **keyed by column name**.
+ *   - Embedded / owned pool: `exec = async (q) => ({ rows: await db.raw([q]) })`
+ *     using a live `turbinePowDB` client's `raw` tagged template.
+ *   - Networked: the raw `@zvndev/powdb-client` returns POSITIONAL rows
+ *     (`{ columns: string[], rows: string[][] }`), so zip them into records.
+ *     A bare `(await client.query(q)).rows` would hand this function `string[][]`
+ *     whose `.name` cell is `undefined` and every table would silently drop out:
+ *     ```ts
+ *     const exec = async (q) => {
+ *       const r = await client.query(q);
+ *       return { rows: r.rows.map((row) => Object.fromEntries(r.columns.map((c, i) => [c, row[i]]))) };
+ *     };
+ *     ```
+ *     (A mis-shaped exec is now caught: if `schema` returns rows but none carry
+ *     a `name`, {@link introspectPowdbDatabase} throws instead of returning an
+ *     empty schema.)
+ *
+ * IMPORTANT LIMITATIONS (all documented, none silent):
+ *   - Relations are ALWAYS `{}`: PowDB has no declared foreign keys, so
+ *     `describe` cannot report them. The recommended flow for relation-aware
+ *     metadata is code-first `defineSchema` + `schemaDefToMetadata`; use
+ *     introspection to bootstrap or verify column shape.
+ *   - Primary key is a HEURISTIC (`describe` has no PK concept): PowDB marks a
+ *     PK column as `required unique`, so the first non-nullable `unique` column
+ *     is chosen (a column named `id` wins ties). A table with no such column
+ *     yields `primaryKey: []` and a warning; single-row ops on it fail loudly.
+ *   - `isGenerated` is always `false`: `describe` does not expose PowDB's `auto`
+ *     modifier, so an introspected int PK is treated as client-supplied unless
+ *     the caller hand-edits the metadata.
+ *   - Doc-field expression indexes are INVISIBLE to `describe`, so they never
+ *     round-trip; only plain `unique`/`index` columns appear in `indexes`.
+ *   - `datetime` / `uuid` / `bytes` columns map to read-oriented TS types
+ *     (`Date` / `string` / `Uint8Array`). Turbine never emits those PowQL types
+ *     on write, so writing to such a column may not round-trip.
+ *
+ * v1 is a PROGRAMMATIC API (exported from `turbine-orm/powdb`); the CLI's
+ * `turbine generate` still defaults to Postgres. Routing a `powdb://` URL
+ * through the CLI would additionally need: a `powdbDialect.introspector`
+ * wired to a networked `exec`, and `cli/config.ts` teaching the generate
+ * funnel to construct a PowDB client instead of a `pg` client for `powdb://`.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.introspectPowdbDatabase = introspectPowdbDatabase;
+const errors_js_1 = require("./errors.js");
+const powdb_js_1 = require("./powdb.js");
+const schema_js_1 = require("./schema.js");
+/** Coerce a wire cell to string (legacy wire cells are strings; native cells may be typed). */
+function asString(v) {
+    return v === null || v === undefined ? '' : String(v);
+}
+/** Coerce a `describe` `nullable` cell (`"true"`/`"false"` or a native boolean) to a JS boolean. */
+function asBool(v) {
+    return v === true || asString(v).toLowerCase() === 'true';
+}
+/**
+ * Map a PowQL type name to the {@link ColumnMetadata} TS/dialect types. The
+ * `tsType` drives read coercion (`coerceValue`) and write typing
+ * (`powqlColumnType`); `dialectType`/`pgType` carry the PowQL type name so
+ * `isFloatColumn` / `isJsonColumn` classify correctly.
+ */
+function mapPowqlType(powqlType) {
+    switch (powqlType) {
+        case 'int':
+            return { tsType: 'number', dialectType: 'int' };
+        case 'float':
+            return { tsType: 'number', dialectType: 'float' };
+        case 'bool':
+            return { tsType: 'boolean', dialectType: 'bool' };
+        case 'json':
+            return { tsType: 'unknown', dialectType: 'json' };
+        case 'datetime':
+            return { tsType: 'Date', dialectType: 'datetime' };
+        case 'uuid':
+            return { tsType: 'string', dialectType: 'uuid' };
+        case 'bytes':
+            return { tsType: 'Uint8Array', dialectType: 'bytes' };
+        default:
+            // `str` and any unknown future scalar fall back to string.
+            return { tsType: 'string', dialectType: 'str' };
+    }
+}
+/**
+ * Read a live PowDB database into {@link SchemaMetadata} via `schema` +
+ * `describe <T>` statements run through the supplied {@link PowdbExec}.
+ *
+ * @param exec Rows-returning executor (embedded `db.raw` or networked `client.query`).
+ * @param options `include`/`exclude` table filters.
+ */
+async function introspectPowdbDatabase(exec, options = {}) {
+    // Gate on the engine's introspection capability (>= 0.10) when the caller
+    // knows the version, so a pre-0.10 engine gets a typed E017 hint instead of
+    // an opaque `unexpected token schema` parse error.
+    if (options.capabilities) {
+        (0, powdb_js_1.requireCapability)(options.capabilities, 'introspection', 'PowDB `describe` introspection');
+    }
+    // ----- Types (one row per table, columns `name`, `columns`) -----
+    const schemaRows = (await exec('schema')).rows;
+    let tableNames = schemaRows.map((r) => asString(r.name)).filter((n) => n.length > 0);
+    // A mis-shaped `exec` (e.g. the raw client's positional `string[][]` rows
+    // passed straight through) yields rows whose `name` cell is `undefined`, so
+    // every table filters out and the schema comes back silently empty. Refuse
+    // that instead of losing data: real rows must carry a `name`.
+    if (schemaRows.length > 0 && tableNames.length === 0) {
+        throw new errors_js_1.ValidationError(`[turbine] PowDB introspection: the \`schema\` statement returned ${schemaRows.length} row(s) but none carried a ` +
+            '`name` cell. The `exec` you supplied likely returns POSITIONAL rows (string[][]) rather than records keyed by ' +
+            'column name; zip `columns` with each row (see introspectPowdbDatabase docs).');
+    }
+    if (options.include?.length) {
+        const inc = new Set(options.include);
+        tableNames = tableNames.filter((t) => inc.has(t));
+    }
+    if (options.exclude?.length) {
+        const exc = new Set(options.exclude);
+        tableNames = tableNames.filter((t) => !exc.has(t));
+    }
+    const tables = {};
+    for (const tableName of tableNames) {
+        // `describe` needs the table name in bare-identifier position → quote it so
+        // a reserved-word / non-bare table name (`order`) does not become a parse
+        // error.
+        const describeRows = (await exec(`describe ${(0, powdb_js_1.quotePowqlIdent)(tableName)}`)).rows.map((r) => ({
+            column: asString(r.column),
+            type: asString(r.type),
+            nullable: asBool(r.nullable),
+            index: asString(r.index),
+        }));
+        const columns = [];
+        const columnMap = {};
+        const reverseColumnMap = {};
+        const dateColumns = new Set();
+        const dialectTypes = {};
+        const pgTypes = {};
+        const allColumns = [];
+        const uniqueColumns = [];
+        const indexes = [];
+        // PK heuristic candidates: non-nullable `unique` columns.
+        const pkCandidates = [];
+        for (const row of describeRows) {
+            const name = row.column;
+            const field = (0, schema_js_1.snakeToCamel)(name);
+            const { tsType, dialectType } = mapPowqlType(row.type);
+            const nullable = row.nullable;
+            const finalTs = nullable ? `${tsType} | null` : tsType;
+            const col = {
+                name,
+                field,
+                dialectType,
+                pgType: dialectType,
+                tsType: finalTs,
+                nullable,
+                // `describe` reports neither defaults nor the `auto` modifier.
+                hasDefault: false,
+                isGenerated: false,
+                isArray: false,
+                arrayType: undefined,
+                pgArrayType: 'text[]',
+            };
+            columns.push(col);
+            columnMap[field] = name;
+            reverseColumnMap[name] = field;
+            allColumns.push(name);
+            dialectTypes[name] = dialectType;
+            pgTypes[name] = dialectType;
+            if (dialectType === 'datetime')
+                dateColumns.add(name);
+            if (row.index === 'unique') {
+                uniqueColumns.push([name]);
+                if (!nullable)
+                    pkCandidates.push(name);
+            }
+            if (row.index === 'unique' || row.index === 'index') {
+                indexes.push({
+                    name: `${tableName}_${name}_idx`,
+                    columns: [name],
+                    unique: row.index === 'unique',
+                    definition: `${row.index === 'unique' ? 'unique ' : ''}index on ${tableName}(${name})`,
+                });
+            }
+        }
+        // Primary key: first non-nullable unique column, preferring one named `id`.
+        let primaryKey = [];
+        if (pkCandidates.length > 0) {
+            primaryKey = [pkCandidates.includes('id') ? 'id' : pkCandidates[0]];
+        }
+        else {
+            console.warn(`[turbine] PowDB introspection: table "${tableName}" has no non-nullable unique column; ` +
+                'primaryKey is [] (single-row operations will fail). Supply a primary key via code-first ' +
+                '`defineSchema` metadata if this table needs findUnique/update/delete by id.');
+        }
+        tables[tableName] = {
+            name: tableName,
+            columns,
+            columnMap,
+            reverseColumnMap,
+            dateColumns,
+            dialectTypes,
+            pgTypes,
+            allColumns,
+            primaryKey,
+            uniqueColumns,
+            // PowDB has no declared foreign keys → no relations from introspection.
+            relations: {},
+            indexes,
+        };
+    }
+    return { tables, enums: {} };
+}