turbine-orm 0.78.0 → 0.79.0

package/dist/client.js

@@ -24,12 +24,13 @@
 import pg from 'pg';
 import { mergeConnectionStringOptions } from './connection-url.js';
 import { postgresDialect } from './dialect.js';
-import { ConnectionError, errorMessageModesDiverged, registerClientErrorMessageMode, runWithErrorMessageMode, setErrorMessageMode, TimeoutError, UnsupportedFeatureError, ValidationError, wrapPgError, } from './errors.js';
+import { ConnectionError, errorMessageModesDiverged, PipelineError, registerClientErrorMessageMode, runWithErrorMessageMode, setErrorMessageMode, TimeoutError, UnsupportedFeatureError, ValidationError, wrapPgError, } from './errors.js';
 import { ObserveEngine } from './observe.js';
 import { executePipeline, pipelineSupported } from './pipeline.js';
 import { QueryInterface, } from './query/index.js';
 import { markTurbineParser, ownLookup, quoteIdent, registerUtcTemporalParsers, suggestKey, warnParserOverwrite, } from './query/utils.js';
 import { shouldWarnOnce, WARN_NS } from './query/warn-registry.js';
+import { currentQueryTag, deferredIdentity, emitStatementEvent, rawIdentity, resultRowCount, runReportedStatement, runWithQueryTag, } from './query-events.js';
 import { createSubscription, validateChannel, } from './realtime.js';
 import { buildTypedSql, TypedSqlQuery } from './typed-sql.js';
 export async function withRetry(fn, options) {
@@ -531,13 +532,8 @@ export class TransactionClient {
                 sql += this.dialect.paramPlaceholder(i + 1);
             }
         });
-        try {
-            const result = await this.client.query(sql, values);
-            return result.rows;
-        }
-        catch (err) {
-            throw wrapPgError(err);
-        }
+        const result = await runReportedStatement(this.queryOptions?._onQuery, rawIdentity('raw'), sql, values, () => this.client.query(sql, values), wrapPgError);
+        return result.rows;
     }
     /**
      * @internal The `turbine-orm/prisma-compat` adapter's transaction seam. NOT
@@ -561,16 +557,13 @@ export class TransactionClient {
      * inside the same BEGIN/COMMIT (and any active SAVEPOINT) as every other
      * statement in the callback. Driver errors are translated by `wrapPgError`,
      * exactly as pool-scoped and table-scoped queries are. Like {@link raw}, it
-     * emits no `$on('query')` event and runs no middleware.
+     * runs no middleware, and it emits one `$on('query')` event with model
+     * `'$raw'` and `action` set to the optional `action` label (the adapter
+     * passes `'$queryRaw'` / `'$executeRaw'` ...; default `'rawQuery'`).
      */
-    async rawQuery(text, params = []) {
-        try {
-            const result = await this.client.query(text, params);
-            return { rows: result.rows, rowCount: result.rowCount };
-        }
-        catch (err) {
-            throw wrapPgError(err);
-        }
+    async rawQuery(text, params = [], action = 'rawQuery') {
+        const result = await runReportedStatement(this.queryOptions?._onQuery, rawIdentity(action), text, params, () => this.client.query(text, params), wrapPgError);
+        return { rows: result.rows, rowCount: result.rowCount };
     }
     /**
      * Create a pool-like wrapper around the transaction client.
@@ -900,7 +893,11 @@ export class TurbineClient {
             _onQuery: (event) => {
                 if (this.queryListeners.size === 0)
                     return;
-                const emitted = this.queryParamsVisible ? event : { ...event, params: event.params.map(() => '[REDACTED]') };
+                // The $tag() scope is read here, at the one seam every emitter shares,
+                // so a tag reaches model, raw, pipeline and batch events alike.
+                const tag = event.tag ?? currentQueryTag();
+                const tagged = tag === undefined || event.tag !== undefined ? event : { ...event, tag };
+                const emitted = this.queryParamsVisible ? tagged : { ...tagged, params: tagged.params.map(() => '[REDACTED]') };
                 for (const listener of this.queryListeners) {
                     try {
                         listener(emitted);
@@ -1512,7 +1509,63 @@ export class TurbineClient {
         // where VALUES as soon as any verbose client existed in the process. The
         // scope is established around the await, so every continuation of the batch
         // resolves this client's mode.
-        return this.withErrorMode(() => executePipeline(this.pool, queries, options));
+        const sink = this.queryListeners.size > 0 ? this.queryOptions._onQuery : undefined;
+        if (!sink)
+            return this.withErrorMode(() => executePipeline(this.pool, queries, options));
+        return this.withErrorMode(() => this.reportedPipeline(sink, queries, options));
+    }
+    /**
+     * {@link pipeline} with one `$on('query')` event per statement. Only taken
+     * when a listener is registered, so an unobserved pipeline runs exactly as
+     * before. Each statement's `transform` is wrapped to capture the driver's
+     * row count on the way through (the pipeline returns transformed values, not
+     * driver results). The statements share one round trip, so the batch's wall
+     * time is split evenly across them and each event carries
+     * `batch: 'pipeline'`.
+     */
+    async reportedPipeline(sink, queries, options) {
+        const rowCounts = new Array(queries.length).fill(undefined);
+        const observed = queries.map((q, i) => ({
+            ...q,
+            transform: (raw) => {
+                rowCounts[i] = resultRowCount(raw);
+                return q.transform(raw);
+            },
+        }));
+        const start = performance.now();
+        let failure;
+        try {
+            return await executePipeline(this.pool, observed, options);
+        }
+        catch (err) {
+            failure = err;
+            throw err;
+        }
+        finally {
+            const duration = (performance.now() - start) / queries.length;
+            // PipelineError names the failing slot; any other failure (connect,
+            // BEGIN) is charged to the first statement that produced no result.
+            const failedIndex = failure === undefined
+                ? -1
+                : failure instanceof PipelineError && failure.failedIndex !== undefined
+                    ? failure.failedIndex
+                    : rowCounts.indexOf(undefined);
+            queries.forEach((q, i) => {
+                const failed = i === failedIndex;
+                // A slot that never ran (or rolled back unseen) is not reported.
+                if (failed || rowCounts[i] !== undefined) {
+                    emitStatementEvent(sink, {
+                        sql: q.sql,
+                        params: q.params,
+                        duration,
+                        ...deferredIdentity(q.tag),
+                        rows: rowCounts[i] ?? 0,
+                        batch: 'pipeline',
+                        ...(failed ? { error: failure instanceof Error ? failure : new Error(String(failure)) } : {}),
+                    });
+                }
+            });
+        }
     }
     /**
      * Check whether the underlying pool supports the real pipeline protocol.
@@ -1548,13 +1601,43 @@ export class TurbineClient {
         if (this.logging) {
             console.log(`[turbine] Raw SQL: ${sql.trim().substring(0, 120)}...`);
         }
-        try {
-            const result = await this.pool.query(sql, values);
-            return result.rows;
-        }
-        catch (err) {
-            throw this.withErrorMode(() => wrapPgError(err));
-        }
+        const result = await runReportedStatement(this.queryOptions._onQuery, rawIdentity('raw'), sql, values, () => this.pool.query(sql, values), (err) => this.withErrorMode(() => wrapPgError(err)));
+        return result.rows;
+    }
+    /**
+     * @internal The `turbine-orm/prisma-compat` adapter's pool-level raw seam,
+     * the twin of {@link TransactionClient.rawQuery}. NOT application API: use
+     * {@link raw} or {@link sql}, whose tagged templates make concatenating a
+     * value into the SQL text impossible. It exists so the adapter's
+     * `$queryRaw` / `$executeRaw` statements emit a `$on('query')` event (model
+     * `'$raw'`, `action` the adapter's label) instead of running unobserved on
+     * the pool. Errors are translated by `wrapPgError`, like {@link raw}.
+     */
+    async rawQuery(text, params = [], action = 'rawQuery') {
+        const result = await runReportedStatement(this.queryOptions._onQuery, rawIdentity(action), text, params, () => this.pool.query(text, params), (err) => this.withErrorMode(() => wrapPgError(err)));
+        return { rows: result.rows, rowCount: result.rowCount };
+    }
+    /**
+     * Run `fn` with `tag` attached to every `$on('query')` event it causes, so a
+     * listener can attribute queries to the feature or code path that issued
+     * them. The scope follows async context: queries in awaited helpers,
+     * transactions, pipelines and raw SQL inside `fn` are all tagged. An inner
+     * `$tag` replaces an outer one for its own duration. The tag is event
+     * metadata only and never reaches SQL.
+     *
+     * Throws {@link ValidationError} (E003) for an empty tag or one longer than
+     * {@link MAX_QUERY_TAG_LENGTH} (128) characters.
+     *
+     * @example
+     * ```ts
+     * const order = await db.$tag('checkout', async () => {
+     *   const cart = await db.carts.findUnique({ where: { id } });
+     *   return db.orders.create({ data: { cartId: cart.id } });
+     * });
+     * ```
+     */
+    $tag(tag, fn) {
+        return runWithQueryTag(tag, fn);
     }
     /**
      * Execute a **typed** raw SQL query, Turbine's answer to Prisma's TypedSQL.
@@ -1594,7 +1677,7 @@ export class TurbineClient {
         // `withErrorMode` docstring already claimed to cover the typed-SQL builder
         // and did not, which left two raw-SQL entry points disagreeing about the
         // same statement, since the adjacent `raw` tag WAS scoped.
-        return new TypedSqlQuery(this.pool, sql, params, this.logging, (fn) => this.withErrorMode(fn));
+        return new TypedSqlQuery(this.pool, sql, params, this.logging, (fn) => this.withErrorMode(fn), this.queryOptions._onQuery);
     }
     // -------------------------------------------------------------------------
     // Transaction support (raw, legacy)
@@ -1834,13 +1917,18 @@ export class TurbineClient {
         if (queries.length === 0) {
             return [];
         }
+        // One `$on('query')` event per statement, `batch: 'transaction'`, only
+        // when someone is listening; each statement is timed on its own.
+        const sink = this.queryListeners.size > 0 ? this.queryOptions._onQuery : undefined;
+        const reported = (dq, run) => runReportedStatement(sink, { ...deferredIdentity(dq.tag), batch: 'transaction' }, dq.sql, dq.params, run, wrapPgError);
         return this.transaction(async (client) => {
             const pipelined = client.supportsPipelining === true &&
                 this.dialect.resultStrategy !== 'reselect';
             if (pipelined) {
                 // Dispatch every statement before awaiting any reply. The driver's
-                // FIFO guarantee makes settled[i] the reply to queries[i].
-                const settled = await Promise.allSettled(queries.map((dq) => client.query(dq.sql, dq.params)));
+                // FIFO guarantee makes settled[i] the reply to queries[i]. Each
+                // statement is timed from its dispatch to its own reply.
+                const settled = await Promise.allSettled(queries.map((dq) => reported(dq, () => client.query(dq.sql, dq.params))));
                 const results = [];
                 for (let i = 0; i < settled.length; i++) {
                     const outcome = settled[i];
@@ -1853,19 +1941,12 @@ export class TurbineClient {
             }
             const results = [];
             for (const dq of queries) {
-                let raw;
-                try {
-                    // Non-RETURNING engines (resultStrategy 'reselect', e.g. MySQL)
-                    // attach a reselect plan that runs the write plus a follow-up SELECT;
-                    // running dq.sql alone would transform a row-less write result.
-                    raw =
-                        this.dialect.resultStrategy === 'reselect' && dq.reselect
-                            ? await dq.reselect((sql, params) => client.query(sql, params))
-                            : await client.query(dq.sql, dq.params);
-                }
-                catch (err) {
-                    throw wrapPgError(err);
-                }
+                // Non-RETURNING engines (resultStrategy 'reselect', e.g. MySQL) attach a
+                // reselect plan that runs the write plus a follow-up SELECT; running
+                // dq.sql alone would transform a row-less write result.
+                const raw = await reported(dq, () => this.dialect.resultStrategy === 'reselect' && dq.reselect
+                    ? dq.reselect((sql, params) => client.query(sql, params))
+                    : client.query(dq.sql, dq.params));
                 results.push(dq.transform(raw));
             }
             return results;

package/dist/index.d.ts

@@ -45,6 +45,7 @@ export { HttpJsonSink, type HttpJsonSinkOptions, type MetricsFlushBatch, type Me
 export { executePipeline, type PipelineOptions, type PipelineResults, pipelineSupported } from './pipeline.js';
 export { fingerprintPrismaSchema } from './prisma-schema-fingerprint.js';
 export { type AggregateArgs, type AggregateResult, type ArrayFilter, AUTO_ASSUMED_ROUND_TRIP_MS, AUTO_COUNT_BATCH_MIN_PARENT_ROWS, AUTO_JOIN_PENALTY_MS_PER_ROW, AUTO_TO_ONE_JOIN_MAX_ROWS, AUTO_TO_ONE_JOIN_ROWS_MAX, AUTO_TO_ONE_JOIN_ROWS_MIN, type ColumnRef, type ConnectOrCreateOp, type CountArgs, type CreateArgs, type CreateDataInput, type CreateManyArgs, type DeferredQuery, type DeleteArgs, type DeleteManyArgs, type FieldResult, type FindManyArgs, type FindManyStreamArgs, type FindUniqueArgs, type GlobalFilters, type GroupByAggregateSpec, type GroupByArgs, type GroupByDistinctOn, type GroupByResult, type HavingClause, type JsonEncoding, type JsonFilter, type JsonPathAggregateTarget, type JsonPathGroupKey, type JsonPathOrderBy, type MiddlewareFn, type NestedCreateOp, type NestedUpdateOp, type NestedUpdateOpItem, type NestedUpsertOpItem, type OmitResult, type OrderByClause, type OrderByObject, type OrderBySpec, type OrderDirection, type PrivilegeOption, type QueryEvent, type QueryEventListener, QueryInterface, type QueryResult, type RelationDescriptor, type RelationFilter, type RelationLoadStrategy, type RelationOrderBy, type RelationOrderByChain, type RelationPickBy, type RelationPickOrderBy, type SelectResult, type SkipGlobalFilters, type TemporalInfinityReading, type TextSearchFilter, type TypedWithClause, UNSAFE, type Unsafe, type UpdateArgs, type UpdateDataInput, type UpdateInput, type UpdateManyArgs, type UpdateOperatorInput, type UpsertArgs, type VectorDistanceFilter, type VectorFilter, type VectorMetric, type VectorOrderBy, type VectorOrderByDistance, type WhereClause, type WhereOperator, type WhereValue, type WithClause, type WithOptions, type WithOrderByObject, type WithResult, } from './query/index.js';
+export { MAX_QUERY_TAG_LENGTH, RAW_QUERY_MODEL } from './query-events.js';
 export { type ActiveSubscription, type NotificationHandler, type Subscription, validateChannel } from './realtime.js';
 export type { CheckMetadata, ColumnMetadata, IndexMetadata, PrismaCompatMap, PrismaModelMap, PrismaRelationMap, PrismaSchemaSource, ReferentialAction, RelationDef, SchemaMetadata, TableMetadata, } from './schema.js';
 export { camelToSnake, isDateType, normalizeKeyColumns, pgArrayType, pgTypeToTs, singularize, snakeToCamel, snakeToPascal, withDbFieldNames, } from './schema.js';

package/dist/index.js

@@ -55,6 +55,8 @@ export { fingerprintPrismaSchema } from './prisma-schema-fingerprint.js';
 // `allowFullTableScan` are unlocked by THIS VALUE and nothing else, so a
 // request body spread into query args cannot enable them (JSON has no symbols).
 export { AUTO_ASSUMED_ROUND_TRIP_MS, AUTO_COUNT_BATCH_MIN_PARENT_ROWS, AUTO_JOIN_PENALTY_MS_PER_ROW, AUTO_TO_ONE_JOIN_MAX_ROWS, AUTO_TO_ONE_JOIN_ROWS_MAX, AUTO_TO_ONE_JOIN_ROWS_MIN, QueryInterface, UNSAFE, } from './query/index.js';
+// $on('query') event metadata: raw-statement model name, $tag() label limit
+export { MAX_QUERY_TAG_LENGTH, RAW_QUERY_MODEL } from './query-events.js';
 // Realtime, LISTEN/NOTIFY pub/sub
 export { validateChannel } from './realtime.js';
 // Schema utilities

package/dist/powql.d.ts

@@ -155,6 +155,34 @@ export declare class PowqlInterface<T extends object = Record<string, unknown>>
      * the two can never disagree about which limit is in force.
      */
     private effectiveLimit;
+    /**
+     * Options for the child-side interfaces the relation loaders and the
+     * relation-filter resolvers build: the client's, with `defaultLimit` cleared
+     * and the unlimited warning off. `defaultLimit` bounds the caller's PAGE; on
+     * an internal fetch that serves that page (a relation's children, a filter's
+     * key set) it would cap the whole page's children, or the key set, at the
+     * page size: a silent wrong answer by another route than the one
+     * {@link pageOf} closes. The SQL batched loader clears it the same way
+     * (`batchedChildOptions` in query/builder.ts).
+     */
+    private childOptions?;
+    private loaderChildOptions;
+    /**
+     * ONE parent's window of its stitched children: the relation's `offset` and
+     * `limit` applied to that parent's own list.
+     *
+     * A relation `limit` means "at most N on EACH parent". The loaders used to
+     * spread it onto the flat child fetch (`post filter .author_id in (...)
+     * limit 5`), which caps the TOTAL across every parent in the chunk, so ten
+     * parents shared five posts and most got none, with no error. It shipped
+     * for the loaders' whole life because the one test of the shape compared
+     * the join path against the loader path and both were wrong the same way;
+     * the cross-engine benchmark found it, where the wrong answer was the fast
+     * one. Every loader now fetches its children unbounded, WITH the relation
+     * `orderBy` (which decides which rows the window keeps), and applies this
+     * at stitch time: the rule the SQL engines' batched loader has always used.
+     */
+    private static pageOf;
     /**
      * Reject a negative `limit` / `offset` before it reaches the engine. PowDB
      * casts both with `as usize` at execution, so below engine 0.20 a negative
@@ -623,9 +651,10 @@ export declare class PowqlInterface<T extends object = Record<string, unknown>>
      *     `referenceKey` on the TARGET table (the join's non-fetched side);
      *   - m2m keeps any `orderBy`/`limit`/`offset` on the loader (the junction-order
      *     stitch can't be reproduced by the 3-table join deterministically);
-     *   - a to-one relation `limit`/`offset` (meaningless) stays on the loader, as
-     *     does a to-many relation `limit`/`offset` when the parent set spills past
-     *     one loader chunk (the loader limits per chunk, the join once globally).
+     *   - a to-one relation `limit`/`offset` (meaningless) stays on the loader. A
+     *     to-many relation `limit`/`offset` is a PER-PARENT bound on both paths,
+     *     fetched unbounded and sliced per parent at stitch time (`pageOf`), so
+     *     the join statement carries neither clause.
      */
     private joinEligible;
     /**

package/dist/powql.js

@@ -357,6 +357,42 @@ export class PowqlInterface {
     effectiveLimit(args) {
         return args.limit ?? this.defaultLimit;
     }
+    /**
+     * Options for the child-side interfaces the relation loaders and the
+     * relation-filter resolvers build: the client's, with `defaultLimit` cleared
+     * and the unlimited warning off. `defaultLimit` bounds the caller's PAGE; on
+     * an internal fetch that serves that page (a relation's children, a filter's
+     * key set) it would cap the whole page's children, or the key set, at the
+     * page size: a silent wrong answer by another route than the one
+     * {@link pageOf} closes. The SQL batched loader clears it the same way
+     * (`batchedChildOptions` in query/builder.ts).
+     */
+    childOptions;
+    loaderChildOptions() {
+        this.childOptions ??= { ...this.options, defaultLimit: undefined, warnOnUnlimited: false };
+        return this.childOptions;
+    }
+    /**
+     * ONE parent's window of its stitched children: the relation's `offset` and
+     * `limit` applied to that parent's own list.
+     *
+     * A relation `limit` means "at most N on EACH parent". The loaders used to
+     * spread it onto the flat child fetch (`post filter .author_id in (...)
+     * limit 5`), which caps the TOTAL across every parent in the chunk, so ten
+     * parents shared five posts and most got none, with no error. It shipped
+     * for the loaders' whole life because the one test of the shape compared
+     * the join path against the loader path and both were wrong the same way;
+     * the cross-engine benchmark found it, where the wrong answer was the fast
+     * one. Every loader now fetches its children unbounded, WITH the relation
+     * `orderBy` (which decides which rows the window keeps), and applies this
+     * at stitch time: the rule the SQL engines' batched loader has always used.
+     */
+    static pageOf(rows, limit, offset) {
+        if (limit === undefined && !offset)
+            return rows;
+        const start = offset ?? 0;
+        return rows.slice(start, limit === undefined ? undefined : start + limit);
+    }
     /**
      * Reject a negative `limit` / `offset` before it reaches the engine. PowDB
      * casts both with `as usize` at execution, so below engine 0.20 a negative
@@ -938,7 +974,7 @@ export class PowqlInterface {
         const childCol = rel.type === 'belongsTo' ? rk[0] : fk[0];
         const localField = this.meta.reverseColumnMap[localCol] ?? localCol;
         const childField = targetMeta.reverseColumnMap[childCol] ?? childCol;
-        const targetQi = new PowqlInterface(this.pool, rel.to, this.schema, [], this.options);
+        const targetQi = new PowqlInterface(this.pool, rel.to, this.schema, [], this.loaderChildOptions());
         const collect = async (w) => {
             const rows = await targetQi.findMany({
                 where: w,
@@ -977,7 +1013,7 @@ export class PowqlInterface {
         const sourceRefField = this.meta.reverseColumnMap[sourceRefCol] ?? sourceRefCol;
         const sourceRefColMeta = this.meta.columns.find((c) => c.name === sourceRefCol);
         const targetPkField = targetMeta.reverseColumnMap[targetPkCol] ?? targetPkCol;
-        const targetQi = new PowqlInterface(this.pool, rel.to, this.schema, [], this.options);
+        const targetQi = new PowqlInterface(this.pool, rel.to, this.schema, [], this.loaderChildOptions());
         const collectTargetPks = async (w) => {
             const rows = await targetQi.findMany({
                 where: w,
@@ -1689,7 +1725,7 @@ export class PowqlInterface {
             const rel = this.meta.relations[relName];
             if (!rel)
                 throw new ValidationError(`Unknown relation "${relName}" on "${this.table}".`);
-            if (strategyIsJoin && parent && this.joinEligible(rel, opt, parent.args, parents.length)) {
+            if (strategyIsJoin && parent && this.joinEligible(rel, opt, parent.args)) {
                 if (this.capabilities.serverJoins) {
                     await this.loadRelationViaJoin(parents, rel, relName, opt, parent, timeout, includePii);
                     continue;
@@ -1712,7 +1748,19 @@ export class PowqlInterface {
                 throw new UnsupportedFeatureError('composite-key nested reads', 'PowDB', `relation "${relName}"`);
             }
             const options = (opt === true ? {} : opt);
-            const targetQi = new PowqlInterface(this.pool, rel.to, this.schema, [], this.options);
+            // The relation's own page, applied PER PARENT at stitch time (see pageOf),
+            // never on the flat fetch below.
+            const relLimit = options.limit;
+            const relOffset = options.offset;
+            this.assertPagination(relLimit, relOffset, `relation "${relName}"`);
+            const single = rel.type === 'belongsTo' || rel.type === 'hasOne';
+            if (relLimit === 0) {
+                // `[]` on every parent by construction: nothing to fetch.
+                for (const parent of parents)
+                    parent[relName] = single ? null : [];
+                continue;
+            }
+            const targetQi = new PowqlInterface(this.pool, rel.to, this.schema, [], this.loaderChildOptions());
             const targetMeta = this.schema.tables[rel.to];
             // Local key on the parent, remote key on the target child.
             const parentKeyCol = rel.type === 'belongsTo' ? fk[0] : rk[0];
@@ -1770,6 +1818,9 @@ export class PowqlInterface {
                 };
                 const children = (await targetQi.findMany({
                     ...fetchOptions,
+                    // Unbounded: the relation limit/offset are per parent, applied below.
+                    limit: undefined,
+                    offset: undefined,
                     where: childWhere,
                     with: options.with,
                     timeout: options.timeout ?? timeout,
@@ -1796,11 +1847,12 @@ export class PowqlInterface {
                         delete child[childKeyField];
                 }
             }
-            const single = rel.type === 'belongsTo' || rel.type === 'hasOne';
             for (const parent of parents) {
                 const k = this.joinKey(parent[parentKeyField]);
                 const matches = (k == null ? undefined : childByKey.get(k)) ?? [];
-                parent[relName] = single ? (matches[0] ?? null) : matches;
+                parent[relName] = single
+                    ? (matches[0] ?? null)
+                    : PowqlInterface.pageOf(matches, relLimit, relOffset);
             }
         }
     }
@@ -1866,7 +1918,13 @@ export class PowqlInterface {
         }
         // (2) Target rows by PK, honouring the relation's own where/with/select/…
         const options = (opt === true ? {} : opt);
-        const targetQi = new PowqlInterface(this.pool, rel.to, this.schema, [], this.options);
+        this.assertPagination(options.limit, options.offset, `relation "${relName}"`);
+        if (options.limit === 0) {
+            for (const parent of parents)
+                parent[relName] = [];
+            return;
+        }
+        const targetQi = new PowqlInterface(this.pool, rel.to, this.schema, [], this.loaderChildOptions());
         // This loader stitches on the TARGET's own primary key, so the PK has to be
         // in the fetch even when the caller's select/omit excludes it, and has to
         // come back off afterwards. Exactly the shape `loadRelation` uses for its
@@ -1903,6 +1961,11 @@ export class PowqlInterface {
             }
         }
         const targetByPk = new Map();
+        // Position of each target in the fetch, i.e. its rank under the relation's
+        // `orderBy`; the stitch below sorts a parent's children by it when an
+        // orderBy was given, so `limit` keeps that parent's top-N and not its first
+        // N junction rows. Across fetch CHUNKS the rank is fetch order.
+        const targetRank = new Map();
         const targetValList = [...allTargetVals].map((v) => targetPkColMeta ? coerceScalar(v, targetPkColMeta.tsType) : v);
         const targetChunk = this.keyChunkSize(targetMeta, targetPkCol);
         for (let i = 0; i < targetValList.length; i += targetChunk) {
@@ -1913,14 +1976,21 @@ export class PowqlInterface {
             };
             const targets = (await targetQi.findMany({
                 ...fetchOptions,
+                // Unbounded: the relation limit/offset are per parent, applied in the stitch.
+                limit: undefined,
+                offset: undefined,
                 where,
                 with: options.with,
                 timeout: options.timeout ?? timeout,
                 // Public findMany, so the sentinel form. See loadRelation above.
                 includePii: includePii ? UNSAFE : undefined,
             }));
-            for (const t of targets)
-                targetByPk.set(String(t[targetPkField]), t);
+            for (const t of targets) {
+                const pk = String(t[targetPkField]);
+                targetByPk.set(pk, t);
+                if (!targetRank.has(pk))
+                    targetRank.set(pk, targetRank.size);
+            }
         }
         // (3) Stitch: each parent → its junction targets (m2m is always a list).
         for (const parent of parents) {
@@ -1932,7 +2002,11 @@ export class PowqlInterface {
                 if (child)
                     children.push(child);
             }
-            parent[relName] = children;
+            if (options.orderBy) {
+                const rank = (t) => targetRank.get(String(t[targetPkField])) ?? 0;
+                children.sort((a, b) => rank(a) - rank(b));
+            }
+            parent[relName] = PowqlInterface.pageOf(children, options.limit, options.offset);
         }
         // Stitching is done: take the forced PK back off. Iterating the map rather
         // than the stitched lists is deliberate, one target can be linked from many
@@ -1976,11 +2050,12 @@ export class PowqlInterface {
      *     `referenceKey` on the TARGET table (the join's non-fetched side);
      *   - m2m keeps any `orderBy`/`limit`/`offset` on the loader (the junction-order
      *     stitch can't be reproduced by the 3-table join deterministically);
-     *   - a to-one relation `limit`/`offset` (meaningless) stays on the loader, as
-     *     does a to-many relation `limit`/`offset` when the parent set spills past
-     *     one loader chunk (the loader limits per chunk, the join once globally).
+     *   - a to-one relation `limit`/`offset` (meaningless) stays on the loader. A
+     *     to-many relation `limit`/`offset` is a PER-PARENT bound on both paths,
+     *     fetched unbounded and sliced per parent at stitch time (`pageOf`), so
+     *     the join statement carries neither clause.
      */
-    joinEligible(rel, opt, args, parentCount) {
+    joinEligible(rel, opt, args) {
         const effLimit = args.limit ?? this.defaultLimit;
         if (effLimit !== undefined || args.offset)
             return false;
@@ -2021,9 +2096,8 @@ export class PowqlInterface {
             return false;
         }
         const single = rel.type === 'belongsTo' || rel.type === 'hasOne';
-        if ((options.limit !== undefined || options.offset) && (single || parentCount > MAX_RELATION_KEYS)) {
+        if ((options.limit !== undefined || options.offset) && single)
             return false;
-        }
         // A `limit 0` relation stays off the join statement for the same reason it
         // stays off a nested projection: PowDB answered `limit 0` with one row below
         // engine 0.20. The loader resolves it client-side, correctly on every version.
@@ -2070,13 +2144,13 @@ export class PowqlInterface {
         const { cols: childCols, forcedPk: childForcedPk } = this.joinChildCols(targetQi, options, includePii);
         const filter = await this.joinFilter(targetQi, parent.resolvedWhere, options.where, 'c', params, options.timeout ?? timeout);
         const order = targetQi.buildOrder(options.orderBy, params, 'c');
+        // No limit/offset clause: on the join they would bound the TOTAL child
+        // count across every parent. The relation's page is per parent (pageOf).
         this.assertPagination(options.limit, options.offset, `relation "${relName}"`);
-        const limitClause = options.limit !== undefined ? ` limit ${this.param(options.limit, params)}` : '';
-        const offsetClause = options.offset ? ` offset ${this.param(options.offset, params)}` : '';
         const proj = this.joinProjection(childCols, `p.${quotePowqlIdent(parentKeyCol)}`, 'c');
         const powql = `${targetQi.qt} as c join ${this.qt} as p ` +
             `on c.${quotePowqlIdent(childKeyCol)} = p.${quotePowqlIdent(parentKeyCol)}` +
-            `${filter}${order}${limitClause}${offsetClause} ${proj}`;
+            `${filter}${order} ${proj}`;
         // A READ: thread a read-shaped action through the exec seam.
         const { rows, native } = await targetQi.exec(powql, params, timeout, 'findMany');
         const single = rel.type === 'belongsTo' || rel.type === 'hasOne';
@@ -2084,7 +2158,9 @@ export class PowqlInterface {
         for (const p of parents) {
             const key = this.joinKey(p[parentKeyField]);
             const matches = (key == null ? undefined : byKey.get(key)) ?? [];
-            p[relName] = single ? (matches[0] ?? null) : matches;
+            p[relName] = single
+                ? (matches[0] ?? null)
+                : PowqlInterface.pageOf(matches, options.limit, options.offset);
         }
     }
     /**

package/dist/prisma-compat.d.ts

@@ -174,7 +174,7 @@ export interface CompatTransactionClient {
      * breaks atomicity. Optional only so a test stub can omit it: when it is
      * absent the raw methods throw instead of escaping the transaction.
      */
-    rawQuery?(text: string, params?: readonly unknown[]): Promise<{
+    rawQuery?(text: string, params?: readonly unknown[], action?: string): Promise<{
         rows: unknown[];
         rowCount: number | null;
     }>;

package/dist/prisma-compat.js

@@ -2067,17 +2067,17 @@ function makeRawSurface(exec, ph) {
     return {
         $queryRaw: async (strings, ...values) => {
             const { text, params } = flattenTemplate(strings, values, ph);
-            return (await exec(text, params)).rows;
+            return (await exec(text, params, '$queryRaw')).rows;
         },
         $queryRawUnsafe: async (sql, ...params) => {
-            return (await exec(sql, params)).rows;
+            return (await exec(sql, params, '$queryRawUnsafe')).rows;
         },
         $executeRaw: async (strings, ...values) => {
             const { text, params } = flattenTemplate(strings, values, ph);
-            return (await exec(text, params)).rowCount ?? 0;
+            return (await exec(text, params, '$executeRaw')).rowCount ?? 0;
         },
         $executeRawUnsafe: async (sql, ...params) => {
-            return (await exec(sql, params)).rowCount ?? 0;
+            return (await exec(sql, params, '$executeRawUnsafe')).rowCount ?? 0;
         },
     };
 }
@@ -2334,8 +2334,12 @@ export function createPrismaCompatClient(client, map, options = {}) {
         baseDelegates.set(prismaModel, makeDelegate(ctx, mm, () => db.table(mm.table), (fn) => db.$transaction((tx) => fn((n) => tx.table(n)))));
     }
     const ph = placeholderOf(db);
-    const runRaw = async (text, params) => {
+    // Prefer the client's own raw seam, which emits a `$on('query')` event; a
+    // client without one (an older core, a test stub) runs on the pool as before.
+    const runRaw = async (text, params, action) => {
         try {
+            if (typeof db.rawQuery === 'function')
+                return await db.rawQuery(text, params, action);
             return await poolOf(db).query(text, params);
         }
         catch (err) {
@@ -2350,14 +2354,14 @@ export function createPrismaCompatClient(client, map, options = {}) {
      * `wrapPgError` is idempotent (it returns an already-typed TurbineError
      * untouched), so the error shape matches the pool path exactly.
      */
-    const txRunRaw = (tx) => async (text, params) => {
+    const txRunRaw = (tx) => async (text, params, action) => {
         if (typeof tx.rawQuery !== 'function') {
             throw decorate(new ValidationError('prisma-compat: raw SQL inside $transaction needs a transaction client that can execute it ' +
                 '(core TransactionClient.rawQuery). Refusing to run the statement on a pool connection, which would ' +
                 'silently place it outside the transaction.'), ctx.options.prismaErrorCodes);
         }
         try {
-            return await tx.rawQuery(text, params);
+            return await tx.rawQuery(text, params, action);
         }
         catch (err) {
             throw decorate(wrapPgError(err), ctx.options.prismaErrorCodes);

package/dist/query/deferred.d.ts

@@ -93,6 +93,21 @@ export interface QueryEvent {
      * observability can see exactly which queries the auto default re-planned.
      */
     strategy?: 'auto-batched';
+    /**
+     * The label of the innermost `db.$tag(label, fn)` scope the query ran in.
+     * Absent outside any scope. Lets a listener attribute a query to the feature
+     * or code path that issued it, which `model` + `action` cannot.
+     */
+    tag?: string;
+    /**
+     * Set on statements that ran as part of a batch rather than on their own:
+     * `'pipeline'` for `db.pipeline(...)`, `'transaction'` for the array form
+     * `$transaction([...])`. A pipeline sends every statement in one round trip,
+     * so its per-statement `duration` is the batch's wall time divided evenly
+     * across the statements (the sum is exact, the split is not). Transaction
+     * batch statements are timed individually. Absent for everything else.
+     */
+    batch?: 'pipeline' | 'transaction';
 }
 export type QueryEventListener = (event: QueryEvent) => void;
 /** Options passed from TurbineClient to QueryInterface */