turbine-orm 0.78.0-next.b792a6a → 0.79.0-next.c53fa34

package/dist/cjs/client.d.ts

@@ -648,9 +648,11 @@ export declare 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'`).
      */
-    rawQuery<T extends object = Record<string, unknown>>(text: string, params?: readonly unknown[]): Promise<{
+    rawQuery<T extends object = Record<string, unknown>>(text: string, params?: readonly unknown[], action?: string): Promise<{
         rows: T[];
         rowCount: number | null;
     }>;
@@ -986,6 +988,16 @@ export declare class TurbineClient {
      * On HTTP-based drivers it falls back to sequential execution.
      */
     pipeline<T extends readonly DeferredQuery<unknown>[]>(...args: T | [T, PipelineOptions?]): Promise<PipelineResults<T>>;
+    /**
+     * {@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'`.
+     */
+    private reportedPipeline;
     /**
      * Check whether the underlying pool supports the real pipeline protocol.
      * Returns `true` for standard pg.Pool TCP connections, `false` for HTTP
@@ -1005,6 +1017,39 @@ export declare class TurbineClient {
      * ```
      */
     raw<T extends Record<string, unknown> = Record<string, unknown>>(strings: TemplateStringsArray, ...values: unknown[]): Promise<T[]>;
+    /**
+     * @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}.
+     */
+    rawQuery<T extends object = Record<string, unknown>>(text: string, params?: readonly unknown[], action?: string): Promise<{
+        rows: T[];
+        rowCount: number | null;
+    }>;
+    /**
+     * 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<R>(tag: string, fn: () => R): R;
     /**
      * Execute a **typed** raw SQL query, Turbine's answer to Prisma's TypedSQL.
      *

package/dist/cjs/client.js

@@ -37,6 +37,7 @@ const pipeline_js_1 = require("./pipeline.js");
 const index_js_1 = require("./query/index.js");
 const utils_js_1 = require("./query/utils.js");
 const warn_registry_js_1 = require("./query/warn-registry.js");
+const query_events_js_1 = require("./query-events.js");
 const realtime_js_1 = require("./realtime.js");
 const typed_sql_js_1 = require("./typed-sql.js");
 async function withRetry(fn, options) {
@@ -538,13 +539,8 @@ class TransactionClient {
                 sql += this.dialect.paramPlaceholder(i + 1);
             }
         });
-        try {
-            const result = await this.client.query(sql, values);
-            return result.rows;
-        }
-        catch (err) {
-            throw (0, errors_js_1.wrapPgError)(err);
-        }
+        const result = await (0, query_events_js_1.runReportedStatement)(this.queryOptions?._onQuery, (0, query_events_js_1.rawIdentity)('raw'), sql, values, () => this.client.query(sql, values), errors_js_1.wrapPgError);
+        return result.rows;
     }
     /**
      * @internal The `turbine-orm/prisma-compat` adapter's transaction seam. NOT
@@ -568,16 +564,13 @@ 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 (0, errors_js_1.wrapPgError)(err);
-        }
+    async rawQuery(text, params = [], action = 'rawQuery') {
+        const result = await (0, query_events_js_1.runReportedStatement)(this.queryOptions?._onQuery, (0, query_events_js_1.rawIdentity)(action), text, params, () => this.client.query(text, params), errors_js_1.wrapPgError);
+        return { rows: result.rows, rowCount: result.rowCount };
     }
     /**
      * Create a pool-like wrapper around the transaction client.
@@ -908,7 +901,11 @@ 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 ?? (0, query_events_js_1.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);
@@ -1520,7 +1517,63 @@ 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(() => (0, pipeline_js_1.executePipeline)(this.pool, queries, options));
+        const sink = this.queryListeners.size > 0 ? this.queryOptions._onQuery : undefined;
+        if (!sink)
+            return this.withErrorMode(() => (0, pipeline_js_1.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] = (0, query_events_js_1.resultRowCount)(raw);
+                return q.transform(raw);
+            },
+        }));
+        const start = performance.now();
+        let failure;
+        try {
+            return await (0, pipeline_js_1.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 errors_js_1.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) {
+                    (0, query_events_js_1.emitStatementEvent)(sink, {
+                        sql: q.sql,
+                        params: q.params,
+                        duration,
+                        ...(0, query_events_js_1.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.
@@ -1556,13 +1609,43 @@ 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(() => (0, errors_js_1.wrapPgError)(err));
-        }
+        const result = await (0, query_events_js_1.runReportedStatement)(this.queryOptions._onQuery, (0, query_events_js_1.rawIdentity)('raw'), sql, values, () => this.pool.query(sql, values), (err) => this.withErrorMode(() => (0, errors_js_1.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 (0, query_events_js_1.runReportedStatement)(this.queryOptions._onQuery, (0, query_events_js_1.rawIdentity)(action), text, params, () => this.pool.query(text, params), (err) => this.withErrorMode(() => (0, errors_js_1.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 (0, query_events_js_1.runWithQueryTag)(tag, fn);
     }
     /**
      * Execute a **typed** raw SQL query, Turbine's answer to Prisma's TypedSQL.
@@ -1602,7 +1685,7 @@ 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 typed_sql_js_1.TypedSqlQuery(this.pool, sql, params, this.logging, (fn) => this.withErrorMode(fn));
+        return new typed_sql_js_1.TypedSqlQuery(this.pool, sql, params, this.logging, (fn) => this.withErrorMode(fn), this.queryOptions._onQuery);
     }
     // -------------------------------------------------------------------------
     // Transaction support (raw, legacy)
@@ -1842,13 +1925,18 @@ 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) => (0, query_events_js_1.runReportedStatement)(sink, { ...(0, query_events_js_1.deferredIdentity)(dq.tag), batch: 'transaction' }, dq.sql, dq.params, run, errors_js_1.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];
@@ -1861,19 +1949,12 @@ 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 (0, errors_js_1.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/cjs/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/cjs/index.js

@@ -35,7 +35,7 @@
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.QueryInterface = exports.AUTO_TO_ONE_JOIN_ROWS_MIN = exports.AUTO_TO_ONE_JOIN_ROWS_MAX = exports.AUTO_TO_ONE_JOIN_MAX_ROWS = exports.AUTO_JOIN_PENALTY_MS_PER_ROW = exports.AUTO_COUNT_BATCH_MIN_PARENT_ROWS = exports.AUTO_ASSUMED_ROUND_TRIP_MS = exports.fingerprintPrismaSchema = exports.pipelineSupported = exports.executePipeline = exports.PgMetricsSink = exports.HttpJsonSink = exports.hasRelationFields = exports.executeNestedUpdate = exports.executeNestedCreate = exports.introspect = exports.generate = exports.wrapPgError = exports.ValidationError = exports.UnsupportedFeatureError = exports.UniqueConstraintError = exports.TurbineErrorCode = exports.TurbineError = exports.TimeoutError = exports.setErrorMessageMode = exports.SerializationFailureError = exports.RelationError = exports.ReadOnlyError = exports.REDACTED_DETAIL = exports.PipelineError = exports.OptimisticLockError = exports.NotNullViolationError = exports.NotFoundError = exports.MigrationError = exports.getErrorMessageMode = exports.ForeignKeyError = exports.ExclusionConstraintError = exports.DeadlockError = exports.ConnectionError = exports.CircularRelationError = exports.CheckConstraintError = exports.postgresDialect = exports.withRetry = exports.TurbineClient = exports.TransactionClient = exports.yugabytedb = exports.timescale = exports.postgresql = exports.cockroachdb = exports.alloydb = void 0;
-exports.TypedSqlQuery = exports.buildTypedSql = exports.turbineHttp = exports.defineSeed = exports.schemaToSQLString = exports.schemaToSQL = exports.schemaPush = exports.schemaDiff = exports.DestructivePushRefusal = exports.schemaDefToMetadata = exports.table = exports.isDocFieldIndexDef = exports.defineSchema = exports.column = exports.ColumnBuilder = exports.applyManyToManyRelations = exports.withDbFieldNames = exports.snakeToPascal = exports.snakeToCamel = exports.singularize = exports.pgTypeToTs = exports.pgArrayType = exports.normalizeKeyColumns = exports.isDateType = exports.camelToSnake = exports.validateChannel = exports.UNSAFE = void 0;
+exports.TypedSqlQuery = exports.buildTypedSql = exports.turbineHttp = exports.defineSeed = exports.schemaToSQLString = exports.schemaToSQL = exports.schemaPush = exports.schemaDiff = exports.DestructivePushRefusal = exports.schemaDefToMetadata = exports.table = exports.isDocFieldIndexDef = exports.defineSchema = exports.column = exports.ColumnBuilder = exports.applyManyToManyRelations = exports.withDbFieldNames = exports.snakeToPascal = exports.snakeToCamel = exports.singularize = exports.pgTypeToTs = exports.pgArrayType = exports.normalizeKeyColumns = exports.isDateType = exports.camelToSnake = exports.validateChannel = exports.RAW_QUERY_MODEL = exports.MAX_QUERY_TAG_LENGTH = exports.UNSAFE = void 0;
 var index_js_1 = require("./adapters/index.js");
 Object.defineProperty(exports, "alloydb", { enumerable: true, get: function () { return index_js_1.alloydb; } });
 Object.defineProperty(exports, "cockroachdb", { enumerable: true, get: function () { return index_js_1.cockroachdb; } });
@@ -110,6 +110,10 @@ Object.defineProperty(exports, "AUTO_TO_ONE_JOIN_ROWS_MAX", { enumerable: true,
 Object.defineProperty(exports, "AUTO_TO_ONE_JOIN_ROWS_MIN", { enumerable: true, get: function () { return index_js_2.AUTO_TO_ONE_JOIN_ROWS_MIN; } });
 Object.defineProperty(exports, "QueryInterface", { enumerable: true, get: function () { return index_js_2.QueryInterface; } });
 Object.defineProperty(exports, "UNSAFE", { enumerable: true, get: function () { return index_js_2.UNSAFE; } });
+// $on('query') event metadata: raw-statement model name, $tag() label limit
+var query_events_js_1 = require("./query-events.js");
+Object.defineProperty(exports, "MAX_QUERY_TAG_LENGTH", { enumerable: true, get: function () { return query_events_js_1.MAX_QUERY_TAG_LENGTH; } });
+Object.defineProperty(exports, "RAW_QUERY_MODEL", { enumerable: true, get: function () { return query_events_js_1.RAW_QUERY_MODEL; } });
 // Realtime, LISTEN/NOTIFY pub/sub
 var realtime_js_1 = require("./realtime.js");
 Object.defineProperty(exports, "validateChannel", { enumerable: true, get: function () { return realtime_js_1.validateChannel; } });

package/dist/cjs/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/cjs/prisma-compat.js

@@ -2104,17 +2104,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;
         },
     };
 }
@@ -2371,8 +2371,12 @@ 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) {
@@ -2387,14 +2391,14 @@ 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 errors_js_1.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((0, errors_js_1.wrapPgError)(err), ctx.options.prismaErrorCodes);

package/dist/cjs/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 */

package/dist/cjs/query-events.d.ts

@@ -0,0 +1,82 @@
+/**
+ * turbine-orm, `$on('query')` event metadata: the raw-statement model name
+ * and per-scope query tags for attribution.
+ *
+ * A tag is a caller-chosen label (`'checkout'`, `'nightly-report'`) that rides
+ * on every {@link QueryEvent} emitted while a `db.$tag(label, fn)` callback is
+ * running, including queries issued from inside awaited helpers, transactions
+ * and pipelines. It exists so telemetry can answer "which feature issued this
+ * query", which model + action alone cannot: `orders.findMany` is called from
+ * a dozen places.
+ *
+ * The tag is scoped by async context rather than threaded through every query
+ * argument type. A per-query option would have to be added to every args type,
+ * the runtime option surface, and the prisma-compat unknown-option check, and
+ * it would still miss raw SQL and pipelines. A scope reaches every emitter with
+ * one read at the single emit seam in client.ts, and it costs nothing when no
+ * `$on('query')` listener is registered, because the store is only read on the
+ * emit path.
+ *
+ * ONE scope per realm. The store hangs off `globalThis` under a
+ * `Symbol.for(...)` key for the same reason the warn-once registry does: the
+ * package ships ESM and CJS, and a mixed graph loading both copies must still
+ * see the tag a caller set through either copy.
+ *
+ * The tag never reaches SQL. It is metadata on the in-process event only; what
+ * a listener does with it (log it, forward it to a collector) is the
+ * listener's business.
+ */
+import type { QueryEvent } from './query/deferred.js';
+/**
+ * The `model` reported for statements that are not tied to one table: `raw`,
+ * `sql`, the transaction-scoped `raw` / `rawQuery`, and prisma-compat's
+ * `$queryRaw` / `$executeRaw` family. `action` names the entry point that ran
+ * it. The `$` prefix cannot collide with a generated table accessor.
+ */
+export declare const RAW_QUERY_MODEL = "$raw";
+/** Longest tag accepted. Keeps a tag a label, not a payload. */
+export declare const MAX_QUERY_TAG_LENGTH = 128;
+/** The tag in force for the code currently running, or `undefined`. */
+export declare function currentQueryTag(): string | undefined;
+/**
+ * Run `fn` with `tag` attached to every query event it causes. An inner scope
+ * replaces an outer one for its own duration. Throws {@link ValidationError}
+ * (E003) for a tag that is not a non-empty string of at most
+ * {@link MAX_QUERY_TAG_LENGTH} characters, before `fn` runs.
+ */
+export declare function runWithQueryTag<R>(tag: string, fn: () => R): R;
+/** A client's event sink, as QueryInterfaceOptions carries it. */
+type QueryEventSink = ((event: QueryEvent) => void) | undefined;
+/** Rows a driver result reports: the affected count, else the returned rows. */
+export declare function resultRowCount(result: {
+    rowCount?: number | null;
+    rows?: unknown[];
+} | undefined): number;
+/**
+ * Emit one query event for a statement that ran outside a QueryInterface (raw
+ * SQL, a pipeline slot, a transaction-batch slot). Never throws: a listener
+ * problem must not turn a successful statement into a failed one.
+ */
+export declare function emitStatementEvent(sink: QueryEventSink, event: Omit<QueryEvent, 'timestamp'>): void;
+/**
+ * Split a DeferredQuery tag (`'<table>.<action>'`) into the event's model and
+ * action. A tag without one is reported as a raw statement.
+ */
+export declare function deferredIdentity(tag: string): {
+    model: string;
+    action: string;
+};
+/**
+ * Run one statement and report it. `identity` is the event's model and action
+ * (plus `batch` for a batch slot); for raw SQL the model is
+ * {@link RAW_QUERY_MODEL} and the action names the entry point (`'raw'`,
+ * `'sql'`, `'rawQuery'`, `'$queryRaw'` ...). `wrap` turns a driver error into
+ * what the caller sees, and the event carries that same error.
+ */
+export declare function runReportedStatement<R extends {
+    rowCount?: number | null;
+    rows?: unknown[];
+}>(sink: QueryEventSink, identity: Pick<QueryEvent, 'model' | 'action' | 'batch'>, sql: string, params: unknown[], run: () => Promise<R>, wrap: (err: unknown) => unknown): Promise<R>;
+/** The identity of a raw statement run through `action`. */
+export declare const rawIdentity: (action: string) => Pick<QueryEvent, "model" | "action">;
+export {};

package/dist/cjs/query-events.js

@@ -0,0 +1,137 @@
+"use strict";
+/**
+ * turbine-orm, `$on('query')` event metadata: the raw-statement model name
+ * and per-scope query tags for attribution.
+ *
+ * A tag is a caller-chosen label (`'checkout'`, `'nightly-report'`) that rides
+ * on every {@link QueryEvent} emitted while a `db.$tag(label, fn)` callback is
+ * running, including queries issued from inside awaited helpers, transactions
+ * and pipelines. It exists so telemetry can answer "which feature issued this
+ * query", which model + action alone cannot: `orders.findMany` is called from
+ * a dozen places.
+ *
+ * The tag is scoped by async context rather than threaded through every query
+ * argument type. A per-query option would have to be added to every args type,
+ * the runtime option surface, and the prisma-compat unknown-option check, and
+ * it would still miss raw SQL and pipelines. A scope reaches every emitter with
+ * one read at the single emit seam in client.ts, and it costs nothing when no
+ * `$on('query')` listener is registered, because the store is only read on the
+ * emit path.
+ *
+ * ONE scope per realm. The store hangs off `globalThis` under a
+ * `Symbol.for(...)` key for the same reason the warn-once registry does: the
+ * package ships ESM and CJS, and a mixed graph loading both copies must still
+ * see the tag a caller set through either copy.
+ *
+ * The tag never reaches SQL. It is metadata on the in-process event only; what
+ * a listener does with it (log it, forward it to a collector) is the
+ * listener's business.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.rawIdentity = exports.MAX_QUERY_TAG_LENGTH = exports.RAW_QUERY_MODEL = void 0;
+exports.currentQueryTag = currentQueryTag;
+exports.runWithQueryTag = runWithQueryTag;
+exports.resultRowCount = resultRowCount;
+exports.emitStatementEvent = emitStatementEvent;
+exports.deferredIdentity = deferredIdentity;
+exports.runReportedStatement = runReportedStatement;
+const node_async_hooks_1 = require("node:async_hooks");
+const errors_js_1 = require("./errors.js");
+/**
+ * The `model` reported for statements that are not tied to one table: `raw`,
+ * `sql`, the transaction-scoped `raw` / `rawQuery`, and prisma-compat's
+ * `$queryRaw` / `$executeRaw` family. `action` names the entry point that ran
+ * it. The `$` prefix cannot collide with a generated table accessor.
+ */
+exports.RAW_QUERY_MODEL = '$raw';
+/** Longest tag accepted. Keeps a tag a label, not a payload. */
+exports.MAX_QUERY_TAG_LENGTH = 128;
+const SCOPE_KEY = Symbol.for('turbine.queryTag.scope');
+function scope() {
+    const g = globalThis;
+    let store = g[SCOPE_KEY];
+    if (!store) {
+        store = new node_async_hooks_1.AsyncLocalStorage();
+        g[SCOPE_KEY] = store;
+    }
+    return store;
+}
+/** The tag in force for the code currently running, or `undefined`. */
+function currentQueryTag() {
+    return scope().getStore();
+}
+/**
+ * Run `fn` with `tag` attached to every query event it causes. An inner scope
+ * replaces an outer one for its own duration. Throws {@link ValidationError}
+ * (E003) for a tag that is not a non-empty string of at most
+ * {@link MAX_QUERY_TAG_LENGTH} characters, before `fn` runs.
+ */
+function runWithQueryTag(tag, fn) {
+    if (typeof tag !== 'string' || !tag.trim() || tag.length > exports.MAX_QUERY_TAG_LENGTH) {
+        throw new errors_js_1.ValidationError(`$tag() needs a label of 1-${exports.MAX_QUERY_TAG_LENGTH} characters.`);
+    }
+    return scope().run(tag, fn);
+}
+/** Rows a driver result reports: the affected count, else the returned rows. */
+function resultRowCount(result) {
+    return typeof result?.rowCount === 'number' ? result.rowCount : (result?.rows?.length ?? 0);
+}
+/**
+ * Emit one query event for a statement that ran outside a QueryInterface (raw
+ * SQL, a pipeline slot, a transaction-batch slot). Never throws: a listener
+ * problem must not turn a successful statement into a failed one.
+ */
+function emitStatementEvent(sink, event) {
+    try {
+        sink?.({ ...event, timestamp: new Date() });
+    }
+    catch {
+        // Listener errors must never crash a query.
+    }
+}
+/**
+ * Split a DeferredQuery tag (`'<table>.<action>'`) into the event's model and
+ * action. A tag without one is reported as a raw statement.
+ */
+function deferredIdentity(tag) {
+    const at = tag.lastIndexOf('.');
+    return at > 0 ? { model: tag.slice(0, at), action: tag.slice(at + 1) } : { model: exports.RAW_QUERY_MODEL, action: tag };
+}
+/**
+ * Run one statement and report it. `identity` is the event's model and action
+ * (plus `batch` for a batch slot); for raw SQL the model is
+ * {@link RAW_QUERY_MODEL} and the action names the entry point (`'raw'`,
+ * `'sql'`, `'rawQuery'`, `'$queryRaw'` ...). `wrap` turns a driver error into
+ * what the caller sees, and the event carries that same error.
+ */
+async function runReportedStatement(sink, identity, sql, params, run, wrap) {
+    const start = performance.now();
+    let result;
+    let error;
+    try {
+        result = await run();
+        return result;
+    }
+    catch (err) {
+        error = wrap(err);
+        throw error;
+    }
+    finally {
+        if (sink) {
+            emitStatementEvent(sink, {
+                ...identity,
+                sql,
+                params,
+                duration: performance.now() - start,
+                rows: resultRowCount(result),
+                ...(error === undefined ? {} : { error: error instanceof Error ? error : new Error(String(error)) }),
+            });
+        }
+    }
+}
+/** The identity of a raw statement run through `action`. */
+const rawIdentity = (action) => ({
+    model: exports.RAW_QUERY_MODEL,
+    action,
+});
+exports.rawIdentity = rawIdentity;