uql-orm 0.95.1 → 0.96.0

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 (58) hide show
  1. package/dist/dialect/abstractSqlDialect.js +21 -13
  2. package/dist/libsql/libsqlDialect.d.ts +4 -1
  3. package/dist/libsql/libsqlDialect.js +4 -1
  4. package/dist/libsql/libsqlQuerierPool.d.ts +1 -1
  5. package/dist/libsql/libsqlQuerierPool.js +1 -1
  6. package/dist/maria/mariadbQuerierPool.js +1 -1
  7. package/dist/migrate/bin.js +2 -4
  8. package/dist/migrate/cli.js +8 -4
  9. package/dist/migrate/codegen/entityTypes.js +6 -15
  10. package/dist/migrate/ddl/indexDdl.d.ts +1 -6
  11. package/dist/migrate/ddl/indexDdl.js +0 -10
  12. package/dist/migrate/ddl/mysqlIndexDdl.d.ts +5 -5
  13. package/dist/migrate/ddl/mysqlIndexDdl.js +11 -6
  14. package/dist/migrate/ddl/tableDdl.d.ts +8 -2
  15. package/dist/migrate/ddl/tableDdl.js +11 -3
  16. package/dist/migrate/drift/driftDetector.js +2 -10
  17. package/dist/migrate/introspection/sqliteIntrospector.d.ts +1 -1
  18. package/dist/migrate/introspection/sqliteIntrospector.js +4 -7
  19. package/dist/migrate/migrator.d.ts +2 -4
  20. package/dist/migrate/migrator.js +12 -20
  21. package/dist/migrate/schemaGenerator.d.ts +5 -0
  22. package/dist/migrate/schemaGenerator.js +18 -9
  23. package/dist/mongo/mongoDialect.d.ts +2 -2
  24. package/dist/mongo/mongoDialect.js +2 -3
  25. package/dist/mongo/mongoIntrospector.js +3 -4
  26. package/dist/mongo/mongoMigrationStorage.d.ts +2 -3
  27. package/dist/mongo/mongoMigrationStorage.js +2 -3
  28. package/dist/mongo/mongoSchemaGenerator.d.ts +6 -4
  29. package/dist/mongo/mongoSchemaGenerator.js +5 -10
  30. package/dist/mongo/mongodbQuerier.js +1 -1
  31. package/dist/mssql/mssqlQuerier.d.ts +6 -3
  32. package/dist/mssql/mssqlQuerier.js +6 -8
  33. package/dist/mssql/mssqlQuerierPool.d.ts +1 -5
  34. package/dist/mssql/mssqlQuerierPool.js +21 -10
  35. package/dist/mysql/mysql2Querier.d.ts +5 -1
  36. package/dist/mysql/mysql2Querier.js +8 -5
  37. package/dist/mysql/mysql2QuerierPool.d.ts +0 -1
  38. package/dist/mysql/mysql2QuerierPool.js +6 -18
  39. package/dist/pglite/pgliteQuerier.js +1 -1
  40. package/dist/postgres/abstractPgQuerierPool.d.ts +3 -2
  41. package/dist/postgres/abstractPgQuerierPool.js +3 -0
  42. package/dist/postgres/pgQuerier.d.ts +1 -0
  43. package/dist/querier/abstractQuerier.js +1 -6
  44. package/dist/querier/abstractSqlQuerier.d.ts +4 -3
  45. package/dist/querier/abstractSqlQuerier.js +14 -16
  46. package/dist/schema/indexColumns.d.ts +8 -0
  47. package/dist/schema/indexColumns.js +28 -0
  48. package/dist/schema/indexDifferences.js +4 -7
  49. package/dist/schema/schemaASTBuilder.js +18 -23
  50. package/dist/sqlite/hranaQuerier.d.ts +5 -6
  51. package/dist/sqlite/sqliteDialect.d.ts +1 -1
  52. package/dist/sqlite/sqliteDialect.js +1 -1
  53. package/dist/turso/tursoDialect.d.ts +3 -3
  54. package/dist/turso/tursoDialect.js +5 -10
  55. package/dist/type/dialect.d.ts +7 -3
  56. package/dist/type/migration.d.ts +2 -9
  57. package/package.json +6 -6
  58. package/skills/uql-orm/SKILL.md +1 -1
@@ -6,11 +6,10 @@ import { diffRelationshipNodes, diffTable } from '../schema/schemaASTDiffer.js';
6
6
  import { DEFAULT_FOREIGN_KEY_ACTION, } from '../schema/types.js';
7
7
  import { qualifyName } from '../util/index.js';
8
8
  import { derivedCheckName, derivedForeignKeyName, derivedPrimaryKeyName, isOwnedName } from '../util/sql.util.js';
9
- import { UqlUsageError } from '../util/uqlError.js';
10
9
  import { splitSqlStatements } from './builder/splitSqlStatements.js';
11
10
  import { formatDefaultValue, sameDefault } from './ddl/defaultSql.js';
12
11
  import { indexDdlFor, tableDdlFor } from './ddl/index.js';
13
- import { sizedType } from './ddl/tableDdl.js';
12
+ import { rebuildRefusal, sizedType } from './ddl/tableDdl.js';
14
13
  import { rebuildTable } from './ddl/tableRebuild.js';
15
14
  import { columnForeignKey, columnIndex, bareColumn, renderIndexDefinition, tableDefinitionToNode, } from './generator/definitionToNode.js';
16
15
  import { indexNodeToSchema } from './generator/indexNodeToSchema.js';
@@ -91,15 +90,14 @@ export class SqlSchemaGenerator {
91
90
  */
92
91
  generateCreateSchema(entities, options = {}) {
93
92
  const tables = this.orderedTables(entities, 'create', options.only);
94
- const withForeignKeys = options.foreignKeys ?? true;
95
93
  // Inline only where a constraint cannot be added afterwards, which is what makes the cyclic case
96
94
  // work everywhere else.
97
- const inline = withForeignKeys && this.features.rebuildsTables;
95
+ const inline = this.features.rebuildsTables;
98
96
  // Namespaces first: a qualified `CREATE TABLE` fails against a schema nobody created, and the
99
97
  // schema is the one part of the layout a migration cannot infer from the table it is making.
100
98
  const statements = this.generateCreateSchemas(tables);
101
99
  statements.push(...tables.flatMap((table) => this.generateCreateTableFromNode(inline ? table : { ...table, outgoingRelations: [] }, options)));
102
- if (withForeignKeys && !inline) {
100
+ if (!inline) {
103
101
  for (const table of tables) {
104
102
  statements.push(...this.addForeignKeyStatements(qualifyName(table.name, table.schema), table.outgoingRelations.map(foreignKeyOf)));
105
103
  }
@@ -157,7 +155,19 @@ export class SqlSchemaGenerator {
157
155
  return [...new Set(named)].map((schema) => this.dialect.createSchemaSql(schema));
158
156
  }
159
157
  generateDropSchema(entities, options = {}) {
160
- return this.orderedTables(entities, 'drop').map((table) => this.generateDropTable(qualifyName(table.name, table.schema), options));
158
+ const tables = this.orderedTables(entities, 'drop').map((table) => qualifyName(table.name, table.schema));
159
+ // A `CASCADE` drop takes the foreign keys with it, and SQLite drops with its constraints off.
160
+ const cascades = options.cascade && this.features.dropTableCascade;
161
+ const existing = cascades || this.features.rebuildsTables ? [] : (options.existing?.getTables() ?? []);
162
+ const foreignKeyDrops = existing.flatMap((table) => {
163
+ const tableName = qualifyName(table.name, table.schema);
164
+ const names = [
165
+ ...table.outgoingRelations.map((relation) => relation.name),
166
+ ...table.externalForeignKeys.map((foreignKey) => constraintNameOf(tableName, foreignKey)),
167
+ ];
168
+ return names.map((name) => this.generateDropForeignKeySql(tableName, name));
169
+ });
170
+ return [...foreignKeyDrops, ...tables.map((tableName) => this.generateDropTable(tableName, options))];
161
171
  }
162
172
  /**
163
173
  * The tables of `entities` in dependency order, optionally narrowed to `only`. The AST always spans
@@ -600,8 +610,7 @@ export class SqlSchemaGenerator {
600
610
  */
601
611
  assertAlterable(what) {
602
612
  if (this.features.rebuildsTables) {
603
- throw new UqlUsageError(`${this.dialect}: ${what} rebuilds the table, which a migration generated from the entities does ` +
604
- '(`uql-migrate generate:entities`) and a hand-written one cannot.');
613
+ throw rebuildRefusal(this.dialect, what);
605
614
  }
606
615
  }
607
616
  }
@@ -609,7 +618,7 @@ export class SqlSchemaGenerator {
609
618
  * What a constraint is called: its own name, or one derived from its columns where nothing named it.
610
619
  * Shared by the add and the drop so a `DROP CONSTRAINT` names exactly what an `ADD CONSTRAINT` made.
611
620
  */
612
- function constraintNameOf(tableName, foreignKey) {
621
+ export function constraintNameOf(tableName, foreignKey) {
613
622
  return foreignKey.name ?? derivedForeignKeyName(tableName, foreignKey.columns);
614
623
  }
615
624
  /**
@@ -15,7 +15,7 @@ export type MongoSortPlan = {
15
15
  /** What a read pipeline contributes to {@link MongoDialect.readStages} beyond the query itself. */
16
16
  type MongoReadStages = {
17
17
  /** Ordering, which runs after the lookups when it reads one of their fields. */
18
- readonly sort?: MongoSortPlan;
18
+ readonly sort: MongoSortPlan;
19
19
  readonly pager?: MongoAggregationPipelineEntry<Document>[];
20
20
  /** A score the read answers as a field, a vector search's or a text search's; a temporary one leaves again. */
21
21
  readonly score?: {
@@ -179,7 +179,7 @@ export declare class MongoDialect extends AbstractDialect {
179
179
  * What a read runs after its entry stage, in the one order that works: the lookups, then the sort and
180
180
  * page that may read them, then the projection. Shared with the `$vectorSearch` pipeline.
181
181
  */
182
- readStages<E extends Document>(entity: Type<E>, q: Query<E>, extra?: MongoReadStages): MongoAggregationPipelineEntry<Document>[];
182
+ readStages<E extends Document>(entity: Type<E>, q: Query<E>, extra: MongoReadStages): MongoAggregationPipelineEntry<Document>[];
183
183
  /**
184
184
  * `$distinct` as a `$group` on the columns the query projects - the same set a SQL dialect puts
185
185
  * after `SELECT DISTINCT` - and the `$replaceRoot` that lifts the grouped key back to the top
@@ -11,7 +11,6 @@ import { UqlUsageError } from '../util/uqlError.js';
11
11
  import { decodeBigIntsExcept } from '../util/wideNumber.js';
12
12
  import { textLanguage } from './textLanguage.js';
13
13
  import { vectorDistanceExpr } from './vectorDistance.js';
14
- const EMPTY_SORT_PLAN = { sort: {}, stages: [], fields: [] };
15
14
  /** A scalar field's operator as the aggregation operator computing it. */
16
15
  const MONGO_ARITHMETIC = { $inc: '$add', $mul: '$multiply' };
17
16
  /** Default {@link DialectFeatures} for MongoDB. */
@@ -734,13 +733,13 @@ export class MongoDialect extends AbstractDialect {
734
733
  * What a read runs after its entry stage, in the one order that works: the lookups, then the sort and
735
734
  * page that may read them, then the projection. Shared with the `$vectorSearch` pipeline.
736
735
  */
737
- readStages(entity, q, extra = {}) {
736
+ readStages(entity, q, extra) {
738
737
  const meta = getMeta(entity);
739
738
  const joins = resolveQueryJoins(meta, q);
740
739
  // The value an ordering by a relation's aggregate reads, and the field it parks it on: both belong
741
740
  // with the lookups, since the `$sort` right after them is what they exist for.
742
741
  const aggregated = this.sortAggregateStages(entity, q.$sort);
743
- const ordering = extra.sort ?? EMPTY_SORT_PLAN;
742
+ const ordering = extra.sort;
744
743
  const lookups = [...this.lookupStages(meta, joins), ...aggregated.stages];
745
744
  // Each to-many and each `$count`, which neither drop nor reorder a row, so they read the page alone.
746
745
  const related = this.relationReadStages(entity, q);
@@ -35,17 +35,16 @@ export class MongoSchemaIntrospector {
35
35
  if (!(await hasCollection(db, tableName))) {
36
36
  return undefined;
37
37
  }
38
- // Annotated rather than inferred: the driver's `indexes()` is overloaded and resolves to `any` on
39
- // some versions, which silently made every field below unchecked.
38
+ // Annotated: the driver types a `listIndexes` entry as `any`, and its `indexes()` leaves `name` optional.
40
39
  const collection = db.collection(tableName);
41
- const indexes = await collection.indexes();
40
+ const indexes = await collection.listIndexes().toArray();
42
41
  const searchIndexes = await listSearchIndexes(collection);
43
42
  return {
44
43
  name: tableName,
45
44
  columns: [],
46
45
  indexes: [
47
46
  ...indexes.map(({ name, key, unique, weights, default_language }) => ({
48
- name: name ?? Object.keys(key).join('_'),
47
+ name,
49
48
  unique: !!unique,
50
49
  ...(weights
51
50
  ? {
@@ -1,7 +1,8 @@
1
1
  import type { MigrationStorage, QuerierPool } from '../type/index.js';
2
2
  import { type MongoQuerier } from './mongoQuerier.js';
3
3
  /**
4
- * Stores migration state in a MongoDB collection, named as the SQL table would be.
4
+ * Stores migration state in a MongoDB collection, named as the SQL table would be, which MongoDB creates
5
+ * on its first insert.
5
6
  */
6
7
  export declare class MongoMigrationStorage implements MigrationStorage {
7
8
  private readonly pool;
@@ -9,8 +10,6 @@ export declare class MongoMigrationStorage implements MigrationStorage {
9
10
  constructor(pool: QuerierPool, options?: {
10
11
  tableName?: string;
11
12
  });
12
- /** Nothing to prepare: MongoDB creates the collection on its first insert. */
13
- ensureStorage(): Promise<void>;
14
13
  executed(): Promise<string[]>;
15
14
  logWithQuerier(querier: MongoQuerier, migrationName: string): Promise<void>;
16
15
  unlogWithQuerier(querier: MongoQuerier, migrationName: string): Promise<void>;
@@ -1,7 +1,8 @@
1
1
  import { DEFAULT_MIGRATIONS_TABLE } from '../migrate/storage/databaseStorage.js';
2
2
  import { withMongoQuerierForMigrations } from './mongoQuerier.js';
3
3
  /**
4
- * Stores migration state in a MongoDB collection, named as the SQL table would be.
4
+ * Stores migration state in a MongoDB collection, named as the SQL table would be, which MongoDB creates
5
+ * on its first insert.
5
6
  */
6
7
  export class MongoMigrationStorage {
7
8
  pool;
@@ -10,8 +11,6 @@ export class MongoMigrationStorage {
10
11
  this.pool = pool;
11
12
  this.collectionName = options.tableName ?? DEFAULT_MIGRATIONS_TABLE;
12
13
  }
13
- /** Nothing to prepare: MongoDB creates the collection on its first insert. */
14
- async ensureStorage() { }
15
14
  executed() {
16
15
  return withMongoQuerierForMigrations(this.pool, 'MongoMigrationStorage', async (querier) => {
17
16
  const documents = await this.collection(querier)
@@ -2,6 +2,8 @@ import type { AnyMigrationOperation } from '../migrate/builder/types.js';
2
2
  import type { TableNode } from '../schema/types.js';
3
3
  import { type CreateSchemaOptions, type EntityWhereMeta, type IndexSchema, type NamingStrategy, type SchemaDiff, type SchemaGenerator, type Type } from '../type/index.js';
4
4
  import { MongoDialect } from './mongoDialect.js';
5
+ /** MongoDB runs no trigger within a write, and a write to an entity declaring one is refused, so there is none to reconcile. */
6
+ declare const noTriggers: () => string[];
5
7
  export declare class MongoSchemaGenerator extends MongoDialect implements SchemaGenerator {
6
8
  /** Takes no default foreign key action, since a document store has no foreign keys. */
7
9
  constructor(namingStrategy?: NamingStrategy);
@@ -36,10 +38,9 @@ export declare class MongoSchemaGenerator extends MongoDialect implements Schema
36
38
  generateDropTable(tableName: string): string;
37
39
  /** A collection's indexes: each dropped, then each created, an alter as both. */
38
40
  generateAlterTable(diff: SchemaDiff): string[];
39
- /** MongoDB runs no trigger within a write, and a write to an entity declaring one is refused, so there is none to reconcile. */
40
- generateTriggers(): string[];
41
- generateTriggersDown(): string[];
42
- generateTriggerDrops(): string[];
41
+ readonly generateTriggers: typeof noTriggers;
42
+ readonly generateTriggersDown: typeof noTriggers;
43
+ readonly generateTriggerDrops: typeof noTriggers;
43
44
  private dropIndexCommand;
44
45
  /** An index as MongoDB's key spec (`-1` descending, `'text'` full-text), refusing the SQL-only options. */
45
46
  generateCreateIndex(tableName: string, index: IndexSchema): string;
@@ -50,3 +51,4 @@ export declare class MongoSchemaGenerator extends MongoDialect implements Schema
50
51
  generateOperation(operation: AnyMigrationOperation): string[];
51
52
  diffSchema(entity: Type<object>, currentTable: TableNode | undefined): SchemaDiff | undefined;
52
53
  }
54
+ export {};
@@ -23,6 +23,8 @@ const ATLAS_SIMILARITY = {
23
23
  l2: 'euclidean',
24
24
  inner: 'dotProduct',
25
25
  };
26
+ /** MongoDB runs no trigger within a write, and a write to an entity declaring one is refused, so there is none to reconcile. */
27
+ const noTriggers = () => [];
26
28
  export class MongoSchemaGenerator extends MongoDialect {
27
29
  /** Takes no default foreign key action, since a document store has no foreign keys. */
28
30
  constructor(namingStrategy) {
@@ -116,16 +118,9 @@ export class MongoSchemaGenerator extends MongoDialect {
116
118
  ...sides(diff.indexes, 'to').map((index) => this.generateCreateIndex(diff.tableName, index)),
117
119
  ];
118
120
  }
119
- /** MongoDB runs no trigger within a write, and a write to an entity declaring one is refused, so there is none to reconcile. */
120
- generateTriggers() {
121
- return [];
122
- }
123
- generateTriggersDown() {
124
- return [];
125
- }
126
- generateTriggerDrops() {
127
- return [];
128
- }
121
+ generateTriggers = noTriggers;
122
+ generateTriggersDown = noTriggers;
123
+ generateTriggerDrops = noTriggers;
129
124
  dropIndexCommand(tableName, index) {
130
125
  return index.type === 'vectorSearch'
131
126
  ? serializeMongoCommand({ action: 'dropSearchIndex', collection: tableName, name: index.name })
@@ -260,7 +260,7 @@ export class MongodbQuerier extends AbstractQuerier {
260
260
  }));
261
261
  // Read off the document as written, which carries its `_id` on either branch.
262
262
  const { id, created } = this.upserted(res);
263
- return { ids: [id], changes: id === undefined ? 0 : 1, created };
263
+ return { ids: [id], changes: 1, created };
264
264
  });
265
265
  }
266
266
  async internalUpsertMany(entity, conflictPaths, payload, update) {
@@ -12,7 +12,7 @@ type MsSqlResult = {
12
12
  };
13
13
  /** The part of the `Readable` a request streams into that a querier drives. */
14
14
  type MsSqlRowStream = AsyncIterable<RawRow> & {
15
- destroy(error: Error): unknown;
15
+ destroy(error: unknown): unknown;
16
16
  on(event: 'error', listener: (error: Error) => void): unknown;
17
17
  };
18
18
  /** The part of an `mssql` `Request` a querier drives. */
@@ -59,7 +59,10 @@ export declare class MsSqlQuerier extends AbstractPoolQuerier<MsSqlConnection> {
59
59
  protected internalBegin(opts?: TransactionOptions): Promise<void>;
60
60
  protected internalCommit(): Promise<void>;
61
61
  protected internalRollback(): Promise<void>;
62
- /** The pool owns the socket; releasing a querier only drops this one's claim on it. */
63
- protected releaseConn(_conn: MsSqlConnection, _discard: boolean): Promise<void>;
62
+ /**
63
+ * The pool owns the socket, so there is nothing to hand back: `release` has already rolled back a
64
+ * transaction left open, and commit and rollback both drop the `Transaction` they end.
65
+ */
66
+ protected releaseConn(): Promise<void>;
64
67
  }
65
68
  export {};
@@ -43,7 +43,7 @@ export class MsSqlQuerier extends AbstractPoolQuerier {
43
43
  const request = this.#request(values);
44
44
  const rows = request.toReadableStream();
45
45
  const completed = request.query(query).catch((err) => {
46
- rows.destroy(err instanceof Error ? err : new Error(String(err)));
46
+ rows.destroy(err);
47
47
  });
48
48
  try {
49
49
  yield* rows;
@@ -76,13 +76,11 @@ export class MsSqlQuerier extends AbstractPoolQuerier {
76
76
  this.#transaction = undefined;
77
77
  await transaction?.rollback();
78
78
  }
79
- /** The pool owns the socket; releasing a querier only drops this one's claim on it. */
80
- async releaseConn(_conn, _discard) {
81
- const transaction = this.#transaction;
82
- this.#transaction = undefined;
83
- // A querier handed back mid-transaction would otherwise leave it open on a pooled connection.
84
- await transaction?.rollback().catch(() => undefined);
85
- }
79
+ /**
80
+ * The pool owns the socket, so there is nothing to hand back: `release` has already rolled back a
81
+ * transaction left open, and commit and rollback both drop the `Transaction` they end.
82
+ */
83
+ async releaseConn() { }
86
84
  }
87
85
  /** The driver's constant for each level UQL names; total, so a new level is a compile error here. */
88
86
  const ISOLATION = {
@@ -7,11 +7,7 @@ export declare class MsSqlQuerierPool extends AbstractSqlQuerierPool<MsSqlQuerie
7
7
  #private;
8
8
  readonly pool: ConnectionPool;
9
9
  constructor(opts: MsSqlConfig, extra?: ExtraOptions);
10
- /**
11
- * `mssql` connects the pool as a whole rather than per checkout, so the promise is shared. A
12
- * failed one is dropped rather than kept: memoized, a single transient failure would be handed to
13
- * every later caller for the life of the pool.
14
- */
15
10
  getQuerier(): Promise<MsSqlQuerier>;
11
+ /** `mssql` refuses to close a pool mid-connect, so the connect under way settles first. */
16
12
  end(): Promise<void>;
17
13
  }
@@ -2,33 +2,44 @@ import { ConnectionPool } from 'mssql';
2
2
  import { dialectOptionsFrom } from '../dialect/abstractDialect.js';
3
3
  import { AbstractSqlQuerierPool } from '../querier/index.js';
4
4
  import { attachPoolErrorHandler } from '../util/index.js';
5
+ import { UqlUsageError } from '../util/uqlError.js';
5
6
  import { MsSqlDialect } from './mssqlDialect.js';
6
7
  import { MsSqlQuerier } from './mssqlQuerier.js';
7
8
  export class MsSqlQuerierPool extends AbstractSqlQuerierPool {
8
9
  pool;
9
- #connected;
10
+ /** The whole pool's one connect, shared by every querier; `ended` once closed, since `mssql` would reconnect it. */
11
+ #connection;
10
12
  constructor(opts, extra) {
11
13
  super(new MsSqlDialect(dialectOptionsFrom(extra)), extra);
12
14
  this.pool = new ConnectionPool(opts);
13
15
  attachPoolErrorHandler(this.pool, 'Idle SQL Server pool connection encountered an error', extra?.logger);
14
16
  }
15
- /**
16
- * `mssql` connects the pool as a whole rather than per checkout, so the promise is shared. A
17
- * failed one is dropped rather than kept: memoized, a single transient failure would be handed to
18
- * every later caller for the life of the pool.
19
- */
20
17
  async getQuerier() {
21
18
  return new MsSqlQuerier(() => this.#connect(), this.dialect, this.extra);
22
19
  }
20
+ /** A failed connect is forgotten rather than handed to every later caller, unless `end` came first. */
23
21
  #connect() {
24
- this.#connected ??= this.pool.connect().catch((err) => {
25
- this.#connected = undefined;
22
+ const current = this.#connection;
23
+ if (current) {
24
+ if (current === 'ended') {
25
+ return Promise.reject(new UqlUsageError('Cannot use a pool after calling end on it'));
26
+ }
27
+ return current;
28
+ }
29
+ const connecting = this.pool.connect().catch((err) => {
30
+ if (this.#connection === connecting) {
31
+ this.#connection = undefined;
32
+ }
26
33
  throw err;
27
34
  });
28
- return this.#connected;
35
+ this.#connection = connecting;
36
+ return connecting;
29
37
  }
38
+ /** `mssql` refuses to close a pool mid-connect, so the connect under way settles first. */
30
39
  async end() {
31
- this.#connected = undefined;
40
+ const connecting = this.#connection;
41
+ this.#connection = 'ended';
42
+ await Promise.allSettled([connecting]);
32
43
  await this.pool.close();
33
44
  }
34
45
  }
@@ -1,5 +1,9 @@
1
- import type { PoolConnection } from 'mysql2/promise';
1
+ import type { PoolConnection } from 'mysql2';
2
2
  import { AbstractPoolQuerier } from '../querier/abstractPoolQuerier.js';
3
+ /**
4
+ * Holds the driver's own connection rather than its promise wrapper, whose types name the connection
5
+ * inside it a promise one too: streaming is the own connection's alone.
6
+ */
3
7
  export declare class MySql2Querier extends AbstractPoolQuerier<PoolConnection> {
4
8
  internalAll<T>(query: string, values?: unknown[]): Promise<T[]>;
5
9
  internalRun(query: string, values?: unknown[]): Promise<import("../index.js").QueryUpdateResult>;
@@ -1,11 +1,15 @@
1
1
  import { AbstractPoolQuerier } from '../querier/abstractPoolQuerier.js';
2
+ /**
3
+ * Holds the driver's own connection rather than its promise wrapper, whose types name the connection
4
+ * inside it a promise one too: streaming is the own connection's alone.
5
+ */
2
6
  export class MySql2Querier extends AbstractPoolQuerier {
3
7
  async internalAll(query, values) {
4
- const [res] = await this.getConn().query(query, values);
8
+ const [res] = await this.getConn().promise().query(query, values);
5
9
  return res;
6
10
  }
7
11
  async internalRun(query, values) {
8
- const [res] = (await this.getConn().query(query, values));
12
+ const [res] = await this.getConn().promise().query(query, values);
9
13
  return this.buildUpdateResult({
10
14
  changes: res.affectedRows,
11
15
  id: res.insertId,
@@ -13,8 +17,7 @@ export class MySql2Querier extends AbstractPoolQuerier {
13
17
  });
14
18
  }
15
19
  async *internalStream(query, values) {
16
- const rawConn = this.getConn().connection;
17
- yield* rawConn.query(query, values).stream();
20
+ yield* this.getConn().query(query, values).stream();
18
21
  }
19
22
  async releaseConn(conn, discard) {
20
23
  // mysql2 resets nothing on release, so a connection the pool takes back after a failed rollback
@@ -23,6 +26,6 @@ export class MySql2Querier extends AbstractPoolQuerier {
23
26
  conn.destroy();
24
27
  return;
25
28
  }
26
- await conn.release();
29
+ conn.release();
27
30
  }
28
31
  }
@@ -4,7 +4,6 @@ import type { ExtraOptions } from '../type/index.js';
4
4
  import { MySql2Querier } from './mysql2Querier.js';
5
5
  import { MySqlDialect } from './mysqlDialect.js';
6
6
  export declare class MySql2QuerierPool extends AbstractSqlQuerierPool<MySql2Querier, MySqlDialect> {
7
- #private;
8
7
  readonly pool: Pool;
9
8
  constructor(opts: PoolOptions, extra?: ExtraOptions);
10
9
  getQuerier(): Promise<MySql2Querier>;
@@ -1,3 +1,4 @@
1
+ import { promisify } from 'node:util';
1
2
  import { createPool } from 'mysql2/promise';
2
3
  import { dialectOptionsFrom } from '../dialect/abstractDialect.js';
3
4
  import { AbstractSqlQuerierPool } from '../querier/index.js';
@@ -5,32 +6,19 @@ import { MySql2Querier } from './mysql2Querier.js';
5
6
  import { MySqlDialect } from './mysqlDialect.js';
6
7
  export class MySql2QuerierPool extends AbstractSqlQuerierPool {
7
8
  pool;
8
- #utcSessions = new WeakSet();
9
9
  constructor(opts, extra) {
10
10
  super(new MySqlDialect(dialectOptionsFrom(extra)), extra);
11
11
  // A BIGINT past 2^53 as its exact text rather than a rounded number, the rule every driver here
12
12
  // decodes by (`decodeWideNumber`); within that range it stays a number, and DECIMAL is untouched.
13
13
  // A date reads as the UTC it holds, whichever zone the process runs in.
14
14
  this.pool = createPool({ supportBigNumbers: true, timezone: 'Z', ...opts });
15
+ // The session in UTC too, so `NOW()` agrees with a bound date: queued as each connection opens, ahead of
16
+ // any statement on it. One that fails has lost its connection, which the next statement reports.
17
+ this.pool.pool.on('connection', (connection) => connection.query("SET time_zone = '+00:00'", () => { }));
15
18
  }
16
19
  async getQuerier() {
17
- return new MySql2Querier(() => this.#connection(), this.dialect, this.extra);
18
- }
19
- /** A connection whose session is UTC too, so `NOW()` agrees with a bound date: set once per connection. */
20
- async #connection() {
21
- const connection = await this.pool.getConnection();
22
- if (this.#utcSessions.has(connection.connection)) {
23
- return connection;
24
- }
25
- try {
26
- await connection.query("SET time_zone = '+00:00'");
27
- }
28
- catch (error) {
29
- connection.release();
30
- throw error;
31
- }
32
- this.#utcSessions.add(connection.connection);
33
- return connection;
20
+ const { pool } = this.pool;
21
+ return new MySql2Querier(promisify(pool.getConnection.bind(pool)), this.dialect, this.extra);
34
22
  }
35
23
  async end() {
36
24
  await this.pool.end();
@@ -21,7 +21,7 @@ export class PgliteQuerier extends AbstractSqlQuerier {
21
21
  const res = await this.db.query(query, values);
22
22
  // `affectedRows`, not `rowCount`: PGlite derives the former from the command tag of a write only,
23
23
  // where the latter also counts a `SELECT`'s rows and is absent altogether from a DDL tag.
24
- return this.buildUpdateResult({ rows: res.rows, changes: res.affectedRows ?? 0 });
24
+ return this.buildUpdateResult({ rows: res.rows, changes: res.affectedRows });
25
25
  }
26
26
  /** The handle belongs to the pool, which hands out one querier per unit of work over it. */
27
27
  async internalRelease() { }
@@ -1,11 +1,12 @@
1
1
  import type { AbstractSqlDialect } from '../dialect/index.js';
2
2
  import { AbstractSqlQuerierPool } from '../querier/index.js';
3
3
  import type { ExtraOptions } from '../type/index.js';
4
- import { type ErrorEmittingPool } from '../util/index.js';
5
4
  import { type PgAnyClient, PgQuerier } from './pgQuerier.js';
6
- export interface PgAnyPool<C extends PgAnyClient> extends ErrorEmittingPool {
5
+ export interface PgAnyPool<C extends PgAnyClient> {
7
6
  connect: () => Promise<C>;
8
7
  end: () => Promise<void>;
8
+ on(event: 'error', listener: (err: Error) => void): unknown;
9
+ on(event: 'connect', listener: (client: C) => void): unknown;
9
10
  }
10
11
  /** A Postgres-wire pool of {@link PgQuerier}s, attaching the error handler that keeps a dropped connection from crashing the process. */
11
12
  export declare abstract class AbstractPgQuerierPool<C extends PgAnyClient, D extends AbstractSqlDialect> extends AbstractSqlQuerierPool<PgQuerier<C>, D> {
@@ -8,6 +8,9 @@ export class AbstractPgQuerierPool extends AbstractSqlQuerierPool {
8
8
  super(dialect, extra);
9
9
  this.pool = pool;
10
10
  attachPoolErrorHandler(pool, 'Idle Postgres pool client encountered an error', extra?.logger);
11
+ // A client the server drops while a querier holds it emits `error` with no statement to report it to,
12
+ // which unheard ends the process. The next statement on it fails instead, and the pool evicts it.
13
+ pool.on('connect', (client) => client.on('error', () => { }));
11
14
  }
12
15
  async getQuerier() {
13
16
  return new PgQuerier(() => this.pool.connect(), this.dialect, this.extra);
@@ -6,6 +6,7 @@ export interface PgAnyClient {
6
6
  rowCount: number | null;
7
7
  }>;
8
8
  query(stream: object): AsyncIterable<RawRow>;
9
+ on(event: 'error', listener: (err: Error) => void): unknown;
9
10
  /** Any truthy argument makes `pg-pool` evict the client instead of returning it to the idle list. */
10
11
  release(discard?: boolean): void | Promise<void>;
11
12
  }
@@ -750,12 +750,7 @@ export class AbstractQuerier {
750
750
  if (!this.hasHook(entity, event))
751
751
  return;
752
752
  for (const listener of this.extra?.listeners ?? []) {
753
- const fn = listener[event];
754
- if (fn) {
755
- const result = fn({ entity, querier: this, payloads, event });
756
- if (result instanceof Promise)
757
- await result;
758
- }
753
+ await listener[event]?.({ entity, querier: this, payloads, event });
759
754
  }
760
755
  await runHooks(entity, event, payloads, { querier: this });
761
756
  }
@@ -23,7 +23,8 @@ export declare abstract class AbstractSqlQuerier extends AbstractQuerier impleme
23
23
  /**
24
24
  * The `auto_increment_increment` stride used to infer the ids of a multi-row insert from the
25
25
  * single id the driver reports (MySQL, which has no `RETURNING`). It is 1 on a standalone server
26
- * but can be higher on a cluster (e.g. Galera). Only called for `firstId` dialects.
26
+ * but can be higher on a cluster (e.g. Galera), and `buildUpdateResult` takes any other as 1.
27
+ * Only called for `firstId` dialects.
27
28
  */
28
29
  protected loadInsertIdIncrement(): Promise<number>;
29
30
  /**
@@ -81,8 +82,8 @@ export declare abstract class AbstractSqlQuerier extends AbstractQuerier impleme
81
82
  private hydrateFields;
82
83
  /**
83
84
  * Runs a statement whose one row carries a {@link AGGREGATE_VALUE_ALIAS} column. `Number` because `COUNT(*)` is BIGINT and
84
- * a caller supplying their own `types` replaces the decoding the pools do at the wire; `?? 0` because
85
- * a catalog that does not know the table answers with no row, which is nothing counted.
85
+ * a caller supplying their own `types` replaces the decoding the pools do at the wire, and reads a `NULL`
86
+ * as 0; no row is 0 too, since a catalog that does not know the table answers with none.
86
87
  */
87
88
  private runCount;
88
89
  protected internalCount<E extends object>(entity: Type<E>, q: QueryPage<E>, opts?: QueryOptions): Promise<number>;
@@ -73,12 +73,12 @@ export class AbstractSqlQuerier extends AbstractQuerier {
73
73
  /**
74
74
  * The `auto_increment_increment` stride used to infer the ids of a multi-row insert from the
75
75
  * single id the driver reports (MySQL, which has no `RETURNING`). It is 1 on a standalone server
76
- * but can be higher on a cluster (e.g. Galera). Only called for `firstId` dialects.
76
+ * but can be higher on a cluster (e.g. Galera), and `buildUpdateResult` takes any other as 1.
77
+ * Only called for `firstId` dialects.
77
78
  */
78
79
  async loadInsertIdIncrement() {
79
- const rows = await this.all('SELECT @@auto_increment_increment AS v');
80
- const value = Number(rows[0]?.v);
81
- return Number.isInteger(value) && value > 0 ? value : 1;
80
+ const [row] = await this.all('SELECT @@auto_increment_increment AS v');
81
+ return Number(row.v);
82
82
  }
83
83
  /**
84
84
  * Hook for subclasses (e.g. pool queriers) to establish a connection. Called before every query and
@@ -248,18 +248,11 @@ export class AbstractSqlQuerier extends AbstractQuerier {
248
248
  // relation that only the populated ones need.
249
249
  for (const key in meta.relations) {
250
250
  const value = row[key];
251
- if (!value)
252
- continue;
253
251
  const rel = meta.relations[key];
254
- if (!rel)
252
+ if (!value || !rel)
255
253
  continue;
256
254
  const relEntity = rel.entity();
257
- if (typeof value === 'string' || Array.isArray(value)) {
258
- // A to-many's rows, as flat as a statement's own.
259
- const rows = typeof value === 'string' ? JSON.parse(value) : value;
260
- row[key] = rows.map(this.rowReader(relEntity));
261
- }
262
- else if (isRecord(value)) {
255
+ if (isRecord(value)) {
263
256
  const relMeta = getMeta(relEntity);
264
257
  if (value[relMeta.ids[0]] == null) {
265
258
  delete row[key];
@@ -268,16 +261,21 @@ export class AbstractSqlQuerier extends AbstractQuerier {
268
261
  this.hydrateFields(relMeta, this.dialect.hydratableFields(relEntity), value);
269
262
  }
270
263
  }
264
+ else {
265
+ // A to-many's rows, as flat as a statement's own.
266
+ const rows = Array.isArray(value) ? value : JSON.parse(String(value));
267
+ row[key] = rows.map(this.rowReader(relEntity));
268
+ }
271
269
  }
272
270
  }
273
271
  /**
274
272
  * Runs a statement whose one row carries a {@link AGGREGATE_VALUE_ALIAS} column. `Number` because `COUNT(*)` is BIGINT and
275
- * a caller supplying their own `types` replaces the decoding the pools do at the wire; `?? 0` because
276
- * a catalog that does not know the table answers with no row, which is nothing counted.
273
+ * a caller supplying their own `types` replaces the decoding the pools do at the wire, and reads a `NULL`
274
+ * as 0; no row is 0 too, since a catalog that does not know the table answers with none.
277
275
  */
278
276
  async runCount(build) {
279
277
  const [row] = await this.query(build);
280
- return Number(row?.[AGGREGATE_VALUE_ALIAS] ?? 0);
278
+ return row ? Number(row[AGGREGATE_VALUE_ALIAS]) : 0;
281
279
  }
282
280
  async internalCount(entity, q, opts) {
283
281
  return this.runCount((ctx) => this.dialect.count(ctx, entity, q, opts));
@@ -1,3 +1,11 @@
1
+ import type { IndexColumnSchema } from '../type/index.js';
1
2
  import type { ColumnNode, IndexNode } from './types.js';
2
3
  /** The table columns an index's entries resolve to, in order; an expression entry resolves to none. */
3
4
  export declare function indexColumns(index: IndexNode): ColumnNode[];
5
+ /** Whether an entry is its column as stored, rather than an expression or a path the engine reprints in its own words. */
6
+ export declare function isColumnEntry(entry: IndexColumnSchema): boolean;
7
+ /**
8
+ * The columns an index can look every row up by, in order, as far as its entries are whole columns: none
9
+ * where it holds only some rows (partial) or is of a type an equality lookup does not read.
10
+ */
11
+ export declare function lookupColumns(index: IndexNode): string[];