turbine-orm 0.75.0 → 0.76.0

package/dist/generate.js

@@ -10,6 +10,7 @@
  */
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { dirname, join, relative, resolve } from 'node:path';
+import { ValidationError } from './errors.js';
 import { pgTypeToTs, singularize, snakeToPascal, timeOfDayKind, withDbFieldNames, } from './schema.js';
 /** Get the TypeScript type name for a table (singularized PascalCase) */
 function entityName(tableName) {
@@ -57,9 +58,59 @@ function writeColumnTsType(col, enums) {
     const widened = isArray ? '(string | Date)[]' : 'string | Date';
     return col.nullable ? `${widened} | null` : widened;
 }
-/** Escape a value for embedding in a single-quoted TypeScript string literal */
+/**
+ * Characters that must never reach generated source verbatim: the two that end
+ * a single-quoted literal (backslash, quote), the C0/C1 control range (a raw
+ * newline alone leaves the literal unterminated and starts a new source line),
+ * and the two Unicode line terminators.
+ */
+// biome-ignore lint/suspicious/noControlCharactersInRegex: neutralizing control characters is this pattern's purpose
+const UNSAFE_EMIT_CHARS_GLOBAL = /[\\'\u0000-\u001f\u007f-\u009f\u2028\u2029]/g;
+/**
+ * Escape a value for embedding in a single-quoted TypeScript string literal.
+ *
+ * Every character that can END the literal has to be neutralized here, not just
+ * the quote. A database identifier is attacker-controlled text (Postgres allows
+ * any character in a double-quoted name, up to 63 bytes) and generated code is
+ * `import`ed, i.e. EXECUTED, so a literal that closes early leaves the rest of
+ * the name in expression position. A raw newline is enough on its own.
+ */
 function escSQ(value) {
-    return value.replace(/\\/g, '\\\\').replace(/'/g, "\\'");
+    return value.replace(UNSAFE_EMIT_CHARS_GLOBAL, (ch) => {
+        switch (ch) {
+            case '\\':
+                return '\\\\';
+            case "'":
+                return "\\'";
+            case '\n':
+                return '\\n';
+            case '\r':
+                return '\\r';
+            case '\t':
+                return '\\t';
+            case '\b':
+                return '\\b';
+            case '\f':
+                return '\\f';
+            case '\v':
+                return '\\v';
+            default:
+                return `\\u${ch.charCodeAt(0).toString(16).padStart(4, '0')}`;
+        }
+    });
+}
+// biome-ignore lint/suspicious/noControlCharactersInRegex: collapsing control characters is this pattern's purpose
+const COMMENT_BREAKING_CHARS = /[\u0000-\u001f\u007f-\u009f\u2028\u2029]+/g;
+/**
+ * Neutralize a catalog string for emission inside a generated JSDoc or line
+ * COMMENT. Two sequences end a comment early and both are legal in a
+ * double-quoted Postgres identifier: an asterisk followed by a slash closes a
+ * block comment, putting everything after it in code position, and a newline
+ * ends a line comment and splits one emitted line into two. Escaping the
+ * asterisk breaks the terminator without changing how the name reads.
+ */
+function docSafe(value) {
+    return value.replace(/\*\//g, '*\\/').replace(COMMENT_BREAKING_CHARS, ' ');
 }
 // ---------------------------------------------------------------------------
 // Main generate function
@@ -284,12 +335,75 @@ function typeSafeRelations(table, warn = true) {
     }
     return usable;
 }
+// ---------------------------------------------------------------------------
+// Identifier boundary
+// ---------------------------------------------------------------------------
+/**
+ * The JavaScript identifier grammar as a WHOLE-STRING match: `IdentifierStart`
+ * (`ID_Start`, `$`, `_`) followed by `IdentifierPart` (`ID_Continue`, `$`, ZWNJ,
+ * ZWJ). Deliberately Unicode-aware rather than `[A-Za-z_$][\w$]*`: a table named
+ * `café` yields the perfectly valid identifier `Café` and there is no reason to
+ * refuse it. What it does refuse is every character that could end the
+ * identifier token, so a name that passes interpolates as exactly one token.
+ */
+const EMITTABLE_IDENTIFIER_RE = /^[\p{ID_Start}$_][\p{ID_Continue}$\u200C\u200D]*$/u;
+/**
+ * Whether `name` can be interpolated into generated TypeScript in IDENTIFIER
+ * position (a type name, an interface name, a class member declaration).
+ *
+ * Identifier position is the one emission site with no escaping option: a value
+ * position becomes a quoted literal ({@link escSQ}), a key position becomes a
+ * quoted key ({@link quoteIfNeeded}), a comment is neutralized
+ * ({@link docSafe}), but `export interface X` needs a real identifier. So the
+ * only sound answer for a name that is not one is to refuse.
+ */
+export function isEmittableIdentifier(name) {
+    return EMITTABLE_IDENTIFIER_RE.test(name);
+}
+function requireEmittable(derived, subject, role) {
+    if (isEmittableIdentifier(derived))
+        return;
+    throw new ValidationError(`[turbine] Cannot generate code for ${subject}: it produces ${JSON.stringify(derived)} as ${role}, ` +
+        `which is not a valid TypeScript identifier. Rename the database object, or exclude it from generation ` +
+        `(introspect \`exclude\`).`);
+}
+/**
+ * Refuse a schema whose names cannot be emitted as TypeScript identifiers.
+ *
+ * Called by every emitter that puts a catalog-derived name in identifier
+ * position ({@link generateTypes}, {@link generateIndex}, {@link generateZod}).
+ * {@link generateMetadata} deliberately does NOT call it: metadata.ts emits no
+ * identifiers derived from catalog names, every name there is a quoted key or a
+ * quoted value, so it has no identifier rule to enforce and stays usable for a
+ * schema whose type layer cannot be generated.
+ *
+ * The check runs on the DERIVED identifier, not the raw name, because that is
+ * what actually lands in the output, but the message names the raw object so
+ * the reader knows what to rename.
+ */
+export function assertEmittableSchema(schema) {
+    for (const enumName of Object.keys(schema.enums)) {
+        requireEmittable(snakeToPascal(enumName), `enum type "${enumName}"`, 'the generated enum type name');
+    }
+    for (const table of Object.values(schema.tables)) {
+        requireEmittable(entityName(table.name), `table "${table.name}"`, 'the generated entity type name');
+        requireEmittable(snakeToCamelStr(table.name), `table "${table.name}"`, 'the generated client accessor');
+        // Only the relations that reach the TYPE layer: a relation shadowing a
+        // column field is already dropped from types.ts, so refusing on its name
+        // would refuse a schema that generates fine.
+        for (const [relName, rel] of typeSafeRelations(table, false)) {
+            requireEmittable(snakeToPascal(relName), `relation "${relName}" on table "${table.name}"`, 'part of the generated `XWithY` interface name');
+            requireEmittable(entityName(rel.to), `relation "${relName}" on table "${table.name}" (target "${rel.to}")`, 'the generated target entity type name');
+        }
+    }
+}
 /**
  * Generate the contents of `types.ts` (entity interfaces, *Create / *Update,
  * and *Relations brand-field interfaces). Exported so tests can pin the
  * generator output without writing files to disk.
  */
 export function generateTypes(schema, options) {
+    assertEmittableSchema(schema);
     const lines = [...generatedFileHeader(options)];
     // We import UpdateOperatorInput so generated *Update types can express
     // atomic increment / decrement / multiply / divide / set operators on
@@ -320,7 +434,7 @@ export function generateTypes(schema, options) {
     // Generate enum types
     for (const [enumName, labels] of Object.entries(schema.enums)) {
         const typeName = snakeToPascal(enumName);
-        lines.push(`/** Database enum: ${enumName} */`);
+        lines.push(`/** Database enum: ${docSafe(enumName)} */`);
         lines.push(`export type ${typeName} = ${labels.map((l) => `'${escSQ(l)}'`).join(' | ')};`);
         lines.push('');
     }
@@ -328,7 +442,7 @@ export function generateTypes(schema, options) {
     for (const table of Object.values(schema.tables)) {
         const typeName = entityName(table.name);
         // --- Base entity interface ---
-        lines.push(`/** Row type for the \`${table.name}\` table */`);
+        lines.push(`/** Row type for the \`${docSafe(table.name)}\` table */`);
         lines.push(`export interface ${typeName} {`);
         for (const col of table.columns) {
             const pkNote = table.primaryKey.includes(col.name) ? ' (primary key)' : '';
@@ -338,7 +452,7 @@ export function generateTypes(schema, options) {
             // The emitted type marks it optional so it tells the truth about absence.
             const piiNote = col.pii ? ' (PII: absent unless selected or includePii)' : '';
             const optional = col.pii ? '?' : '';
-            lines.push(`  /** Column: ${col.name}, ${col.pgType}${pkNote}${nullNote}${piiNote} */`);
+            lines.push(`  /** Column: ${docSafe(col.name)}, ${docSafe(col.pgType)}${pkNote}${nullNote}${piiNote} */`);
             lines.push(`  ${quoteIfNeeded(col.field)}${optional}: ${columnTsType(col, schema.enums)};`);
         }
         lines.push('}');
@@ -346,7 +460,7 @@ export function generateTypes(schema, options) {
         // --- Create input type ---
         // Required: non-nullable columns without defaults (except PK)
         // Optional: nullable columns (default to NULL) or columns with explicit defaults
-        lines.push(`/** Input type for creating a row in \`${table.name}\` */`);
+        lines.push(`/** Input type for creating a row in \`${docSafe(table.name)}\` */`);
         lines.push(`export type ${typeName}Create = {`);
         for (const col of table.columns) {
             // STORED generated columns are computed by the database, never writable.
@@ -369,7 +483,7 @@ export function generateTypes(schema, options) {
         // Numeric columns additionally accept `UpdateOperatorInput<number>` so
         // users can write `{ viewCount: { increment: 1 } }` without an `as any`.
         const nonPkCols = table.columns.filter((c) => !table.primaryKey.includes(c.name) && !c.isGeneratedStored);
-        lines.push(`/** Input type for updating a row in \`${table.name}\` */`);
+        lines.push(`/** Input type for updating a row in \`${docSafe(table.name)}\` */`);
         lines.push(`export type ${typeName}Update = {`);
         for (const col of nonPkCols) {
             lines.push(`  ${quoteIfNeeded(col.field)}?: ${updateFieldType(writeColumnTsType(col, schema.enums))};`);
@@ -387,14 +501,14 @@ export function generateTypes(schema, options) {
         const safeRelations = safeRelationsByTable.get(table.name) ?? [];
         const hasRelations = safeRelations.length > 0;
         if (hasRelations) {
-            lines.push(`/** Available relations for the \`${table.name}\` table */`);
+            lines.push(`/** Available relations for the \`${docSafe(table.name)}\` table */`);
             lines.push(`export interface ${typeName}Relations {`);
             for (const [relName, rel] of safeRelations) {
                 const targetType = entityName(rel.to);
                 // manyToMany is a collection too → 'many' cardinality (same as hasMany).
                 const cardinality = rel.type === 'hasMany' || rel.type === 'manyToMany' ? "'many'" : "'one'";
                 const targetRelations = tablesWithRelations.has(rel.to) ? `${targetType}Relations` : '{}';
-                lines.push(`  ${relName}: RelationDescriptor<${targetType}, ${cardinality}, ${targetRelations}>;`);
+                lines.push(`  ${quoteIfNeeded(relName)}: RelationDescriptor<${targetType}, ${cardinality}, ${targetRelations}>;`);
             }
             lines.push('}');
             lines.push('');
@@ -402,15 +516,15 @@ export function generateTypes(schema, options) {
             for (const [relName, rel] of safeRelations) {
                 const targetType = entityName(rel.to);
                 if (rel.type === 'hasMany' || rel.type === 'manyToMany') {
-                    lines.push(`/** ${typeName} with \`${relName}\` relation loaded (${rel.type}: ${rel.to}) */`);
+                    lines.push(`/** ${typeName} with \`${docSafe(relName)}\` relation loaded (${rel.type}: ${docSafe(rel.to)}) */`);
                     lines.push(`export interface ${typeName}With${snakeToPascal(relName)} extends ${typeName} {`);
-                    lines.push(`  ${relName}: ${targetType}[];`);
+                    lines.push(`  ${quoteIfNeeded(relName)}: ${targetType}[];`);
                     lines.push('}');
                 }
                 else {
-                    lines.push(`/** ${typeName} with \`${relName}\` relation loaded (${rel.type}: ${rel.to}) */`);
+                    lines.push(`/** ${typeName} with \`${docSafe(relName)}\` relation loaded (${rel.type}: ${docSafe(rel.to)}) */`);
                     lines.push(`export interface ${typeName}With${snakeToPascal(relName)} extends ${typeName} {`);
-                    lines.push(`  ${relName}: ${targetType} | null;`);
+                    lines.push(`  ${quoteIfNeeded(relName)}: ${targetType} | null;`);
                     lines.push('}');
                 }
                 lines.push('');
@@ -507,7 +621,7 @@ export function generateTypes(schema, options) {
             lines.push(`export type ${typeName}CreateInput = ${typeName}Create & {`);
             for (const [relName, rel] of safeRelations) {
                 const targetType = entityName(rel.to);
-                lines.push(`  ${relName}?: ${targetType}NestedCreateInput;`);
+                lines.push(`  ${quoteIfNeeded(relName)}?: ${targetType}NestedCreateInput;`);
             }
             lines.push('};');
             lines.push('');
@@ -515,10 +629,10 @@ export function generateTypes(schema, options) {
             for (const [relName, rel] of safeRelations) {
                 const targetType = entityName(rel.to);
                 if (rel.type === 'hasMany') {
-                    lines.push(`  ${relName}?: ${targetType}NestedUpdateInput;`);
+                    lines.push(`  ${quoteIfNeeded(relName)}?: ${targetType}NestedUpdateInput;`);
                 }
                 else {
-                    lines.push(`  ${relName}?: ${targetType}NestedCreateInput;`);
+                    lines.push(`  ${quoteIfNeeded(relName)}?: ${targetType}NestedCreateInput;`);
                 }
             }
             lines.push('};');
@@ -623,6 +737,7 @@ function zodBaseType(col, enums, forWrite = false) {
  * the output without writing files.
  */
 export function generateZod(schema, options) {
+    assertEmittableSchema(schema);
     const lines = [...generatedFileHeader(options)];
     // `zod` is a USER dependency, this generated file imports it, but the Turbine
     // library runtime never does, so Zod stays out of the package's dep graph.
@@ -631,7 +746,7 @@ export function generateZod(schema, options) {
     for (const table of Object.values(schema.tables)) {
         const typeName = entityName(table.name);
         // Full-row schema.
-        lines.push(`/** Zod schema for a \`${table.name}\` row */`);
+        lines.push(`/** Zod schema for a \`${docSafe(table.name)}\` row */`);
         lines.push(`export const ${typeName}Schema = z.object({`);
         for (const col of table.columns) {
             let expr = zodBaseType(col, schema.enums);
@@ -643,7 +758,7 @@ export function generateZod(schema, options) {
         lines.push('');
         // Create schema, STORED generated columns can never be written; PK,
         // defaulted, and nullable columns are optional.
-        lines.push(`/** Zod schema for creating a \`${table.name}\` row */`);
+        lines.push(`/** Zod schema for creating a \`${docSafe(table.name)}\` row */`);
         lines.push(`export const ${typeName}CreateSchema = z.object({`);
         for (const col of table.columns) {
             if (col.isGeneratedStored)
@@ -659,7 +774,7 @@ export function generateZod(schema, options) {
         lines.push('});');
         lines.push('');
         // Update schema, PK and STORED generated columns omitted; all else optional.
-        lines.push(`/** Zod schema for updating a \`${table.name}\` row */`);
+        lines.push(`/** Zod schema for updating a \`${docSafe(table.name)}\` row */`);
         lines.push(`export const ${typeName}UpdateSchema = z.object({`);
         for (const col of table.columns) {
             if (col.isGeneratedStored)
@@ -689,7 +804,7 @@ export function generateMetadata(schema, options) {
         '  tables: {',
     ];
     for (const table of Object.values(schema.tables)) {
-        lines.push(`    ${table.name}: {`);
+        lines.push(`    ${quoteIfNeeded(table.name)}: {`);
         lines.push(`      name: '${escSQ(table.name)}',`);
         // columns
         lines.push('      columns: [');
@@ -750,7 +865,7 @@ export function generateMetadata(schema, options) {
                         `sourceKey: ${keyLiteral(rel.through.sourceKey)}, ` +
                         `targetKey: ${keyLiteral(rel.through.targetKey)} }`;
             }
-            lines.push(`        ${relName}: { type: '${escSQ(rel.type)}', name: '${escSQ(rel.name)}', from: '${escSQ(rel.from)}', to: '${escSQ(rel.to)}', foreignKey: ${fkLiteral}, referenceKey: ${refLiteral}${throughLiteral} },`);
+            lines.push(`        ${quoteIfNeeded(relName)}: { type: '${escSQ(rel.type)}', name: '${escSQ(rel.name)}', from: '${escSQ(rel.from)}', to: '${escSQ(rel.to)}', foreignKey: ${fkLiteral}, referenceKey: ${refLiteral}${throughLiteral} },`);
         }
         lines.push('      },');
         // indexes
@@ -783,7 +898,7 @@ export function generateMetadata(schema, options) {
     // enums
     lines.push('  enums: {');
     for (const [enumName, labels] of Object.entries(schema.enums)) {
-        lines.push(`    ${enumName}: [${labels.map((l) => `'${escSQ(l)}'`).join(', ')}],`);
+        lines.push(`    ${quoteIfNeeded(enumName)}: [${labels.map((l) => `'${escSQ(l)}'`).join(', ')}],`);
     }
     lines.push('  },');
     lines.push('};');
@@ -798,6 +913,7 @@ export function generateMetadata(schema, options) {
 // index.ts generator (configured client with typed table accessors)
 // ---------------------------------------------------------------------------
 export function generateIndex(schema, options) {
+    assertEmittableSchema(schema);
     const tableEntries = Object.values(schema.tables);
     // Must mirror generateTypes: `XRelations` only exists in types.ts when the
     // table has at least one type-safe (non-column-shadowing) relation.
@@ -844,7 +960,7 @@ export function generateIndex(schema, options) {
         const accessor = snakeToCamelStr(table.name);
         const hasRelations = hasSafeRelations.get(table.name) === true;
         const genericArgs = hasRelations ? `${typeName}, ${typeName}Relations` : typeName;
-        lines.push(`  /** Query interface for the \`${table.name}\` table (transaction-scoped) */`);
+        lines.push(`  /** Query interface for the \`${docSafe(table.name)}\` table (transaction-scoped) */`);
         lines.push(`  declare readonly ${accessor}: ${accessorType(table, genericArgs)};`);
     }
     lines.push('}');
@@ -867,7 +983,7 @@ export function generateIndex(schema, options) {
     lines.push(' *');
     lines.push(' * Tables:');
     for (const table of tableEntries) {
-        lines.push(` *   - \`${snakeToCamelStr(table.name)}\` (${table.name})`);
+        lines.push(` *   - \`${docSafe(snakeToCamelStr(table.name))}\` (${docSafe(table.name)})`);
     }
     lines.push(' *');
     lines.push(' * @example');
@@ -876,7 +992,7 @@ export function generateIndex(schema, options) {
     if (tableEntries.length > 0) {
         const firstTable = tableEntries[0];
         const accessor = snakeToCamelStr(firstTable.name);
-        lines.push(` * const rows = await db.${accessor}.findMany();`);
+        lines.push(` * const rows = await db.${docSafe(accessor)}.findMany();`);
     }
     lines.push(' * ```');
     lines.push(' */');
@@ -886,7 +1002,7 @@ export function generateIndex(schema, options) {
         const accessor = snakeToCamelStr(table.name);
         const hasRelations = hasSafeRelations.get(table.name) === true;
         const genericArgs = hasRelations ? `${typeName}, ${typeName}Relations` : typeName;
-        lines.push(`  /** Query interface for the \`${table.name}\` table */`);
+        lines.push(`  /** Query interface for the \`${docSafe(table.name)}\` table */`);
         lines.push(`  declare readonly ${accessor}: ${accessorType(table, genericArgs)};`);
     }
     lines.push('');
@@ -1061,8 +1177,37 @@ function serializeColumn(col) {
         parts.push(`maxLength: ${col.maxLength}`);
     return `{ ${parts.join(', ')} }`;
 }
+/**
+ * The subset of names emitted BARE in generated object-key position. Anchored
+ * on purpose: the previous rule only tested whether a name contained a
+ * character outside the set, so a name made entirely of allowed characters but
+ * starting with a digit (`2fa`) was emitted bare and did not parse.
+ */
+const BARE_KEY_RE = /^[A-Za-z_$][A-Za-z0-9_$]*$/;
+/**
+ * Emit `s` in generated object-KEY position.
+ *
+ * A key is the one place in the output where catalog text would otherwise land
+ * in EXPRESSION position: `{ [expr]: v }` is a COMPUTED key, evaluated when the
+ * object is constructed, so an unquoted name carrying brackets runs on
+ * `import`. The bare form is therefore gated on a WHOLE-STRING match of the
+ * identifier grammar, which no bracket, parenthesis, quote, newline, or space
+ * can pass; every other name becomes a fully escaped string literal, which is
+ * inert in key position.
+ *
+ * The literal has to be ESCAPED, not merely wrapped: this function used to
+ * return `'${s}'` verbatim, so a name containing a quote closed the key and
+ * reopened in expression position.
+ *
+ * KNOWN LIMIT, deliberately not handled here: a database object named
+ * `__proto__` still sets the emitted object literal's PROTOTYPE rather than
+ * adding a property, because the object-literal special case applies to the
+ * quoted spelling too. Quoting is not a fix for it, so there is no branch for
+ * it; the consequence is a metadata map that silently omits that one entry, not
+ * code execution.
+ */
 function quoteIfNeeded(s) {
-    return /[^a-zA-Z0-9_$]/.test(s) ? `'${s}'` : s;
+    return BARE_KEY_RE.test(s) ? s : `'${escSQ(s)}'`;
 }
 function snakeToCamelStr(s) {
     return s.replace(/_([a-z])/g, (_, c) => c.toUpperCase());

package/dist/index.d.ts

@@ -10,7 +10,7 @@
  * //    npx turbine generate
  *
  * // 2. Import the generated client:
- * import { turbine } from './generated/turbine';
+ * import { turbine } from './generated/turbine/index.js';
  *
  * const db = turbine({ connectionString: process.env.DATABASE_URL });
  *

package/dist/index.js

@@ -10,7 +10,7 @@
  * //    npx turbine generate
  *
  * // 2. Import the generated client:
- * import { turbine } from './generated/turbine';
+ * import { turbine } from './generated/turbine/index.js';
  *
  * const db = turbine({ connectionString: process.env.DATABASE_URL });
  *

package/dist/introspect.d.ts

@@ -105,6 +105,23 @@ export interface IntrospectOptions {
      */
     dialect?: Dialect;
 }
+/**
+ * Refuse one catalog identifier carrying a character from
+ * {@link UNSAFE_CATALOG_CHARS}. `subject` names the object in the error.
+ */
+export declare function assertSafeCatalogIdentifier(name: string, subject: string): void;
+/**
+ * Walk a freshly introspected {@link SchemaMetadata} and refuse any catalog
+ * identifier that carries a control character (see
+ * {@link assertSafeCatalogIdentifier}).
+ *
+ * Covers every string that is a NAME: tables, columns (catalog name and derived
+ * field), relations (key, name, endpoints, keys, junction), enum types and their
+ * labels, index names and their columns, and check-constraint names. It does
+ * NOT cover free-text SQL, index definitions, check expressions, and column
+ * defaults are emitted with `JSON.stringify` and are not identifiers.
+ */
+export declare function assertSafeCatalogSchema(schema: SchemaMetadata): void;
 /**
  * Introspect a database into {@link SchemaMetadata}, routing through the active
  * dialect's {@link Dialect.introspector} so each engine can override the catalog

package/dist/introspect.js

@@ -301,6 +301,99 @@ export function defaultExcludedTablesPresent(names, options = {}) {
 // ---------------------------------------------------------------------------
 // Main introspection function
 // ---------------------------------------------------------------------------
+// ---------------------------------------------------------------------------
+// Catalog identifier boundary
+// ---------------------------------------------------------------------------
+/**
+ * Characters that no legitimate SQL object name carries and that are exactly
+ * the primitives for breaking OUT of a generated string literal or comment: the
+ * C0 control range (NUL, newline, carriage return, tab), the C1 range, and the
+ * two Unicode line terminators.
+ *
+ * Postgres permits ANY character in a double-quoted identifier up to 63 bytes,
+ * so a catalog name is attacker-controlled text as soon as anyone but the DBA
+ * can create an object. `turbine generate` turns those names into TypeScript
+ * that is then `import`ed, i.e. EXECUTED, and `turbine studio` / the MCP server
+ * render them into HTML and JSON. Escaping at each of those sinks is the actual
+ * fix (see `escSQ` / `quoteIfNeeded` / `docSafe` in generate.ts); this boundary
+ * is the belt-and-braces refusal one layer earlier, and it names the object so
+ * the operator can see WHICH one is malformed instead of debugging generated
+ * output.
+ *
+ * Deliberately narrow. It does NOT refuse a name that merely cannot become a
+ * TypeScript identifier (`2fa_codes`), because `introspect()` also feeds
+ * Studio, the MCP server, and `doctor`, none of which emit identifiers, and
+ * refusing there would break tools that work today. That question belongs to
+ * the code generator and is answered by `assertEmittableSchema` in generate.ts.
+ */
+// biome-ignore lint/suspicious/noControlCharactersInRegex: detecting control characters is this pattern's purpose
+const UNSAFE_CATALOG_CHARS = /[\u0000-\u001f\u007f-\u009f\u2028\u2029]/;
+/**
+ * Refuse one catalog identifier carrying a character from
+ * {@link UNSAFE_CATALOG_CHARS}. `subject` names the object in the error.
+ */
+export function assertSafeCatalogIdentifier(name, subject) {
+    const match = UNSAFE_CATALOG_CHARS.exec(name);
+    if (match === null)
+        return;
+    const code = match[0].charCodeAt(0).toString(16).padStart(4, '0');
+    throw new ValidationError(`[turbine] Refusing to introspect ${subject}: its name contains the control character U+${code.toUpperCase()} ` +
+        `at position ${match.index}. Such a name cannot be safely emitted into generated code, SQL comments, or ` +
+        `tooling output. Rename the database object, or exclude it from introspection.`);
+}
+/**
+ * Walk a freshly introspected {@link SchemaMetadata} and refuse any catalog
+ * identifier that carries a control character (see
+ * {@link assertSafeCatalogIdentifier}).
+ *
+ * Covers every string that is a NAME: tables, columns (catalog name and derived
+ * field), relations (key, name, endpoints, keys, junction), enum types and their
+ * labels, index names and their columns, and check-constraint names. It does
+ * NOT cover free-text SQL, index definitions, check expressions, and column
+ * defaults are emitted with `JSON.stringify` and are not identifiers.
+ */
+export function assertSafeCatalogSchema(schema) {
+    for (const [enumName, labels] of Object.entries(schema.enums)) {
+        assertSafeCatalogIdentifier(enumName, `enum type "${enumName}"`);
+        for (const label of labels) {
+            assertSafeCatalogIdentifier(label, `a label of enum type "${enumName}"`);
+        }
+    }
+    for (const [tableKey, table] of Object.entries(schema.tables)) {
+        assertSafeCatalogIdentifier(tableKey, `table "${tableKey}"`);
+        assertSafeCatalogIdentifier(table.name, `table "${tableKey}"`);
+        const where = `table "${table.name}"`;
+        for (const col of table.columns) {
+            assertSafeCatalogIdentifier(col.name, `column "${col.name}" on ${where}`);
+            assertSafeCatalogIdentifier(col.field, `the field name derived for a column on ${where}`);
+        }
+        for (const [relKey, rel] of Object.entries(table.relations)) {
+            const relWhere = `relation "${relKey}" on ${where}`;
+            assertSafeCatalogIdentifier(relKey, relWhere);
+            assertSafeCatalogIdentifier(rel.name, relWhere);
+            assertSafeCatalogIdentifier(rel.from, `the source table of ${relWhere}`);
+            assertSafeCatalogIdentifier(rel.to, `the target table of ${relWhere}`);
+            for (const k of [rel.foreignKey, rel.referenceKey].flat()) {
+                assertSafeCatalogIdentifier(k, `a key column of ${relWhere}`);
+            }
+            if (rel.through) {
+                assertSafeCatalogIdentifier(rel.through.table, `the junction table of ${relWhere}`);
+                for (const k of [rel.through.sourceKey, rel.through.targetKey].flat()) {
+                    assertSafeCatalogIdentifier(k, `a junction key column of ${relWhere}`);
+                }
+            }
+        }
+        for (const idx of table.indexes) {
+            assertSafeCatalogIdentifier(idx.name, `index "${idx.name}" on ${where}`);
+            for (const c of idx.columns) {
+                assertSafeCatalogIdentifier(c, `a column of index "${idx.name}" on ${where}`);
+            }
+        }
+        for (const chk of table.checks ?? []) {
+            assertSafeCatalogIdentifier(chk.name, `check constraint "${chk.name}" on ${where}`);
+        }
+    }
+}
 /**
  * Introspect a database into {@link SchemaMetadata}, routing through the active
  * dialect's {@link Dialect.introspector} so each engine can override the catalog
@@ -314,7 +407,11 @@ export async function introspect(options) {
         : // Dialects without an introspector fall back to the Postgres catalog reader.
             await introspectPostgresCatalog(options);
     // Applied here rather than inside each introspector so every engine gets it.
-    return options.relationNames ? applyRelationRenames(schema, options.relationNames) : schema;
+    const renamed = options.relationNames ? applyRelationRenames(schema, options.relationNames) : schema;
+    // Same reason: one boundary for every engine, and AFTER the renames so a
+    // caller-supplied relation name is checked too.
+    assertSafeCatalogSchema(renamed);
+    return renamed;
 }
 /**
  * Rename introspected relations, per table, from the name turbine derived to

package/dist/mssql.d.ts

@@ -149,6 +149,24 @@ type QueryArg = string | {
 export declare class MssqlPool implements PgCompatPool {
     /** The underlying `mssql` ConnectionPool, exposed as an escape hatch (seed / DDL / advanced ops). */
     readonly pool: MssqlConnectionPool;
+    /**
+     * The dialect this pool speaks, published so a consumer holding only the POOL
+     * can find it.
+     *
+     * `executePipeline` (src/pipeline.ts) is that consumer: it receives a pool and
+     * nothing else, and its transaction control used to be the literal strings
+     * `BEGIN` / `COMMIT` / `ROLLBACK`. A bare `BEGIN` is a statement-BLOCK opener
+     * in T-SQL, so it missed {@link MssqlTxClient}'s `BEGIN TRAN(SACTION)` branch,
+     * reached the server as a block with no `END`, and was rejected; the COMMIT
+     * and ROLLBACK behind it then found no open transaction and no-oped. Reading
+     * the dialect off the pool is what lets the batch emit `BEGIN TRANSACTION`
+     * and land on the driver's Transaction API instead.
+     *
+     * SQL Server is the only engine whose transaction keywords differ from
+     * Postgres's, so it is the only pool shim that needs to publish this; the
+     * lookup treats an absent `dialect` as PostgreSQL.
+     */
+    readonly dialect: Dialect;
     private readonly sqlNS;
     private closed;
     constructor(pool: MssqlConnectionPool, sqlNS: MssqlModule);

package/dist/mssql.js

@@ -94,6 +94,7 @@ import { postgresDialect, } from './dialect.js';
 import { ConnectionError, malformedConnectionStringMessage, markValueBearingMessage, RelationError, UnsupportedFeatureError, ValidationError, } from './errors.js';
 import { applyTableFilters, deriveEngineRelations } from './introspect.js';
 import importOptionalPeer from './optional-peer-import.cjs';
+import { availableClause } from './query/utils.js';
 import { camelToSnake, isDateType, normalizeKeyColumns, snakeToCamel, } from './schema.js';
 // ---------------------------------------------------------------------------
 // SQL Server / connection limits
@@ -358,6 +359,24 @@ class MssqlTxClient {
 export class MssqlPool {
     /** The underlying `mssql` ConnectionPool, exposed as an escape hatch (seed / DDL / advanced ops). */
     pool;
+    /**
+     * The dialect this pool speaks, published so a consumer holding only the POOL
+     * can find it.
+     *
+     * `executePipeline` (src/pipeline.ts) is that consumer: it receives a pool and
+     * nothing else, and its transaction control used to be the literal strings
+     * `BEGIN` / `COMMIT` / `ROLLBACK`. A bare `BEGIN` is a statement-BLOCK opener
+     * in T-SQL, so it missed {@link MssqlTxClient}'s `BEGIN TRAN(SACTION)` branch,
+     * reached the server as a block with no `END`, and was rejected; the COMMIT
+     * and ROLLBACK behind it then found no open transaction and no-oped. Reading
+     * the dialect off the pool is what lets the batch emit `BEGIN TRANSACTION`
+     * and land on the driver's Transaction API instead.
+     *
+     * SQL Server is the only engine whose transaction keywords differ from
+     * Postgres's, so it is the only pool shim that needs to publish this; the
+     * lookup treats an absent `dialect` as PostgreSQL.
+     */
+    dialect = mssqlDialect;
     sqlNS;
     closed = false;
     constructor(pool, sqlNS) {
@@ -886,7 +905,7 @@ function buildForJsonSubquery(dialect, ctx) {
             const nestedRelDef = targetMeta.relations[nestedRelName];
             if (!nestedRelDef) {
                 throw new RelationError(`[turbine] Unknown relation "${nestedRelName}" on table "${targetTable}". ` +
-                    `Available: ${Object.keys(targetMeta.relations).join(', ')}`);
+                    availableClause(Object.keys(targetMeta.relations), 'It has no relations.'));
             }
             const sub = ctx.recurse(nestedRelDef, nestedSpec, parentAlias, depth + 1, [...path, relDef.name]);
             cols.push(`JSON_QUERY((${sub})) AS ${q(nestedRelName)}`);