turbine-orm 0.90.2 → 0.91.0-next.32b6789

package/README.md

@@ -21,39 +21,38 @@ Six reasons, each with the mechanism that makes it true:
 1. **One dependency.** `dependencies` is `{ "pg": "^8.15.0" }`. No engine binary, no WASM compiler, no adapter packages in lockstep. The optional engines (SQLite, MySQL, SQL Server, PowDB, all tiered Experimental in [STABILITY.md](STABILITY.md)) are peer dependencies or Node builtins you install only if you use them.
 2. **Written from scratch.** Turbine is not a layer over Knex or a query-builder library. Query compilation is plain string building with an FNV-1a shape fingerprint into a bounded LRU of SQL templates, so there is no plan cache to size and no compiler running on your event loop.
 3. **Nested relations in one statement.** A `with` clause compiles to correlated `json_agg` subqueries, so users with posts with comments is one round trip, typed end to end: `users[0].posts[0].comments[0].author.name` autocompletes with no annotation.
-4. **Close to raw SQL.** In the last published run, Turbine's overhead over a hand-written `pg` control was 1.08x by geometric mean. The table is below; the losses are stated with the wins.
+4. **Faster than Drizzle and Prisma.** In the 0.91.0 run Drizzle took 1.4x as long as Turbine and Prisma 2.0x, by geometric mean, on a dedicated benchmark machine. The table is below; the losses are stated with the wins.
 5. **Agents get a skill and typed tools, not a SQL prompt.** `npx turbine skill` installs a query-writing skill whose every claim is executed against a live database before release; `npx turbine mcp` exposes eleven read-only MCP tools, including a relation graph and a join-path finder that returns the `with` clause to write. Every tool runs inside `BEGIN READ ONLY`, and PII-tagged columns are redacted before rows reach a model.
 6. **The dangerous operations ask first.** Destructive migration statements refuse to run without typed consent. `update`/`delete` with an empty `where` throws. Columns tagged `pii: true` are excluded from the emitted SQL's projections. `turbine doctor` reports missing FK indexes offline, no account, no telemetry.
 
 ## Benchmarks
 
-Measured **2026-08-15 against turbine-orm 0.71.0**, versus **Prisma 7.9.1** (`@prisma/adapter-pg`, `relationJoins` on) and **Drizzle 0.45.2** (relational queries), on local **PostgreSQL 17.9** over a Unix socket, with a hand-written `pg` control arm. Node v24.18.0, Apple Silicon (M5 Max). Same schema, same data (1K users, 10K posts, 50K comments), same pool config. Each figure is the median over 200 rounds with arm order rotated per round, taken as the median of three full runs.
+Measured **2026-10-15 against turbine-orm 0.91.0**, versus **Drizzle 0.45.3** (relational queries) and **Prisma 7.10.0** (`@prisma/adapter-pg`, `relationJoins` on), with a hand-written `pg` control arm. Run by the repository's [`benchmarks.yml`](.github/workflows/benchmarks.yml) workflow on a dedicated machine: AMD Ryzen 9 7950X host, 4-vCPU 16 GB Firecracker VM, client and PostgreSQL 17 (Docker) on the same VM over a Unix socket. PostgreSQL 17.11, Node v24.18.0, `pg` 8.23.1 under every arm. Same schema, same data (1K users, 10K posts, 50K comments), same pool config. Each figure is the median over 200 rounds with arm order rotated per round, taken as the median of 3 full runs.
 
-| Scenario | Turbine 0.71 | Prisma 7.9 | Drizzle 0.45 | raw pg |
+| Scenario | Turbine 0.91.0 | Drizzle 0.45.3 | Prisma 7.10.0 | raw pg |
 |---|---|---|---|---|
-| findMany, 100 users (flat) | **0.181 ms** | 0.241 ms | 0.242 ms | 0.164 ms |
-| findMany, 50 users + posts (L2) *(contested)* | **1.670 ms** | 4.302 ms | 1.711 ms | 1.847 ms |
-| findMany, 10 users → posts → comments (L3) *(contested)* | **1.082 ms** | 4.204 ms | 1.166 ms | n/a |
-| findUnique, single user by PK | **0.035 ms** | 0.078 ms | 0.080 ms | 0.036 ms |
-| findUnique, user + posts + comments (L3) | **0.146 ms** | 0.374 ms | 0.285 ms | n/a |
-| count, all users | **0.038 ms** | 0.070 ms | 0.053 ms | 0.041 ms |
-| stream, iterate 50K rows (batch 1000) | 50.39 ms | 54.81 ms | **39.49 ms** | 42.33 ms |
-| atomic increment, `view_count + 1` *(contested)* | **0.067 ms** | 0.106 ms | 0.073 ms | 0.055 ms |
-| pipeline, 5-query batch | **0.165 ms** | 0.338 ms | 0.341 ms | 0.177 ms |
-| hot findUnique, 500x same shape | **0.026 ms** | 0.059 ms | 0.069 ms | 0.030 ms |
+| findMany, 100 users | **0.204 ms** | 0.307 ms | 0.349 ms | 0.198 ms |
+| findMany, 50 users + posts *(tie)* | 1.470 ms | 1.488 ms | 2.930 ms | 0.791 ms |
+| findMany, 10 users + posts + comments | **0.795 ms** | 0.899 ms | 2.303 ms | n/a |
+| findUnique by primary key | **0.090 ms** | 0.151 ms | 0.179 ms | 0.074 ms |
+| findUnique, user + posts + comments | **0.278 ms** | 0.467 ms | 0.599 ms | n/a |
+| count, all users | **0.080 ms** | 0.115 ms | 0.170 ms | 0.077 ms |
+| stream 50,000 comments, per row *(tie)* | 55.27 ms | 57.33 ms | 85.99 ms | 56.38 ms |
+| atomic increment | **0.175 ms** | 0.185 ms | 0.274 ms | 0.143 ms |
+| pipeline, 5-query batch | **0.333 ms** | 0.707 ms | 0.782 ms | 0.365 ms |
+| hot findUnique, rotating ids | **0.078 ms** | 0.143 ms | 0.159 ms | 0.072 ms |
 
 What that run says:
 
-- **Turbine ran at 1.08x hand-written `pg`**, where Drizzle ran at 1.47x and Prisma at 1.81x (geometric mean over the eight scenarios with a raw control). That 1.08x is the conservative reading: the raw L2 control statement still uses the `json_build_object` encoding Turbine has moved off, which is worth 1.83x on its own, so the figure the harness records unadjusted is 1.00x. The adjusted one is published instead.
-- Across all ten scenarios Turbine was **2.02x faster than Prisma 7.9** and **1.46x faster than Drizzle 0.45** by geometric mean. Turbine took nine scenarios, Drizzle one, Prisma none. The one Drizzle took was streaming, and 0.72.0 takes it back (below).
-- **Streaming was Drizzle's one win, by 22%** (39.49 ms vs 50.39 ms) on 0.71.0. **0.72.0 closes it**: the remaining gap was temporal decoding rather than the cursor, and a direct scan for the canonical ISO wire shape (declining anything else back to `pg`'s own parser) takes `findManyStream` from 52.44 ms to **37.06 ms** against Drizzle's 42.09 ms re-measured in the same rotation, and `findManyStreamBatches` to **31.65 ms**. Scope, because it matters: that is a targeted re-measurement of one scenario on a paired one-process harness, not a re-run of the ten above, so the table's stream row still shows 0.71.0 and the absolute values are not comparable. Method and controls in [`benchmarks/RESULTS-0.72.0.md`](benchmarks/RESULTS-0.72.0.md).
-- **Pipelining is Turbine's clearest win**: one TCP flush for 5 queries runs 2.04x faster than Prisma and 2.07x faster than Drizzle, level with raw `pg`.
-- Three scenarios (L2, L3, atomic increment) are marked *contested*: the contiguous cross-check harness disagrees with itself across runs of the same configuration there, so neither side claims them. Both nested reads were losses in the previous run and the improvement behind them reproduces on both harnesses; whether it is enough to pass Drizzle is what is unsettled.
-- The sub-0.15 ms scenarios carry roughly one third uncertainty in their absolute values. Orderings held across runs; margins should not be quoted, and that includes L2's 2.5%.
+- **Across all ten scenarios Drizzle took 1.40x as long as Turbine and Prisma 2.00x**, by geometric mean. Turbine won or tied every one against Drizzle (2 ties) and won all ten against Prisma.
+- **Against hand-written `pg`, Turbine ran at 1.14x, Drizzle at 1.61x and Prisma at 2.17x** (geometric mean over the 8 scenarios with a control). Where a query returns nested rows, the control decodes them into objects with `Date` timestamps as the ORMs do. The 0.71.0 figure of 1.08x was adjusted by hand against a control that did more work than Turbine; this one is not adjusted.
+- **Pipelining is the clearest win over a network**: five dashboard queries 25 ms from the database take 25 ms as one batch against 171 ms as a transaction.
+- **Where Turbine loses:** deep `OFFSET` pagination unless `forceCustomPlan` is set, and per-row streaming against the Drizzle 1.0 release candidate (`findManyStreamBatches` ties it).
+- Figures under 0.15 ms carry roughly one third uncertainty in their absolute values. Orderings held across runs; those margins should not be quoted.
 
-Full method, the drift-floor measurement, and the harness-disagreement table: [`benchmarks/RESULTS-0.71.0.md`](https://github.com/zvndev/turbine-orm/blob/main/benchmarks/RESULTS-0.71.0.md).
+Full method, the extra scenarios, streaming, latency and the losses: [`benchmarks/RESULTS-0.91.0.md`](https://github.com/zvndev/turbine-orm/blob/main/benchmarks/RESULTS-0.91.0.md), or the charts at [turbineorm.dev/benchmarks](https://turbineorm.dev/benchmarks).
 
-Reproduce it: `cd benchmarks && npm install && npx prisma generate && DATABASE_URL=... npx tsx bench-interleaved.ts`
+Reproduce it on a fresh machine with `gh workflow run benchmarks.yml`, or locally with `benchmarks/run-round.sh` (see [`benchmarks/README.md`](benchmarks/README.md)).
 
 ## Quick Start
 
@@ -272,7 +271,7 @@ Going deep on one database means the parts other ORMs push to raw SQL are typed
 
 ## Serverless and edge
 
-The core is driver-agnostic: hand any pg-compatible pool to `turbineHttp()` and Turbine runs on Vercel Edge, Cloudflare Workers, Deno Deploy, or anywhere else without TCP. The main entry's import graph is held under **146 kB brotli** (edge entry under **114 kB**) with `pg` external, enforced by `size-limit` in CI at those exact numbers; run `npm run size` for the current figure.
+The core is driver-agnostic: hand any pg-compatible pool to `turbineHttp()` and Turbine runs on Vercel Edge, Cloudflare Workers, Deno Deploy, or anywhere else without TCP. The main entry's import graph is held under **148 kB brotli** (edge entry under **116 kB**) with `pg` external, enforced by `size-limit` in CI at those exact numbers; run `npm run size` for the current figure.
 
 ```typescript
 import { Pool } from '@neondatabase/serverless';
@@ -359,11 +358,11 @@ It is also built to be extended rather than wrapped. All SQL generation routes t
 |---|---|---|---|---|---|
 | **Engine / runtime** | No engine binary (`pg` only) | Client + TS/WASM query compiler | No engine | No engine | Kysely as query runner; SQL built by MikroORM (v7) |
 | **Runtime deps** | 1 (`pg`) | `@prisma/client` + required driver adapter | 0 | 0 | `@mikro-orm/core` (0 deps) + a driver package |
-| **Main bundle (brotli)** | under 146 kB import graph (CI-enforced), `pg` external | ~1.6 MB client (TS/WASM compiler) | ~7 KB core | small | |
+| **Main bundle (brotli)** | under 148 kB import graph (CI-enforced), `pg` external | ~1.6 MB client (TS/WASM compiler) | ~7 KB core | small | |
 | **Studio** | Read-only by default | Full CRUD, cloud-hosted | Full CRUD; [Gateway](https://gateway.drizzle.team/) self-hosted, free | None | AdminJS integration guide (CRUD panel) |
 | **Error PII safety** | Keys only by default | Values in messages | Raw pg errors | Raw pg errors | |
 | **Migrations** | SQL-first, SHA-256 checksums | DSL-generated, shadow DB | SQL or Drizzle Kit | None | Generated by diffing entities against a snapshot or the database; TS/JS classes |
-| **Edge runtime** | One import swap, under 114 kB brotli (CI-enforced) | Driver adapter + WASM compiler | Native | Native | Cloudflare Workers and Deno (v7) |
+| **Edge runtime** | One import swap, under 116 kB brotli (CI-enforced) | Driver adapter + WASM compiler | Native | Native | Cloudflare Workers and Deno (v7) |
 | **Pipeline batching** | Parse/Bind/Execute protocol | Sequential in txn | Sequential | Manual | `flush()` runs queued changes in one transaction |
 | **Typed errors** | `isRetryable` discriminant | Error codes only | None | None | `DriverException` subclasses (`UniqueConstraintViolationException`, ...) |
 | **Nested relations** | 1 query, deep type inference | 1 query per relation by default; single-query `relationJoins` is Preview | 1 query, `relations()` re-declaration | Manual (`jsonArrayFrom`) | `populate`; default `balanced`: joins to-one, one query per to-many relation |

package/dist/cjs/dialect.d.ts

@@ -501,6 +501,17 @@ export interface EngineCapabilities {
      * not bound by it.
      */
     readonly maxInsertRows: number;
+    /**
+     * The most bind parameters each statement of a `createMany` that runs as
+     * several statements carries: at most `maxBindParameters`, and lower where
+     * an engine slows faster than linearly with a statement's size. SQLite
+     * finds each named parameter by a linear search, at prepare and at bind, so
+     * 40,000 six-column rows took 141 s in statements of 32,766 parameters and
+     * 1 s in statements of 250. A call whose rows cannot be told apart
+     * across statements, or on a pool with no `connect()`, is not split below
+     * `maxBindParameters` (see `planCreateMany`).
+     */
+    readonly chunkBindParameters: number;
     /**
      * What a single-statement upsert conflicts on. `'explicit'`: the conflict
      * target it names. `'any-unique-key'`: whichever unique key collides first
@@ -531,6 +542,16 @@ export interface EngineCapabilities {
      * it afterwards, so the statement runs in a transaction it can roll back.
      */
     readonly bulkUpsertAppliesRepeatedKeys: boolean;
+    /**
+     * A `skipDuplicates` insert reports a skipped row as affected, so its row
+     * count cannot be the rows it inserted. MySQL: its skip is a no-op
+     * `ON DUPLICATE KEY UPDATE`, which under `CLIENT_FOUND_ROWS` (mysql2's
+     * default) counts a matched row, and a one-row statement's result carries no
+     * `info` to subtract the duplicates from. `createMany` refuses
+     * `skipDuplicates` with `returning: false` here (E017). False on an engine
+     * that never runs a skip.
+     */
+    readonly skipDuplicatesCountsSkipped: boolean;
     /** `$transaction({ readOnly: true })`: `READ ONLY` after the dialect's BEGIN. Else E017. */
     readonly readOnlyTransactions: boolean;
     /**
@@ -817,7 +838,11 @@ export interface Dialect {
     readonly explainQuery?: {
         prefix: string;
     };
-    /** Build a dialect-specific RETURNING clause. Return an empty string when unsupported. */
+    /**
+     * Build a dialect-specific RETURNING clause. Return an empty string when
+     * unsupported, and for an empty column list (a write that returns no column,
+     * `createMany({ returning: false })`).
+     */
     buildReturningClause(selection?: ReturningSelection): string;
     /** Build a single-row INSERT statement. Inputs are SQL-ready quoted fragments. */
     buildInsertStatement(input: InsertStatementInput): string;

package/dist/cjs/dialect.js

@@ -108,12 +108,14 @@ exports.postgresDialect = {
         // Counted in a 16-bit field.
         maxBindParameters: 65535,
         maxInsertRows: Number.POSITIVE_INFINITY,
+        chunkBindParameters: 65535,
         upsertConflictTarget: 'explicit',
         setClauseOrder: 'snapshot',
         reselectLocksRows: false,
         integerDivision: '/',
         updateExpressions: true,
         bulkUpsertAppliesRepeatedKeys: false,
+        skipDuplicatesCountsSkipped: false,
         readOnlyTransactions: true,
         connectionParameters: true,
         backendCancel: true,
@@ -191,6 +193,8 @@ exports.postgresDialect = {
         return `COALESCE((${subquery}), ${fallback})`;
     },
     buildReturningClause(selection = '*') {
+        if (selection !== '*' && selection.length === 0)
+            return '';
         return ` RETURNING ${selection === '*' ? '*' : selection.join(', ')}`;
     },
     buildInsertStatement(input) {

package/dist/cjs/index.d.ts

@@ -47,9 +47,9 @@ 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 CaseArm, type ExprOperand, expr, type NumericOperand } from './query/expr.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, col, 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 JsonValue, jsonValue, 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 { 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 CreateManyCount, type CreateManyResult, col, 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 JsonValue, jsonValue, 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 type { SqlCommentOptions } from './query/sql-comment.js';
-export type { AggregateResultOf, ConflictTarget, ConflictUpdateData, CreateManyOnConflict, DefaultInputTypes, ExcludedRef, GlobalFilter, NestedToOneCreateOp, NestedToOneUpdateOp, OptionalInput, PercentileMethod, PercentileSpec, RelationKind, RowLock, RowLockMode, SqlExpr, SqlExprKind, TableInputTypes, } from './query/types.js';
+export type { AggregateResultOf, ConflictTarget, ConflictUpdateData, CreateManyOnConflict, DefaultInputTypes, ExcludedRef, FieldPercentiles, GlobalFilter, NestedToOneCreateOp, NestedToOneUpdateOp, OptionalInput, PercentileArgs, PercentileExprSpec, PercentileKeysChecked, PercentileMethod, PercentileSpec, RelationKind, RowLock, RowLockMode, SqlExpr, SqlExprKind, TableInputTypes, } from './query/types.js';
 export { MAX_QUERY_TAG_LENGTH, RAW_QUERY_MODEL } from './query-events.js';
 export { type ActiveSubscription, type ListenOptions, type ListenReconnectOptions, type NotificationHandler, type Subscription, validateChannel, } from './realtime.js';
 export type { CheckMetadata, ColumnMetadata, IndexMetadata, PrismaCompatMap, PrismaModelMap, PrismaRelationMap, PrismaSchemaSource, ReferentialAction, RelationDef, SchemaMetadata, TableMetadata, } from './schema.js';

package/dist/cjs/mssql.js

@@ -644,6 +644,7 @@ exports.mssqlDialect = {
         // The limit the driver can actually send (see MSSQL_MAX_PARAMS), not 2100.
         maxBindParameters: MSSQL_MAX_PARAMS,
         maxInsertRows: MSSQL_MAX_INSERT_ROWS,
+        chunkBindParameters: MSSQL_MAX_PARAMS,
         upsertConflictTarget: 'explicit',
         setClauseOrder: 'snapshot',
         reselectLocksRows: false,
@@ -651,6 +652,7 @@ exports.mssqlDialect = {
         updateExpressions: true,
         // MERGE refuses a target row matched twice (error 8672).
         bulkUpsertAppliesRepeatedKeys: false,
+        skipDuplicatesCountsSkipped: false,
         readOnlyTransactions: false,
         connectionParameters: false,
         backendCancel: false,

package/dist/cjs/mysql.js

@@ -709,6 +709,7 @@ exports.mysqlDialect = {
         // Counted in a 16-bit field.
         maxBindParameters: 65535,
         maxInsertRows: Number.POSITIVE_INFINITY,
+        chunkBindParameters: 65535,
         upsertConflictTarget: 'any-unique-key',
         setClauseOrder: 'left-to-right',
         reselectLocksRows: true,
@@ -716,6 +717,8 @@ exports.mysqlDialect = {
         updateExpressions: true,
         // Caught by the onConflict re-read, which runs in the reselect transaction.
         bulkUpsertAppliesRepeatedKeys: true,
+        // A skipped row is a no-op ON DUPLICATE KEY UPDATE, counted under FOUND_ROWS.
+        skipDuplicatesCountsSkipped: true,
         readOnlyTransactions: true,
         connectionParameters: false,
         backendCancel: false,

package/dist/cjs/powdb.js

@@ -147,12 +147,14 @@ exports.powdbDialect = {
         structuredValueColumns: 'scalars',
         maxBindParameters: Number.POSITIVE_INFINITY,
         maxInsertRows: Number.POSITIVE_INFINITY,
+        chunkBindParameters: Number.POSITIVE_INFINITY,
         upsertConflictTarget: 'explicit',
         setClauseOrder: 'snapshot',
         reselectLocksRows: false,
         integerDivision: '/',
         updateExpressions: false,
         bulkUpsertAppliesRepeatedKeys: false,
+        skipDuplicatesCountsSkipped: false,
         readOnlyTransactions: false,
         connectionParameters: false,
         backendCancel: false,

package/dist/cjs/powql.d.ts

@@ -37,7 +37,7 @@
 import type { PowdbPool } from './powdb.js';
 import type { MiddlewareFn, QueryInterfaceOptions } from './query/index.js';
 import type { TableClient } from './query/table-client.js';
-import type { AggregateArgs, AggregateResultOf, CountArgs, CreateArgs, CreateManyArgs, DeleteArgs, DeleteManyArgs, FieldResult, FindManyArgs, FindUniqueArgs, GroupByArgs, GroupByResult, OptionalInput, QueryResult, TypedWithClause, UpdateArgs, UpdateManyArgs, UpsertArgs } from './query/types.js';
+import type { AggregateArgs, AggregateResultOf, CountArgs, CreateArgs, CreateManyArgs, CreateManyResult, DeleteArgs, DeleteManyArgs, FieldResult, FindManyArgs, FindUniqueArgs, GroupByArgs, GroupByResult, OptionalInput, QueryResult, TypedWithClause, UpdateArgs, UpdateManyArgs, UpsertArgs } from './query/types.js';
 import { type SchemaMetadata } from './schema.js';
 /**
  * Max values one `in` / `notIn` on a PowDB-native `datetime` column may carry.
@@ -1146,7 +1146,10 @@ export declare class PowqlInterface<T extends object = Record<string, unknown>>
      * byte-identical PowQL.
      */
     private assertUniformCreateManyRows;
-    createMany<S extends Record<string, boolean> | undefined = undefined, O extends Record<string, boolean> | undefined = undefined>(args: CreateManyArgs<T, OptionalInput<T>, S, O>): Promise<FieldResult<T, S, O>[]>;
+    createMany<S extends Record<string, boolean> | undefined = undefined, O extends Record<string, boolean> | undefined = undefined, C extends boolean | undefined = undefined>(args: CreateManyArgs<T, OptionalInput<T>, S, O, C>): Promise<CreateManyResult<FieldResult<T, S, O>, C>>;
+    /** `returning: false` validated: a boolean, and not combined with a projection. */
+    private createManyCountOnly;
+    private insertMany;
     update<S extends Record<string, boolean> | undefined = undefined, O extends Record<string, boolean> | undefined = undefined>(args: UpdateArgs<T, NoRelations, S, O>): Promise<FieldResult<T, S, O>>;
     updateMany(args: UpdateManyArgs<T>): Promise<{
         count: number;

package/dist/cjs/powql.js

@@ -3860,35 +3860,56 @@ class PowqlInterface {
     async createMany(args) {
         args = this.normalizeArgs(args);
         return this.withMiddleware('createMany', args, async () => {
-            if (args.onConflict !== undefined) {
-                throw new errors_js_1.UnsupportedFeatureError('createMany({ onConflict })', 'powdb', "PowQL's upsert statement takes one row. Call upsert() per row inside $transaction.");
-            }
-            // Validated as every engine validates it; it acts only on onConflict's
-            // update, which is refused above.
-            (0, types_js_1.resolveSkipGlobalFilters)(args.skipGlobalFilters);
-            if (args.skipDuplicates) {
-                // PowQL's `insert … returning` has no conflict clause, so there is no
-                // faithful skip-duplicates form; refuse rather than silently insert.
-                throw new errors_js_1.UnsupportedFeatureError('createMany({ skipDuplicates: true })', 'powdb', 'PowQL insert has no ON CONFLICT DO NOTHING equivalent, filter duplicates before inserting.');
-            }
-            // Resolved before the write, so a bad projection writes nothing.
-            const plan = this.writeReturnPlan(args);
-            const supplied = args.data.map((d) => this.applyPkDefault(d));
-            if (!supplied.length)
-                return [];
-            // Uniformity is judged on what the caller supplied, as the SQL engines
-            // judge it; defaults are then filled per row.
-            this.assertUniformCreateManyRows(supplied);
-            const inputs = supplied.map((d) => this.applyColumnDefaults(d));
-            const params = [];
-            const tuples = inputs.map((d) => {
-                const assigns = this.scalarData(d);
-                return `{ ${assigns.map((a) => `${(0, powdb_shared_js_1.quotePowqlIdent)(a.col.name)} := ${this.writeRef(a.value, a.col, params)}`).join(', ')} }`;
-            });
-            // Multi-row insert with `returning` hands back every inserted row in one round-trip.
-            const { rows, native } = await this.exec(`insert ${this.qt} ${tuples.join(', ')} returning`, params, args.timeout, 'createMany');
-            return this.shape(rows, native).map((r) => this.shapeWriteRow(r, plan));
+            // `returning: false` is checked as the SQL engines check it. PowQL's
+            // insert still returns the rows, which are counted and dropped.
+            const countOnly = this.createManyCountOnly(args);
+            const rows = await this.insertMany(args);
+            return countOnly ? { count: rows.length } : rows;
+        });
+    }
+    /** `returning: false` validated: a boolean, and not combined with a projection. */
+    createManyCountOnly(args) {
+        const { returning } = args;
+        if (returning === undefined || returning === true)
+            return false;
+        if (returning !== false) {
+            throw new errors_js_1.ValidationError(`createMany on "${this.table}": returning must be true or false, received ${typeof returning}.`);
+        }
+        if (args.select !== undefined || args.omit !== undefined) {
+            throw new errors_js_1.ValidationError(`createMany on "${this.table}": returning: false returns { count } and no rows, so it takes no ` +
+                `\`${args.select !== undefined ? 'select' : 'omit'}\`. Drop one of them.`);
+        }
+        return true;
+    }
+    async insertMany(args) {
+        if (args.onConflict !== undefined) {
+            throw new errors_js_1.UnsupportedFeatureError('createMany({ onConflict })', 'powdb', "PowQL's upsert statement takes one row. Call upsert() per row inside $transaction.");
+        }
+        // Validated as every engine validates it; it acts only on onConflict's
+        // update, which is refused above.
+        (0, types_js_1.resolveSkipGlobalFilters)(args.skipGlobalFilters);
+        if (args.skipDuplicates) {
+            // PowQL's `insert … returning` has no conflict clause, so there is no
+            // faithful skip-duplicates form; refuse rather than silently insert.
+            throw new errors_js_1.UnsupportedFeatureError('createMany({ skipDuplicates: true })', 'powdb', 'PowQL insert has no ON CONFLICT DO NOTHING equivalent, filter duplicates before inserting.');
+        }
+        // Resolved before the write, so a bad projection writes nothing.
+        const plan = this.writeReturnPlan(args);
+        const supplied = args.data.map((d) => this.applyPkDefault(d));
+        if (!supplied.length)
+            return [];
+        // Uniformity is judged on what the caller supplied, as the SQL engines
+        // judge it; defaults are then filled per row.
+        this.assertUniformCreateManyRows(supplied);
+        const inputs = supplied.map((d) => this.applyColumnDefaults(d));
+        const params = [];
+        const tuples = inputs.map((d) => {
+            const assigns = this.scalarData(d);
+            return `{ ${assigns.map((a) => `${(0, powdb_shared_js_1.quotePowqlIdent)(a.col.name)} := ${this.writeRef(a.value, a.col, params)}`).join(', ')} }`;
         });
+        // Multi-row insert with `returning` hands back every inserted row in one round-trip.
+        const { rows, native } = await this.exec(`insert ${this.qt} ${tuples.join(', ')} returning`, params, args.timeout, 'createMany');
+        return this.shape(rows, native).map((r) => this.shapeWriteRow(r, plan));
     }
     async update(args) {
         args = this.normalizeArgs(args);

package/dist/cjs/prisma-compat.d.ts

@@ -137,7 +137,7 @@ export interface CompatQueryInterface {
     findFirstOrThrow(args?: Record<string, unknown>): Promise<unknown>;
     findUniqueOrThrow(args: Record<string, unknown>): Promise<unknown>;
     create(args: Record<string, unknown>): Promise<unknown>;
-    createMany(args: Record<string, unknown>): Promise<unknown[]>;
+    createMany(args: Record<string, unknown>): Promise<unknown>;
     update(args: Record<string, unknown>): Promise<unknown>;
     updateMany(args: Record<string, unknown>): Promise<{
         count: number;
@@ -156,7 +156,7 @@ export interface CompatQueryInterface {
     buildFindFirstOrThrow(args?: Record<string, unknown>): DeferredQuery<unknown>;
     buildFindUniqueOrThrow(args: Record<string, unknown>): DeferredQuery<unknown>;
     buildCreate(args: Record<string, unknown>): DeferredQuery<unknown>;
-    buildCreateMany(args: Record<string, unknown>): DeferredQuery<unknown[]>;
+    buildCreateMany(args: Record<string, unknown>): DeferredQuery<unknown>;
     buildUpdate(args: Record<string, unknown>): DeferredQuery<unknown>;
     buildUpdateMany(args: Record<string, unknown>): DeferredQuery<{
         count: number;

package/dist/cjs/prisma-compat.js

@@ -1901,12 +1901,12 @@ function createManyRunsOf(t) {
 async function createManyByRun(qi, t, runs) {
     let count = 0;
     for (const run of runs) {
-        const args = { data: run };
+        const args = { data: run, returning: false };
         if (t.skipDuplicates)
             args.skipDuplicates = true;
         if (t.timeout !== undefined)
             args.timeout = t.timeout;
-        count += (await qi.createMany(args)).length;
+        count += (await qi.createMany(args)).count;
     }
     return { count };
 }
@@ -2002,7 +2002,10 @@ function makeDelegate(ctx, mm, getQI, runInTx) {
                     `array of them, received ${describeValue(data)}.`);
             }
             const rows = list.map((d) => translateWriteData(ctx, mm, applyCreateDefaults(mm, d)));
-            const t = { data: rows };
+            // Prisma's createMany resolves to { count }, which core counts
+            // without returning the rows (a plain MySQL insert returns none, so
+            // counting rows reported 0 there).
+            const t = { data: rows, returning: false };
             (0, index_js_1.applyNativeOptions)(index_js_1.CREATE_MANY_OPTIONS, args, t);
             if (args.skipDuplicates)
                 t.skipDuplicates = true;
@@ -2014,11 +2017,11 @@ function makeDelegate(ctx, mm, getQI, runInTx) {
             // stays all-or-nothing and the count is the total actually inserted.
             const runs = createManyRunsOf(t);
             if (runs.length <= 1)
-                return qi.createMany(t).then((r) => ({ count: r.length }));
+                return qi.createMany(t);
             return runInTx((table) => createManyByRun(table(mm.table), t, runs));
         }, {
             build: (qi, t) => qi.buildCreateMany(t),
-            reshape: (raw) => ({ count: raw.length }),
+            reshape: (raw) => raw,
             // A mixed batch is more than one statement, so the array
             // $transaction([...]) form runs the whole array sequentially in a tx.
             nested: (t) => createManyRunsOf(t).length > 1,

package/dist/cjs/query/aggregates.js

@@ -54,6 +54,7 @@ exports.buildHavingNumericClauses = buildHavingNumericClauses;
 exports.buildAggregate = buildAggregate;
 const errors_js_1 = require("../errors.js");
 const schema_js_1 = require("../schema.js");
+const expr_js_1 = require("./expr.js");
 const filters_js_1 = require("./filters.js");
 const types_js_1 = require("./types.js");
 const utils_js_1 = require("./utils.js");
@@ -325,7 +326,7 @@ function buildGroupBy(qi, args) {
     buildAggregates('_avg', 'AVG', args._avg);
     buildAggregates('_min', 'MIN', args._min);
     buildAggregates('_max', 'MAX', args._max);
-    const percentiles = planPercentiles(qi, args._percentile, params, includePii, 'groupBy', claimResultKey);
+    const percentiles = planPercentiles(qi, args._percentile, params, includePii, 'groupBy', claimResultKey, (key) => key === '_count' || usedResultKeys.has(key));
     selectExprs.push(...percentiles.map((plan) => plan.expr));
     let sql = `SELECT ${selectExprs.join(', ')} FROM ${fromSql} GROUP BY ${groupExprs.join(', ')}`;
     // HAVING, filter whole groups by their aggregate values.
@@ -1070,7 +1071,7 @@ const PERCENTILE_HINT = {
     mssql: 'Percentile aggregates are not available on SQL Server in this release: PERCENTILE_CONT is a window ' +
         'function there, not an aggregate.',
 };
-const PERCENTILE_SPEC_KEYS = ['p', 'method'];
+const PERCENTILE_SPEC_KEYS = ['p', 'method', 'of'];
 const PERCENTILE_METHODS = ['cont', 'disc'];
 const PERCENTILE_NOT_ORDERABLE = 'ordering or filtering groups by _percentile is not supported yet.';
 /**
@@ -1085,8 +1086,14 @@ const PERCENTILE_NOT_ORDERABLE = 'ordering or filtering groups by _percentile is
  * form), a JSON-path target, and two keys naming one column. Both methods need
  * `includePii: UNSAFE` on a PII column: `disc` returns a stored cell, and so
  * does `cont` at p = 0 or 1 or over a one-row group.
+ *
+ * A key with `of` names an expression's result (see `PercentileExprSpec`): it
+ * must not name a field, the expression compiles through `compileReadExpr`,
+ * it is ordered as `float8`, and its SQL alias is `_percentile_of_<n>`, so the
+ * caller's name never reaches the SQL. Every PII column it reads as a value
+ * needs `includePii: UNSAFE`, as a column percentile does.
  */
-function planPercentiles(qi, spec, params, includePii, operation, claimResultKey) {
+function planPercentiles(qi, spec, params, includePii, operation, claimResultKey, resultKeyTaken) {
     if (spec === undefined)
         return [];
     const where = `${operation} _percentile on table "${qi.table}"`;
@@ -1102,6 +1109,16 @@ function planPercentiles(qi, spec, params, includePii, operation, claimResultKey
     const meta = qi.schema.tables[qi.table];
     const plans = [];
     const aliases = new Set();
+    // Column aliases are `_percentile_<column>`; an expression's is the first
+    // free `_percentile_of_<n>`, chosen after every column alias is known so a
+    // column named `of_0` keeps its own.
+    const columnAliases = new Set();
+    for (const [key] of entries) {
+        const column = (0, utils_js_1.resolveColumnName)(qi.tableMeta, key);
+        if (column !== undefined)
+            columnAliases.add(`_percentile_${column}`);
+    }
+    let exprCount = 0;
     for (const [key, entry] of entries) {
         const label = `${where}, field "${key}"`;
         if (typeof entry !== 'object' || entry === null || Array.isArray(entry)) {
@@ -1116,7 +1133,7 @@ function planPercentiles(qi, spec, params, includePii, operation, claimResultKey
                 throw new errors_js_1.ValidationError(`${label}: unknown key "${k}".${hint ? ` Did you mean "${hint}"?` : ''} Expected { p, method? }.`);
             }
         }
-        const { p, method = 'cont' } = entry;
+        const { p, method = 'cont', of } = entry;
         if (!PERCENTILE_METHODS.includes(method)) {
             throw new errors_js_1.ValidationError(`${label}: method must be 'cont' or 'disc', received ${describeValue(method)}.`);
         }
@@ -1129,6 +1146,10 @@ function planPercentiles(qi, spec, params, includePii, operation, claimResultKey
         else {
             assertFraction(p, label);
         }
+        if (of !== undefined) {
+            plans.push(planExpressionPercentile(qi, key, of, p, method, params, includePii, operation, label, aliases, columnAliases, exprCount++, claimResultKey, resultKeyTaken));
+            continue;
+        }
         const col = qi.toColumn(key);
         if (method === 'cont' && qi.tableMeta.dateColumns.has(col)) {
             throw new errors_js_1.ValidationError(`${label}: method 'cont' interpolates and needs a numeric or interval column, and "${col}" is a ` +
@@ -1158,6 +1179,51 @@ function planPercentiles(qi, spec, params, includePii, operation, claimResultKey
     }
     return plans;
 }
+/** One `_percentile` entry over an expression (`of`); see {@link planPercentiles}. */
+function planExpressionPercentile(qi, key, of, p, method, params, includePii, operation, label, aliases, columnAliases, index, claimResultKey, resultKeyTaken) {
+    const column = (0, utils_js_1.resolveColumnName)(qi.tableMeta, key);
+    if (column !== undefined) {
+        throw new errors_js_1.ValidationError(`${label}: "${key}" is a field of the table, and \`of\` names an expression. Give the expression a name ` +
+            `that is not a field (the name is only its result's key), or drop \`of\` for the percentile of "${key}".`);
+    }
+    const compiled = (0, expr_js_1.compileReadExpr)({
+        qi,
+        name: key,
+        operation: `${operation} _percentile`,
+        bind: (value, cls) => {
+            params.push(value);
+            return `${qi.p(params.length)}::${cls === 'int' ? 'int8' : 'numeric'}`;
+        },
+        predicate: (when) => {
+            const sql = whereMod.buildWhereClause(qi, when, params);
+            if (sql === null)
+                throw new errors_js_1.ValidationError(`${label}: an expr.case() arm's when compiles to no predicate.`);
+            return sql;
+        },
+    }, of);
+    const meta = qi.schema.tables[qi.table];
+    for (const col of compiled.values) {
+        const field = qi.tableMeta.reverseColumnMap[col] ?? (0, schema_js_1.snakeToCamel)(col);
+        assertAggregatePiiOptIn(qi.table, meta, field, col, `${operation} _percentile "${key}"`, includePii);
+    }
+    // The caller's key never names the alias, so it skips every name already
+    // taken, a groupBy key included, rather than collide with one.
+    let n = index;
+    const taken = (alias) => aliases.has(alias) || columnAliases.has(alias) || resultKeyTaken?.(alias) === true;
+    while (taken(`_percentile_of_${n}`))
+        n++;
+    const alias = `_percentile_of_${n}`;
+    aliases.add(alias);
+    claimResultKey?.(alias, `_percentile "${key}"`);
+    params.push(Array.isArray(p) ? [...p] : p);
+    const fractions = `${qi.p(params.length)}::float8${Array.isArray(p) ? '[]' : ''}`;
+    return {
+        expr: `percentile_${method}(${fractions}) WITHIN GROUP (ORDER BY (${compiled.sql})::float8) AS ${qi.q(alias)}`,
+        alias,
+        field: key,
+        col: null,
+    };
+}
 function assertFraction(value, label) {
     if (typeof value === 'number' && Number.isFinite(value) && value >= 0 && value <= 1)
         return;
@@ -1199,6 +1265,10 @@ function readPercentiles(qi, plans, row) {
 function percentileElement(qi, col, value) {
     if (value === null || value === undefined)
         return null;
+    // An expression is ordered as float8, which the driver reads as a number
+    // (a supplied pool's own parser may hand back text).
+    if (col === null)
+        return typeof value === 'string' ? Number(value) : value;
     if (typeof value === 'string' && isInt8Type(whereMod.getColumnPgType(qi, col))) {
         const n = Number(value);
         return Number.isSafeInteger(n) ? n : value;