turbine-orm 0.49.0 → 0.50.0

package/dist/cjs/introspect.d.ts

@@ -0,0 +1,269 @@
+/**
+ * turbine-orm — Schema introspection
+ *
+ * Connects to a live Postgres database, reads information_schema + pg_catalog,
+ * and produces a SchemaMetadata object describing every table, column, relation,
+ * and index in the target schema.
+ *
+ * This is the foundation of `npx turbine generate`.
+ */
+import { type Dialect } from './dialect.js';
+import { type ColumnMetadata, type IndexMetadata, type ReferentialAction, type RelationDef, type SchemaMetadata } from './schema.js';
+/**
+ * Map a `pg_constraint.confdeltype` / `confupdtype` character to a
+ * {@link ReferentialAction}. Postgres encodes: `a` = NO ACTION, `r` = RESTRICT,
+ * `c` = CASCADE, `n` = SET NULL, `d` = SET DEFAULT.
+ */
+export declare function pgConfActionToReferential(ch: string): ReferentialAction;
+/**
+ * Migration-bookkeeping tables that introspection drops by default: Turbine's
+ * own `_turbine_migrations` / `_turbine_metrics` and Prisma's
+ * `_prisma_migrations`. These are almost never meant to be surfaced as typed
+ * accessors, and a fresh migrate-from-Prisma introspection would otherwise emit
+ * a `PrismaMigrations` entity plus stray FK-derived relations on neighbours.
+ *
+ * A table named here is dropped UNLESS it is explicitly listed in
+ * `options.include` (`include` is the escape hatch, no separate flag), and
+ * naming a default-excluded table restores its old generated output byte for
+ * byte. The list is deliberately tight (exactly these three); leading-
+ * underscore tables are legitimate user tables and are never blanket-excluded.
+ */
+export declare const DEFAULT_EXCLUDED_TABLES: readonly ["_turbine_migrations", "_prisma_migrations", "_turbine_metrics"];
+/** The include / exclude filters shared by every introspector's table selection. */
+export interface TableFilterOptions {
+    /** Tables to include (empty/undefined = all). Applied first. */
+    include?: string[];
+    /** Tables the user asked to exclude. Applied after include. */
+    exclude?: string[];
+}
+/**
+ * The single authority for turning a raw list of candidate table names into the
+ * introspected set, shared by the Postgres catalog reader and every engine
+ * introspector (SQLite / MySQL / MSSQL / PowDB) so all surfaces agree.
+ *
+ * Order of operations:
+ *   1. `include` filter: when non-empty, keep only the named tables.
+ *   2. user `exclude`: drop anything the caller listed.
+ *   3. {@link DEFAULT_EXCLUDED_TABLES}: drop migration bookkeeping tables,
+ *      EXCEPT any that the caller explicitly named in `include` (the escape
+ *      hatch that restores the pre-0.41 output for those tables).
+ */
+export declare function applyTableFilters(names: string[], options?: TableFilterOptions): string[];
+/**
+ * The subset of {@link DEFAULT_EXCLUDED_TABLES} that were present in `names` but
+ * dropped by {@link applyTableFilters} (i.e. not re-added via `include`). Pure
+ * helper so the CLI can report "skipped internal table X" without re-deriving
+ * the filtering rule.
+ */
+export declare function defaultExcludedTablesPresent(names: string[], options?: TableFilterOptions): string[];
+export interface IntrospectOptions {
+    /** Postgres connection string */
+    connectionString: string;
+    /** Schema to introspect (default: 'public') */
+    schema?: string;
+    /** Tables to include (default: all). Glob-like patterns not supported yet. */
+    include?: string[];
+    /** Tables to exclude (default: none). Applied after include. */
+    exclude?: string[];
+    /**
+     * Also introspect **views** and **materialized views** as read-only
+     * {@link TableMetadata} entries (`isView: true`). Off by default. Write
+     * builders reject views (E003); a view without a primary key is excluded from
+     * the generated `findUnique`-family accessor types.
+     */
+    includeViews?: boolean;
+    /**
+     * Opt OUT of the unique-FK → `hasOne` flip (F2). By default (`false`)
+     * introspection emits a to-one (`hasOne`) relation on the parent side when a
+     * child's foreign-key column set is EXACTLY covered by a UNIQUE constraint or
+     * a non-partial, non-expression UNIQUE index, matching Prisma one-to-one
+     * introspection. Set to `true` to keep the pre-0.41 behavior where every such
+     * relation was emitted as `hasMany` (a to-many array). See
+     * {@link detectUniqueForeignKeySets}.
+     */
+    legacyToManyUniques?: boolean;
+    /**
+     * Called with any {@link DEFAULT_EXCLUDED_TABLES} that were present in the
+     * database but dropped from this run (F12), so the CLI can print a
+     * "skipped internal table X (add it to include to keep it)" note. Not invoked
+     * when the set is empty. Postgres path only for now.
+     */
+    onDefaultTableExclusion?: (tables: string[]) => void;
+    /**
+     * 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>;
+/**
+ * Parse the indexed column names out of a `pg_indexes.indexdef` string.
+ *
+ * `indexdef` always reads `CREATE [UNIQUE] INDEX name ON tbl USING method
+ * (col, ...) [WHERE predicate]`. We anchor on the `USING` clause's parenthesised
+ * column list (the same precedent as `describeIndexDefMismatch` in
+ * schema-sql.ts) so a PARTIAL index's trailing `WHERE (...)` parentheses are
+ * never mistaken for the column list. The older greedy `/\((.+)\)/` swallowed
+ * `) WHERE (` and spliced a raw predicate fragment into the column names, which
+ * then leaked into generated compound-unique selector names.
+ *
+ * Each column is de-quoted (Postgres quotes non-lowercase identifiers such as a
+ * Prisma implicit m2m junction's `"A"` / `"B"`), so the names match the
+ * unquoted column names carried elsewhere in the metadata. Expression columns
+ * (anything containing a parenthesis) are dropped conservatively: a functional
+ * index does not name a plain column.
+ */
+export declare function parseIndexColumns(indexdef: string): string[];
+/**
+ * Whether an `indexdef` carries a top-level `WHERE` predicate (a PARTIAL index).
+ * pg_indexes only ever emits `WHERE` as the partial predicate, so a keyword
+ * match is sufficient (matches the `describeIndexDefMismatch` precedent).
+ */
+export declare function indexHasWhere(indexdef: string): boolean;
+/**
+ * Recover the raw check expression from `pg_get_constraintdef` output, which
+ * wraps it as `CHECK ((expr))`. Strips the leading `CHECK ` keyword and one
+ * balanced outer paren pair; leaves anything unexpected untouched.
+ */
+export declare function stripCheckWrapper(def: string): string;
+/** A foreign-key constraint grouped by constraint name (composite FKs carry column arrays). */
+export interface ForeignKeyEntry {
+    sourceTable: string;
+    sourceColumns: string[];
+    targetTable: string;
+    targetColumns: string[];
+    constraintName: string;
+}
+/**
+ * Derive a belongsTo relation name from its FK column. Strips a trailing
+ * `_id` (snake_case) or `Id` (camelCase column names — common in Prisma-ported
+ * schemas where columns are quoted camelCase identifiers), then camelCases:
+ * `current_version_id` and `currentVersionId` both yield `currentVersion`.
+ * Stripping is what keeps the scalar FK field (`currentVersionId`) targetable
+ * alongside the relation. A column literally named `id` (nothing left after
+ * stripping) keeps its own name.
+ */
+export declare function relationNameFromColumn(column: string): string;
+/**
+ * True for the tsType forms a json/jsonb column maps to (`unknown`, nullable
+ * `unknown | null`). A relation shadowing such a column is a HISTORICAL shadow
+ * that worked at runtime and compiled (`unknown` absorbs the relation
+ * payload), so the legacy-first naming keeps it instead of renaming.
+ */
+export declare function isUnknownTsType(tsType: string): boolean;
+/**
+ * Parse the column list of a PLAIN unique index from its `pg_indexes.indexdef`,
+ * returning `null` for anything that does NOT guarantee at-most-one child row:
+ *
+ *   - a PARTIAL index (has a `WHERE` clause): only unique within the predicate;
+ *   - an EXPRESSION index (`lower(email)`, `(a || b)`): the uniqueness is on the
+ *     expression, not the raw FK column set.
+ *
+ * Anchors on the `USING <method> (` clause the same way
+ * {@link describeIndexDefMismatch} does, so a partial index's `WHERE (...)`
+ * parentheses are never mistaken for the column list. Every column token must be
+ * a bare or double-quoted identifier; anything else (a function call, an
+ * operator expression) fails the check and yields `null`.
+ */
+export declare function parsePlainUniqueIndexColumns(indexdef: string): string[] | null;
+/**
+ * Assemble, per table, every column set that EXACTLY guarantees at-most-one row:
+ * the primary key, every UNIQUE constraint, and every PLAIN (non-partial,
+ * non-expression) UNIQUE index. Consumed by
+ * {@link buildRelationsFromForeignKeys} to flip a child relation whose FK column
+ * set matches one of these sets from `hasMany` to `hasOne` (F2, Prisma
+ * one-to-one parity).
+ */
+export declare function detectUniqueForeignKeySets(pkByTable: Map<string, string[]>, uniqueByTable: Map<string, string[][]>, indexesByTable: Map<string, IndexMetadata[]>): Map<string, string[][]>;
+/**
+ * Build the belongsTo/hasMany relation maps for every table from its foreign
+ * keys. Naming rules (LEGACY-FIRST — a relation name that previously worked at
+ * runtime must never change out from under a regenerating app):
+ *
+ *   1. First compute the historical derivation exactly as it shipped before
+ *      the collision guard existed: belongsTo strips a case-SENSITIVE `_id`
+ *      suffix (`snakeToCamel(col.replace(/_id$/, ''))` when several FKs point
+ *      at the same target, else the singularized target table), and hasMany is
+ *      `snakeToCamel(`${source}_by_${strippedColumn}`)` (else the source
+ *      table). If that legacy name is free, KEEP IT — even when it looks odd
+ *      (`blogPostsByAuthorId`, `postsBy_Author`): those names were collision-
+ *      free and worked, so regenerating must not rename them.
+ *   2. If the legacy name collides ONLY with a scalar column whose tsType is
+ *      `unknown` (json/jsonb), keep it anyway with a warning: the shadow is
+ *      historical, ran fine at runtime, and compiled (`unknown` absorbs the
+ *      relation payload; generate.ts's typeSafeRelations omits the relation
+ *      from the type layer).
+ *   3. On a genuine collision (concrete-typed column shadow, or a previously
+ *      assigned relation), fall back to the modern derivation — the `_id`/`Id`
+ *      case-insensitive strip of {@link relationNameFromColumn} plus the
+ *      `By`-composed reverse name — which fixes the camelCase-FK shadowing
+ *      shapes that were actually BROKEN before (relation name === scalar FK
+ *      field → unusable types).
+ *   4. Last resort: deterministic `Rel`/`Rel2` suffix + warning.
+ *
+ * @param columnFieldsByTable camelCase column *fields* per table — used to
+ *   guarantee relations never shadow concrete-typed scalar columns.
+ * @param unknownTypedFieldsByTable subset of the column fields whose tsType is
+ *   `unknown` (json/jsonb) — legacy shadows of these are preserved (rule 2).
+ * @param uniqueSetsByTable when provided (F2), the child-table column sets that
+ *   guarantee at-most-one row (PK + unique constraints + plain unique indexes,
+ *   from {@link detectUniqueForeignKeySets}). A reverse relation whose FK column
+ *   set EXACTLY matches one of the child's unique sets is emitted as `hasOne`
+ *   (to-one) instead of `hasMany`, and named with the SINGULAR of the child
+ *   table (falling back to the legacy plural name on collision). Omit it (the
+ *   engine introspectors and `defineSchema` path do) to keep every reverse
+ *   relation `hasMany`.
+ */
+export declare function buildRelationsFromForeignKeys(foreignKeys: ForeignKeyEntry[], columnFieldsByTable: Map<string, Set<string>>, fkActions?: Map<string, {
+    onDelete: ReferentialAction;
+    onUpdate: ReferentialAction;
+}>, unknownTypedFieldsByTable?: Map<string, Set<string>>, uniqueSetsByTable?: Map<string, string[][]>): Map<string, Record<string, RelationDef>>;
+/**
+ * Conservative auto-`manyToMany` detection over pure junction tables, shared
+ * by the Postgres introspector, the engine introspectors (SQLite / MySQL /
+ * MSSQL), the MCP server, and `schemaDefToMetadata()` so all surfaces derive
+ * IDENTICAL relation names for the same logical schema.
+ *
+ * A table J is a PURE junction only when ALL of these hold:
+ *   1. J's junction KEY is exactly two columns: either a two-column primary
+ *      key, OR (Prisma implicit m2m junctions have NO primary key) a two-column
+ *      UNIQUE index over exactly the two FK columns, supplied via the optional
+ *      `uniqueIndexColsByTable`. When that map is absent the behavior is
+ *      unchanged: only a two-column PK qualifies.
+ *   2. J has exactly two FKs, each single-column.
+ *   3. Each FK's source column is one of J's two key columns.
+ *   4. The two FKs target two DISTINCT tables (A and B).
+ *   5. J has no payload columns beyond the two FK/key columns.
+ *
+ * For such a J linking A and B this ADDS a `manyToMany` on A → B and B → A
+ * routed `through` J. It never removes or renames an existing relation:
+ *   - an already-assigned relation with the same name → SKIP (additive-only,
+ *     unchanged historical behavior);
+ *   - a shadowed json/jsonb (`unknown`-typed) column → keep the historical
+ *     name + warn (it worked at runtime and compiled);
+ *   - a shadowed concrete-typed column → deterministic `Rel` suffix + warn
+ *     instead of silently dropping the relation.
+ */
+export declare function addAutoManyToManyRelations(tableNames: Iterable<string>, foreignKeys: ForeignKeyEntry[], pkByTable: Map<string, string[]>, columnNamesByTable: Map<string, string[]>, relationsByTable: Map<string, Record<string, RelationDef>>, columnFieldsByTable?: Map<string, Set<string>>, unknownTypedFieldsByTable?: Map<string, Set<string>>, uniqueIndexColsByTable?: Map<string, string[][]>): void;
+/**
+ * One-stop relation derivation for the engine introspectors (SQLite / MySQL /
+ * MSSQL): filters the FK list to the introspected table set, seeds the
+ * taken-name / json-shadow maps from the engine's column metadata, and runs
+ * the SAME `buildRelationsFromForeignKeys` + `addAutoManyToManyRelations`
+ * pipeline as the Postgres introspector — so every engine derives identical
+ * relation names for the same logical schema (the engines previously carried
+ * stale copies of a retired naming scheme).
+ */
+export declare function deriveEngineRelations(tableNames: string[], foreignKeys: ForeignKeyEntry[], pkByTable: Map<string, string[]>, columnsByTable: Map<string, Pick<ColumnMetadata, 'name' | 'field' | 'tsType'>[]>): Map<string, Record<string, RelationDef>>;

package/dist/cjs/mssql.d.ts

@@ -0,0 +1,232 @@
+/**
+ * turbine-orm/mssql — Microsoft SQL Server engine (driver-injected, optional peer)
+ *
+ * Binds Turbine to SQL Server 2016+ via the `mssql` driver (which wraps
+ * `tedious`). `mssql` is **not** a root dependency — it is an **optional peer**:
+ * `npm i turbine-orm` pulls nothing extra, and only consumers who
+ * `import 'turbine-orm/mssql'` install `mssql` themselves. The factory loads it
+ * through a dynamic `import('mssql')` so importing this module never crashes when
+ * `mssql` is absent for a consumer who does not use it. Turbine's root runtime
+ * dependency stays exactly `pg`.
+ *
+ * ## The three hard SQL Server realities this engine solves
+ *
+ *  1. **No `RETURNING`.** `INSERT`/`UPDATE`/`DELETE` cannot trail a `RETURNING`
+ *     clause; SQL Server returns affected rows via `OUTPUT INSERTED.*` /
+ *     `OUTPUT DELETED.*` injected MID-statement (between the column list and
+ *     `VALUES`, or between `SET …` and `WHERE …`). `mssqlDialect.resultStrategy =
+ *     'output'`: the statement returns its own rows in ONE round-trip (executed
+ *     exactly like the PostgreSQL `'returning'` path). Upsert becomes a
+ *     `MERGE … WHEN MATCHED … WHEN NOT MATCHED … OUTPUT INSERTED.* ;` (a MERGE
+ *     must end with `;`). This is the first shipped engine to exercise the
+ *     Phase-0 `'output'` result strategy.
+ *  2. **No `json_agg`.** SQL Server has no JSON aggregate function; the idiomatic
+ *     single-query nested-relation path is `(SELECT child cols … FOR JSON PATH)`,
+ *     whose object shape is expressed by the child SELECT's column ALIASES rather
+ *     than an explicit `JSON_OBJECT(...)`. That does NOT map onto
+ *     `buildJsonObject`/`buildJsonArrayAgg`, so `mssqlDialect` defines the
+ *     additive `Dialect.buildRelationSubquery` override (the sanctioned Phase-3
+ *     seam extension) and owns the whole correlated subquery. To-many wraps
+ *     `ISNULL((… FOR JSON PATH), '[]')` (FOR JSON over zero rows is NULL, not
+ *     `[]`); to-one adds `, WITHOUT_ARRAY_WRAPPER` and lets NULL be the no-row
+ *     value. Nested relations are embedded with `JSON_QUERY(...)` so they stay
+ *     real JSON instead of being escaped as a string. `INCLUDE_NULL_VALUES`
+ *     keeps NULL columns present (matching PostgreSQL `json_build_object`).
+ *  3. **No `LIMIT`.** Paging is `ORDER BY … OFFSET n ROWS FETCH NEXT m ROWS ONLY`,
+ *     which requires an ORDER BY — a stable `ORDER BY (SELECT NULL)` is injected
+ *     when the query has none (`Dialect.buildLimitOffset`).
+ *
+ * ## Named `@pN` placeholders (no positional `?`)
+ *
+ * `mssqlDialect.paramPlaceholder = (i) => '@p' + i`. The driver shim binds via
+ * `request.input('p' + i, value)`, so binding is by NAME and independent of where
+ * each placeholder lands in the SQL text — exactly the guarantee PostgreSQL's
+ * numbered `$N` gives. (SQL Server is naturally named-param friendly, sidestepping
+ * the positional-`?` mis-bind bug the SQLite/MySQL phases hit.)
+ *
+ * ## Capabilities & limits (vs PostgreSQL)
+ *
+ * - **Single query nested relations preserved** via `FOR JSON PATH` (SQL Server
+ *   2016+). Ordered/limited to-many uses `ORDER BY … OFFSET/FETCH` inside the FOR
+ *   JSON subquery (no inner-subquery rewrite needed — FOR JSON aggregates AFTER
+ *   the row selection).
+ * - **Result strategy `'output'`:** create/update/delete/upsert return their rows
+ *   from the same statement. `createMany` returns the inserted rows via
+ *   `OUTPUT INSERTED.*` on the multi-row VALUES insert (≤ 1000 rows / 2100 params
+ *   per statement — exceeding either throws a clear `ValidationError`; chunk
+ *   yourself or use single `create`s).
+ * - **MERGE concurrency caveat:** `MERGE` is the upsert primitive; under high
+ *   concurrency a `MERGE` can still race (it is NOT a substitute for a unique
+ *   constraint). Keep the conflict target backed by a real `UNIQUE`/`PK` index,
+ *   and rely on the typed `UniqueConstraintError` (2627/2601 → E008) for the
+ *   loser of a race.
+ * - **Unsupported (throw `UnsupportedFeatureError`):** pgvector distance ops,
+ *   LISTEN/NOTIFY (`$listen`/`$notify`), RLS `sessionContext` (sp_set_session_context
+ *   exists but is connection-scoped, not transaction-local, so it is not wired —
+ *   throws rather than silently leaking context across pooled connections).
+ * - **Advisory-lock migration locking** is available in principle via
+ *   `sp_getapplock`/`sp_releaseapplock` (`supportsAdvisoryLock = true`); the
+ *   migrate CLI is still PostgreSQL-only, so this flag documents intent for a
+ *   future adapter.
+ * - **Case-insensitive matching** uses `LOWER(col) LIKE LOWER(ref)` — deterministic
+ *   regardless of the column's collation (note this can defeat an index unless a
+ *   computed/persisted `LOWER()` index exists).
+ * - **bignum:** the shim applies the same safe-int policy Turbine uses for Postgres
+ *   `int8` (number when it fits in 2^53, decimal string otherwise) WITHOUT mutating
+ *   any global driver state. `DECIMAL`/`NUMERIC`/`MONEY` come back as strings;
+ *   `BIT` binds/returns booleans.
+ * - **`DISTINCT ON`** is PostgreSQL-only and is not translated — avoid `distinct`
+ *   on SQL Server.
+ *
+ * ## Example
+ *
+ * ```ts
+ * import { turbineMssql } from 'turbine-orm/mssql';
+ * import { SCHEMA } from './generated/turbine/metadata.js';
+ *
+ * const db = await turbineMssql('mssql://sa:Passw0rd!@localhost:1433/app', SCHEMA);
+ * const users = await db.users.findMany({ with: { posts: true }, limit: 10 });
+ * await db.disconnect();
+ * ```
+ */
+import { type PgCompatPool, type PgCompatPoolClient, TurbineClient, type TurbineConfig } from './client.js';
+import { type Dialect, type IntrospectOptions } from './dialect.js';
+import { type SchemaMetadata } from './schema.js';
+interface MssqlRequest {
+    input(name: string, value: unknown): MssqlRequest;
+    query<R = Record<string, unknown>>(text: string): Promise<MssqlQueryResult<R>>;
+    batch<R = Record<string, unknown>>(text: string): Promise<MssqlQueryResult<R>>;
+}
+/** Per-column metadata `mssql` attaches to a recordset (`recordset.columns`). */
+interface MssqlColumnMeta {
+    [name: string]: {
+        type?: {
+            name?: string;
+            declaration?: string;
+        };
+    } | undefined;
+}
+interface MssqlQueryResult<R = Record<string, unknown>> {
+    recordset?: R[] & {
+        columns?: MssqlColumnMeta;
+    };
+    recordsets?: R[][];
+    rowsAffected?: number[];
+}
+interface MssqlTransaction {
+    begin(isolationLevel?: number): Promise<unknown>;
+    commit(): Promise<unknown>;
+    rollback(): Promise<unknown>;
+}
+interface MssqlConnectionPool {
+    connect(): Promise<MssqlConnectionPool>;
+    request(): MssqlRequest;
+    close(): Promise<unknown>;
+    readonly connected?: boolean;
+}
+/** The subset of the `mssql` module namespace the shim constructs. */
+interface MssqlModule {
+    connect(config: any): Promise<MssqlConnectionPool>;
+    ConnectionPool: new (config: any) => MssqlConnectionPool;
+    Request: new (parent: MssqlConnectionPool | MssqlTransaction) => MssqlRequest;
+    Transaction: new (pool: MssqlConnectionPool) => MssqlTransaction;
+    ISOLATION_LEVEL: Record<string, number>;
+}
+/** pg-style query argument: a SQL string or a `{ text, values }` config object. */
+type QueryArg = string | {
+    name?: string;
+    text: string;
+    values?: unknown[];
+};
+/**
+ * A {@link PgCompatPool} backed by an `mssql` ConnectionPool. Non-transaction
+ * queries run on a fresh pooled `Request`; `connect()` returns a
+ * {@link MssqlTxClient} that drives a single transaction through the mssql
+ * `Transaction` API so `BEGIN`/`COMMIT`/`ROLLBACK`/savepoints all run on the same
+ * physical connection.
+ */
+export declare class MssqlPool implements PgCompatPool {
+    /** The underlying `mssql` ConnectionPool — exposed as an escape hatch (seed / DDL / advanced ops). */
+    readonly pool: MssqlConnectionPool;
+    private readonly sqlNS;
+    private closed;
+    constructor(pool: MssqlConnectionPool, sqlNS: MssqlModule);
+    query(text: QueryArg, values?: unknown[]): Promise<any>;
+    connect(): Promise<PgCompatPoolClient>;
+    end(): Promise<void>;
+}
+/**
+ * Map a SQL Server column type to a TypeScript type. `dialectType` is the
+ * `INFORMATION_SCHEMA.COLUMNS.DATA_TYPE` (lowercase, e.g. `bigint`, `nvarchar`,
+ * `datetime2`, `bit`, `uniqueidentifier`).
+ */
+export declare function mssqlTypeToTs(dialectType: string, nullable: boolean): string;
+/**
+ * SQL Server 2016+ implementation of the {@link Dialect} contract. Bracket
+ * identifier quoting (`[…]`), named `@pN` placeholders, the `FOR JSON PATH`
+ * nested-relation override (no `json_agg`), no `RETURNING`
+ * (`resultStrategy = 'output'` via `OUTPUT INSERTED.*` / `MERGE`), `OFFSET/FETCH`
+ * paging, and the Postgres-only capabilities disabled (vector / LISTEN-NOTIFY /
+ * RLS).
+ */
+export declare const mssqlDialect: Dialect;
+/** Async executor that returns plain row objects for a parameterized (`@pN`) query. */
+export type MssqlRowExecutor = (sql: string, params: unknown[]) => Promise<Record<string, unknown>[]>;
+/**
+ * Introspect a SQL Server database into the same {@link SchemaMetadata} shape the
+ * Postgres catalog introspector produces, using a caller-supplied query executor
+ * (so tests can dogfood an already-open `mssql` pool/connection). Reads
+ * `INFORMATION_SCHEMA.*` plus `sys.identity_columns` / `sys.foreign_keys` /
+ * `sys.indexes`.
+ *
+ * @param exec   Runs a parameterized (`@p1`, `@p2`, …) query and returns rows.
+ * @param schema The SQL Server schema to introspect (default `dbo`).
+ */
+export declare function introspectMssqlWith(exec: MssqlRowExecutor, schema?: string, options?: {
+    include?: string[];
+    exclude?: string[];
+}): Promise<SchemaMetadata>;
+/**
+ * Open a short-lived `mssql` connection from `options.connectionString`, introspect
+ * the database (schema = `options.schema` or `dbo`), and close it. Wraps
+ * {@link introspectMssqlWith} for the {@link DialectIntrospector} seam used by
+ * `introspect()` / `npx turbine generate`.
+ */
+export declare function introspectMssql(options: IntrospectOptions): Promise<SchemaMetadata>;
+interface MssqlConnectionConfig {
+    server?: string;
+    port?: number;
+    user?: string;
+    password?: string;
+    database?: string;
+    options?: {
+        encrypt?: boolean;
+        trustServerCertificate?: boolean;
+    };
+}
+/** Options for {@link turbineMssql}. Mirrors the relevant {@link TurbineConfig} fields. */
+export interface TurbineMssqlOptions extends Pick<TurbineConfig, 'logging' | 'defaultLimit' | 'warnOnUnlimited'> {
+    /** SQL Server schema for introspection / DDL (default `dbo`). */
+    schema?: string;
+}
+/**
+ * Create a {@link TurbineClient} bound to SQL Server 2016+ via `mssql`.
+ *
+ * Pass one of:
+ *  - a connection string (`'mssql://sa:pass@host:1433/db'`),
+ *  - an `mssql` config object (`{ server, user, password, database, options }`),
+ *  - an existing `MssqlPool` (injection — you own its lifecycle, `disconnect()` is
+ *    a no-op).
+ *
+ * When Turbine builds the pool (string/config), it probes
+ * `SERVERPROPERTY('ProductMajorVersion')` to reject SQL Server < 2016, and
+ * `disconnect()` closes the pool it created.
+ *
+ * @example
+ * ```ts
+ * import { turbineMssql } from 'turbine-orm/mssql';
+ * const db = await turbineMssql('mssql://sa:Passw0rd!@localhost:1433/app', SCHEMA);
+ * ```
+ */
+export declare function turbineMssql(target: string | MssqlConnectionConfig | MssqlPool, schema: SchemaMetadata, options?: TurbineMssqlOptions): Promise<TurbineClient>;
+export {};

package/dist/cjs/mssql.js

@@ -491,6 +491,12 @@ exports.mssqlDialect = {
     // round-trip (Phase-0 'output' strategy, executed like 'returning').
     resultStrategy: 'output',
     supportsReturning: false,
+    // MERGE can carry `WHEN MATCHED AND <pred>`, but the predicate the builder
+    // hands over is written in UNQUALIFIED column references, which are ambiguous
+    // between the MERGE target (T) and source (S) aliases. `buildUpsertStatement`
+    // below therefore emits no predicate; reporting false keeps the builder from
+    // compiling one (and from binding its now-orphaned parameters).
+    supportsUpsertUpdateWhere: false,
     supportsILike: false,
     supportsVector: false,
     // SQL Server full-text is `CONTAINS`/`FREETEXT` over a full-text catalog: a