turbine-orm 0.19.1 → 0.21.0

package/dist/dialect.d.ts

@@ -5,7 +5,8 @@
  * PostgreSQL-native by default, but query generation now depends on this
  * contract for the SQL primitives that vary across MySQL and SQLite.
  */
-import { type SchemaMetadata } from './schema.js';
+import type { WithOptions } from './query/types.js';
+import { type RelationDef, type SchemaMetadata, type TableMetadata } from './schema.js';
 export type DialectName = 'postgresql' | 'mysql' | 'sqlite' | (string & {});
 export interface InsertStatementInput {
     /** SQL-ready quoted table name. */
@@ -86,9 +87,136 @@ export interface CreateIndexStatementInput {
     /** SQL-ready quoted index columns. */
     columns: string[];
 }
+/**
+ * How a dialect surfaces the row(s) produced by an INSERT/UPDATE/DELETE/upsert.
+ *
+ *  - `'returning'` — a trailing `RETURNING *` clause returns the affected rows
+ *    in the same statement (PostgreSQL, SQLite ≥ 3.35). The executor reads them
+ *    directly from the statement result.
+ *  - `'output'` — the statement itself emits the rows in a non-RETURNING shape
+ *    (SQL Server `OUTPUT INSERTED.*`). Executed exactly like `'returning'`: the
+ *    rows come back on the statement result.
+ *  - `'reselect'` — the engine cannot return rows from a write (MySQL). The
+ *    executor runs the write, then issues a follow-up `SELECT` (by primary
+ *    key / unique / where predicate) to fetch the affected row(s). The build
+ *    method supplies the {@link DeferredQuery} `reselect` plan that owns the
+ *    statement ordering (write-then-select for create/update/upsert;
+ *    select-then-write for delete, whose row is gone after the statement runs).
+ */
+export type ResultStrategy = 'returning' | 'output' | 'reselect';
+/**
+ * Minimal connection surface needed to drive a server-side stream (cursor /
+ * driver iterator). `pg.PoolClient` and `PgCompatPoolClient` both satisfy it.
+ * Declared locally so {@link Dialect.openStream} stays free of an import cycle
+ * back into `client.ts`.
+ */
+export interface StreamableConnection {
+    query(text: string, values?: unknown[]): Promise<{
+        rows: Record<string, unknown>[];
+    }>;
+}
+/**
+ * Inputs for {@link Dialect.buildUpdateStatement} — full UPDATE assembly. Used by
+ * engines whose returning shape is injected MID-statement rather than as a trailing
+ * clause (SQL Server `OUTPUT INSERTED.*` lands between `SET …` and `WHERE …`).
+ */
+export interface UpdateStatementInput {
+    /** SQL-ready quoted table name. */
+    table: string;
+    /** SQL-ready `col = expr` assignments. */
+    setClauses: string[];
+    /** SQL-ready WHERE fragment INCLUDING the leading ` WHERE ` (or '' for none). */
+    whereSql: string;
+    /** SQL-ready returning selection (default `*`). */
+    returning?: string;
+}
+/**
+ * Inputs for {@link Dialect.buildDeleteStatement} — full DELETE assembly. SQL Server
+ * injects `OUTPUT DELETED.*` between `DELETE FROM <t>` and `WHERE …`.
+ */
+export interface DeleteStatementInput {
+    /** SQL-ready quoted table name. */
+    table: string;
+    /** SQL-ready WHERE fragment INCLUDING the leading ` WHERE ` (or '' for none). */
+    whereSql: string;
+    /** SQL-ready returning selection (default `*`). */
+    returning?: string;
+}
+/**
+ * Inputs for {@link Dialect.buildLimitOffset} — the trailing pagination clause of an
+ * outer SELECT. PostgreSQL/MySQL/SQLite use `LIMIT x [OFFSET y]`; SQL Server has no
+ * `LIMIT` and uses `[ORDER BY …] OFFSET y ROWS [FETCH NEXT x ROWS ONLY]` (which
+ * requires an ORDER BY — a stable default is injected when {@link hasOrderBy} is false).
+ */
+export interface LimitOffsetInput {
+    /** SQL-ready placeholder/literal for the row LIMIT, or undefined for no limit. */
+    limitPlaceholder?: string;
+    /** SQL-ready placeholder/literal for the OFFSET, or undefined for no offset. */
+    offsetPlaceholder?: string;
+    /** Whether the outer SELECT already carries an ORDER BY (so none must be injected). */
+    hasOrderBy: boolean;
+}
+/**
+ * Everything an engine needs to OVERRIDE nested-relation subquery generation, for
+ * dialects whose JSON-aggregation shape is fundamentally different from PostgreSQL's
+ * `json_agg(json_build_object(...))` (SQL Server's `FOR JSON PATH` expresses the
+ * object shape through the child SELECT's column ALIASES rather than an explicit
+ * `JSON_OBJECT`, so it cannot be assembled from {@link Dialect.buildJsonObject} /
+ * {@link Dialect.buildJsonArrayAgg} primitives — see {@link Dialect.buildRelationSubquery}).
+ *
+ * The query builder pre-resolves the parts that are engine-independent (alias,
+ * select/omit-resolved columns, recursion + param threading) and hands them to the
+ * dialect. **Param-push ordering contract:** the override MUST push values to
+ * {@link params} in the same order the builder's collect path expects so the SQL
+ * cache and pipeline batching stay in sync —
+ *   - to-many with `limit`/`orderBy` (the "wrap" path) and manyToMany:
+ *     `buildWhere(...)` → push `limit` → `recurse(...)` for each nested relation;
+ *   - everything else (to-one, unordered/unlimited to-many): `recurse(...)` for each
+ *     nested relation → `buildWhere(...)` (no limit param).
+ */
+export interface RelationSubqueryContext {
+    /** The relation being expanded (its `type`, `to`, `foreignKey`/`referenceKey`, `through`). */
+    relDef: RelationDef;
+    /** The `with` spec for this relation: `true`, or a {@link WithOptions} object. */
+    spec: true | WithOptions;
+    /** Shared parameter array — push BOUND values here in the order described above. */
+    params: unknown[];
+    /** Parent alias or table name (RAW identifier, not quoted) to correlate against. */
+    parentRef: string;
+    /** Pre-allocated unique alias for this relation's target rows (e.g. `t0`). */
+    alias: string;
+    /** Target table name (snake_case). */
+    targetTable: string;
+    /** Target table metadata. */
+    targetMeta: TableMetadata;
+    /** Resolved target columns (snake_case) honoring `select` / `omit`. */
+    targetColumns: string[];
+    /** Current recursion depth (for nested {@link recurse} calls, pass `depth + 1`). */
+    depth: number;
+    /** Breadcrumb path of relation/table names for circular-relation errors. */
+    path: string[];
+    /** Quote a RAW identifier through the active dialect. */
+    quote(name: string): string;
+    /**
+     * Build a WHERE fragment for `spec.where` against `whereAlias`, PUSHING its params
+     * to {@link params}. Returns '' when the spec has no `where`. Call exactly once.
+     */
+    buildWhere(whereAlias: string): string;
+    /**
+     * Recurse to build a nested relation's subquery (PUSHING its params to
+     * {@link params}). Uses the shared alias counter, so nested aliases never collide.
+     */
+    recurse(relDef: RelationDef, spec: true | WithOptions, parentRef: string, depth: number, path: string[]): string;
+}
 export interface Dialect {
     /** Dialect identifier. */
     readonly name: DialectName;
+    /**
+     * How write statements surface their affected rows. PostgreSQL uses
+     * `'returning'`; the executor branches on this so non-RETURNING engines
+     * (MySQL `'reselect'`, SQL Server `'output'`) can still return rows.
+     */
+    readonly resultStrategy: ResultStrategy;
     /** Parameter placeholder for the Nth value, using a 1-indexed public count. */
     paramPlaceholder(index: number): string;
     /** Quote a SQL identifier (table, column, cursor, alias). */
@@ -103,8 +231,42 @@ export interface Dialect {
     buildJsonObject(pairs: [key: string, expr: string][]): string;
     /** Build a JSON array aggregation expression with a dialect-specific empty-array fallback. */
     buildJsonArrayAgg(jsonObjectExpr: string, orderBy?: string): string;
+    /**
+     * Whether the array-aggregate (`buildJsonArrayAgg`) can take an inline
+     * `ORDER BY` argument. PostgreSQL's `json_agg(... ORDER BY ...)` can, so this
+     * is `true`. Engines whose array aggregate has no ORDER BY argument
+     * (MySQL `JSON_ARRAYAGG`, SQLite `json_group_array`) set this `false` to force
+     * the inner-subquery rewrite for every ordered to-many relation.
+     */
+    readonly aggSupportsInlineOrderBy: boolean;
+    /**
+     * Render `LIMIT` / `OFFSET` as inline integer literals instead of bound
+     * parameters. MySQL sets this `true`: mysql2's binary (prepared) protocol sends
+     * JS numbers as `DOUBLE`, which MySQL's `LIMIT`/`OFFSET` reject ("Incorrect
+     * arguments to mysqld_stmt_execute"). The values are Turbine-validated
+     * non-negative integers (never user strings), so inlining is injection-safe.
+     * PostgreSQL / SQLite / SQL Server leave this falsy and keep pagination
+     * parameterized, so their generated SQL stays byte-identical.
+     */
+    readonly inlineLimitOffset?: boolean;
+    /**
+     * Wrap a correlated nested-relation subquery (and its empty/null fallback) for
+     * embedding as a JSON value in a parent `json_build_object`. PostgreSQL emits
+     * `COALESCE((subquery), fallback)`. SQLite must additionally `json(...)`-wrap
+     * the subquery (its `json_group_array` double-encodes nested objects);
+     * SQL Server uses `ISNULL((... FOR JSON PATH), '[]')`.
+     */
+    wrapJsonSubresult(subquery: string, fallback: string): string;
     /** Whether INSERT/UPDATE/DELETE support RETURNING rows. */
     readonly supportsReturning: boolean;
+    /** Whether this dialect/engine supports pgvector distance ops (KNN / distance WHERE). */
+    readonly supportsVector: boolean;
+    /** Whether this dialect/engine supports LISTEN/NOTIFY realtime pub/sub. */
+    readonly supportsListenNotify: boolean;
+    /** Whether this dialect/engine supports row-level-security session GUCs (set_config). */
+    readonly supportsRLS: boolean;
+    /** Whether this dialect/engine supports advisory-lock-style migration locking. */
+    readonly supportsAdvisoryLock: boolean;
     /** Build a dialect-specific RETURNING clause. Return an empty string when unsupported. */
     buildReturningClause(selection?: string): string;
     /** Build a single-row INSERT statement. Inputs are SQL-ready quoted fragments. */
@@ -127,6 +289,32 @@ export interface Dialect {
     buildCorrelation(leftRef: string, leftColumns: string | string[], rightRef: string, rightColumns: string | string[]): string;
     /** Optional type mapping hook for code generation/introspection. */
     typeToTypeScript?(dialectType: string, nullable: boolean): string;
+    /**
+     * Cast an aggregate result expression to an integer or float SQL type.
+     * PostgreSQL uses the postfix casts `expr::int` / `expr::float`; portable
+     * engines (e.g. SQLite, which has no `::` cast operator) emit
+     * `CAST(expr AS INTEGER/REAL)`. Optional: when a dialect omits it, the query
+     * builder falls back to the PostgreSQL postfix cast, so dialects that predate
+     * this hook keep emitting byte-identical SQL.
+     */
+    castAggregate?(expr: string, target: 'int' | 'float'): string;
+    /**
+     * Build a membership (`IN` / `NOT IN`) predicate from a column/expression and
+     * a single bound parameter reference. PostgreSQL binds the whole list as one
+     * array param (`expr = ANY($n)` / `expr != ALL($n)`), so the placeholder count
+     * stays independent of the list length and the SQL cache remains valid.
+     * Engines without array parameters (SQLite) override this together with
+     * {@link inClauseParam} to use a length-independent single-placeholder form
+     * (e.g. `expr IN (SELECT value FROM json_each(?))`). Optional: the query
+     * builder falls back to the PostgreSQL `ANY`/`ALL` form when absent.
+     */
+    buildInClause?(expr: string, paramRef: string, negated: boolean): string;
+    /**
+     * The single bound value for an `IN` list (paired with {@link buildInClause}).
+     * PostgreSQL passes the array through unchanged; SQLite serializes it to a
+     * JSON string consumed by `json_each`. Optional: defaults to the array itself.
+     */
+    inClauseParam?(values: unknown[]): unknown;
     /** Optional array-cast hook for bulk insert implementations. */
     arrayType?(baseType: string): string;
     /** Map a schema-builder column type to dialect DDL. */
@@ -149,6 +337,68 @@ export interface Dialect {
     buildMigrationInsertApplied(table: string): string;
     /** Build the query that deletes a rolled-back migration record. */
     buildMigrationDeleteApplied(table: string): string;
+    /** `BEGIN`, optionally with a SQL-ready isolation-level suffix. */
+    beginStatement(isolationLevel?: string): string;
+    /** Commit the current transaction. */
+    commitStatement(): string;
+    /** Roll back the current transaction. */
+    rollbackStatement(): string;
+    /** Establish a savepoint with the given (SQL-ready) name. */
+    savepointStatement(name: string): string;
+    /** Release the named savepoint. */
+    releaseSavepointStatement(name: string): string;
+    /** Roll back to the named savepoint. */
+    rollbackToSavepointStatement(name: string): string;
+    /**
+     * Build a transaction-local session-config (GUC) assignment for RLS /
+     * multi-tenant context. Both name and value are bound parameters.
+     */
+    buildSetSessionConfig(name: string, value: string): BuiltStatement;
+    /**
+     * Drive a server-side stream of result rows on a single connection, yielding
+     * row batches of up to `batchSize`. PostgreSQL uses a `DECLARE CURSOR` /
+     * `FETCH` / `CLOSE` loop inside a transaction; other engines use their
+     * driver's native streaming iterator.
+     */
+    openStream(connection: StreamableConnection, sql: string, params: unknown[], batchSize: number): AsyncGenerator<Record<string, unknown>[], void, undefined>;
+    /**
+     * Schema introspector for this engine. `introspect()` routes through it so
+     * engines can override the catalog SQL. PostgreSQL wraps the
+     * information_schema / pg_catalog reader in `introspect.ts`.
+     */
+    readonly introspector?: DialectIntrospector;
+    /**
+     * Build the trailing pagination clause for an OUTER SELECT. Optional: when a
+     * dialect omits it, the query builder emits the PostgreSQL form
+     * (` LIMIT <ph>` and/or ` OFFSET <ph>`), so PG/MySQL/SQLite stay byte-identical.
+     * SQL Server has no `LIMIT`, so it implements this to emit
+     * `[ORDER BY (SELECT NULL)] OFFSET <off> ROWS [FETCH NEXT <lim> ROWS ONLY]`.
+     */
+    buildLimitOffset?(input: LimitOffsetInput): string;
+    /**
+     * Assemble a full UPDATE statement. Optional: omitted by engines whose returning
+     * shape is a trailing clause (PG/SQLite `RETURNING`, MySQL none) — the builder
+     * falls back to `UPDATE <t> SET <set> <where><returningClause>`. SQL Server
+     * implements this to inject `OUTPUT INSERTED.*` between `SET …` and `WHERE …`.
+     */
+    buildUpdateStatement?(input: UpdateStatementInput): string;
+    /**
+     * Assemble a full DELETE statement. Optional: see {@link buildUpdateStatement}.
+     * SQL Server injects `OUTPUT DELETED.*` between `DELETE FROM <t>` and `WHERE …`.
+     */
+    buildDeleteStatement?(input: DeleteStatementInput): string;
+    /**
+     * OVERRIDE nested-relation subquery generation entirely. Optional: when a dialect
+     * omits it, the builder uses its native `json_agg(json_build_object(...))` path
+     * (PG) routed through {@link buildJsonObject} / {@link buildJsonArrayAgg} /
+     * {@link wrapJsonSubresult} — so MySQL and SQLite, which only swap those
+     * primitives, produce identical output and never define this hook. SQL Server
+     * defines it to emit `FOR JSON PATH` correlated subqueries (its JSON aggregate
+     * is expressed through the child SELECT's column aliases, which does not map onto
+     * the primitive hooks). See {@link RelationSubqueryContext} for the
+     * param-push-ordering contract the override must honor.
+     */
+    buildRelationSubquery?(ctx: RelationSubqueryContext): string;
 }
 export interface DialectIntrospector {
     introspect(options: IntrospectOptions): Promise<SchemaMetadata>;
@@ -159,6 +409,13 @@ export interface IntrospectOptions {
     include?: string[];
     exclude?: string[];
 }
+/**
+ * @deprecated Migration locking is owned by the {@link DatabaseAdapter} seam
+ * (`src/adapters/index.ts` — `acquireLock`/`releaseLock`/`statementTimeout`),
+ * which is the single canonical locking seam. This interface was never
+ * implemented or wired and is retained only for type back-compat; new engines
+ * MUST provide a `DatabaseAdapter` instead. Will be removed in a future major.
+ */
 export interface DialectMigrator {
     acquireLock(lockId: number): Promise<boolean>;
     releaseLock(lockId: number): Promise<void>;

package/dist/dialect.js

@@ -10,11 +10,17 @@ import { pgArrayType, pgTypeToTs } from './schema.js';
 /** PostgreSQL implementation of the dialect contract. */
 export const postgresDialect = {
     name: 'postgresql',
+    resultStrategy: 'returning',
     supportsReturning: true,
     supportsILike: true,
     jsonPathSupport: 'native',
     emptyJsonArrayLiteral: "'[]'::json",
     nullJsonLiteral: 'NULL',
+    aggSupportsInlineOrderBy: true,
+    supportsVector: true,
+    supportsListenNotify: true,
+    supportsRLS: true,
+    supportsAdvisoryLock: true,
     paramPlaceholder(index) {
         return `$${index}`;
     },
@@ -32,6 +38,9 @@ export const postgresDialect = {
         const suffix = orderBy ? ` ${orderBy}` : '';
         return `COALESCE(json_agg(${jsonObjectExpr}${suffix}), ${this.emptyJsonArrayLiteral})`;
     },
+    wrapJsonSubresult(subquery, fallback) {
+        return `COALESCE((${subquery}), ${fallback})`;
+    },
     buildReturningClause(selection = '*') {
         return ` RETURNING ${selection}`;
     },
@@ -73,6 +82,15 @@ export const postgresDialect = {
     typeToTypeScript(dialectType, nullable) {
         return pgTypeToTs(dialectType, nullable);
     },
+    castAggregate(expr, target) {
+        return `${expr}::${target}`;
+    },
+    buildInClause(expr, paramRef, negated) {
+        return negated ? `${expr} != ALL(${paramRef})` : `${expr} = ANY(${paramRef})`;
+    },
+    inClauseParam(values) {
+        return values;
+    },
     arrayType(baseType) {
         return pgArrayType(baseType);
     },
@@ -128,5 +146,70 @@ export const postgresDialect = {
     buildMigrationDeleteApplied(table) {
         return `DELETE FROM ${table} WHERE name = ${this.paramPlaceholder(1)}`;
     },
+    beginStatement(isolationLevel) {
+        return isolationLevel ? `BEGIN ISOLATION LEVEL ${isolationLevel}` : 'BEGIN';
+    },
+    commitStatement() {
+        return 'COMMIT';
+    },
+    rollbackStatement() {
+        return 'ROLLBACK';
+    },
+    savepointStatement(name) {
+        return `SAVEPOINT ${name}`;
+    },
+    releaseSavepointStatement(name) {
+        return `RELEASE SAVEPOINT ${name}`;
+    },
+    rollbackToSavepointStatement(name) {
+        return `ROLLBACK TO SAVEPOINT ${name}`;
+    },
+    buildSetSessionConfig(name, value) {
+        // set_config(name, value, is_local=true) — the parameterizable,
+        // transaction-local equivalent of `SET LOCAL` (which rejects bind params).
+        return {
+            sql: `SELECT set_config(${this.paramPlaceholder(1)}, ${this.paramPlaceholder(2)}, true)`,
+            params: [name, value],
+        };
+    },
+    async *openStream(connection, sql, params, batchSize) {
+        // Cursors require a single connection inside a transaction. Identical SQL
+        // sequence to the historical inline implementation: BEGIN → DECLARE … NO
+        // SCROLL CURSOR FOR → FETCH n (loop) → CLOSE → COMMIT; ROLLBACK on error.
+        const cursorName = `turbine_cursor_${Date.now()}_${Math.random().toString(36).slice(2, 8)}`;
+        const quotedCursor = this.quoteIdentifier(cursorName);
+        await connection.query(this.beginStatement());
+        try {
+            await connection.query(`DECLARE ${quotedCursor} NO SCROLL CURSOR FOR ${sql}`, params);
+            while (true) {
+                const batch = await connection.query(`FETCH ${batchSize} FROM ${quotedCursor}`);
+                if (batch.rows.length === 0)
+                    break;
+                yield batch.rows;
+                if (batch.rows.length < batchSize)
+                    break;
+            }
+            await connection.query(`CLOSE ${quotedCursor}`);
+            await connection.query(this.commitStatement());
+        }
+        catch (err) {
+            try {
+                await connection.query(this.rollbackStatement());
+            }
+            catch {
+                // Connection may already be broken — ignore rollback error.
+            }
+            throw err;
+        }
+    },
+    // Postgres introspection wraps the information_schema / pg_catalog reader in
+    // introspect.ts. A dynamic import keeps the static graph acyclic (introspect.ts
+    // imports postgresDialect) and calls the raw catalog reader (never the router).
+    introspector: {
+        async introspect(options) {
+            const { introspectPostgresCatalog } = await import('./introspect.js');
+            return introspectPostgresCatalog(options);
+        },
+    },
 };
 //# sourceMappingURL=dialect.js.map

package/dist/errors.d.ts

@@ -22,6 +22,7 @@ export declare const TurbineErrorCode: {
     readonly PIPELINE: "TURBINE_E014";
     readonly OPTIMISTIC_LOCK: "TURBINE_E015";
     readonly EXCLUSION_VIOLATION: "TURBINE_E016";
+    readonly UNSUPPORTED_FEATURE: "TURBINE_E017";
 };
 export type TurbineErrorCode = (typeof TurbineErrorCode)[keyof typeof TurbineErrorCode];
 /** Base error class for all Turbine errors */
@@ -273,6 +274,17 @@ export declare class OptimisticLockError extends TurbineError {
         expectedVersion: unknown;
     });
 }
+/**
+ * Thrown when a Postgres-only feature (pgvector distance ops, LISTEN/NOTIFY
+ * realtime, RLS session GUCs, advisory-lock migration locking, ...) is invoked
+ * on a dialect/engine whose capability flag reports it unsupported. Surfaces a
+ * clear `unsupported on <engine>` message instead of generating broken SQL.
+ */
+export declare class UnsupportedFeatureError extends TurbineError {
+    readonly feature: string;
+    readonly dialect: string;
+    constructor(feature: string, dialect: string, hint?: string);
+}
 /**
  * Translate a pg driver error into a typed Turbine error.
  * If the error doesn't match a known constraint code, returns it unchanged.

package/dist/errors.js

@@ -22,6 +22,7 @@ export const TurbineErrorCode = {
     PIPELINE: 'TURBINE_E014',
     OPTIMISTIC_LOCK: 'TURBINE_E015',
     EXCLUSION_VIOLATION: 'TURBINE_E016',
+    UNSUPPORTED_FEATURE: 'TURBINE_E017',
 };
 /** Base error class for all Turbine errors */
 export class TurbineError extends Error {
@@ -435,6 +436,22 @@ export class OptimisticLockError extends TurbineError {
         this.expectedVersion = opts.expectedVersion;
     }
 }
+/**
+ * Thrown when a Postgres-only feature (pgvector distance ops, LISTEN/NOTIFY
+ * realtime, RLS session GUCs, advisory-lock migration locking, ...) is invoked
+ * on a dialect/engine whose capability flag reports it unsupported. Surfaces a
+ * clear `unsupported on <engine>` message instead of generating broken SQL.
+ */
+export class UnsupportedFeatureError extends TurbineError {
+    feature;
+    dialect;
+    constructor(feature, dialect, hint) {
+        super(TurbineErrorCode.UNSUPPORTED_FEATURE, `[turbine] ${feature} is unsupported on "${dialect}".${hint ? ` ${hint}` : ''}`);
+        this.name = 'UnsupportedFeatureError';
+        this.feature = feature;
+        this.dialect = dialect;
+    }
+}
 /**
  * Parse column names out of a pg `detail` string like:
  *   "Key (email)=(foo@bar) already exists."

package/dist/generate.js

@@ -359,6 +359,10 @@ function generateMetadata(schema) {
     lines.push('  },');
     lines.push('};');
     lines.push('');
+    // Back-compat lowercase alias. `SCHEMA` is the canonical export, but docs and
+    // users frequently import `schema`; emit both so either name resolves.
+    lines.push('export const schema = SCHEMA;');
+    lines.push('');
     return lines.join('\n');
 }
 // ---------------------------------------------------------------------------

package/dist/index.d.ts

@@ -34,16 +34,16 @@
  */
 export type { DatabaseAdapter, IntrospectionOverrides } from './adapters/index.js';
 export { alloydb, cockroachdb, postgresql, timescale, yugabytedb } from './adapters/index.js';
-export { type Middleware, type MiddlewareNext, type MiddlewareParams, type PgCompatPool, type PgCompatPoolClient, type PgCompatQueryResult, type RetryOptions, TransactionClient, type TransactionOptions, TurbineClient, type TurbineConfig, withRetry, } from './client.js';
-export type { BuiltStatement, BulkInsertStatementInput, ColumnDefinitionInput, ColumnTypeInput, CreateIndexStatementInput, CreateTableStatementInput, Dialect, DialectIntrospector, DialectMigrator, DialectName, InsertStatementInput, IntrospectOptions as DialectIntrospectOptions, UpsertStatementInput, } from './dialect.js';
+export { type Middleware, type MiddlewareNext, type MiddlewareParams, type PgCompatPool, type PgCompatPoolClient, type PgCompatQueryResult, type RetryOptions, TransactionClient, type TransactionOptions, TurbineClient, type TurbineConfig, type TurbineDriver, withRetry, } from './client.js';
+export type { BuiltStatement, BulkInsertStatementInput, ColumnDefinitionInput, ColumnTypeInput, CreateIndexStatementInput, CreateTableStatementInput, Dialect, DialectIntrospector, DialectMigrator, DialectName, InsertStatementInput, IntrospectOptions as DialectIntrospectOptions, ResultStrategy, StreamableConnection, UpsertStatementInput, } from './dialect.js';
 export { postgresDialect } from './dialect.js';
-export { CheckConstraintError, CircularRelationError, ConnectionError, DeadlockError, type ErrorMessageMode, ExclusionConstraintError, ForeignKeyError, getErrorMessageMode, MigrationError, NotFoundError, NotNullViolationError, OptimisticLockError, PipelineError, type PipelineResultSlot, RelationError, SerializationFailureError, setErrorMessageMode, TimeoutError, TurbineError, TurbineErrorCode, UniqueConstraintError, ValidationError, wrapPgError, } from './errors.js';
+export { CheckConstraintError, CircularRelationError, ConnectionError, DeadlockError, type ErrorMessageMode, ExclusionConstraintError, ForeignKeyError, getErrorMessageMode, MigrationError, NotFoundError, NotNullViolationError, OptimisticLockError, PipelineError, type PipelineResultSlot, RelationError, SerializationFailureError, setErrorMessageMode, TimeoutError, TurbineError, TurbineErrorCode, UniqueConstraintError, UnsupportedFeatureError, ValidationError, wrapPgError, } from './errors.js';
 export { type GenerateOptions, generate } from './generate.js';
 export { type IntrospectOptions, introspect } from './introspect.js';
 export { executeNestedCreate, executeNestedUpdate, hasRelationFields, type NestedWriteContext, } from './nested-write.js';
 export type { ObserveConfig, ObserveHandle } from './observe.js';
 export { executePipeline, type PipelineOptions, type PipelineResults, pipelineSupported } from './pipeline.js';
-export { type AggregateArgs, type AggregateResult, type ArrayFilter, type ConnectOrCreateOp, type CountArgs, type CreateArgs, type CreateManyArgs, type DeferredQuery, type DeleteArgs, type DeleteManyArgs, type FieldResult, type FindManyArgs, type FindManyStreamArgs, type FindUniqueArgs, type GroupByArgs, type HavingClause, type JsonFilter, type MiddlewareFn, type NestedCreateOp, type NestedUpdateOp, type OmitResult, type OrderByClause, type OrderDirection, type QueryEvent, type QueryEventListener, QueryInterface, type QueryResult, type RelationDescriptor, type RelationFilter, type SelectResult, type TextSearchFilter, type TypedWithClause, type UpdateArgs, type UpdateInput, type UpdateManyArgs, type UpdateOperatorInput, type UpsertArgs, type VectorDistanceFilter, type VectorFilter, type VectorMetric, type VectorOrderBy, type VectorOrderByDistance, type WhereClause, type WhereOperator, type WhereValue, type WithClause, type WithOptions, type WithResult, } from './query/index.js';
+export { type AggregateArgs, type AggregateResult, type ArrayFilter, type ConnectOrCreateOp, type CountArgs, type CreateArgs, type CreateDataInput, type CreateManyArgs, type DeferredQuery, type DeleteArgs, type DeleteManyArgs, type FieldResult, type FindManyArgs, type FindManyStreamArgs, type FindUniqueArgs, type GroupByArgs, type HavingClause, type JsonFilter, type MiddlewareFn, type NestedCreateOp, type NestedUpdateOp, type NestedUpdateOpItem, type NestedUpsertOpItem, type OmitResult, type OrderByClause, type OrderDirection, type QueryEvent, type QueryEventListener, QueryInterface, type QueryResult, type RelationDescriptor, type RelationFilter, type SelectResult, type TextSearchFilter, type TypedWithClause, type UpdateArgs, type UpdateDataInput, type UpdateInput, type UpdateManyArgs, type UpdateOperatorInput, type UpsertArgs, type VectorDistanceFilter, type VectorFilter, type VectorMetric, type VectorOrderBy, type VectorOrderByDistance, type WhereClause, type WhereOperator, type WhereValue, type WithClause, type WithOptions, type WithResult, } from './query/index.js';
 export { type ActiveSubscription, type NotificationHandler, type Subscription, validateChannel } from './realtime.js';
 export type { ColumnMetadata, IndexMetadata, RelationDef, SchemaMetadata, TableMetadata, } from './schema.js';
 export { camelToSnake, isDateType, normalizeKeyColumns, pgArrayType, pgTypeToTs, singularize, snakeToCamel, snakeToPascal, } from './schema.js';

package/dist/index.js

@@ -37,7 +37,7 @@ export { alloydb, cockroachdb, postgresql, timescale, yugabytedb } from './adapt
 export { TransactionClient, TurbineClient, withRetry, } from './client.js';
 export { postgresDialect } from './dialect.js';
 // Error types
-export { CheckConstraintError, CircularRelationError, ConnectionError, DeadlockError, ExclusionConstraintError, ForeignKeyError, getErrorMessageMode, MigrationError, NotFoundError, NotNullViolationError, OptimisticLockError, PipelineError, RelationError, SerializationFailureError, setErrorMessageMode, TimeoutError, TurbineError, TurbineErrorCode, UniqueConstraintError, ValidationError, wrapPgError, } from './errors.js';
+export { CheckConstraintError, CircularRelationError, ConnectionError, DeadlockError, ExclusionConstraintError, ForeignKeyError, getErrorMessageMode, MigrationError, NotFoundError, NotNullViolationError, OptimisticLockError, PipelineError, RelationError, SerializationFailureError, setErrorMessageMode, TimeoutError, TurbineError, TurbineErrorCode, UniqueConstraintError, UnsupportedFeatureError, ValidationError, wrapPgError, } from './errors.js';
 // Code generation
 export { generate } from './generate.js';
 // Introspection

package/dist/introspect.d.ts

@@ -7,6 +7,7 @@
  *
  * This is the foundation of `npx turbine generate`.
  */
+import { type Dialect } from './dialect.js';
 import { type SchemaMetadata } from './schema.js';
 export interface IntrospectOptions {
     /** Postgres connection string */
@@ -17,6 +18,23 @@ export interface IntrospectOptions {
     include?: string[];
     /** Tables to exclude (default: none). Applied after include. */
     exclude?: string[];
+    /**
+     * Dialect whose {@link Dialect.introspector} drives the catalog reads.
+     * Defaults to {@link postgresDialect}. Engines plug their own introspector
+     * here so `introspect()` works across databases.
+     */
+    dialect?: Dialect;
 }
+/**
+ * Introspect a database into {@link SchemaMetadata}, routing through the active
+ * dialect's {@link Dialect.introspector} so each engine can override the catalog
+ * SQL. PostgreSQL is driven by {@link introspectPostgresCatalog}.
+ */
 export declare function introspect(options: IntrospectOptions): Promise<SchemaMetadata>;
+/**
+ * PostgreSQL catalog introspector: reads information_schema + pg_catalog and
+ * produces {@link SchemaMetadata}. This is the implementation wrapped by
+ * `postgresDialect.introspector`; call {@link introspect} for dialect routing.
+ */
+export declare function introspectPostgresCatalog(options: IntrospectOptions): Promise<SchemaMetadata>;
 //# sourceMappingURL=introspect.d.ts.map

package/dist/introspect.js

@@ -94,7 +94,26 @@ const SQL_ENUMS = `
 // ---------------------------------------------------------------------------
 // Main introspection function
 // ---------------------------------------------------------------------------
+/**
+ * Introspect a database into {@link SchemaMetadata}, routing through the active
+ * dialect's {@link Dialect.introspector} so each engine can override the catalog
+ * SQL. PostgreSQL is driven by {@link introspectPostgresCatalog}.
+ */
 export async function introspect(options) {
+    const dialect = options.dialect ?? postgresDialect;
+    const introspector = dialect.introspector;
+    if (introspector) {
+        return introspector.introspect(options);
+    }
+    // Dialects without an introspector fall back to the Postgres catalog reader.
+    return introspectPostgresCatalog(options);
+}
+/**
+ * PostgreSQL catalog introspector: reads information_schema + pg_catalog and
+ * produces {@link SchemaMetadata}. This is the implementation wrapped by
+ * `postgresDialect.introspector`; call {@link introspect} for dialect routing.
+ */
+export async function introspectPostgresCatalog(options) {
     const schema = options.schema ?? 'public';
     const dialect = postgresDialect;
     const pool = new pg.Pool({