turbine-orm 0.16.0 → 0.18.0

package/dist/client.js

@@ -22,10 +22,13 @@
  * ```
  */
 import pg from 'pg';
-import { setErrorMessageMode, TimeoutError, wrapPgError } from './errors.js';
+import { setErrorMessageMode, TimeoutError, ValidationError, wrapPgError } from './errors.js';
 import { ObserveEngine } from './observe.js';
 import { executePipeline, pipelineSupported } from './pipeline.js';
 import { QueryInterface, } from './query/index.js';
+import { quoteIdent } from './query/utils.js';
+import { createSubscription, validateChannel, } from './realtime.js';
+import { buildTypedSql, TypedSqlQuery } from './typed-sql.js';
 export async function withRetry(fn, options) {
     const maxAttempts = options?.maxAttempts ?? 3;
     const baseDelay = options?.baseDelay ?? 50;
@@ -57,6 +60,13 @@ const ISOLATION_LEVELS = {
     RepeatableRead: 'REPEATABLE READ',
     Serializable: 'SERIALIZABLE',
 };
+/**
+ * Strict GUC (session variable) name: an optionally namespaced identifier such
+ * as `app.current_tenant` or `search_path`. Even though the name is passed as a
+ * bound parameter to `set_config`, a malformed name is a programmer error worth
+ * rejecting loudly before it reaches the database.
+ */
+const GUC_NAME_REGEX = /^[A-Za-z_][A-Za-z0-9_]*(\.[A-Za-z_][A-Za-z0-9_]*)?$/;
 // ---------------------------------------------------------------------------
 // TransactionClient — provides typed table accessors within a transaction
 // ---------------------------------------------------------------------------
@@ -189,6 +199,8 @@ export class TurbineClient {
     errorMessagesSafe;
     /** True when Turbine created the pool and is responsible for tearing it down */
     ownsPool = true;
+    /** Active LISTEN subscriptions — torn down on disconnect() so it never hangs */
+    activeSubscriptions = new Set();
     constructor(config = {}, schema) {
         /**
          * Parse int8 (bigint, OID 20) as JavaScript number instead of string.
@@ -460,6 +472,40 @@ export class TurbineClient {
             throw wrapPgError(err);
         }
     }
+    /**
+     * Execute a **typed** raw SQL query — Turbine's answer to Prisma's TypedSQL.
+     *
+     * Like {@link raw}, every interpolated `${value}` becomes a `$N` parameter
+     * (never string-concatenated), so it is injection-safe by construction. The
+     * difference is the caller-supplied row type and the chainable result: the
+     * returned {@link TypedSqlQuery} can be `await`ed directly for `T[]`, or
+     * refined with `.one()` (→ `T | null`) or `.scalar<V>()` (→ `V | null`).
+     *
+     * Rows are returned as-is — no snake→camel mapping (matching `raw()`). Alias
+     * columns in SQL if you want camelCase keys.
+     *
+     * @example
+     * ```ts
+     * // rows
+     * const rows = await db.sql<{ id: number; name: string }>`
+     *   SELECT id, name FROM users WHERE org_id = ${orgId}
+     * `;
+     *
+     * // single row or null
+     * const user = await db.sql<{ id: number; name: string }>`
+     *   SELECT id, name FROM users WHERE id = ${userId}
+     * `.one();
+     *
+     * // scalar
+     * const total = await db.sql<{ count: number }>`
+     *   SELECT COUNT(*)::int AS count FROM users
+     * `.scalar();
+     * ```
+     */
+    sql(strings, ...values) {
+        const { sql, params } = buildTypedSql(strings, values);
+        return new TypedSqlQuery(this.pool, sql, params, this.logging);
+    }
     // -------------------------------------------------------------------------
     // Transaction support (raw — legacy)
     // -------------------------------------------------------------------------
@@ -542,6 +588,21 @@ export class TurbineClient {
                     beginSQL += ` ISOLATION LEVEL ${level}`;
             }
             await client.query(beginSQL);
+            // Apply transaction-local session context (RLS / multi-tenant GUCs).
+            // Order matters: BEGIN -> isolation level (above) -> set_config loop ->
+            // user fn. Any error here propagates to the catch below and rolls back
+            // like any other transaction failure. We use set_config(name, value,
+            // is_local=true) — the parameterizable, transaction-scoped equivalent of
+            // SET LOCAL — so both name and value are BOUND params, never interpolated.
+            if (options?.sessionContext) {
+                for (const [name, value] of Object.entries(options.sessionContext)) {
+                    if (!GUC_NAME_REGEX.test(name)) {
+                        throw new ValidationError(`[turbine] Invalid session-context GUC name "${name}" — must match ` +
+                            '/^[A-Za-z_][A-Za-z0-9_]*(\\.[A-Za-z_][A-Za-z0-9_]*)?$/ (optionally namespaced, e.g. "app.current_tenant")');
+                    }
+                    await client.query('SELECT set_config($1, $2, true)', [name, String(value)]);
+                }
+            }
             // Create the transaction client with typed table accessors
             const tx = new TransactionClient(client, this.schema, this.middlewares, this.queryOptions);
             // Dynamically attach table accessors to tx
@@ -613,6 +674,94 @@ export class TurbineClient {
             releaseOnce();
         }
     }
+    /**
+     * Convenience wrapper around `$transaction` for the multi-tenant / RLS case:
+     * runs `fn` inside a transaction with the given session GUCs applied via
+     * `set_config(..., is_local=true)`. Equivalent to
+     * `$transaction(fn, { sessionContext: context })`.
+     *
+     * @example
+     * ```ts
+     * const invoices = await db.$withSession(
+     *   { 'app.current_tenant': tenantId },
+     *   (tx) => tx.invoices.findMany(),
+     * );
+     * ```
+     */
+    async $withSession(context, fn) {
+        return this.$transaction(fn, { sessionContext: context });
+    }
+    // -------------------------------------------------------------------------
+    // LISTEN / NOTIFY — Postgres realtime pub/sub
+    // -------------------------------------------------------------------------
+    /**
+     * Subscribe to a Postgres NOTIFY channel. The handler fires with each
+     * notification's payload string (the empty string when a payload-less
+     * NOTIFY is sent) for as long as the subscription is active.
+     *
+     * Each `$listen` checks out its OWN dedicated long-lived connection from the
+     * pool and runs `LISTEN "channel"` on it; `subscription.unsubscribe()`
+     * UNLISTENs, detaches the handler, and releases that connection. Active
+     * subscriptions are tracked and force-released on `disconnect()` so shutdown
+     * never hangs.
+     *
+     * The channel name CANNOT be a bound parameter (`LISTEN $1` is a syntax
+     * error), so it is validated against a strict identifier regex AND quoted via
+     * `quoteIdent` before interpolation — it is the only identifier this method
+     * places into SQL text.
+     *
+     * **Serverless caveat:** LISTEN needs a persistent connection that can push
+     * async notifications. Stateless HTTP drivers (Neon HTTP, Vercel Postgres)
+     * cannot do this — `$listen` throws a `ConnectionError` rather than hang.
+     * `$notify` works on every driver.
+     *
+     * @example
+     * ```ts
+     * const sub = await db.$listen('order_created', (payload) => {
+     *   const order = JSON.parse(payload);
+     *   console.log('new order', order.id);
+     * });
+     * // ...later
+     * await sub.unsubscribe();
+     * ```
+     */
+    async $listen(channel, handler) {
+        validateChannel(channel);
+        const quoted = quoteIdent(channel);
+        if (this.logging) {
+            console.log(`[turbine] LISTEN ${quoted}`);
+        }
+        const sub = await createSubscription(this.pool, channel, quoted, handler, (closed) => {
+            this.activeSubscriptions.delete(closed);
+        });
+        this.activeSubscriptions.add(sub);
+        return sub;
+    }
+    /**
+     * Send a Postgres NOTIFY on `channel` with an optional payload string.
+     *
+     * Issued as `SELECT pg_notify($1, $2)` — both the channel and payload are
+     * BOUND parameters (no quoting/injection concern). The channel is still
+     * validated against the identifier regex for parity with `$listen` and to
+     * catch typos loudly. Works on every driver, including serverless HTTP pools.
+     *
+     * @example
+     * ```ts
+     * await db.$notify('order_created', JSON.stringify({ id: 7 }));
+     * ```
+     */
+    async $notify(channel, payload) {
+        validateChannel(channel);
+        if (this.logging) {
+            console.log(`[turbine] NOTIFY ${channel}`);
+        }
+        try {
+            await this.pool.query('SELECT pg_notify($1, $2)', [channel, payload ?? '']);
+        }
+        catch (err) {
+            throw wrapPgError(err);
+        }
+    }
     // -------------------------------------------------------------------------
     // Retry — automatic retry for retryable errors (deadlock, serialization)
     // -------------------------------------------------------------------------
@@ -660,6 +809,21 @@ export class TurbineClient {
      * method is a no-op — the caller is responsible for the pool's lifecycle.
      */
     async disconnect() {
+        // Tear down any live LISTEN subscriptions first. Each holds a dedicated
+        // pooled connection checked out; if we ended the pool (or returned for an
+        // external pool) without releasing them, pool.end() would wait forever for
+        // those connections to return. _forceRelease() detaches the handler and
+        // releases the client WITHOUT issuing UNLISTEN (pointless if we're ending
+        // the pool / the connection is going away anyway). This runs for both
+        // owned and external pools so subscriptions never leak.
+        if (this.activeSubscriptions.size > 0) {
+            // _forceRelease mutates activeSubscriptions via the onClosed callback,
+            // so iterate a snapshot.
+            for (const sub of [...this.activeSubscriptions]) {
+                sub._forceRelease();
+            }
+            this.activeSubscriptions.clear();
+        }
         if (!this.ownsPool) {
             if (this.logging) {
                 console.log('[turbine] disconnect() skipped — external pool is not owned by Turbine');

package/dist/errors.js

@@ -197,7 +197,13 @@ export class UniqueConstraintError extends TurbineError {
             const constraintPart = constraint ? ` on ${constraint}` : '';
             const columnsPart = columns && columns.length > 0 ? ` (${columns.join(', ')})` : '';
             message = `[turbine] Unique constraint violation${constraintPart}${columnsPart}`;
-            const detail = detailFromCause(cause);
+            // PII-safe by default: the raw pg `detail` string contains the
+            // conflicting row VALUES (e.g. `Key (email)=(alice@x.com) already
+            // exists.`). Only append it in 'verbose' mode. In 'safe' mode the
+            // message carries keys/constraint/column names only — the structured
+            // `.columns`/`.constraint`/`.column` fields and `.cause` still expose
+            // the full detail for programmatic use.
+            const detail = errorMessageMode === 'verbose' ? detailFromCause(cause) : undefined;
             if (detail)
                 message += `: ${detail}`;
         }
@@ -218,7 +224,13 @@ export class ForeignKeyError extends TurbineError {
         if (!message) {
             const constraintPart = constraint ? ` on ${constraint}` : '';
             message = `[turbine] Foreign key constraint violation${constraintPart}`;
-            const detail = detailFromCause(cause);
+            // PII-safe by default: the raw pg `detail` string contains the
+            // conflicting row VALUES (e.g. `Key (email)=(alice@x.com) already
+            // exists.`). Only append it in 'verbose' mode. In 'safe' mode the
+            // message carries keys/constraint/column names only — the structured
+            // `.columns`/`.constraint`/`.column` fields and `.cause` still expose
+            // the full detail for programmatic use.
+            const detail = errorMessageMode === 'verbose' ? detailFromCause(cause) : undefined;
             if (detail)
                 message += `: ${detail}`;
         }
@@ -238,7 +250,13 @@ export class NotNullViolationError extends TurbineError {
         if (!message) {
             const columnPart = column ? ` on column "${column}"` : '';
             message = `[turbine] NOT NULL constraint violation${columnPart}`;
-            const detail = detailFromCause(cause);
+            // PII-safe by default: the raw pg `detail` string contains the
+            // conflicting row VALUES (e.g. `Key (email)=(alice@x.com) already
+            // exists.`). Only append it in 'verbose' mode. In 'safe' mode the
+            // message carries keys/constraint/column names only — the structured
+            // `.columns`/`.constraint`/`.column` fields and `.cause` still expose
+            // the full detail for programmatic use.
+            const detail = errorMessageMode === 'verbose' ? detailFromCause(cause) : undefined;
             if (detail)
                 message += `: ${detail}`;
         }
@@ -323,7 +341,13 @@ export class CheckConstraintError extends TurbineError {
         if (!message) {
             const constraintPart = constraint ? ` on ${constraint}` : '';
             message = `[turbine] Check constraint violation${constraintPart}`;
-            const detail = detailFromCause(cause);
+            // PII-safe by default: the raw pg `detail` string contains the
+            // conflicting row VALUES (e.g. `Key (email)=(alice@x.com) already
+            // exists.`). Only append it in 'verbose' mode. In 'safe' mode the
+            // message carries keys/constraint/column names only — the structured
+            // `.columns`/`.constraint`/`.column` fields and `.cause` still expose
+            // the full detail for programmatic use.
+            const detail = errorMessageMode === 'verbose' ? detailFromCause(cause) : undefined;
             if (detail)
                 message += `: ${detail}`;
         }
@@ -342,7 +366,13 @@ export class ExclusionConstraintError extends TurbineError {
         if (!message) {
             const constraintPart = constraint ? ` on ${constraint}` : '';
             message = `[turbine] Exclusion constraint violation${constraintPart}`;
-            const detail = detailFromCause(cause);
+            // PII-safe by default: the raw pg `detail` string contains the
+            // conflicting row VALUES (e.g. `Key (email)=(alice@x.com) already
+            // exists.`). Only append it in 'verbose' mode. In 'safe' mode the
+            // message carries keys/constraint/column names only — the structured
+            // `.columns`/`.constraint`/`.column` fields and `.cause` still expose
+            // the full detail for programmatic use.
+            const detail = errorMessageMode === 'verbose' ? detailFromCause(cause) : undefined;
             if (detail)
                 message += `: ${detail}`;
         }

package/dist/generate.js

@@ -152,7 +152,8 @@ export function generateTypes(schema) {
             lines.push(`export interface ${typeName}Relations {`);
             for (const [relName, rel] of Object.entries(table.relations)) {
                 const targetType = entityName(rel.to);
-                const cardinality = rel.type === 'hasMany' ? "'many'" : "'one'";
+                // 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}>;`);
             }
@@ -161,7 +162,7 @@ export function generateTypes(schema) {
             // --- Legacy per-relation interfaces (kept for backward compatibility) ---
             for (const [relName, rel] of Object.entries(table.relations)) {
                 const targetType = entityName(rel.to);
-                if (rel.type === 'hasMany') {
+                if (rel.type === 'hasMany' || rel.type === 'manyToMany') {
                     lines.push(`/** ${typeName} with \`${relName}\` relation loaded (${rel.type}: ${rel.to}) */`);
                     lines.push(`export interface ${typeName}With${snakeToPascal(relName)} extends ${typeName} {`);
                     lines.push(`  ${relName}: ${targetType}[];`);
@@ -328,7 +329,17 @@ function generateMetadata(schema) {
             const refLiteral = Array.isArray(rel.referenceKey)
                 ? `[${rel.referenceKey.map((c) => `'${escSQ(c)}'`).join(', ')}]`
                 : `'${escSQ(rel.referenceKey)}'`;
-            lines.push(`        ${relName}: { type: '${escSQ(rel.type)}', name: '${escSQ(rel.name)}', from: '${escSQ(rel.from)}', to: '${escSQ(rel.to)}', foreignKey: ${fkLiteral}, referenceKey: ${refLiteral} },`);
+            // manyToMany relations carry a `through` junction descriptor — emit it so
+            // the runtime query builder can JOIN through the junction table.
+            let throughLiteral = '';
+            if (rel.through) {
+                const keyLiteral = (k) => Array.isArray(k) ? `[${k.map((c) => `'${escSQ(c)}'`).join(', ')}]` : `'${escSQ(k)}'`;
+                throughLiteral =
+                    `, through: { table: '${escSQ(rel.through.table)}', ` +
+                        `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('      },');
         // indexes

package/dist/index.d.ts

@@ -43,10 +43,12 @@ 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 JsonFilter, type NestedCreateOp, type NestedUpdateOp, type OmitResult, 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 WithClause, type WithOptions, type WithResult, } from './query/index.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 JsonFilter, 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 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';
-export { ColumnBuilder, type ColumnConfig, type ColumnDef, type ColumnType, type ColumnTypeName, column, defineSchema, type SchemaDef, type TableDef, table, } from './schema-builder.js';
+export { applyManyToManyRelations, ColumnBuilder, type ColumnConfig, type ColumnDef, type ColumnType, type ColumnTypeName, column, defineSchema, type ManyToManyDef, type SchemaDef, type TableDef, table, } from './schema-builder.js';
 export { type AlterColumnDef, type AlterDef, type DiffResult, type PushResult, type SchemaSqlOptions, schemaDiff, schemaPush, schemaToSQL, schemaToSQLString, } from './schema-sql.js';
 export { type TurbineHttpOptions, turbineHttp } from './serverless.js';
+export { buildTypedSql, TypedSqlQuery } from './typed-sql.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -48,14 +48,18 @@ export { executeNestedCreate, executeNestedUpdate, hasRelationFields, } from './
 export { executePipeline, pipelineSupported } from './pipeline.js';
 // Query builder
 export { QueryInterface, } from './query/index.js';
+// Realtime — LISTEN/NOTIFY pub/sub
+export { validateChannel } from './realtime.js';
 // Schema utilities
 export { camelToSnake, isDateType, normalizeKeyColumns, pgArrayType, pgTypeToTs, singularize, snakeToCamel, snakeToPascal, } from './schema.js';
 // Schema builder — define schemas in TypeScript
-export { ColumnBuilder, column, defineSchema, 
+export { applyManyToManyRelations, ColumnBuilder, column, defineSchema, 
 // Legacy compat (deprecated — use object format with defineSchema)
 table, } from './schema-builder.js';
 // Schema SQL — generate DDL, diff, and push
 export { schemaDiff, schemaPush, schemaToSQL, schemaToSQLString, } from './schema-sql.js';
 // Serverless / edge factory
 export { turbineHttp } from './serverless.js';
+// Typed raw SQL — Turbine's TypedSQL escape hatch
+export { buildTypedSql, TypedSqlQuery } from './typed-sql.js';
 //# sourceMappingURL=index.js.map

package/dist/introspect.js

@@ -275,6 +275,87 @@ export async function introspect(options) {
                 referenceKey,
             };
         }
+        // ----- Conservative many-to-many auto-detection (PURELY ADDITIVE) -----
+        //
+        // Auto-detecting m2m is a footgun: any table with two FKs *looks* like a
+        // junction, but a `enrollments(student_id, course_id, grade, enrolled_at)`
+        // table is a first-class entity, not a join table. Prisma and Drizzle both
+        // require explicit m2m declaration for exactly this reason.
+        //
+        // We only treat a table J as a PURE junction when ALL of these hold:
+        //   1. J's primary key is exactly two columns.
+        //   2. J has exactly two FKs, each single-column.
+        //   3. Each FK's source column is one of J's two PK columns (the PK *is* the
+        //      two FK columns — no surrogate PK, no extra identity).
+        //   4. The two FKs target two DISTINCT tables (A and B).
+        //   5. J has no columns beyond those two FK/PK columns (no payload columns
+        //      like `grade` or `created_at`).
+        //
+        // For such a J linking A and B we ADD a `manyToMany` relation on A → B and
+        // symmetrically on B → A, both routed `through` J. The existing belongsTo /
+        // hasMany relations derived from J's FKs are left untouched — this block
+        // never removes or renames anything. If the chosen relation name already
+        // exists on the source table (e.g. another relation grabbed it), we SKIP to
+        // stay additive.
+        for (const tableName of tableNames) {
+            const pk = pkByTable.get(tableName) ?? [];
+            if (pk.length !== 2)
+                continue;
+            // FKs whose source is this table.
+            const tableFks = foreignKeys.filter((fk) => fk.sourceTable === tableName);
+            if (tableFks.length !== 2)
+                continue;
+            // Both FKs must be single-column.
+            if (tableFks.some((fk) => fk.sourceColumns.length !== 1))
+                continue;
+            const fkCols = tableFks.map((fk) => fk.sourceColumns[0]);
+            const pkSet = new Set(pk);
+            // Both FK columns must be the PK columns (and vice-versa).
+            if (!fkCols.every((c) => pkSet.has(c)))
+                continue;
+            if (new Set(fkCols).size !== 2)
+                continue;
+            // Two DISTINCT target tables.
+            const [fkA, fkB] = tableFks;
+            if (fkA.targetTable === fkB.targetTable)
+                continue;
+            // No payload columns: J's columns are exactly the two FK/PK columns.
+            const jCols = (columnsByTable.get(tableName) ?? []).map((c) => c.name);
+            if (jCols.length !== 2)
+                continue;
+            // For each direction, the m2m `referenceKey` is the *targeted* table's
+            // referenced column(s); the junction's sourceKey is the FK column pointing
+            // to that table; the targetKey is the FK column pointing to the OTHER table.
+            const addM2M = (self, other) => {
+                const sourceTbl = self.targetTable; // A
+                const targetTbl = other.targetTable; // B
+                const relName = snakeToCamel(targetTbl); // plural table name → e.g. "tags"
+                if (!relationsByTable.has(sourceTbl))
+                    relationsByTable.set(sourceTbl, {});
+                const existing = relationsByTable.get(sourceTbl);
+                // Additive-only: never clobber an existing relation name.
+                if (existing[relName])
+                    return;
+                existing[relName] = {
+                    type: 'manyToMany',
+                    name: relName,
+                    from: sourceTbl,
+                    to: targetTbl,
+                    // referenceKey = A's referenced column(s) that J's sourceKey points at.
+                    referenceKey: self.targetColumns.length === 1 ? self.targetColumns[0] : self.targetColumns,
+                    // foreignKey is unused for m2m correlation but kept for shape parity
+                    // (mirrors the source-side reference for back-compat consumers).
+                    foreignKey: self.targetColumns.length === 1 ? self.targetColumns[0] : self.targetColumns,
+                    through: {
+                        table: tableName,
+                        sourceKey: self.sourceColumns[0], // J col → A
+                        targetKey: other.sourceColumns[0], // J col → B
+                    },
+                };
+            };
+            addM2M(fkA, fkB); // A → B
+            addM2M(fkB, fkA); // B → A
+        }
         // ----- Assemble TableMetadata for each table -----
         const tables = {};
         for (const tableName of tableNames) {

package/dist/nested-write.js

@@ -137,17 +137,29 @@ export async function executeNestedCreate(ctx, tableName, data, depth = 0, path
         }
         validateOps(relName, ops, false);
     }
-    // Insert the parent row
-    const parentRow = (await ctx.tx.table(tableName).create({ data: scalars }));
-    // Process each relation
+    // belongsTo relations put the foreign key on the PARENT row, so they must be
+    // resolved BEFORE the parent is inserted — otherwise a NOT NULL FK column
+    // fails on the initial INSERT. We resolve each belongsTo op (create/connect/
+    // connectOrCreate) to its referenced row and fold the FK values into the
+    // parent's own INSERT.
+    const belongsToFks = {};
+    for (const [relName, ops] of Object.entries(relations)) {
+        const rel = tableMeta.relations[relName];
+        if (rel.type === 'belongsTo') {
+            Object.assign(belongsToFks, await resolveBelongsToForCreate(ctx, rel, ops, tableName, depth, path, relName));
+        }
+    }
+    // Insert the parent row (scalars + resolved belongsTo foreign keys)
+    const parentRow = (await ctx.tx.table(tableName).create({
+        data: { ...scalars, ...belongsToFks },
+    }));
+    // Process hasMany / hasOne relations — their FK lives on the CHILD, so they
+    // need the parent row to exist first.
     for (const [relName, ops] of Object.entries(relations)) {
         const rel = tableMeta.relations[relName];
         if (rel.type === 'hasMany' || rel.type === 'hasOne') {
             await processHasManyCreate(ctx, rel, ops, parentRow, depth, path, relName);
         }
-        else if (rel.type === 'belongsTo') {
-            await processBelongsToCreate(ctx, rel, ops, parentRow, tableName, depth, path, relName);
-        }
     }
     // Build the `with` clause for the final read to return the full tree
     const withClause = {};
@@ -312,6 +324,58 @@ async function processHasManyCreate(ctx, rel, ops, parentRow, depth, path, relNa
 // ---------------------------------------------------------------------------
 // belongsTo create operations
 // ---------------------------------------------------------------------------
+/**
+ * Resolve a belongsTo relation's create/connect/connectOrCreate op to the
+ * foreign-key value(s) that belong on the PARENT row, returning them keyed by
+ * the parent's own field names so they can be merged into the parent INSERT.
+ *
+ * Used by the create path only. (The update path uses processBelongsToCreate,
+ * which UPDATEs the FK after the parent already exists.)
+ */
+async function resolveBelongsToForCreate(ctx, rel, ops, parentTable, depth, path, relName) {
+    const fks = normalizeKeyColumns(rel.foreignKey);
+    const refs = normalizeKeyColumns(rel.referenceKey);
+    const parentMeta = ctx.schema.tables[parentTable];
+    const relatedTable = ctx.schema.tables[rel.to];
+    let relatedRow = null;
+    if (ops.create !== undefined) {
+        const items = toArray(ops.create);
+        if (items.length > 0) {
+            relatedRow = (await executeNestedCreate(ctx, rel.to, items[0], depth + 1, [...path, relName]));
+        }
+    }
+    else if (ops.connect !== undefined) {
+        const items = toArray(ops.connect);
+        if (items.length > 0) {
+            const target = items[0];
+            relatedRow = (await ctx.tx.table(rel.to).findUnique({ where: target }));
+            if (!relatedRow) {
+                throw new ValidationError(`[turbine] connect on "${relName}": no ${rel.to} row found matching ${JSON.stringify(target)}.`);
+            }
+        }
+    }
+    else if (ops.connectOrCreate !== undefined) {
+        const items = toArray(ops.connectOrCreate);
+        if (items.length > 0) {
+            const op = items[0];
+            relatedRow = (await ctx.tx.table(rel.to).findUnique({ where: op.where }));
+            if (!relatedRow) {
+                // For belongsTo the FK lives on the parent, so the related row is
+                // created plainly (no FK injection) and we read its reference key.
+                relatedRow = (await ctx.tx.table(rel.to).create({ data: op.create }));
+            }
+        }
+    }
+    const fkScalars = {};
+    if (relatedRow) {
+        for (let i = 0; i < fks.length; i++) {
+            const fkField = parentMeta.reverseColumnMap[fks[i]] ?? fks[i];
+            const refField = relatedTable?.reverseColumnMap[refs[i]] ?? refs[i];
+            fkScalars[fkField] = relatedRow[refField];
+        }
+    }
+    return fkScalars;
+}
 async function processBelongsToCreate(ctx, rel, ops, parentRow, parentTable, depth, path, relName) {
     const fks = normalizeKeyColumns(rel.foreignKey);
     const refs = normalizeKeyColumns(rel.referenceKey);