uql-orm 0.115.5 → 0.116.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -1,10 +1,12 @@
1
1
  import { AbstractPoolQuerier } from '../querier/abstractPoolQuerier.js';
2
- import type { RawRow } from '../type/index.js';
2
+ import type { BoundStatement, RawRow } from '../type/index.js';
3
3
  import type { SqlExecution } from '../util/sql.util.js';
4
4
  import { type PgResult } from './pgExecution.js';
5
+ import { type PgTypes } from './pgPipeline.js';
5
6
  export interface PgAnyClient {
6
7
  query(text: string, values?: unknown[]): Promise<PgResult>;
7
8
  query(stream: object): AsyncIterable<RawRow>;
9
+ getTypeParser: PgTypes['getTypeParser'];
8
10
  on(event: 'error', listener: (err: Error) => void): unknown;
9
11
  removeListener(event: 'error', listener: (err: Error) => void): unknown;
10
12
  /** Any truthy argument makes `pg-pool` evict the client instead of returning it to the idle list. */
@@ -21,6 +23,12 @@ export declare class PgQuerier extends AbstractPoolQuerier<PgAnyClient> {
21
23
  */
22
24
  protected acquired(conn: PgAnyClient): PgAnyClient;
23
25
  protected execute(sql: string, values?: unknown[]): Promise<SqlExecution>;
26
+ /**
27
+ * `statements` as one request: written ahead of one `Sync`, so they cost one round trip. Outside a transaction they
28
+ * run in one opened and committed in the same request, all or none, which also scopes a setting bound for the
29
+ * database's policies, as CockroachDB scopes one only in a transaction; rolled back where one fails.
30
+ */
31
+ protected executeBatch(statements: readonly BoundStatement[]): Promise<SqlExecution[]>;
24
32
  internalStream(query: string, values?: unknown[]): AsyncGenerator<RawRow, void, any>;
25
33
  protected releaseConn(conn: PgAnyClient, discard: boolean): Promise<void>;
26
34
  }
@@ -1,6 +1,7 @@
1
1
  import { AbstractPoolQuerier } from '../querier/abstractPoolQuerier.js';
2
2
  import { noop } from '../util/object.util.js';
3
3
  import { pgExecution } from './pgExecution.js';
4
+ import { pipelined } from './pgPipeline.js';
4
5
  /**
5
6
  * Querier for every client with node-postgres' API: `pg` itself, for Postgres and CockroachDB, and
6
7
  * Neon's serverless driver; the dialect is whichever the pool built.
@@ -17,6 +18,28 @@ export class PgQuerier extends AbstractPoolQuerier {
17
18
  async execute(sql, values) {
18
19
  return pgExecution(await this.getConn().query(sql, values));
19
20
  }
21
+ /**
22
+ * `statements` as one request: written ahead of one `Sync`, so they cost one round trip. Outside a transaction they
23
+ * run in one opened and committed in the same request, all or none, which also scopes a setting bound for the
24
+ * database's policies, as CockroachDB scopes one only in a transaction; rolled back where one fails.
25
+ */
26
+ async executeBatch(statements) {
27
+ const conn = this.getConn();
28
+ if (this.hasOpenTransaction) {
29
+ return (await pipelined(conn, statements)).map(pgExecution);
30
+ }
31
+ const { dialect } = this;
32
+ const begin = dialect.getBeginTransactionStatements().map((sql) => ({ sql, values: [] }));
33
+ const listed = [...begin, ...statements, { sql: dialect.commitTransactionCommand, values: [] }];
34
+ try {
35
+ return (await pipelined(conn, listed, begin.length)).slice(begin.length, -1).map(pgExecution);
36
+ }
37
+ catch (error) {
38
+ // The failed transaction stays open past the `Sync`; its own failure is the one worth reporting.
39
+ await conn.query(dialect.rollbackTransactionCommand).catch(noop);
40
+ throw error;
41
+ }
42
+ }
20
43
  async *internalStream(query, values) {
21
44
  const { default: QueryStream } = await import('pg-query-stream');
22
45
  yield* this.getConn().query(new QueryStream(query, values));
@@ -152,23 +152,33 @@ export declare abstract class AbstractQuerier implements Querier {
152
152
  */
153
153
  private insertRows;
154
154
  /**
155
- * {@link guardWrite} under a pool holding writes to the policies, answering how the write of `rows` runs: alone, or
156
- * with the rows it wrote read back against the check they could not settle, in a transaction undoing it where one
157
- * does not hold. Where the database holds the policies the rows still get their pinned fields and an early refusal,
158
- * and nothing is read back. A checked write is refused where this querier holds no transaction to undo it in.
155
+ * How a statement doing `write` to `rows` runs where this pool reads rows to hold it to the check {@link guardWrite}
156
+ * answers and, for an update, to the transitions: alone where neither applies; else in a transaction reading each
157
+ * found row before the write, refusing one no transition lets go unwritten, then each written row after it against
158
+ * the check and what its transitions leave. A write read around is refused where no transaction undoes it.
159
159
  */
160
160
  private guarded;
161
+ /** The transitions this pool holds an update of `meta` to under the context: none where the database holds them. */
162
+ private heldTransitions;
161
163
  /**
162
- * {@link guardWrite} where this pool reads written rows back, answering the check to read them against; else
163
- * {@link pinUpserted}'s pinning alone, where it guards writes at all.
164
+ * What each row `found` names owes `transitions` once written, by its {@link rowKey}: each reads the row as found
165
+ * first, and one that lets it go nowhere refuses the write before it runs. Rows holding alike owe alike.
166
+ */
167
+ private transitionsOwed;
168
+ /** The {@link rowKey}s of the rows among `ids` holding `where` as they are stored. */
169
+ private idsHolding;
170
+ /**
171
+ * {@link guardWrite} where this pool guards writes: it pins and refuses `rows`, answering the check left to read
172
+ * them back against.
164
173
  */
165
174
  private guardRows;
166
- /** {@link pinWrite} where this pool guards writes: an upsert's branches check what they write, or its database does. */
167
- private pinUpserted;
168
175
  /** Whether {@link atomically} undoes every step of a write that fails partway: a transaction holds them. */
169
176
  private undoesSteps;
170
- /** Refuses, undoing the write, where any row `ids` names does not hold `check` once written. */
171
- private holdToCheck;
177
+ /**
178
+ * Refuses, undoing the write, where any row `ids` names does not hold `check` and what `owed` holds it to once
179
+ * written: one count per distinct predicate.
180
+ */
181
+ private holdWritten;
172
182
  /** Writes `rows`, its columns only, and onto each one the key the database generated for it, where it can tell. */
173
183
  protected abstract internalInsertMany<E extends object>(entity: Type<E>, rows: EntityData<E>[]): Promise<void>;
174
184
  updateOneById<E extends object, const S extends FieldKey<E> = never, const V extends BooleanLike = true, const W extends boolean = false>(entity: Type<E>, id: EntityId<E>, payload: UpdateWrite<E>, opts?: QueryOptions & WriteOptions<E, S, V, W>): Promise<WriteResults<E, S, V, W>['affected']>;
@@ -304,7 +314,10 @@ export declare abstract class AbstractQuerier implements Querier {
304
314
  deleteMany<E extends object, const S extends FieldKey<E> = never, const V extends BooleanLike = true, const W extends boolean = false>(entity: Type<E>, q: QuerySearch<E>, opts?: QueryOptions & WriteOptions<E, S, V, W>): Promise<WriteResults<E, S, V, W>['affectedMany']>;
305
315
  /** The number of rows deleted, or the rows `returning` reads as they were: held before the delete, which deletes those. */
306
316
  private deleteWhere;
307
- /** Whether an update is its one statement over `q`: no version to lock, relation to write or page to settle first. */
317
+ /**
318
+ * Whether an update is its one statement over `q`: no version to lock, relation to write, page to settle first, or
319
+ * transition to read its rows as found for.
320
+ */
308
321
  private updatesByFilter;
309
322
  /** Whether a delete is its one statement over `q`: no hook, cascade or page needs its rows read first. */
310
323
  private deletesByFilter;
@@ -1,8 +1,10 @@
1
1
  import { getMeta, idOf, namesEvery, namesKey, relationOf } from '../entity/index.js';
2
+ import { getContext } from '../context/context.js';
2
3
  import { SAVEPOINT_PREFIX } from '../dialect/aliases.js';
3
4
  import { namesRows } from '../dialect/operators.js';
4
5
  import { parseQueryLock, PAST_POLICIES } from '../type/index.js';
5
- import { childrenExcept, childrenOf, chunk, clone, entityName, fillOnFields, filterFieldKeys, getKeys, deletionOf, hasKeys, getRelationRequestSummary, guardWrite, pinWrite, idOnlyQuery, keyJoins, keySet, isPagedQuery, isScalarId, LoggerWrapper, normalizeScalarFieldSelection, parentJoins, pointAt, queryLoggerFor, parseRelationAtKey, rowKey, runHooks, someKey, targetJoins, foundRowAssigned, whereAnd, whereIds, whereKeysIn, whereWith, withDeleted, cascadingRelations, isClass, defaultReadKeys, holdsForeignKey, noop, } from '../util/index.js';
6
+ import { childrenExcept, childrenOf, chunk, clone, entityName, fillOnFields, filterFieldKeys, getKeys, accessOf, deletionOf, hasKeys, getRelationRequestSummary, guardWrite, idOnlyQuery, keyJoins, keySet, isPagedQuery, isScalarId, LoggerWrapper, normalizeScalarFieldSelection, parentJoins, pointAt, queryLoggerFor, parseRelationAtKey, rowKey, runHooks, someKey, targetJoins, foundRowAssigned, whereAnd, whereIds, whereKeysIn, whereWith, withDeleted, cascadingRelations, isClass, defaultReadKeys, holdsForeignKey, noop, } from '../util/index.js';
7
+ import { movesRefused, oldReads, onWritten, pairsRows, policyTransitions, } from '../util/policy.util.js';
6
8
  import { UqlOptimisticLockError, UqlSecurityError, UqlUsageError } from '../util/uqlError.js';
7
9
  import { keysetRead } from './keyset.js';
8
10
  import { enrichError } from './queryError.js';
@@ -426,62 +428,121 @@ export class AbstractQuerier {
426
428
  }, () => rows.map((row) => idOf(meta, row)));
427
429
  }
428
430
  /**
429
- * {@link guardWrite} under a pool holding writes to the policies, answering how the write of `rows` runs: alone, or
430
- * with the rows it wrote read back against the check they could not settle, in a transaction undoing it where one
431
- * does not hold. Where the database holds the policies the rows still get their pinned fields and an early refusal,
432
- * and nothing is read back. A checked write is refused where this querier holds no transaction to undo it in.
431
+ * How a statement doing `write` to `rows` runs where this pool reads rows to hold it to the check {@link guardWrite}
432
+ * answers and, for an update, to the transitions: alone where neither applies; else in a transaction reading each
433
+ * found row before the write, refusing one no transition lets go unwritten, then each written row after it against
434
+ * the check and what its transitions leave. A write read around is refused where no transaction undoes it.
433
435
  */
434
436
  guarded(entity, rows, write) {
435
- const check = this.guardRows(getMeta(entity), rows, write);
436
- const held = (run, written) => {
437
- if (!check) {
437
+ const meta = getMeta(entity);
438
+ const check = this.guardRows(meta, rows, write);
439
+ const checked = this.dialect.policies.checks ? check : undefined;
440
+ const transitions = pairsRows(write) ? this.heldTransitions(meta) : [];
441
+ const reads = !!checked || transitions.length > 0;
442
+ const held = (run, written, found) => {
443
+ if (!reads) {
438
444
  return run();
439
445
  }
440
446
  if (!this.undoesSteps()) {
441
447
  throw new UqlUsageError(`'${entity.name}' policies check written rows by reading them back, which needs a transaction ${this.dialect.engineName} holds none of here`);
442
448
  }
443
449
  return this.atomically(async () => {
450
+ const owed = await this.transitionsOwed(entity, found ?? [], transitions);
444
451
  const result = await run();
445
- await this.holdToCheck(entity, written(result), check);
452
+ await this.holdWritten(entity, written(result), checked, owed);
446
453
  return result;
447
454
  });
448
455
  };
449
- return Object.assign(held, { reads: !!check });
456
+ return Object.assign(held, { reads });
457
+ }
458
+ /** The transitions this pool holds an update of `meta` to under the context: none where the database holds them. */
459
+ heldTransitions(meta) {
460
+ return this.dialect.policies.checks && meta.policies?.length ? policyTransitions(meta, getContext()) : [];
450
461
  }
451
462
  /**
452
- * {@link guardWrite} where this pool reads written rows back, answering the check to read them against; else
453
- * {@link pinUpserted}'s pinning alone, where it guards writes at all.
463
+ * What each row `found` names owes `transitions` once written, by its {@link rowKey}: each reads the row as found
464
+ * first, and one that lets it go nowhere refuses the write before it runs. Rows holding alike owe alike.
454
465
  */
455
- guardRows(meta, rows, write) {
456
- const { guards, checks } = this.dialect.policies;
457
- if (checks) {
458
- return guardWrite(meta, rows, write);
466
+ async transitionsOwed(entity, found, transitions) {
467
+ const meta = getMeta(entity);
468
+ const refused = () => new UqlSecurityError(movesRefused(entity.name));
469
+ const live = transitions.filter((transition) => transition !== false);
470
+ if (live.length < transitions.length) {
471
+ throw refused();
459
472
  }
460
- if (guards) {
461
- pinWrite(meta, rows, write);
473
+ const owed = new Map(found.map((id) => [rowKey(whereIds(meta, id), meta.ids), { signature: '', left: [] }]));
474
+ for (const transition of live) {
475
+ const holding = await Promise.all(oldReads(transition).map((read) => this.idsHolding(entity, found, read)));
476
+ const folded = new Map();
477
+ for (const [key, row] of owed) {
478
+ const signature = holding.map((ids) => (ids.has(key) ? '1' : '0')).join('');
479
+ let left = folded.get(signature);
480
+ if (left === undefined) {
481
+ left = onWritten(transition, (at) => signature[at] === '1');
482
+ folded.set(signature, left);
483
+ }
484
+ if (left === false) {
485
+ throw refused();
486
+ }
487
+ row.signature += `${signature}.`;
488
+ if (left !== true) {
489
+ row.left.push(left);
490
+ }
491
+ }
462
492
  }
463
- return undefined;
493
+ return owed;
464
494
  }
465
- /** {@link pinWrite} where this pool guards writes: an upsert's branches check what they write, or its database does. */
466
- pinUpserted(meta, rows) {
467
- if (this.dialect.policies.guards) {
468
- pinWrite(meta, rows, 'insert');
495
+ /** The {@link rowKey}s of the rows among `ids` holding `where` as they are stored. */
496
+ async idsHolding(entity, ids, where) {
497
+ const meta = getMeta(entity);
498
+ const holding = new Set();
499
+ const named = ids.map((id) => whereIds(meta, id));
500
+ for (const q of this.keyedReads(meta.ids, named, meta.ids)) {
501
+ const rows = await this.internalFindMany(entity, { ...q, $where: whereAnd(q.$where, [where]) }, UNPOLICED);
502
+ rows.forEach((row) => holding.add(rowKey(row, meta.ids)));
469
503
  }
504
+ return holding;
505
+ }
506
+ /**
507
+ * {@link guardWrite} where this pool guards writes: it pins and refuses `rows`, answering the check left to read
508
+ * them back against.
509
+ */
510
+ guardRows(meta, rows, write) {
511
+ return this.dialect.policies.guards ? guardWrite(meta, rows, write) : undefined;
470
512
  }
471
513
  /** Whether {@link atomically} undoes every step of a write that fails partway: a transaction holds them. */
472
514
  undoesSteps() {
473
515
  return this.dialect.features.transactions || this.scopeHere() !== undefined;
474
516
  }
475
- /** Refuses, undoing the write, where any row `ids` names does not hold `check` once written. */
476
- async holdToCheck(entity, ids, check) {
517
+ /**
518
+ * Refuses, undoing the write, where any row `ids` names does not hold `check` and what `owed` holds it to once
519
+ * written: one count per distinct predicate.
520
+ */
521
+ async holdWritten(entity, ids, check, owed) {
477
522
  const meta = getMeta(entity);
478
523
  const known = ids.filter((id) => id !== undefined);
479
524
  if (known.length < ids.length) {
480
525
  throw new UqlUsageError(`'${entity.name}' wrote a row whose key it cannot read back to check against its policies`);
481
526
  }
482
- const holding = await this.writeBatches(known, meta.ids.length, (batch) => this.internalCount(entity, { $where: whereAnd(whereIds(meta, batch), [check]) }, UNPOLICED));
483
- if (holding < known.length) {
484
- throw new UqlSecurityError(`a row written to '${entity.name}' does not hold its policies under this context`);
527
+ const groups = new Map();
528
+ for (const id of known) {
529
+ const row = owed.get(rowKey(whereIds(meta, id), meta.ids));
530
+ const signature = row?.signature ?? '';
531
+ let group = groups.get(signature);
532
+ if (!group) {
533
+ group = { where: [...(check ? [check] : []), ...(row?.left ?? [])], ids: [] };
534
+ groups.set(signature, group);
535
+ }
536
+ group.ids.push(id);
537
+ }
538
+ for (const group of groups.values()) {
539
+ if (!group.where.length) {
540
+ continue;
541
+ }
542
+ const holding = await this.writeBatches(group.ids, meta.ids.length, (batch) => this.internalCount(entity, { $where: whereAnd(whereIds(meta, batch), group.where) }, UNPOLICED));
543
+ if (holding < group.ids.length) {
544
+ throw new UqlSecurityError(`a row written to '${entity.name}' does not hold its policies under this context`);
545
+ }
485
546
  }
486
547
  }
487
548
  async updateOneById(entity, id, payload, opts) {
@@ -558,25 +619,28 @@ export class AbstractQuerier {
558
619
  assertLockableUpdate(meta, q, settles);
559
620
  const lock = lockVersion(meta, lockKey, q, row);
560
621
  row[lockKey] = lock.next;
561
- const changes = await held(() => this.updateColumns(entity, lock.q, row, opts, 0), (changed) => (changed ? [idOf(meta, { ...q.$where })] : []));
622
+ const id = idOf(meta, { ...q.$where });
623
+ const changed = (count) => (count ? [id] : []);
624
+ const changes = await held(() => this.updateColumns(entity, lock.q, row, opts, 0), changed, [id]);
562
625
  return changes || this.throwStaleVersion(entity, lockKey, q, lock.expected, opts);
563
626
  }
564
627
  if (!settles && !settled && !held.reads) {
565
628
  return this.updateColumns(entity, q, row, opts, 0);
566
629
  }
567
- const write = async () => {
568
- const ids = settled ?? (await this.settleIds(entity, q, opts));
630
+ const write = async (ids) => {
569
631
  if (!ids.length) {
570
- return { ids, changes: 0 };
632
+ return 0;
571
633
  }
572
634
  const changes = await this.writeBatches(ids, meta.ids.length, (batch) => this.updateColumns(entity, { $where: whereIds(meta, batch) }, row, opts, batch.length));
573
635
  for (const relKey of relKeys) {
574
636
  await this.replaceChildren(entity, relKey, ids, row[relKey]);
575
637
  }
576
- return { ids, changes };
638
+ return changes;
577
639
  };
578
- const { changes } = await held(() => this.atomically(write), ({ ids }) => ids);
579
- return changes;
640
+ return this.atomically(async () => {
641
+ const ids = settled ?? (await this.settleIds(entity, q, opts));
642
+ return held(() => write(ids), () => ids, ids);
643
+ });
580
644
  }
581
645
  /**
582
646
  * Why an update matched no row. The filter named the row by its id, so reading by that id alone
@@ -708,7 +772,7 @@ export class AbstractQuerier {
708
772
  /** Upserts `rows`, each naming every conflict key, reading first where `reads`: the id each got. */
709
773
  async upsertIds(entity, q, rows, reads) {
710
774
  const meta = getMeta(entity);
711
- this.pinUpserted(meta, rows);
775
+ this.guardRows(meta, rows, 'insert');
712
776
  const ids = reads ? await this.readThenUpsert(entity, q, rows) : await this.reportedOrKeptIds(entity, q, rows);
713
777
  return rows.map((row, index) => adoptId(meta, row, ids[index] ?? this.unmatched(entity, q, row)));
714
778
  }
@@ -746,7 +810,7 @@ export class AbstractQuerier {
746
810
  async upsertReturning(writes, entity, q, rows, keys) {
747
811
  const meta = getMeta(entity);
748
812
  const read = [...new Set([...keys, ...meta.ids, ...getKeys(q.$conflict)])];
749
- this.pinUpserted(meta, rows);
813
+ this.guardRows(meta, rows, 'insert');
750
814
  const written = await this.withKept(entity, q, rows, await writes.upsert(entity, q, rows, read), read, (row) => row);
751
815
  const stands = rows.map((row, index) => {
752
816
  const stand = written[index] ?? this.unmatched(entity, q, row);
@@ -862,10 +926,16 @@ export class AbstractQuerier {
862
926
  return reported;
863
927
  });
864
928
  }
865
- /** Whether an update is its one statement over `q`: no version to lock, relation to write or page to settle first. */
929
+ /**
930
+ * Whether an update is its one statement over `q`: no version to lock, relation to write, page to settle first, or
931
+ * transition to read its rows as found for.
932
+ */
866
933
  updatesByFilter(entity, q, payload, opts) {
867
934
  const meta = getMeta(entity);
868
- return !meta.version && !writesRelations(meta, [payload]) && !this.settlesWrite(entity, q, opts);
935
+ return (!meta.version &&
936
+ !writesRelations(meta, [payload]) &&
937
+ !this.settlesWrite(entity, q, opts) &&
938
+ !this.heldTransitions(meta).length);
869
939
  }
870
940
  /** Whether a delete is its one statement over `q`: no hook, cascade or page needs its rows read first. */
871
941
  deletesByFilter(entity, q, opts) {
@@ -879,12 +949,15 @@ export class AbstractQuerier {
879
949
  /** Deletes the rows `q` matches, or the ones `read` holds, reading them first where a hook, cascade or page needs them. */
880
950
  async deleteRows(entity, q, opts, read) {
881
951
  const meta = getMeta(entity);
882
- if (!read && this.deletesByFilter(entity, q, opts)) {
952
+ const deleting = opts ?? {};
953
+ // A soft delete is an update, held as one: its written row checked, and its transitions. Its stamp is filled as it
954
+ // writes, so the row the guard sees sets no field.
955
+ const held = this.guarded(entity, [{}], accessOf(meta, deleting));
956
+ if (!read && !held.reads && this.deletesByFilter(entity, q, opts)) {
883
957
  return this.internalDeleteMany(entity, q, opts);
884
958
  }
885
959
  const cascades = cascadingRelations(meta, 'delete').length > 0;
886
960
  const watched = this.watchesDelete(entity);
887
- const deleting = opts ?? {};
888
961
  return this.atomically(async () => {
889
962
  // A hook receives the rows themselves; the ids read off them name the same rows a second read might not.
890
963
  const doomed = read ?? (await this.readForWrite(entity, watched ? q : idOnlyQuery(meta, q), deletionOf(meta, deleting).opts));
@@ -893,13 +966,14 @@ export class AbstractQuerier {
893
966
  }
894
967
  const ids = doomed.map((row) => idOf(meta, row));
895
968
  await this.emitHook(entity, 'beforeDelete', doomed);
896
- const changes = await this.writeBatches(ids, meta.ids.length, async (batch) => {
969
+ const write = () => this.writeBatches(ids, meta.ids.length, async (batch) => {
897
970
  // Children first: they hold the foreign key, which a schema without `ON DELETE CASCADE` enforces.
898
971
  if (cascades) {
899
972
  await this.deleteChildren(entity, batch, deleting);
900
973
  }
901
974
  return this.internalDeleteMany(entity, { $where: whereIds(meta, batch) }, opts);
902
975
  });
976
+ const changes = await held(write, () => ids, ids);
903
977
  await this.emitHook(entity, 'afterDelete', doomed);
904
978
  return changes;
905
979
  });
@@ -27,19 +27,22 @@ export declare abstract class AbstractSqlQuerier extends AbstractQuerier impleme
27
27
  all<T extends object = RawRow>(...statement: SqlStatement): Promise<T[]>;
28
28
  run(...statement: SqlStatement): Promise<QueryUpdateResult>;
29
29
  /**
30
- * Runs `statements` as one request, all or none, joining an open transaction: what a driver taking a list as one
31
- * declares. Called for two or more.
30
+ * Runs `statements` as one request, all or none: in a transaction of its own outside one, which scopes a context
31
+ * bound ahead of them, else joining the open one. What a driver taking a list as one declares. Called for two or more.
32
32
  */
33
33
  protected executeBatch?(statements: readonly BoundStatement[]): Promise<SqlExecution[]>;
34
34
  /**
35
35
  * The one path every statement takes, alone or as a list answering a result each, all or none: one request where
36
36
  * the driver has {@link executeBatch}, a failure tagged with the statement it names; else in turn, in a transaction
37
- * where `atomic` (a split write) asks for one, opened before the queue is taken, which its `BEGIN` waits on.
37
+ * where `atomic` (a split write) asks for one, opened before the queue is taken, which its `BEGIN` waits on. A
38
+ * context the database's policies read is bound ahead of them, in the same request where the driver sends lists;
39
+ * else in a transaction opened for it, which scopes the binding.
38
40
  */
39
41
  protected runStatements(statements: readonly BoundStatement[], atomic?: boolean): Promise<readonly SqlExecution[]>;
40
42
  /**
41
- * The statement binding the ambient context into the open transaction ahead of its next statement: none where it is
42
- * bound already, or there is nothing to bind. `ask` runs the question of the connected role.
43
+ * The statement binding the ambient context ahead of the next statement: none where the open transaction bound it
44
+ * already, or there is nothing to bind. Outside one, every request binds it anew. `ask` runs the question of the
45
+ * connected role.
43
46
  */
44
47
  private pendingBinding;
45
48
  /** Whether a statement here runs under a context the database's policies read, which binds in a transaction. */
@@ -112,31 +112,34 @@ export class AbstractSqlQuerier extends AbstractQuerier {
112
112
  /**
113
113
  * The one path every statement takes, alone or as a list answering a result each, all or none: one request where
114
114
  * the driver has {@link executeBatch}, a failure tagged with the statement it names; else in turn, in a transaction
115
- * where `atomic` (a split write) asks for one, opened before the queue is taken, which its `BEGIN` waits on.
115
+ * where `atomic` (a split write) asks for one, opened before the queue is taken, which its `BEGIN` waits on. A
116
+ * context the database's policies read is bound ahead of them, in the same request where the driver sends lists;
117
+ * else in a transaction opened for it, which scopes the binding.
116
118
  */
117
119
  async runStatements(statements, atomic = false) {
118
- if (!this.dialect.policies.database) {
119
- return this.runBound(statements, atomic);
120
+ if (!this.executeBatch && !this.scopeHere() && this.bindsContext()) {
121
+ return this.atomically(() => this.runStatements(statements, atomic));
120
122
  }
121
- if (!this.scopeHere()) {
122
- return this.bindsContext()
123
- ? this.atomically(() => this.runStatements(statements, atomic))
124
- : this.runBound(statements, atomic);
125
- }
126
- const binding = await this.pendingBinding((sql) => this.onConnection(() => this.execute(sql)));
123
+ const binding = this.dialect.policies.database
124
+ ? await this.pendingBinding((sql) => this.onConnection(() => this.execute(sql)))
125
+ : undefined;
127
126
  const results = await this.runBound(binding ? [binding, ...statements] : statements, atomic);
128
127
  return binding ? results.slice(1) : results;
129
128
  }
130
129
  /**
131
- * The statement binding the ambient context into the open transaction ahead of its next statement: none where it is
132
- * bound already, or there is nothing to bind. `ask` runs the question of the connected role.
130
+ * The statement binding the ambient context ahead of the next statement: none where the open transaction bound it
131
+ * already, or there is nothing to bind. Outside one, every request binds it anew. `ask` runs the question of the
132
+ * connected role.
133
133
  */
134
134
  async pendingBinding(ask) {
135
- const { entries, bound } = nextBinding(this.#bound, getContext());
135
+ const held = this.scopeHere() !== undefined;
136
+ const { entries, bound } = nextBinding(held ? this.#bound : NOTHING_BOUND, getContext());
136
137
  if (entries.length && this.bindsContext()) {
137
138
  await this.assertHeldToPolicies(ask, roleOf(entries, this.dialect.policies.role));
138
139
  }
139
- this.#bound = bound;
140
+ if (held) {
141
+ this.#bound = bound;
142
+ }
140
143
  return this.dialect.contextBinding(entries);
141
144
  }
142
145
  /** Whether a statement here runs under a context the database's policies read, which binds in a transaction. */
@@ -150,14 +153,17 @@ export class AbstractSqlQuerier extends AbstractQuerier {
150
153
  assertHeldToPolicies(ask, role) {
151
154
  const { dialect } = this;
152
155
  const held = cachedIn(heldToPolicies, dialect, () => new Map());
153
- return cachedIn(held, role, () => ask(dialect.rowSecurityBypassQuery(role)).then(({ rows }) => {
156
+ // A failed answer is forgotten, so the next statement asks again.
157
+ return cachedIn(held, role, () => ask(dialect.rowSecurityBypassQuery(role))
158
+ .then(({ rows }) => {
154
159
  if (rows[0]?.['bypasses'] !== false) {
155
160
  throw new UqlUsageError(`a pool with policies: 'native' runs a context's statements as a role ${dialect.engineName} lets past row-level security: connect as, or name, one that does not, or leave policies unset`);
156
161
  }
157
- })).catch((error) => {
162
+ })
163
+ .catch((error) => {
158
164
  held.delete(role);
159
165
  throw error;
160
- });
166
+ }));
161
167
  }
162
168
  /** {@link runStatements} once the context is bound. */
163
169
  runBound(statements, atomic) {
@@ -308,6 +308,7 @@ export type TriggerWrite = {
308
308
  } | {
309
309
  readonly kind: 'refuse';
310
310
  readonly message: string;
311
+ readonly sqlState?: string;
311
312
  };
312
313
  /**
313
314
  * What a SQL statement is rendered through, as a `sql` callback and a query context see it:
@@ -4,7 +4,7 @@ import type { PolicyMeta, PolicySection } from './policy.js';
4
4
  import type { Querier } from './querier.js';
5
5
  import type { EntityAccess, FilterOptions, RelationQuery, Wire } from './query.js';
6
6
  import type { ColumnRef, JsonPathRef, QuerySql, SqlFor, RelationAggregate } from './querySql.js';
7
- import type { QueryWhere } from './queryWhere.js';
7
+ import type { QueryWhere, QueryWhereFields, RowSide, RowsWhere } from './queryWhere.js';
8
8
  import type { StandardSchemaV1 } from './standardSchema.js';
9
9
  import type { AtLeastOne, ExactlyOne, IsBranded, IsEqual, Merge, IsJson, JsonBrand, IsMany, Json, JsonScalar, Scalar, Type, AbstractType, Unpacked, Writable } from './utility.js';
10
10
  import type { VectorDistance, VectorIndexOptions, VectorIndexType } from './vector.js';
@@ -817,9 +817,9 @@ type TriggerUpdateEvent = TriggerEventOn<'Update'>;
817
817
  * The rows an event has, as `where` keys them: the incoming one on an insert, the outgoing one on a
818
818
  * delete, both on an update.
819
819
  */
820
- type TriggerRow<Ev extends TriggerEvent> = Ev extends TriggerEventOn<'Insert'> ? '$new' : Ev extends TriggerEventOn<'Delete'> ? '$old' : '$new' | '$old';
820
+ type TriggerRow<Ev extends TriggerEvent> = Ev extends TriggerEventOn<'Insert'> ? '$new' : Ev extends TriggerEventOn<'Delete'> ? '$old' : RowSide;
821
821
  /** One row's refs, rendering `NEW."col"` or `OLD."col"`, or `never` where the event has no such row. */
822
- type TriggerRowRefs<E, Ev extends TriggerEvent, R extends '$new' | '$old'> = R extends TriggerRow<Ev> ? RefMap<E> : never;
822
+ type TriggerRowRefs<E, Ev extends TriggerEvent, R extends RowSide> = R extends TriggerRow<Ev> ? RefMap<E> : never;
823
823
  /**
824
824
  * What a trigger runs, over its rows: the incoming row first and the outgoing one second, on every event.
825
825
  * The one an event lacks is `never`, so reading it does not compile, and a body reading only the outgoing
@@ -827,12 +827,17 @@ type TriggerRowRefs<E, Ev extends TriggerEvent, R extends '$new' | '$old'> = R e
827
827
  */
828
828
  type TriggerBody<E, Ev extends TriggerEvent> = (newRow: TriggerRowRefs<E, Ev, '$new'>, oldRow: TriggerRowRefs<E, Ev, '$old'>) => QuerySql;
829
829
  /**
830
- * A condition as data: a predicate on each row it names, of the rows the event has, all of which hold.
831
- * The row is `$`-marked, as the operators inside it are, so it never reads as a field of the entity.
830
+ * A condition as data: a predicate on each row it names, of the rows the event has, all of which hold. The row is
831
+ * `$`-marked, as the operators inside it are, so it never reads as a field of the entity. An update's pairs its rows
832
+ * in groups, and holds a condition beside neither on both, as a policy's does.
832
833
  */
833
- type TriggerPredicate<E, Ev extends TriggerEvent> = {
834
+ type TriggerPredicate<E, Ev extends TriggerEvent> = Ev extends TriggerUpdateEvent ? TriggerWhere<E> : {
834
835
  readonly [R in TriggerRow<Ev>]?: EntityPredicate<E>;
835
836
  };
837
+ /** An update trigger's predicate over its two rows, on the table's own fields. */
838
+ type TriggerWhere<E> = RowsWhere<QueryWhereFields<E, QuerySql, FieldKey<E>>, EntityPredicate<E>>;
839
+ /** A trigger's predicate, whatever its event. */
840
+ export type TriggerMetaWhere<E> = TriggerPredicate<E, TriggerEvent>;
836
841
  /**
837
842
  * The body, the engine's own SQL: one for every engine it reads alike, or a map naming one per engine
838
843
  * where they differ, as SQL Server's set-based `inserted`/`deleted` does. A missing entry for the engine
@@ -890,7 +895,7 @@ export type TriggerOptions<E = unknown> = {
890
895
  */
891
896
  export type EntityTriggerMeta<E = object> = Merge<TriggerOptions<E>, {
892
897
  readonly of?: readonly string[];
893
- readonly where?: TriggerPredicate<E, TriggerUpdateEvent> | TriggerMetaBody<E>;
898
+ readonly where?: TriggerMetaWhere<E> | TriggerMetaBody<E>;
894
899
  readonly run: TriggerMetaBody<E> | Readonly<Partial<Record<SqlDialectName, TriggerMetaBody<E>>>>;
895
900
  }>;
896
901
  /**
@@ -1,6 +1,6 @@
1
1
  import type { EntityAccess, UqlContext } from './query.js';
2
2
  import type { QuerySql, SQL_VALUE_TYPE } from './querySql.js';
3
- import type { QueryWhere } from './queryWhere.js';
3
+ import type { QueryWhere, QueryWhereFields, QueryWhereRootOperator, RowsWhere } from './queryWhere.js';
4
4
  /**
5
5
  * A context key read where a policy's predicate takes a value, as data: `{ $context: 'tenantId' }`. Read off
6
6
  * {@link $context}, which types it by {@link UqlContext}, so a key holding a string never meets a number column.
@@ -39,8 +39,13 @@ export type ContextRefs = string extends ContextKey ? {
39
39
  export type TenantKey<V> = string extends ContextKey ? [contextKey?: ContextRef<V>] : [ContextRef<ContextValue<'tenantId'>>] extends [ContextRef<V>] ? 'tenantId' extends ContextKey ? [contextKey?: ContextRef<V>] : [contextKey: ContextRef<V>] : [contextKey: ContextRef<V>];
40
40
  /** What a policy's predicate interpolates where a query takes SQL: SQL itself, or a context key. */
41
41
  export type PolicySql = QuerySql | ContextKeyRef;
42
- /** A policy's predicate: a `$where` over the entity, its relations included, whose values may read the context. */
43
- export type PolicyWhere<E> = QueryWhere<E, PolicySql>;
42
+ /** A `$where` over the entity, its relations included, whose values may read the context: a filter's, a row's. */
43
+ export type ContextWhere<E> = QueryWhere<E, PolicySql>;
44
+ /**
45
+ * A policy's predicate: a {@link ContextWhere} holding every row a statement touches, and `$old` the row as found or
46
+ * `$new` the row as written alone, grouped as any condition is: `{ $or: [{ $old: { status: 'draft' } }, ...] }`.
47
+ */
48
+ export type PolicyWhere<E> = RowsWhere<QueryWhereFields<E, PolicySql> & Pick<QueryWhereRootOperator<E, PolicySql>, '$text' | '$exists' | '$nexists'>, ContextWhere<E>, PolicySql>;
44
49
  /**
45
50
  * How a policy joins the others holding a statement: rows any `allow` reaches, and of them only those every `must`
46
51
  * holds, Postgres's permissive and restrictive policies. An entity with policies and no `allow` for a statement
@@ -60,8 +65,6 @@ export type PolicyWhen = string extends ContextKey ? {
60
65
  export type PolicyOptions<E> = {
61
66
  /** The statements it holds, every one where unset. An update and a delete are held to the `read` ones too. */
62
67
  readonly ops?: readonly EntityAccess[];
63
- /** What a written row must hold, the predicate itself where unset: Postgres's `WITH CHECK`. */
64
- readonly check?: PolicyWhere<E>;
65
68
  readonly when?: PolicyWhen;
66
69
  /** Names it in the database; derived from its effect and position where unset. */
67
70
  readonly name?: string;
@@ -1,5 +1,5 @@
1
1
  import type { FieldKey, FieldKeyOf, JsonFieldPaths, MethodKey, RelationKey, RelationTarget, ToManyRelationKey, UpdateWrite, WrittenId } from './entity.js';
2
- import type { PolicyWhere } from './policy.js';
2
+ import type { ContextWhere } from './policy.js';
3
3
  import type { QueryLock } from './queryLock.js';
4
4
  import type { QuerySql } from './querySql.js';
5
5
  import type { QueryWhere } from './queryWhere.js';
@@ -110,7 +110,7 @@ export interface UqlContext {
110
110
  * the filter skipped where the context lacks a key it reads; or a function of the ambient {@link UqlContext}, skipped
111
111
  * where it answers `undefined`.
112
112
  */
113
- export type FilterWhere<E> = PolicyWhere<E> | ((context: UqlContext | undefined) => QueryWhere<E> | undefined);
113
+ export type FilterWhere<E> = ContextWhere<E> | ((context: UqlContext | undefined) => QueryWhere<E> | undefined);
114
114
  /** What a field takes: reading it (select, filter, sort, distinct, aggregate) and writing it. */
115
115
  export type FieldAccess = 'read' | 'insert' | 'update';
116
116
  /** What a statement does to an entity's rows: a field's access, and deleting rows, which no field has a part in. */