uql-orm 0.116.3 → 0.116.5

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.
Files changed (39) hide show
  1. package/dist/bunSql/bunSql.util.d.ts +2 -1
  2. package/dist/bunSql/bunSql.util.js +7 -2
  3. package/dist/cockroachdb/cockroachDialect.d.ts +3 -3
  4. package/dist/cockroachdb/cockroachDialect.js +3 -3
  5. package/dist/dialect/abstractSqlDialect.d.ts +3 -1
  6. package/dist/dialect/abstractSqlDialect.js +7 -3
  7. package/dist/migrate/ddl/indexCapabilities.js +18 -3
  8. package/dist/migrate/ddl/pgIndexDdl.d.ts +3 -0
  9. package/dist/migrate/ddl/pgIndexDdl.js +7 -0
  10. package/dist/migrate/introspection/postgresIntrospector.d.ts +7 -3
  11. package/dist/migrate/introspection/postgresIntrospector.js +14 -4
  12. package/dist/migrate/migrationLock.js +2 -1
  13. package/dist/mongodb/mongodbQuerier.d.ts +1 -1
  14. package/dist/mongodb/mongodbQuerier.js +1 -1
  15. package/dist/mssql/mssqlQuerier.d.ts +1 -3
  16. package/dist/mssql/mssqlQuerier.js +2 -13
  17. package/dist/pglite/pgliteQuerier.d.ts +37 -8
  18. package/dist/pglite/pgliteQuerier.js +55 -4
  19. package/dist/pglite/pgliteQuerierPool.d.ts +8 -6
  20. package/dist/pglite/pgliteQuerierPool.js +30 -19
  21. package/dist/postgres/pgExecution.d.ts +3 -2
  22. package/dist/postgres/pgExecution.js +2 -2
  23. package/dist/postgres/pgWireTypes.d.ts +7 -2
  24. package/dist/postgres/pgWireTypes.js +13 -5
  25. package/dist/querier/abstractPoolQuerier.d.ts +2 -2
  26. package/dist/querier/abstractQuerier.d.ts +3 -2
  27. package/dist/querier/abstractQuerier.js +8 -0
  28. package/dist/querier/abstractSqlQuerier.d.ts +17 -12
  29. package/dist/querier/abstractSqlQuerier.js +31 -21
  30. package/dist/querier/queryError.d.ts +2 -0
  31. package/dist/querier/queryError.js +8 -0
  32. package/dist/schema/indexDifferences.d.ts +2 -2
  33. package/dist/schema/indexDifferences.js +4 -0
  34. package/dist/sqlite/hranaQuerier.d.ts +1 -8
  35. package/dist/sqlite/hranaQuerier.js +0 -15
  36. package/dist/type/universalQuerier.d.ts +2 -1
  37. package/dist/util/sql.util.d.ts +2 -1
  38. package/package.json +2 -2
  39. package/skills/uql-orm/SKILL.md +3 -2
@@ -3,6 +3,7 @@ import type { PrimaryKey, RawRow } from '../type/index.js';
3
3
  import type { SqlExecution } from '../util/sql.util.js';
4
4
  /** The header a `bun:sql` result carries next to its rows. */
5
5
  export type BunSqlHeader = {
6
+ command?: string;
6
7
  count?: number;
7
8
  affectedRows?: number | null;
8
9
  lastInsertRowid?: PrimaryKey;
@@ -21,7 +22,7 @@ export type BunSqlDialectName = 'postgres' | 'cockroachdb' | 'mysql' | 'mariadb'
21
22
  /**
22
23
  * A `bun:sql` result as the querier reads it: its rows, each BIGINT decoded exactly; the rows it touched,
23
24
  * `affectedRows` on MySQL (whose `count` is 0 on a write) then `count` on Postgres, `undefined` to leave it to
24
- * the rows; and a MySQL-family insert's id, by the same wide-integer rule.
25
+ * the rows; a MySQL-family insert's id, by the same wide-integer rule; and the command tag.
25
26
  */
26
27
  export declare function bunSqlExecution(res: BunSqlResult): SqlExecution;
27
28
  /**
@@ -3,11 +3,16 @@ import { decodeBigInts, decodeWideNumber } from '../util/wideNumber.js';
3
3
  /**
4
4
  * A `bun:sql` result as the querier reads it: its rows, each BIGINT decoded exactly; the rows it touched,
5
5
  * `affectedRows` on MySQL (whose `count` is 0 on a write) then `count` on Postgres, `undefined` to leave it to
6
- * the rows; and a MySQL-family insert's id, by the same wide-integer rule.
6
+ * the rows; a MySQL-family insert's id, by the same wide-integer rule; and the command tag.
7
7
  */
8
8
  export function bunSqlExecution(res) {
9
9
  const id = typeof res.lastInsertRowid === 'bigint' ? decodeWideNumber(res.lastInsertRowid) : res.lastInsertRowid;
10
- return { rows: Array.from(res, decodeBigInts), changes: res.affectedRows || res.count || undefined, id };
10
+ return {
11
+ rows: Array.from(res, decodeBigInts),
12
+ changes: res.affectedRows || res.count || undefined,
13
+ id,
14
+ command: res.command,
15
+ };
11
16
  }
12
17
  /**
13
18
  * Normalizes `SQL.Options` into what Bun's SQL engine expects for a given dialect: the adapter a
@@ -10,11 +10,11 @@ export declare class CockroachDialect extends PgLikeSqlDialect {
10
10
  rowSecurityApplies(): string;
11
11
  /**
12
12
  * pgvector's but `l1`: `<+>` and `vector_l1_ops` answer "unimplemented: operator class ... is not
13
- * supported" (verified live on v26.2), tracked at https://github.com/cockroachdb/cockroach/issues/147839.
13
+ * supported" (verified live on v26.4), tracked at https://github.com/cockroachdb/cockroach/issues/147839.
14
14
  * Re-check that issue before adding it.
15
15
  */
16
16
  readonly vectorMetrics: Map<import("../type/vector.js").VectorDistance, import("../type/vector.js").VectorMetric>;
17
- /** Neither `regconfig` nor `WEBSEARCH_TO_TSQUERY` exist here (v26.3): the config goes as text, the search as plain words. */
17
+ /** Neither `regconfig` nor `WEBSEARCH_TO_TSQUERY` exist here (v26.4): the config goes as text, the search as plain words. */
18
18
  protected readonly textConfigCast = "";
19
19
  protected readonly textQueryFn = "PLAINTO_TSQUERY";
20
20
  /** Its own beam for either type that builds its vector index; it refuses pgvector's `hnsw.ef_search`. */
@@ -23,7 +23,7 @@ export declare class CockroachDialect extends PgLikeSqlDialect {
23
23
  readonly features: SqlDialectFeatures;
24
24
  /**
25
25
  * Not Postgres' `pg_class.reltuples`, which CockroachDB answers `NULL` for even straight after an
26
- * `ANALYZE` (verified live on v26.2) - it keeps its optimizer's row counts in its own statistics
26
+ * `ANALYZE` (verified live on v26.4) - it keeps its optimizer's row counts in its own statistics
27
27
  * instead, and `SHOW STATISTICS` is how they are read. Bracketed so it can be selected from; the
28
28
  * newest row wins, and a table never analyzed has none at all, which reads as `0`.
29
29
  */
@@ -14,11 +14,11 @@ export class CockroachDialect extends PgLikeSqlDialect {
14
14
  }
15
15
  /**
16
16
  * pgvector's but `l1`: `<+>` and `vector_l1_ops` answer "unimplemented: operator class ... is not
17
- * supported" (verified live on v26.2), tracked at https://github.com/cockroachdb/cockroach/issues/147839.
17
+ * supported" (verified live on v26.4), tracked at https://github.com/cockroachdb/cockroach/issues/147839.
18
18
  * Re-check that issue before adding it.
19
19
  */
20
20
  vectorMetrics = new Map([...PG_VECTOR_METRICS].filter(([metric]) => metric !== 'l1'));
21
- /** Neither `regconfig` nor `WEBSEARCH_TO_TSQUERY` exist here (v26.3): the config goes as text, the search as plain words. */
21
+ /** Neither `regconfig` nor `WEBSEARCH_TO_TSQUERY` exist here (v26.4): the config goes as text, the search as plain words. */
22
22
  textConfigCast = '';
23
23
  textQueryFn = 'PLAINTO_TSQUERY';
24
24
  /** Its own beam for either type that builds its vector index; it refuses pgvector's `hnsw.ef_search`. */
@@ -36,7 +36,7 @@ export class CockroachDialect extends PgLikeSqlDialect {
36
36
  };
37
37
  /**
38
38
  * Not Postgres' `pg_class.reltuples`, which CockroachDB answers `NULL` for even straight after an
39
- * `ANALYZE` (verified live on v26.2) - it keeps its optimizer's row counts in its own statistics
39
+ * `ANALYZE` (verified live on v26.4) - it keeps its optimizer's row counts in its own statistics
40
40
  * instead, and `SHOW STATISTICS` is how they are read. Bracketed so it can be selected from; the
41
41
  * newest row wins, and a table never analyzed has none at all, which reads as `0`.
42
42
  */
@@ -136,7 +136,9 @@ export declare abstract class AbstractSqlDialect extends VectorSqlDialect implem
136
136
  */
137
137
  readonly maxFunctionArgs: number;
138
138
  /** The statements opening a transaction, its modes inline in the `BEGIN` as the Postgres family takes them. */
139
- getBeginTransactionStatements({ isolationLevel, readOnly }?: TransactionOptions): string[];
139
+ getBeginTransactionStatements(opts?: TransactionOptions): string[];
140
+ /** A transaction's modes as the Postgres family spells them after `BEGIN` or `SET TRANSACTION`, `''` for none. */
141
+ transactionModes({ isolationLevel, readOnly }?: TransactionOptions): string;
140
142
  createContext(options?: QueryContextOptions): QueryContext;
141
143
  /** A statement as it is sent: the SQL `build` writes, or a `sql` renders, and the values it binds. */
142
144
  compile(build: QueryBuildFn | QuerySql): {
@@ -145,10 +145,14 @@ export class AbstractSqlDialect extends VectorSqlDialect {
145
145
  */
146
146
  maxFunctionArgs = Infinity;
147
147
  /** The statements opening a transaction, its modes inline in the `BEGIN` as the Postgres family takes them. */
148
- getBeginTransactionStatements({ isolationLevel, readOnly } = {}) {
148
+ getBeginTransactionStatements(opts) {
149
+ const modes = this.transactionModes(opts);
150
+ return [modes ? `${this.beginTransactionCommand} ${modes}` : this.beginTransactionCommand];
151
+ }
152
+ /** A transaction's modes as the Postgres family spells them after `BEGIN` or `SET TRANSACTION`, `''` for none. */
153
+ transactionModes({ isolationLevel, readOnly } = {}) {
149
154
  const modes = [isolationLevel && `ISOLATION LEVEL ${isolationLevel.toUpperCase()}`, readOnly && 'READ ONLY'];
150
- const inline = modes.filter((mode) => typeof mode === 'string');
151
- return [inline.length ? `${this.beginTransactionCommand} ${inline.join(', ')}` : this.beginTransactionCommand];
155
+ return modes.filter((mode) => typeof mode === 'string').join(', ');
152
156
  }
153
157
  createContext(options = {}) {
154
158
  return new SqlQueryContext(this, [], undefined, options.inlineValues);
@@ -9,18 +9,33 @@ function typesWith(types, features) {
9
9
  return new Map(types.map((type) => [type, expressed]));
10
10
  }
11
11
  const DECLARE_VECTOR = "; declare type: 'vector' instead";
12
+ /** What every Postgres index type takes. Only `btree` and `gist` add `INCLUDE`, and only `btree` a nulls order. */
13
+ const PG_INDEX_FEATURES = ['expression', 'partial', 'opsClass', 'jsonPath'];
14
+ /** CockroachDB's, which has no operator class. Neither an inverted nor a vector index takes `INCLUDE`. */
15
+ const CRDB_INDEX_FEATURES = ['expression', 'partial', 'jsonPath'];
12
16
  /** Each engine's {@link IndexCapabilities}, total over the engines. */
13
17
  export const INDEX_CAPABILITIES = {
14
18
  /** Postgres 18's `pg_am`, with pgvector's two, and `fulltext`, which builds a `gin` one. */
15
19
  postgres: {
16
- types: typesWith(['btree', 'hash', 'gin', 'gist', 'brin', 'hnsw', 'ivfflat', 'fulltext'], ['expression', 'partial', 'nullsOrder', 'opsClass', 'include', 'jsonPath']),
20
+ types: new Map([
21
+ ...typesWith(['btree'], [...PG_INDEX_FEATURES, 'include', 'nullsOrder']),
22
+ ...typesWith(['gist'], [...PG_INDEX_FEATURES, 'include']),
23
+ ...typesWith(['hash', 'gin', 'brin', 'hnsw', 'ivfflat', 'fulltext'], PG_INDEX_FEATURES),
24
+ ]),
17
25
  keywords: NONE,
18
26
  hints: NONE,
19
27
  inline: false,
20
28
  },
21
- /** v26.3 answers `hash` and `brin` "unimplemented", `ivfflat` "unrecognized"; no nulls order nor operator class. */
29
+ /**
30
+ * v26.4 answers `brin` "unimplemented" and `ivfflat` "unrecognized". A `hash` index is hash-sharded, spreading
31
+ * sequential keys over 16 buckets, and keys on no computed column.
32
+ */
22
33
  cockroachdb: {
23
- types: typesWith(['btree', 'gin', 'gist', 'hnsw', 'vector', 'fulltext'], ['expression', 'partial', 'include', 'jsonPath']),
34
+ types: new Map([
35
+ ...typesWith(['btree'], [...CRDB_INDEX_FEATURES, 'include']),
36
+ ...typesWith(['hash'], ['partial', 'include']),
37
+ ...typesWith(['gin', 'gist', 'hnsw', 'vector', 'fulltext'], CRDB_INDEX_FEATURES),
38
+ ]),
24
39
  keywords: new Map([['vector', 'VECTOR INDEX']]),
25
40
  hints: new Map([['ivfflat', DECLARE_VECTOR]]),
26
41
  inline: true,
@@ -17,6 +17,9 @@ export declare class PgIndexDdl extends IndexDdl {
17
17
  /** CockroachDB's native `CREATE VECTOR INDEX`, for `type: 'vector'`; it has neither `NULLS FIRST/LAST` nor `jsonb_path_ops`. */
18
18
  export declare class CockroachIndexDdl extends PgIndexDdl {
19
19
  protected isVectorIndex(index: IndexSchema): boolean;
20
+ /** Hash-sharded: `(a) USING hash INCLUDE (b)`, since `USING hash (a)` answers "unimplemented". */
21
+ protected indexAccessMethod(index: IndexSchema): string;
22
+ protected indexInclude(index: IndexSchema): string;
20
23
  /** Its build-time candidate list alone: pgvector's `WITH (m = 16)` answers "invalid storage parameter", `hnsw` included. */
21
24
  protected indexTuning(index: IndexSchema): string;
22
25
  }
@@ -54,6 +54,13 @@ export class CockroachIndexDdl extends PgIndexDdl {
54
54
  isVectorIndex(index) {
55
55
  return index.type === 'vector' || super.isVectorIndex(index);
56
56
  }
57
+ /** Hash-sharded: `(a) USING hash INCLUDE (b)`, since `USING hash (a)` answers "unimplemented". */
58
+ indexAccessMethod(index) {
59
+ return index.type === 'hash' ? '' : super.indexAccessMethod(index);
60
+ }
61
+ indexInclude(index) {
62
+ return (index.type === 'hash' ? ' USING hash' : '') + super.indexInclude(index);
63
+ }
57
64
  /** Its build-time candidate list alone: pgvector's `WITH (m = 16)` answers "invalid storage parameter", `hnsw` included. */
58
65
  indexTuning(index) {
59
66
  return this.isVectorIndex(index) && index.efConstruction !== undefined
@@ -35,6 +35,8 @@ export declare class PostgresSchemaIntrospector extends AbstractSqlSchemaIntrosp
35
35
  protected getColumns(read: TableRowReader, tableName: string): Promise<ReadColumn[]>;
36
36
  /** Whether `information_schema.columns c` lists a column the table shows: every one, on Postgres. */
37
37
  protected readonly visibleColumnSql: QuerySql;
38
+ /** Whether index entry `a` is a column the table shows, or an expression: every one, on Postgres. */
39
+ protected readonly visibleIndexEntrySql: QuerySql;
38
40
  /**
39
41
  * `attname` where the entry is a column, `pg_get_indexdef` for that one position where it is an
40
42
  * expression. Neither alone will do: an expression entry has `attnum = 0`, so joining `pg_attribute`
@@ -72,7 +74,7 @@ export declare class PostgresSchemaIntrospector extends AbstractSqlSchemaIntrosp
72
74
  protected isAutoIncrement(columnDefault: string | null, isIdentity: string): boolean;
73
75
  }
74
76
  /**
75
- * CockroachDB answers the same catalogue queries and differs only in what it can express: v26.2.5
77
+ * CockroachDB answers the same catalogue queries and differs only in what it can express: v26.4
76
78
  * still rejects `NULLS FIRST/LAST` and operator classes as "unimplemented", and it sorts nulls first
77
79
  * on an ASC column where Postgres sorts them last. Reading a nulls order back would therefore report
78
80
  * every ascending index as drifted, against an entity that could not have asked for one.
@@ -81,11 +83,13 @@ export declare class CockroachSchemaIntrospector extends PostgresSchemaIntrospec
81
83
  protected readonly indexFacets: ReadonlySet<IndexFacet>;
82
84
  /** Not `rowid`, the `NOT VISIBLE` key it gives a table declared without one, which no entity can name. */
83
85
  protected readonly visibleColumnSql: QuerySql;
86
+ /** Not the hidden shard column a hash-sharded index keys on first. */
87
+ protected readonly visibleIndexEntrySql: QuerySql;
84
88
  /** None: it rejects a stated nulls order, so reading one back gives an index it would refuse to rebuild. */
85
89
  protected readonly nullsFirstSql: QuerySql;
86
90
  /**
87
- * Every index reports the access method `prefix` and no operator class, so a vector index is read off
88
- * its definition, `USING cspann (vec vector_cosine_ops)`: its type, and its last key's class.
91
+ * Every index reports the access method `prefix` and no operator class, so its type is read off its definition:
92
+ * `USING cspann (vec vector_cosine_ops)` a vector one, with its last key's class, and `(a) USING HASH` a hash one.
89
93
  */
90
94
  protected readonly indexMethodSql: QuerySql;
91
95
  protected readonly opsClassSql: QuerySql;
@@ -132,6 +132,8 @@ export class PostgresSchemaIntrospector extends AbstractSqlSchemaIntrospector {
132
132
  }
133
133
  /** Whether `information_schema.columns c` lists a column the table shows: every one, on Postgres. */
134
134
  visibleColumnSql = sql `TRUE`;
135
+ /** Whether index entry `a` is a column the table shows, or an expression: every one, on Postgres. */
136
+ visibleIndexEntrySql = sql `TRUE`;
135
137
  /**
136
138
  * `attname` where the entry is a column, `pg_get_indexdef` for that one position where it is an
137
139
  * expression. Neither alone will do: an expression entry has `attnum = 0`, so joining `pg_attribute`
@@ -170,6 +172,7 @@ export class PostgresSchemaIntrospector extends AbstractSqlSchemaIntrospector {
170
172
  AND NOT EXISTS (
171
173
  SELECT 1 FROM pg_constraint con WHERE con.conindid = ix.indexrelid AND con.contype = 'x'
172
174
  )
175
+ AND ${this.visibleIndexEntrySql}
173
176
  ORDER BY i.relname, k.n
174
177
  `);
175
178
  // One row per index entry, ordered by position, so the rows of an index are its entries in order.
@@ -345,7 +348,7 @@ function mapIndexEntry(row) {
345
348
  };
346
349
  }
347
350
  /**
348
- * CockroachDB answers the same catalogue queries and differs only in what it can express: v26.2.5
351
+ * CockroachDB answers the same catalogue queries and differs only in what it can express: v26.4
349
352
  * still rejects `NULLS FIRST/LAST` and operator classes as "unimplemented", and it sorts nulls first
350
353
  * on an ASC column where Postgres sorts them last. Reading a nulls order back would therefore report
351
354
  * every ascending index as drifted, against an entity that could not have asked for one.
@@ -356,15 +359,22 @@ export class CockroachSchemaIntrospector extends PostgresSchemaIntrospector {
356
359
  'include',
357
360
  'vector',
358
361
  'distance',
362
+ 'hash',
359
363
  ]);
360
364
  /** Not `rowid`, the `NOT VISIBLE` key it gives a table declared without one, which no entity can name. */
361
365
  visibleColumnSql = sql `c.is_hidden = 'NO'`;
366
+ /** Not the hidden shard column a hash-sharded index keys on first. */
367
+ visibleIndexEntrySql = sql `(a.attname IS NULL OR NOT EXISTS (
368
+ SELECT 1 FROM information_schema.columns c
369
+ WHERE c.table_schema = n.nspname AND c.table_name = t.relname AND c.column_name = a.attname AND c.is_hidden = 'YES'
370
+ ))`;
362
371
  /** None: it rejects a stated nulls order, so reading one back gives an index it would refuse to rebuild. */
363
372
  nullsFirstSql = sql `NULL::BOOL`;
364
373
  /**
365
- * Every index reports the access method `prefix` and no operator class, so a vector index is read off
366
- * its definition, `USING cspann (vec vector_cosine_ops)`: its type, and its last key's class.
374
+ * Every index reports the access method `prefix` and no operator class, so its type is read off its definition:
375
+ * `USING cspann (vec vector_cosine_ops)` a vector one, with its last key's class, and `(a) USING HASH` a hash one.
367
376
  */
368
- indexMethodSql = sql `CASE WHEN pg_get_indexdef(ix.indexrelid) LIKE '% USING cspann %' THEN 'vector' ELSE am.amname END`;
377
+ indexMethodSql = sql `CASE substring(pg_get_indexdef(ix.indexrelid) from ' USING (cspann|HASH)')
378
+ WHEN 'cspann' THEN 'vector' WHEN 'HASH' THEN 'hash' ELSE am.amname END`;
369
379
  opsClassSql = sql `CASE WHEN k.n = ix.indnkeyatts THEN substring(pg_get_indexdef(ix.indexrelid) from '(\\w+_ops)\\)') END`;
370
380
  }
@@ -15,7 +15,8 @@ const mysqlLock = (name) => {
15
15
  };
16
16
  /**
17
17
  * The journal's lock row, inserted only where it is absent, which one run alone can: the lock of an engine with no
18
- * named one. CockroachDB's write to it cannot stay uncommitted for the run, which a function it creates would wait on.
18
+ * usable named one. CockroachDB's advisory lock held for a session excludes nobody, and one held by a transaction, or
19
+ * an uncommitted write to this row, stalls the run's own DDL on its other connection (verified on v26.4).
19
20
  */
20
21
  const journalRowLock = (name) => {
21
22
  const { table, name: column } = journalIds(name);
@@ -36,7 +36,7 @@ export declare class MongodbQuerier extends AbstractQuerier implements MongoQuer
36
36
  * The collection's metadata count, which the driver exposes as its own call and which takes no
37
37
  * filter - the reason {@link UniversalQuerier.estimatedCount} takes none either.
38
38
  */
39
- estimatedCount<E extends Document>(entity: Type<E>): Promise<number>;
39
+ protected internalEstimatedCount<E extends Document>(entity: Type<E>): Promise<number>;
40
40
  internalInsertMany<E extends Document>(entity: Type<E>, rows: EntityData<E>[]): Promise<void>;
41
41
  internalUpdateMany<E extends Document>(entity: Type<E>, qm: QuerySearch<E>, payload: UpdatePayload<E>, opts?: StatementOptions): Promise<number>;
42
42
  /** The filter and update of an update of the documents matching `where` with `payload`, its `onUpdate` fills included. */
@@ -134,7 +134,7 @@ export class MongodbQuerier extends AbstractQuerier {
134
134
  * The collection's metadata count, which the driver exposes as its own call and which takes no
135
135
  * filter - the reason {@link UniversalQuerier.estimatedCount} takes none either.
136
136
  */
137
- async estimatedCount(entity) {
137
+ async internalEstimatedCount(entity) {
138
138
  return this.execute('estimatedCount', (session) => this.collection(entity).estimatedDocumentCount({ session }));
139
139
  }
140
140
  async internalInsertMany(entity, rows) {
@@ -41,7 +41,7 @@ export type MsSqlConnection = {
41
41
  * own pool and hands out `Request`s, so what UQL holds is the pool plus, once a transaction opens,
42
42
  * the `Transaction` every later request has to be bound to.
43
43
  */
44
- export declare class MsSqlQuerier extends AbstractPoolQuerier<MsSqlConnection> {
44
+ export declare class MsSqlQuerier extends AbstractPoolQuerier<MsSqlConnection, MsSqlTransaction> {
45
45
  #private;
46
46
  /**
47
47
  * `rowsAffected` carries one entry per statement, and a write runs in a batch of several - the table variable
@@ -61,8 +61,6 @@ export declare class MsSqlQuerier extends AbstractPoolQuerier<MsSqlConnection> {
61
61
  * the level goes to its `begin`: sent as a statement it would land on whichever connection served it.
62
62
  */
63
63
  protected internalBegin(opts?: TransactionOptions): Promise<void>;
64
- protected internalCommit(): Promise<void>;
65
- protected internalRollback(): Promise<void>;
66
64
  /**
67
65
  * The pool owns the socket, so there is nothing to hand back: `release` has already rolled back a
68
66
  * transaction left open, and commit and rollback both drop the `Transaction` they end.
@@ -8,14 +8,13 @@ import { decodeWireTypes } from './mssqlWireTypes.js';
8
8
  * the `Transaction` every later request has to be bound to.
9
9
  */
10
10
  export class MsSqlQuerier extends AbstractPoolQuerier {
11
- #transaction;
12
11
  /**
13
12
  * Values bind by name, `@p1` upward, matching {@link MsSqlDialect.placeholder}. `mssql` infers a type
14
13
  * from the JS value, right for a `Uint8Array` and harmlessly wrong for a bare `null` (`NVarChar`), but
15
14
  * a `Date` it binds as the legacy `DATETIME`, whose 1/300 s steps no `DATETIME2` column compares equal to.
16
15
  */
17
16
  #request(values) {
18
- const request = this.#transaction ? this.#transaction.request() : this.getConn().request();
17
+ const request = (this.tx ?? this.getConn()).request();
19
18
  values?.forEach((value, index) => {
20
19
  const name = `p${index + 1}`;
21
20
  return value instanceof Date ? request.input(name, mssql.DateTime2, value) : request.input(name, value);
@@ -63,17 +62,7 @@ export class MsSqlQuerier extends AbstractPoolQuerier {
63
62
  async internalBegin(opts) {
64
63
  const transaction = this.getConn().transaction();
65
64
  await transaction.begin(opts?.isolationLevel && mssql.ISOLATION_LEVEL[ISOLATION[opts.isolationLevel]]);
66
- this.#transaction = transaction;
67
- }
68
- async internalCommit() {
69
- const transaction = this.#transaction;
70
- this.#transaction = undefined;
71
- await transaction?.commit();
72
- }
73
- async internalRollback() {
74
- const transaction = this.#transaction;
75
- this.#transaction = undefined;
76
- await transaction?.rollback();
65
+ this.tx = transaction;
77
66
  }
78
67
  /**
79
68
  * The pool owns the socket, so there is nothing to hand back: `release` has already rolled back a
@@ -1,23 +1,52 @@
1
1
  import { type PgResult } from '../postgres/pgExecution.js';
2
- import { AbstractSqlQuerier } from '../querier/index.js';
3
- import type { ExtraOptions } from '../type/index.js';
2
+ import { AbstractSqlQuerier, type TransactionHandle } from '../querier/abstractSqlQuerier.js';
3
+ import type { ExtraOptions, TransactionOptions } from '../type/index.js';
4
4
  import type { SqlExecution } from '../util/sql.util.js';
5
5
  import type { PgliteDialect } from './pgliteDialect.js';
6
- /** The two methods uql uses of `@electric-sql/pglite`, stated so its published types do not depend on a pre-1.0 package. */
7
- export type PgliteDatabase = {
8
- query(query: string, params?: unknown[]): Promise<PgResult>;
6
+ type Decode = (text: string) => unknown;
7
+ /** How one statement's rows decode, by type OID, over the handle's own parsers. */
8
+ export type PgliteQueryOptions = {
9
+ readonly parsers: Readonly<Record<number, Decode>>;
10
+ };
11
+ /** What runs a statement on PGlite: the handle, or a transaction open on it. */
12
+ type PgliteExecutor = {
13
+ query(query: string, params?: unknown[], options?: PgliteQueryOptions): Promise<PgResult>;
14
+ };
15
+ /**
16
+ * The part of `@electric-sql/pglite` uql uses, stated so its published types do not depend on a pre-1.0 package:
17
+ * a `PGlite`, or a `PGliteWorker` sharing one across tabs.
18
+ */
19
+ export type PgliteDatabase = PgliteExecutor & {
20
+ readonly parsers: Readonly<Partial<Record<number, Decode>>>;
21
+ transaction<T>(run: (tx: PgliteOpenTransaction) => Promise<T>): Promise<T>;
9
22
  close(): Promise<void>;
10
23
  };
24
+ /** A transaction PGlite runs a callback in. */
25
+ type PgliteOpenTransaction = PgliteExecutor & {
26
+ rollback(): Promise<void>;
27
+ };
28
+ type PgliteTransaction = PgliteExecutor & TransactionHandle;
11
29
  /**
12
30
  * Querier for PGlite, Postgres compiled to WASM and run in this process.
13
31
  *
14
32
  * @remarks Extends {@link AbstractSqlQuerier} rather than `PgQuerier`, whose stream needs `pg-query-stream`,
15
- * which PGlite's client cannot run. `BEGIN`/`COMMIT` are plain statements on the single connection.
33
+ * which PGlite's client cannot run.
16
34
  */
17
- export declare class PgliteQuerier extends AbstractSqlQuerier {
35
+ export declare class PgliteQuerier extends AbstractSqlQuerier<PgliteTransaction> {
18
36
  readonly db: PgliteDatabase;
19
- constructor(db: PgliteDatabase, dialect: PgliteDialect, extra?: ExtraOptions);
37
+ /** Passed with each statement on a handle the pool did not open, whose own parsers stay its owner's. */
38
+ private readonly queryOptions?;
39
+ constructor(db: PgliteDatabase, dialect: PgliteDialect, extra?: ExtraOptions,
40
+ /** Passed with each statement on a handle the pool did not open, whose own parsers stay its owner's. */
41
+ queryOptions?: PgliteQueryOptions | undefined);
20
42
  /** Every querier of the pool is this one handle's session, so they share its transaction. */
21
43
  protected get connection(): object;
44
+ /** On the transaction its session holds, which only the flow holding it reaches here: every other waits its turn. */
22
45
  protected execute(sql: string, values?: unknown[]): Promise<SqlExecution>;
46
+ /**
47
+ * Through PGlite's own `transaction`, the one lock every caller of the handle respects, another tab's included.
48
+ * One that cannot take its modes is rolled back, or its lock would hold the handle for good.
49
+ */
50
+ protected internalBegin(opts?: TransactionOptions): Promise<void>;
23
51
  }
52
+ export {};
@@ -1,22 +1,73 @@
1
1
  import { pgExecution } from '../postgres/pgExecution.js';
2
- import { AbstractSqlQuerier } from '../querier/index.js';
2
+ import { AbstractSqlQuerier } from '../querier/abstractSqlQuerier.js';
3
+ import { slotOf } from '../querier/transaction.js';
3
4
  /**
4
5
  * Querier for PGlite, Postgres compiled to WASM and run in this process.
5
6
  *
6
7
  * @remarks Extends {@link AbstractSqlQuerier} rather than `PgQuerier`, whose stream needs `pg-query-stream`,
7
- * which PGlite's client cannot run. `BEGIN`/`COMMIT` are plain statements on the single connection.
8
+ * which PGlite's client cannot run.
8
9
  */
9
10
  export class PgliteQuerier extends AbstractSqlQuerier {
10
11
  db;
11
- constructor(db, dialect, extra) {
12
+ queryOptions;
13
+ constructor(db, dialect, extra,
14
+ /** Passed with each statement on a handle the pool did not open, whose own parsers stay its owner's. */
15
+ queryOptions) {
12
16
  super(dialect, extra);
13
17
  this.db = db;
18
+ this.queryOptions = queryOptions;
14
19
  }
15
20
  /** Every querier of the pool is this one handle's session, so they share its transaction. */
16
21
  get connection() {
17
22
  return this.db;
18
23
  }
24
+ /** On the transaction its session holds, which only the flow holding it reaches here: every other waits its turn. */
19
25
  async execute(sql, values) {
20
- return pgExecution(await this.db.query(sql, values));
26
+ const holder = slotOf(this.db).held?.scope.querier;
27
+ const on = (holder instanceof PgliteQuerier && holder.tx) || this.db;
28
+ return pgExecution(await on.query(sql, values, this.queryOptions));
21
29
  }
30
+ /**
31
+ * Through PGlite's own `transaction`, the one lock every caller of the handle respects, another tab's included.
32
+ * One that cannot take its modes is rolled back, or its lock would hold the handle for good.
33
+ */
34
+ async internalBegin(opts) {
35
+ const tx = await hold(this.db);
36
+ const modes = this.dialect.transactionModes(opts);
37
+ if (modes) {
38
+ try {
39
+ await tx.query(`SET TRANSACTION ${modes}`);
40
+ }
41
+ catch (err) {
42
+ await tx.rollback();
43
+ throw err;
44
+ }
45
+ }
46
+ this.tx = tx;
47
+ }
48
+ }
49
+ /**
50
+ * Opens a transaction on `db` that stays open until its handle ends it: PGlite's own runs a callback, which
51
+ * waits here for the commit or rollback. PGlite commits it, refusing one a failed statement aborted.
52
+ */
53
+ async function hold(db) {
54
+ const opened = Promise.withResolvers();
55
+ const decided = Promise.withResolvers();
56
+ const ended = db.transaction(async (tx) => {
57
+ opened.resolve(tx);
58
+ if (!(await decided.promise)) {
59
+ await tx.rollback();
60
+ }
61
+ });
62
+ ended.catch(opened.reject);
63
+ const tx = await opened.promise;
64
+ const end = (commit) => {
65
+ decided.resolve(commit);
66
+ return ended;
67
+ };
68
+ return {
69
+ query: (sql, values, options) => tx.query(sql, values, options),
70
+ commit: () => end(true),
71
+ rollback: () => end(false),
72
+ };
22
73
  }
@@ -5,15 +5,17 @@ import { PgliteDialect } from './pgliteDialect.js';
5
5
  import { type PgliteDatabase, PgliteQuerier } from './pgliteQuerier.js';
6
6
  /** PGlite's own options but `dataDir`, the pool's first argument; `extensions: { vector }` enables pgvector. Type-only. */
7
7
  export type PglitePoolOptions = Except<PGliteOptions, 'dataDir'>;
8
+ /** Opens the handle a pool runs on, as a `PGliteWorker` sharing one database across tabs: `() => PGliteWorker.create(worker)`. */
9
+ export type PgliteOpen = () => Promise<PgliteDatabase>;
8
10
  /**
9
- * A pool for PGlite, Postgres in WASM in this process, on one connection. A second `BEGIN` silently joins
10
- * the open transaction, so a unit of work needing its own needs its own pool. Transactions are plain
11
- * statements, so pass `relaxedDurability` on a persistent `dataDir` to skip a flush per statement.
11
+ * A pool for PGlite, Postgres in WASM, on one connection: a `dataDir` it opens, or a handle `open` answers. Its
12
+ * transactions hold PGlite's own lock, which every caller of the handle waits on, another tab's included. Pass
13
+ * `relaxedDurability` on a persistent `dataDir` to skip a flush per statement.
12
14
  */
13
15
  export declare class PgliteQuerierPool extends AbstractSharedHandleQuerierPool<PgliteDatabase, PgliteQuerier, PgliteDialect> {
14
- readonly dataDir: string;
15
- readonly opts?: PglitePoolOptions | undefined;
16
- constructor(dataDir?: string, opts?: PglitePoolOptions | undefined, extra?: ExtraOptions);
16
+ #private;
17
+ constructor(dataDir?: string, opts?: PglitePoolOptions, extra?: ExtraOptions);
18
+ constructor(open: PgliteOpen, extra?: ExtraOptions);
17
19
  protected openDb(): Promise<PgliteDatabase>;
18
20
  protected buildQuerier(db: PgliteDatabase): PgliteQuerier;
19
21
  }
@@ -1,32 +1,43 @@
1
1
  import { dialectOptionsFrom } from '../dialect/abstractDialect.js';
2
- import { PG_DECODERS } from '../postgres/pgWireTypes.js';
2
+ import { PG_DECODERS, wireDecoders } from '../postgres/pgWireTypes.js';
3
3
  import { AbstractSharedHandleQuerierPool } from '../querier/abstractSharedHandleQuerierPool.js';
4
4
  import { PgliteDialect } from './pgliteDialect.js';
5
5
  import { PgliteQuerier } from './pgliteQuerier.js';
6
+ function openedByCaller(args) {
7
+ return typeof args[0] === 'function';
8
+ }
6
9
  /**
7
- * A pool for PGlite, Postgres in WASM in this process, on one connection. A second `BEGIN` silently joins
8
- * the open transaction, so a unit of work needing its own needs its own pool. Transactions are plain
9
- * statements, so pass `relaxedDurability` on a persistent `dataDir` to skip a flush per statement.
10
+ * A pool for PGlite, Postgres in WASM, on one connection: a `dataDir` it opens, or a handle `open` answers. Its
11
+ * transactions hold PGlite's own lock, which every caller of the handle waits on, another tab's included. Pass
12
+ * `relaxedDurability` on a persistent `dataDir` to skip a flush per statement.
10
13
  */
11
14
  export class PgliteQuerierPool extends AbstractSharedHandleQuerierPool {
12
- dataDir;
13
- opts;
14
- constructor(dataDir = 'memory://', opts, extra) {
15
+ #open;
16
+ /** uql's decoders, sent with each statement on a handle the caller opened, whose own parsers stay its owner's. */
17
+ #queryOptions;
18
+ constructor(...args) {
19
+ const byCaller = openedByCaller(args);
20
+ const extra = byCaller ? args[1] : args[2];
15
21
  super(new PgliteDialect(dialectOptionsFrom(extra)), extra);
16
- this.dataDir = dataDir;
17
- this.opts = opts;
22
+ this.#open = byCaller ? () => this.#decodingPerQuery(args[0]) : () => openPglite(args[0], args[1]);
23
+ }
24
+ openDb() {
25
+ return this.#open();
18
26
  }
19
- async openDb() {
20
- const { PGlite } = await import('@electric-sql/pglite');
21
- // Every Postgres-wire pool's decoders, which PGlite applies to an array's elements too; a caller's own
22
- // `parsers` still win. The declared return type is what checks {@link PgliteDatabase} against the real
23
- // driver, so no cast is needed below it.
24
- return PGlite.create(this.dataDir, {
25
- ...this.opts,
26
- parsers: { ...Object.fromEntries(PG_DECODERS), ...this.opts?.parsers },
27
- });
27
+ async #decodingPerQuery(open) {
28
+ const db = await open();
29
+ this.#queryOptions = { parsers: Object.fromEntries(wireDecoders((oid) => db.parsers[oid] ?? String)) };
30
+ return db;
28
31
  }
29
32
  buildQuerier(db) {
30
- return new PgliteQuerier(db, this.dialect, this.extra);
33
+ return new PgliteQuerier(db, this.dialect, this.extra, this.#queryOptions);
31
34
  }
32
35
  }
36
+ /**
37
+ * PGlite with every Postgres-wire pool's decoders, which it applies to an array's elements too, a caller's own
38
+ * `parsers` overriding them.
39
+ */
40
+ async function openPglite(dataDir = 'memory://', opts) {
41
+ const { PGlite } = await import('@electric-sql/pglite');
42
+ return PGlite.create(dataDir, { ...opts, parsers: { ...Object.fromEntries(PG_DECODERS), ...opts?.parsers } });
43
+ }
@@ -1,8 +1,9 @@
1
1
  import type { RawRow } from '../type/index.js';
2
2
  import type { SqlExecution } from '../util/sql.util.js';
3
- /** A Postgres-wire result as the querier reads it: its rows, and its command tag's count. */
3
+ /** A Postgres-wire result as the querier reads it: its rows, and its command tag, named and counted. */
4
4
  export type PgResult = {
5
5
  readonly rows: RawRow[];
6
6
  readonly rowCount?: number | null;
7
+ readonly command?: string | null;
7
8
  };
8
- export declare function pgExecution({ rows, rowCount }: PgResult): SqlExecution;
9
+ export declare function pgExecution({ rows, rowCount, command }: PgResult): SqlExecution;
@@ -1,3 +1,3 @@
1
- export function pgExecution({ rows, rowCount }) {
2
- return { rows, changes: rowCount };
1
+ export function pgExecution({ rows, rowCount, command }) {
2
+ return { rows, changes: rowCount, command };
3
3
  }
@@ -15,8 +15,13 @@ type Decode = (text: string) => unknown;
15
15
  */
16
16
  export declare const PG_DECODERS: ReadonlyMap<number, Decode>;
17
17
  /**
18
- * {@link PG_DECODERS} as `pg`'s text-format parsers, an array decoding each element as its scalar does.
19
- * At the wire, which every result crosses; per pool, never a global parser, and a caller's own `types` win.
18
+ * {@link PG_DECODERS} and each array of {@link ELEMENT_OIDS}, decoding each element as its scalar does, over the
19
+ * text parsers a driver answers by OID: its `TEXT[]` one splits the array, its own decodes a `NUMERIC`.
20
+ */
21
+ export declare function wireDecoders(textParser: (oid: number) => Decode): Map<number, Decode>;
22
+ /**
23
+ * {@link wireDecoders} as `pg`'s text-format parsers. At the wire, which every result crosses; per pool, never
24
+ * a global parser, and a caller's own `types` win.
20
25
  */
21
26
  export declare function wireTypes(types: PgTypes): CustomTypesConfig;
22
27
  export {};
@@ -33,16 +33,24 @@ const ELEMENT_OIDS = new Map([
33
33
  [OID.NUMERIC_ARRAY, OID.NUMERIC],
34
34
  ]);
35
35
  /**
36
- * {@link PG_DECODERS} as `pg`'s text-format parsers, an array decoding each element as its scalar does.
37
- * At the wire, which every result crosses; per pool, never a global parser, and a caller's own `types` win.
36
+ * {@link PG_DECODERS} and each array of {@link ELEMENT_OIDS}, decoding each element as its scalar does, over the
37
+ * text parsers a driver answers by OID: its `TEXT[]` one splits the array, its own decodes a `NUMERIC`.
38
38
  */
39
- export function wireTypes(types) {
40
- const splitArray = types.getTypeParser(OID.TEXT_ARRAY, 'text');
39
+ export function wireDecoders(textParser) {
40
+ const splitArray = textParser(OID.TEXT_ARRAY);
41
41
  const decoders = new Map(PG_DECODERS);
42
42
  for (const [arrayOid, oid] of ELEMENT_OIDS) {
43
- const decode = PG_DECODERS.get(oid) ?? types.getTypeParser(oid, 'text');
43
+ const decode = PG_DECODERS.get(oid) ?? textParser(oid);
44
44
  decoders.set(arrayOid, (text) => decodeElements(splitArray(text), decode));
45
45
  }
46
+ return decoders;
47
+ }
48
+ /**
49
+ * {@link wireDecoders} as `pg`'s text-format parsers. At the wire, which every result crosses; per pool, never
50
+ * a global parser, and a caller's own `types` win.
51
+ */
52
+ export function wireTypes(types) {
53
+ const decoders = wireDecoders((oid) => types.getTypeParser(oid, 'text'));
46
54
  return {
47
55
  // Text only: in binary mode an INT8 arrives as an 8-byte Buffer, and `Number(buffer)` is `NaN`.
48
56
  getTypeParser: (oid, format) => (format === 'text' && decoders.get(oid)) || types.getTypeParser(oid, format),
@@ -1,7 +1,7 @@
1
1
  import type { AbstractSqlDialect } from '../dialect/index.js';
2
2
  import type { ExtraOptions } from '../type/index.js';
3
- import { AbstractSqlQuerier } from './abstractSqlQuerier.js';
4
- export declare abstract class AbstractPoolQuerier<C> extends AbstractSqlQuerier {
3
+ import { AbstractSqlQuerier, type TransactionHandle } from './abstractSqlQuerier.js';
4
+ export declare abstract class AbstractPoolQuerier<C, Tx extends TransactionHandle = TransactionHandle> extends AbstractSqlQuerier<Tx> {
5
5
  protected readonly connect: () => Promise<C>;
6
6
  protected conn: C | undefined;
7
7
  protected getConn(): C;
@@ -113,8 +113,9 @@ export declare abstract class AbstractQuerier implements Querier {
113
113
  }, Q>, opts?: QueryOptions): Promise<QueryAggregateResult<E, Q>[]>;
114
114
  aggregate<E extends object, const Q extends QueryAggregate<E>>(entity: Type<E>, q: Captured<QueryAggregate<E, Q>, Q>, opts?: QueryOptions): Promise<QueryAggregateResult<E, Q>[]>;
115
115
  protected abstract internalAggregate<E extends object>(entity: Type<E>, q: QueryAggregate<E>, opts?: QueryOptions): Promise<RawRow[]>;
116
- /** Abstract outright: nothing is shared to do around it. See {@link UniversalQuerier.estimatedCount}. */
117
- abstract estimatedCount<E extends object>(entity: Type<E>): Promise<number>;
116
+ /** See {@link UniversalQuerier.estimatedCount}, refused where the pool holds the entity's policies, as CockroachDB's is. */
117
+ estimatedCount<E extends object>(entity: Type<E>): Promise<number>;
118
+ protected abstract internalEstimatedCount<E extends object>(entity: Type<E>): Promise<number>;
118
119
  insertOne<E extends object, const S extends FieldKey<E> = never, const V extends BooleanLike = true, const W extends boolean = false>(entity: Type<E>, payload: EntityWrite<E>, opts?: WriteOptions<E, S, V, W>): Promise<WriteResults<E, S, V, W>['written']>;
119
120
  insertMany<E extends object, const S extends FieldKey<E> = never, const V extends BooleanLike = true, const W extends boolean = false>(entity: Type<E>, payload: readonly EntityWrite<E>[], opts?: WriteOptions<E, S, V, W>): Promise<WriteResults<E, S, V, W>['written'][]>;
120
121
  /**
@@ -334,6 +334,14 @@ export class AbstractQuerier {
334
334
  aggregate(...args) {
335
335
  return this.internalAggregate(...entityArgs(args));
336
336
  }
337
+ /** See {@link UniversalQuerier.estimatedCount}, refused where the pool holds the entity's policies, as CockroachDB's is. */
338
+ async estimatedCount(entity) {
339
+ const { scopes, database } = this.dialect.policies;
340
+ if ((scopes || database) && getMeta(entity).policies?.length) {
341
+ throw new UqlSecurityError(`cannot estimate '${entity.name}', which its policies hold: count it instead`);
342
+ }
343
+ return this.internalEstimatedCount(entity);
344
+ }
337
345
  async insertOne(entity, payload, opts) {
338
346
  const [written] = await this.insertWritten(entity, [payload], opts);
339
347
  return written;
@@ -2,10 +2,21 @@ import type { AbstractSqlDialect } from '../dialect/index.js';
2
2
  import type { EntityData, EntityMeta, ExtraOptions, WrittenId, Query, QueryAggregate, QueryUpsert, QueryPage, StatementOptions, QuerySearch, QueryUpdateResult, RawRow, SavepointCommand, SqlQuerier, SqlStatement, Type, TransactionOptions, UpdatePayload, BoundStatement, ReportedWrite } from '../type/index.js';
3
3
  import type { SqlExecution } from '../util/sql.util.js';
4
4
  import { AbstractQuerier, type ReportingWrites } from './abstractQuerier.js';
5
- export declare abstract class AbstractSqlQuerier extends AbstractQuerier implements SqlQuerier {
5
+ /**
6
+ * A transaction a driver holds as an object rather than statements: Hrana's session, `mssql`'s `Transaction`,
7
+ * PGlite's lock. Its `internalBegin` sets {@link AbstractSqlQuerier.tx}, of the type its querier names, and its
8
+ * statements run on it.
9
+ */
10
+ export type TransactionHandle = {
11
+ commit(): Promise<unknown>;
12
+ rollback(): Promise<unknown>;
13
+ };
14
+ export declare abstract class AbstractSqlQuerier<Tx extends TransactionHandle = TransactionHandle> extends AbstractQuerier implements SqlQuerier {
6
15
  #private;
7
16
  readonly dialect: AbstractSqlDialect;
8
17
  hasOpenTransaction: boolean;
18
+ /** The open transaction, where the driver holds it as a {@link TransactionHandle}. */
19
+ protected tx?: Tx;
9
20
  constructor(dialect: AbstractSqlDialect, extra?: ExtraOptions);
10
21
  /** Runs one statement on the driver: what it read, how many rows it changed, and any id its header reports. */
11
22
  protected abstract execute(sql: string, values?: unknown[]): Promise<SqlExecution>;
@@ -112,7 +123,7 @@ export declare abstract class AbstractSqlQuerier extends AbstractQuerier impleme
112
123
  */
113
124
  private runCount;
114
125
  protected internalCount<E extends object>(entity: Type<E>, q: QueryPage<E>, opts?: StatementOptions): Promise<number>;
115
- estimatedCount<E extends object>(entity: Type<E>): Promise<number>;
126
+ protected internalEstimatedCount<E extends object>(entity: Type<E>): Promise<number>;
116
127
  protected internalAggregate<E extends object>(entity: Type<E>, q: QueryAggregate<E>, opts?: StatementOptions): Promise<RawRow[]>;
117
128
  internalInsertMany<E extends object>(entity: Type<E>, rows: EntityData<E>[]): Promise<void>;
118
129
  /**
@@ -157,21 +168,15 @@ export declare abstract class AbstractSqlQuerier extends AbstractQuerier impleme
157
168
  protected internalDeleteMany<E extends object>(entity: Type<E>, q: QuerySearch<E>, opts?: StatementOptions): Promise<number>;
158
169
  protected openTransaction(opts?: TransactionOptions): Promise<void>;
159
170
  /**
160
- * A `COMMIT` that fails can leave the transaction open (SQLite answers `SQLITE_BUSY` and keeps it), so the
161
- * flag stays for the rollback after it. A `ROLLBACK` always ends it: one the server refuses, a deadlock
162
- * victim's on SQL Server, left nothing open to roll back.
171
+ * A handle is dropped before it ends: one outliving a failed end would carry every later statement into a
172
+ * transaction the server may have ended. A `ROLLBACK` always ends it, a deadlock victim's on SQL Server included;
173
+ * a `COMMIT` that fails can leave it open (SQLite's `SQLITE_BUSY`) for the rollback after it.
163
174
  */
164
175
  protected endTransaction(commit: boolean): Promise<void>;
165
176
  /** A rollback to a savepoint undoes the context bound inside it, so the next statement binds it again. */
166
177
  protected savepoint(command: SavepointCommand, name: string): Promise<void>;
167
- /**
168
- * How this driver opens, commits and rolls back: the dialect's statements, unless its transactions
169
- * are objects rather than statements - Hrana's session handle, `mssql`'s `Transaction` - in which
170
- * case it overrides all three. The bookkeeping around them stays above, written once.
171
- */
178
+ /** Opens a transaction on the engine: the dialect's statements, or a driver's {@link tx} it sets instead. */
172
179
  protected internalBegin(opts?: TransactionOptions): Promise<void>;
173
- protected internalCommit(): Promise<void>;
174
- protected internalRollback(): Promise<void>;
175
180
  /** Transaction statements skip `timed()`, so they attach their own query context to a failure. */
176
181
  private runTransactionCommand;
177
182
  }
@@ -9,7 +9,7 @@ import { sql, statementOf } from '../util/sql.js';
9
9
  import { UqlUsageError } from '../util/uqlError.js';
10
10
  import { AbstractQuerier } from './abstractQuerier.js';
11
11
  import { streamViaCursor } from './cursorStream.js';
12
- import { enrichError, failedIndexOf } from './queryError.js';
12
+ import { enrichError, failedIndexOf, isAbortedTransaction } from './queryError.js';
13
13
  import { rowReader } from './rowReader.js';
14
14
  /**
15
15
  * Row indexes split by whether the row names its key, the one thing that changes what an insert can
@@ -67,9 +67,15 @@ function inPayloadOrder(meta, rows, reported) {
67
67
  }
68
68
  /** Each role found held to a dialect's policies, by name (`undefined` the connection's own), answered once per pool. */
69
69
  const heldToPolicies = new WeakMap();
70
+ /** A commit the engine answered with a rollback: on the Postgres family, a failed statement aborts the transaction whole. */
71
+ function abortedCommitError(cause) {
72
+ return new UqlUsageError('the transaction rolled back instead of committing, as a statement in it failed: let the failure end it, or run that statement in a nested transaction, whose savepoint keeps the failure to itself', { cause });
73
+ }
70
74
  export class AbstractSqlQuerier extends AbstractQuerier {
71
75
  dialect;
72
76
  hasOpenTransaction = false;
77
+ /** The open transaction, where the driver holds it as a {@link TransactionHandle}. */
78
+ tx;
73
79
  #bound = NOTHING_BOUND;
74
80
  /** Cached `auto_increment_increment` stride; see {@link loadInsertIdIncrement}. */
75
81
  #insertIdIncrement;
@@ -316,7 +322,8 @@ export class AbstractSqlQuerier extends AbstractQuerier {
316
322
  * closes itself when the loop exits early.
317
323
  */
318
324
  async *internalStream(query, values) {
319
- if (!this.dialect.features.serverSideCursors) {
325
+ // A session the pool's queriers share would hold a cursor's transaction open under every other caller of it.
326
+ if (!this.dialect.features.serverSideCursors || this.connection !== this) {
320
327
  yield* (await this.execute(query, values)).rows;
321
328
  return;
322
329
  }
@@ -334,7 +341,7 @@ export class AbstractSqlQuerier extends AbstractQuerier {
334
341
  async internalCount(entity, q, opts) {
335
342
  return this.runCount((ctx) => this.dialect.count(ctx, entity, q, opts));
336
343
  }
337
- async estimatedCount(entity) {
344
+ async internalEstimatedCount(entity) {
338
345
  return this.runCount((ctx) => this.dialect.estimatedCount(ctx, entity));
339
346
  }
340
347
  async internalAggregate(entity, q, opts) {
@@ -521,18 +528,31 @@ export class AbstractSqlQuerier extends AbstractQuerier {
521
528
  this.#bound = NOTHING_BOUND;
522
529
  }
523
530
  /**
524
- * A `COMMIT` that fails can leave the transaction open (SQLite answers `SQLITE_BUSY` and keeps it), so the
525
- * flag stays for the rollback after it. A `ROLLBACK` always ends it: one the server refuses, a deadlock
526
- * victim's on SQL Server, left nothing open to roll back.
531
+ * A handle is dropped before it ends: one outliving a failed end would carry every later statement into a
532
+ * transaction the server may have ended. A `ROLLBACK` always ends it, a deadlock victim's on SQL Server included;
533
+ * a `COMMIT` that fails can leave it open (SQLite's `SQLITE_BUSY`) for the rollback after it.
527
534
  */
528
535
  async endTransaction(commit) {
529
- if (commit) {
530
- await this.internalCommit();
536
+ const { tx, dialect } = this;
537
+ if (commit && !tx) {
538
+ const { command } = await this.runTransactionCommand(dialect.commitTransactionCommand);
531
539
  this.hasOpenTransaction = false;
540
+ if (command === 'ROLLBACK') {
541
+ throw abortedCommitError();
542
+ }
532
543
  return;
533
544
  }
545
+ this.tx = undefined;
534
546
  try {
535
- await this.internalRollback();
547
+ if (tx) {
548
+ await (commit ? tx.commit() : tx.rollback());
549
+ }
550
+ else {
551
+ await this.runTransactionCommand(dialect.rollbackTransactionCommand);
552
+ }
553
+ }
554
+ catch (err) {
555
+ throw isAbortedTransaction(err) ? abortedCommitError(err) : err;
536
556
  }
537
557
  finally {
538
558
  this.hasOpenTransaction = false;
@@ -548,26 +568,16 @@ export class AbstractSqlQuerier extends AbstractQuerier {
548
568
  this.#bound = unsettled(this.#bound);
549
569
  }
550
570
  }
551
- /**
552
- * How this driver opens, commits and rolls back: the dialect's statements, unless its transactions
553
- * are objects rather than statements - Hrana's session handle, `mssql`'s `Transaction` - in which
554
- * case it overrides all three. The bookkeeping around them stays above, written once.
555
- */
571
+ /** Opens a transaction on the engine: the dialect's statements, or a driver's {@link tx} it sets instead. */
556
572
  async internalBegin(opts) {
557
573
  for (const sql of this.dialect.getBeginTransactionStatements(opts)) {
558
574
  await this.runTransactionCommand(sql);
559
575
  }
560
576
  }
561
- internalCommit() {
562
- return this.runTransactionCommand(this.dialect.commitTransactionCommand);
563
- }
564
- internalRollback() {
565
- return this.runTransactionCommand(this.dialect.rollbackTransactionCommand);
566
- }
567
577
  /** Transaction statements skip `timed()`, so they attach their own query context to a failure. */
568
578
  async runTransactionCommand(sql) {
569
579
  try {
570
- await this.execute(sql);
580
+ return await this.execute(sql);
571
581
  }
572
582
  catch (err) {
573
583
  throw enrichError(err, this.logger, sql);
@@ -8,6 +8,8 @@ export interface QueryError extends Error {
8
8
  query?: string;
9
9
  values?: readonly unknown[];
10
10
  }
11
+ /** Whether `err` is Postgres refusing a commit because a failed statement aborted the transaction (SQLSTATE `25P02`). */
12
+ export declare function isAbortedTransaction(err: unknown): boolean;
11
13
  /**
12
14
  * Names what `err` ran into on any engine, or `undefined` for anything else. Pure: the error is only
13
15
  * read, so it works on any driver error, whether or not a querier saw it first.
@@ -47,6 +47,14 @@ const SQLITE_MESSAGE_KINDS = [
47
47
  ['CHECK constraint failed', 'checkViolation'],
48
48
  ['database is locked', 'retryable'],
49
49
  ];
50
+ /** Whether `err` is Postgres refusing a commit because a failed statement aborted the transaction (SQLSTATE `25P02`). */
51
+ export function isAbortedTransaction(err) {
52
+ if (typeof err !== 'object' || err === null) {
53
+ return false;
54
+ }
55
+ const { code } = err;
56
+ return code === '25P02';
57
+ }
50
58
  /**
51
59
  * Names what `err` ran into on any engine, or `undefined` for anything else. Pure: the error is only
52
60
  * read, so it works on any driver error, whether or not a querier saw it first.
@@ -3,10 +3,10 @@ import type { IndexNode, TableNode } from './types.js';
3
3
  /**
4
4
  * What an introspector reports about an index, and so all a diff may compare; apart from `IndexFeature`, what an engine emits.
5
5
  * `vector` is whether it is a vector index at all, for an engine with one vector index whatever type declared it;
6
- * `distance` is the metric a vector index was built for.
6
+ * `distance` is the metric a vector index was built for. `hash` is whether it is hash-sharded, for an engine reading no other type.
7
7
  * `textIndex` is a text index's weights and language, kept by an engine that lists its fields in no declared order.
8
8
  */
9
- export type IndexFacet = 'order' | 'nulls' | 'opsClass' | 'accessMethod' | 'include' | 'vector' | 'distance' | 'textIndex';
9
+ export type IndexFacet = 'order' | 'nulls' | 'opsClass' | 'accessMethod' | 'include' | 'vector' | 'distance' | 'hash' | 'textIndex';
10
10
  type ComparableIndex = Pick<IndexNode, 'name' | 'entries' | 'unique' | 'where'>;
11
11
  /**
12
12
  * Whether the table has this index already, by shape rather than name, uniqueness included. An index
@@ -129,6 +129,10 @@ export function describeIndexDifferences(source, target, facets) {
129
129
  const [expected, actual] = [source, target].map((index) => (isVectorIndexType(index.type) ? 'yes' : 'no'));
130
130
  differences.push(`vector index: ${actual} -> ${expected}`);
131
131
  }
132
+ if (facets.has('hash') && (source.type === 'hash') !== (target.type === 'hash')) {
133
+ const [expected, actual] = [source, target].map((index) => (index.type === 'hash' ? 'yes' : 'no'));
134
+ differences.push(`hash-sharded: ${actual} -> ${expected}`);
135
+ }
132
136
  if (facets.has('include')) {
133
137
  // Order carries no meaning in an `INCLUDE` list, so it is compared as a set.
134
138
  const [sourceInclude, targetInclude] = [source.include ?? [], target.include ?? []].map((columns) => [...columns].sort().join(', '));
@@ -43,9 +43,8 @@ export type HranaQuerierConnectionOptions = {
43
43
  * @remarks Transactions use the client's own session handle rather than `BEGIN`/`COMMIT` statements,
44
44
  * because over plain HTTP consecutive requests need not share a connection.
45
45
  */
46
- export declare class HranaQuerier extends AbstractSqlQuerier {
46
+ export declare class HranaQuerier extends AbstractSqlQuerier<HranaTransaction> {
47
47
  readonly client: HranaClient;
48
- private tx?;
49
48
  private readonly closeClientOnRelease;
50
49
  constructor(client: HranaClient, dialect: SqliteDialect, extra?: ExtraOptions, connection?: HranaQuerierConnectionOptions);
51
50
  /** Runs on the open transaction's handle when there is one. */
@@ -53,11 +52,5 @@ export declare class HranaQuerier extends AbstractSqlQuerier {
53
52
  /** A list as one request: the client's `batch`, all or none; inside an open transaction, its own, which joins it. */
54
53
  protected executeBatch(statements: readonly BoundStatement[]): Promise<SqlExecution[]>;
55
54
  protected internalBegin(opts?: TransactionOptions): Promise<void>;
56
- /**
57
- * Both drop the handle before the call, not after: one that outlived a failed commit would carry
58
- * every later statement into a transaction the server may already have ended.
59
- */
60
- protected internalCommit(): Promise<void>;
61
- protected internalRollback(): Promise<void>;
62
55
  internalRelease(): Promise<void>;
63
56
  }
@@ -9,7 +9,6 @@ import { sqliteStatements, toBindValues } from './bindValues.js';
9
9
  */
10
10
  export class HranaQuerier extends AbstractSqlQuerier {
11
11
  client;
12
- tx;
13
12
  closeClientOnRelease;
14
13
  constructor(client, dialect, extra, connection) {
15
14
  super(dialect, extra);
@@ -29,20 +28,6 @@ export class HranaQuerier extends AbstractSqlQuerier {
29
28
  async internalBegin(opts) {
30
29
  this.tx = await this.client.transaction(opts?.readOnly ? 'read' : 'write');
31
30
  }
32
- /**
33
- * Both drop the handle before the call, not after: one that outlived a failed commit would carry
34
- * every later statement into a transaction the server may already have ended.
35
- */
36
- async internalCommit() {
37
- const tx = this.tx;
38
- this.tx = undefined;
39
- await tx?.commit();
40
- }
41
- async internalRollback() {
42
- const tx = this.tx;
43
- this.tx = undefined;
44
- await tx?.rollback();
45
- }
46
31
  async internalRelease() {
47
32
  if (this.closeClientOnRelease) {
48
33
  this.client.close();
@@ -125,7 +125,8 @@ export interface UniversalQuerier extends SharedQuerier<'server', QueryOptions>
125
125
  aggregate<E extends object, const Q extends QueryAggregate<E>>(entity: Type<E>, q: Captured<QueryAggregate<E, Q>, Q>, opts?: QueryOptions): Promise<QueryAggregateResult<E, Q>[]>;
126
126
  /**
127
127
  * The table's row count as the engine's statistics state it, without reading a row: approximate, as
128
- * stale as the last `ANALYZE`, and unfiltered, so soft-deleted rows count. SQLite has none and throws.
128
+ * stale as the last `ANALYZE`, and unfiltered, so soft-deleted rows count. SQLite has none and throws, and it is
129
+ * refused for an entity whose policies the pool holds, since it would count the rows they hide.
129
130
  */
130
131
  estimatedCount<E extends object>(entity: Type<E>): Promise<number>;
131
132
  }
@@ -46,12 +46,13 @@ export declare function derivedForeignKeyName(table: string, columns: readonly s
46
46
  export declare function escapeSqlId(val: string | undefined, escapeIdChar?: '`' | '"', forbidQualified?: boolean, addDot?: boolean): string;
47
47
  /**
48
48
  * What a statement came back with: the rows it read (a `RETURNING`'s included), how many rows it changed where
49
- * the driver tells it, and the first id a header reports (MySQL's `insertId`).
49
+ * the driver tells it, the first id a header reports (MySQL's `insertId`), and the Postgres wire's command tag.
50
50
  */
51
51
  export type SqlExecution = {
52
52
  readonly rows: RawRow[];
53
53
  readonly changes?: number | null;
54
54
  readonly id?: PrimaryKey;
55
+ readonly command?: string | null;
55
56
  };
56
57
  /** The column a `RETURNING` reports ids under: uql's own statements alias the key to it, and a raw `run()` names it so. */
57
58
  export declare const RETURNED_ID = "id";
package/package.json CHANGED
@@ -3,7 +3,7 @@
3
3
  "homepage": "https://uql-orm.dev",
4
4
  "description": "JSON-native TypeScript ORM for Bun, Browsers, Edge, Node, Workers. Supports PostgreSQL, PGlite, MySQL, MariaDB, SQLite, CockroachDB, SQL Server, Turso, Neon, Cloudflare D1 and MongoDB. Queries are plain JSON, typed to the leaf.",
5
5
  "license": "MIT",
6
- "version": "0.116.3",
6
+ "version": "0.116.5",
7
7
  "type": "module",
8
8
  "engines": {
9
9
  "node": ">=22.18"
@@ -50,7 +50,7 @@
50
50
  "clean": "rimraf dist .tsconfig.tsbuildinfo"
51
51
  },
52
52
  "peerDependencies": {
53
- "@electric-sql/pglite": ">=0.5.10 <0.6",
53
+ "@electric-sql/pglite": ">=0.5.15 <0.6",
54
54
  "@libsql/client": ">=0.6.0 <0.19",
55
55
  "@neondatabase/serverless": ">=0.9.0 <2",
56
56
  "@nestjs/common": ">=10.0.0 <13",
@@ -37,7 +37,7 @@ export const pool = new PgQuerierPool({ connectionString: process.env.DATABASE_U
37
37
  export default { pool, entities: [User, Post] } satisfies Config;
38
38
  ```
39
39
 
40
- Driver entry points: `uql-orm/postgres`, `mysql`, `mariadb`, `sqlite`, `mongodb`, `libsql`, `turso`, `neon`, `d1`, `pglite`, `bun-sql`, `mssql`, `cockroachdb`. Build the pool once per process and import it.
40
+ Driver entry points: `uql-orm/postgres`, `mysql`, `mariadb`, `sqlite`, `mongodb`, `libsql`, `turso`, `neon`, `d1`, `pglite`, `bun-sql`, `mssql`, `cockroachdb`. Build the pool once per process and import it. `new PgliteQuerierPool(dataDir, opts)` opens PGlite itself; `new PgliteQuerierPool(() => PGliteWorker.create(worker))` runs on a handle you open, as a worker sharing one database across tabs, and its transactions hold PGlite's lock, which every other user of the handle waits on.
41
41
 
42
42
  The pool's first argument is the driver's own config; set an acquire timeout there (`connectionTimeoutMillis` on the `pg` family), which otherwise waits forever. The second holds uql's options: `namingStrategy: new SnakeCaseNamingStrategy()` maps `createdAt` to `created_at` in queries and migrations alike (never name each column by hand), `logger: true` or a level list, `slowQuery: 200` (ms), and a default `schema`. Call `await pool.end()` on shutdown, except in serverless functions: https://uql-orm.dev/pool.md
43
43
 
@@ -189,7 +189,7 @@ await withContext({ tenantId: 42, userId: 'u1' }, () => pool.findMany(Invoice, {
189
189
  - A policy is data: `{ allow: where }` or `{ must: where }`, beside `ops` (`'read'`, `'insert'`, `'update'`, `'delete'`, every one where unset), `when` (context keys at a value, or one of a list) and `name`. Its `where` holds every row a statement touches, found and written; `$old: {...}` in it holds only the row as found (a row failing it is not reached) and `$new: {...}` only the row as written (a write failing it is refused). A read or delete sees `$old`, an insert `$new`, an update both. A group pairing both, `$or: [{ $old: ... }, { $new: ... }]`, is a transition: only in a `must` with `ops: ['update']`, held on every engine (natively by a trigger), soft deletes included. There is no `check`. A row is reached when any `allow` holding the statement reaches it and every `must` holds. An entity declaring no `allow` is allowed every row its `must`s (and tenant) leave; one declaring some reaches no row in a statement none of them holds. An update or delete is held to the `read` ones too. A soft delete is an update: the `update` policies hold it, and `delete` ones a hard delete. `{}` reaches every row. A policy stated once as a constant serves every entity with the fields it names.
190
190
  - `explainPolicies(Invoice, 'update')` answers what the policies hold a statement to under the ambient context, as a policy states it: `$old` the rows it reaches, `$new` what a row it writes must hold, `$and` an update's transitions. What to look at when a read reaches no row.
191
191
  - `$context.tenantId` reads the context key in a predicate, typed by `UqlContext`: once it declares keys, a misspelled one, or one in `when`, does not compile; a relation is read like any `$where` (`{ allow: { members: { userId: $context.userId } } }`). A key the context lacks or holds null matches nothing, as SQL's NULL compares: no context, no rows.
192
- - Policies hold every read, populate, relation filter and count, and every write: an insert gets each field a policy pins to one value (`companyId`), a write setting another is refused with `UqlSecurityError`, and a `$new` condition the row alone cannot settle, or a transition, is read in the write's transaction (MongoDB needs `transaction()` for one; D1 refuses it). Nothing per call turns a policy off: run trusted, cross-tenant work on a pool built with `{ policies: false }`.
192
+ - Policies hold every read, populate, relation filter and count, and every write: an insert gets each field a policy pins to one value (`companyId`), a write setting another is refused with `UqlSecurityError`, and a `$new` condition the row alone cannot settle, or a transition, is read in the write's transaction (MongoDB needs `transaction()` for one; D1 refuses it). Nothing per call turns a policy off: run trusted, cross-tenant work on a pool built with `{ policies: false }`. `estimatedCount` throws for an entity whose policies the pool holds, since it counts the rows they hide: use `count`.
193
193
  - `{ policies: 'native' }` on a Postgres or CockroachDB pool has the database hold them: migrations install `CREATE POLICY` (RLS enabled and forced), each transaction binds the context with `set_config`, and raw SQL is held too. Connect it as a role that is no superuser and lacks `BYPASSRLS`; a statement under a context is refused otherwise. `role: $context.role` beside it runs each transaction as the database role the context names, and a `when` on that key compares that role exactly (`current_user`). CockroachDB takes no relation in a native policy, and a Postgres insert must be readable by the context inserting it. https://uql-orm.dev/multi-tenancy.md
194
194
 
195
195
  ## Queries
@@ -276,6 +276,7 @@ await pool.transaction(async (querier) => {
276
276
  ```
277
277
 
278
278
  - The callback commits when it returns and rolls back when it throws. Inside it, `pool` calls run on its querier. A nested `transaction()` is a savepoint; MongoDB refuses it.
279
+ - On the Postgres family a failed statement aborts its whole transaction, so one caught and carried past cannot commit: the commit rejects with `UqlUsageError`. Run a statement that may fail in a nested `transaction()`, whose savepoint keeps the failure to itself.
279
280
  - `querier.onCommit(fn)` runs `fn` after the outermost commit, never on rollback.
280
281
  - A transaction opened in one place and ended in another uses `beginTransaction`, `commitTransaction` and `rollbackTransaction`. A querier from `pool.getQuerier()` is yours to release: bind it with `await using`.
281
282
  - A `findManyStream` holds its querier until the loop ends, refusing other statements meanwhile: run them after the loop, or on another connection.