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
@@ -51,7 +51,21 @@ function accumulates(value) {
51
51
  }
52
52
  /** Conditions joined by `AND`, parenthesized where there is more than one. */
53
53
  function conjunction(parts) {
54
- return parts.length > 1 ? `(${parts.join(' AND ')})` : parts.join('');
54
+ return parts.length > 1 ? `(${chain(parts, 'AND')})` : parts.join('');
55
+ }
56
+ /** The most operands one level of a chain holds. */
57
+ const CHAIN_WIDTH = 16;
58
+ /**
59
+ * `parts` joined by `op`, a longer list nested in parenthesized groups so its depth grows with the log of
60
+ * its length: a flat chain is as deep as it is long, which the Rust Turso engine refuses past 100 and SQLite past 1000.
61
+ */
62
+ function chain(parts, op) {
63
+ if (parts.length <= CHAIN_WIDTH) {
64
+ return parts.join(` ${op} `);
65
+ }
66
+ const size = Math.ceil(parts.length / CHAIN_WIDTH);
67
+ const groups = Array.from({ length: Math.ceil(parts.length / size) }, (_, at) => parts.slice(at * size, (at + 1) * size));
68
+ return groups.map((group) => `(${chain(group, op)})`).join(` ${op} `);
55
69
  }
56
70
  /**
57
71
  * How `op` reads a JSON value: an ordered comparison as a number, an equality as its operand compares,
@@ -551,7 +565,7 @@ export class AbstractSqlDialect extends VectorSqlDialect {
551
565
  if (!parts.length) {
552
566
  return;
553
567
  }
554
- const body = parts.join(join === '$or' ? ' OR ' : ' AND ');
568
+ const body = chain(parts, join === '$or' ? 'OR' : 'AND');
555
569
  const parenthesize = parts.length > 1 && (opts.operand || negate);
556
570
  ctx.append((negate ? 'NOT ' : '') + (parenthesize ? `(${body})` : body));
557
571
  }
@@ -758,7 +772,8 @@ export class AbstractSqlDialect extends VectorSqlDialect {
758
772
  }
759
773
  /** The JSON array at `slot` contains at least one of `values`, each as `$all` reads it. */
760
774
  jsonAny(ctx, slot, values) {
761
- return `(${values.map((value) => this.jsonAll(ctx, slot, [value])).join(' OR ')})`;
775
+ const anyOf = values.map((value) => this.jsonAll(ctx, slot, [value]));
776
+ return `(${chain(anyOf, 'OR')})`;
762
777
  }
763
778
  /** An element of the array at `slot` itself, read the way `mode` reads a path: its document, or its root. */
764
779
  jsonElemValue(_slot, alias, mode) {
@@ -1176,9 +1191,6 @@ export class AbstractSqlDialect extends VectorSqlDialect {
1176
1191
  * another table of the statement took it first.
1177
1192
  */
1178
1193
  readOptions(ctx, meta, opts = {}) {
1179
- if (opts.alias !== undefined) {
1180
- return opts;
1181
- }
1182
1194
  const name = this.resolveTableAlias(meta);
1183
1195
  const alias = ctx.claimAlias(name);
1184
1196
  return alias === name ? opts : { ...opts, alias };
@@ -1858,7 +1870,7 @@ export class AbstractSqlDialect extends VectorSqlDialect {
1858
1870
  const meta = getMeta(entity);
1859
1871
  const rel = relationOf(meta, aggregate.relation);
1860
1872
  const parent = prefix || this.resolveTableAlias(meta);
1861
- if (aggregate.page?.$limit === undefined && aggregate.page?.$skip === undefined) {
1873
+ if (!aggregate.page || (aggregate.page.$limit === undefined && aggregate.page.$skip === undefined)) {
1862
1874
  this.appendRelationSubquery(ctx, meta, aggregate.relation, rel, { prefix: parent }, aggregate);
1863
1875
  return;
1864
1876
  }
@@ -1881,12 +1893,8 @@ export class AbstractSqlDialect extends VectorSqlDialect {
1881
1893
  const correlation = raw(({ ctx: pageCtx }) => this.appendCorrelation(pageCtx, meta, rel, parent, alias));
1882
1894
  const { where: $where, page } = aggregate;
1883
1895
  // `1` where nothing is aggregated: a tally counts the rows the page holds, whatever they carry.
1884
- const { field, search } = aggregate;
1885
- const read = !field
1886
- ? raw `1`
1887
- : search
1888
- ? raw(({ ctx: readCtx }) => this.appendVectorDistance(readCtx, getMeta(entity), field, search, alias))
1889
- : refs(entity)[field];
1896
+ const { field } = aggregate;
1897
+ const read = field ? refs(entity)[field] : raw `1`;
1890
1898
  const query = {
1891
1899
  ...page,
1892
1900
  $select: [read.as(AGGREGATE_VALUE_ALIAS)],
@@ -1,5 +1,7 @@
1
1
  import { SqliteDialect } from '../sqlite/sqliteDialect.js';
2
- import type { VectorDistance, VectorMetric } from '../type/index.js';
2
+ import type { SqlDialectFeatures, VectorDistance, VectorMetric } from '../type/index.js';
3
+ /** libSQL's server parses a statement before SQLite does, and its parser takes no `ORDER BY` inside an aggregate. */
4
+ export declare const LIBSQL_FEATURES: SqlDialectFeatures;
3
5
  /**
4
6
  * SQLite Dialect specialization for the `@libsql/client` driver.
5
7
  *
@@ -7,6 +9,7 @@ import type { VectorDistance, VectorMetric } from '../type/index.js';
7
9
  * functions, which `TursoDialect` inherits.
8
10
  */
9
11
  export declare class LibsqlDialect extends SqliteDialect {
12
+ readonly features: SqlDialectFeatures;
10
13
  /** libSQL's built-in vector functions, and the metric its DiskANN index names; no `inner` (only the Rust engine has it) and no `l1`. */
11
14
  readonly vectorMetrics: ReadonlyMap<VectorDistance, VectorMetric>;
12
15
  }
@@ -1,4 +1,6 @@
1
- import { SqliteDialect } from '../sqlite/sqliteDialect.js';
1
+ import { SQLITE_FEATURES, SqliteDialect } from '../sqlite/sqliteDialect.js';
2
+ /** libSQL's server parses a statement before SQLite does, and its parser takes no `ORDER BY` inside an aggregate. */
3
+ export const LIBSQL_FEATURES = { ...SQLITE_FEATURES, orderedJsonAggregates: false };
2
4
  /**
3
5
  * SQLite Dialect specialization for the `@libsql/client` driver.
4
6
  *
@@ -6,6 +8,7 @@ import { SqliteDialect } from '../sqlite/sqliteDialect.js';
6
8
  * functions, which `TursoDialect` inherits.
7
9
  */
8
10
  export class LibsqlDialect extends SqliteDialect {
11
+ features = LIBSQL_FEATURES;
9
12
  /** libSQL's built-in vector functions, and the metric its DiskANN index names; no `inner` (only the Rust engine has it) and no `l1`. */
10
13
  vectorMetrics = new Map([
11
14
  ['cosine', { fn: 'vector_distance_cos', index: 'cosine' }],
@@ -7,7 +7,7 @@ import { LibsqlDialect } from './libsqlDialect.js';
7
7
  * Pool for libSQL. One client serves every querier, since Hrana keeps no per-connection state: a
8
8
  * transaction takes its own session handle. The pool builds that client from `@libsql/client`'s
9
9
  * `Config`, or shares one the caller built (`@libsql/client/web`, `@libsql/client-wasm`), which stays
10
- * theirs to close.
10
+ * theirs to close and must read integers as `bigint` (`intMode: 'bigint'`), or one past 2^53 throws.
11
11
  */
12
12
  export declare class LibsqlQuerierPool extends AbstractSharedHandleQuerierPool<HranaClient, HranaQuerier, LibsqlDialect> {
13
13
  private readonly conf;
@@ -6,7 +6,7 @@ import { LibsqlDialect } from './libsqlDialect.js';
6
6
  * Pool for libSQL. One client serves every querier, since Hrana keeps no per-connection state: a
7
7
  * transaction takes its own session handle. The pool builds that client from `@libsql/client`'s
8
8
  * `Config`, or shares one the caller built (`@libsql/client/web`, `@libsql/client-wasm`), which stays
9
- * theirs to close.
9
+ * theirs to close and must read integers as `bigint` (`intMode: 'bigint'`), or one past 2^53 throws.
10
10
  */
11
11
  export class LibsqlQuerierPool extends AbstractSharedHandleQuerierPool {
12
12
  conf;
@@ -14,7 +14,7 @@ export class MariadbQuerierPool extends AbstractSqlQuerierPool {
14
14
  // whatever `timezone` says; that only sets the session's zone, UTC, so `NOW()` agrees.
15
15
  this.pool = createPool({ timezone: 'Z', dateStrings: true, ...opts });
16
16
  // `mariadb` fires 'error' at runtime without declaring it, hence the cast; this makes it visible.
17
- attachPoolErrorHandler(this.pool, 'Idle MariaDB pool connection encountered an error', extra?.logger);
17
+ attachPoolErrorHandler(this.pool, 'MariaDB pool connection encountered an error', extra?.logger);
18
18
  }
19
19
  async getQuerier() {
20
20
  return new MariadbQuerier(() => this.pool.getConnection(), this.dialect, this.extra);
@@ -1,6 +1,4 @@
1
1
  #!/usr/bin/env node
2
2
  import { main } from './cli.js';
3
- main(process.argv.slice(2)).catch((err) => {
4
- console.error(err);
5
- process.exit(1);
6
- });
3
+ // `main` reports its own failures and exits with 1, so it never rejects.
4
+ await main(process.argv.slice(2));
@@ -1,13 +1,13 @@
1
1
  #!/usr/bin/env node
2
2
  import * as fs from 'node:fs';
3
3
  import * as path from 'node:path';
4
+ import { UqlUsageError } from '../util/uqlError.js';
4
5
  import { assertCliConfig } from './assertCliConfig.js';
5
6
  import { loadConfig } from './cli-config.js';
6
7
  import { createEntityCodeGenerator } from './codegen/entityCodeGenerator.js';
7
8
  import { entityTypesSource } from './codegen/entityTypes.js';
8
9
  import { detectDrift } from './drift/driftDetector.js';
9
10
  import { Migrator } from './migrator.js';
10
- import { buildEntityAST } from './schemaGenerator.js';
11
11
  import { DEFAULT_MIGRATIONS_TABLE } from './storage/databaseStorage.js';
12
12
  export async function main(args = process.argv.slice(2)) {
13
13
  let customPath;
@@ -247,11 +247,15 @@ export async function runDriftCheck(migrator, config) {
247
247
  else {
248
248
  console.log('\nChecking for schema drift...');
249
249
  const generator = await migrator.getSchemaGenerator();
250
- const expectedAST = generator.buildAST?.(config.entities) ?? buildEntityAST(generator, config.entities);
250
+ // MongoDB's generator builds no AST: a collection has only its indexes to compare, which a dry run lists.
251
+ if (!generator.buildAST) {
252
+ throw new UqlUsageError('drift:check compares tables, and this database has none: `sync --dry-run` prints the index changes a sync would make');
253
+ }
254
+ const expectedAST = generator.buildAST(config.entities);
251
255
  // Build actual schema from database
252
256
  const actualAST = await migrator.schemaIntrospector.introspect();
253
- // Detect drift. The dialect renders canonical types as SQL - without it every type formats as
254
- // `unknown` and type drift compares equal, silently reporting a mismatched column as in sync.
257
+ // The dialect renders canonical types as SQL: without it no type drift is reported, silently
258
+ // passing a mismatched column as in sync.
255
259
  const report = detectDrift(expectedAST, actualAST, {
256
260
  dialect: config.pool?.dialect,
257
261
  defaultsEqual: generator.defaultsEqual,
@@ -1,6 +1,6 @@
1
1
  import { getMeta } from '../../entity/index.js';
2
2
  import { canonicalToTypeScript, resolveColumnCanonicalType } from '../../schema/canonicalType.js';
3
- import { declaresNotNull, isToManyRelation, upperFirst } from '../../util/index.js';
3
+ import { declaresNotNull, definedEntries, isToManyRelation, upperFirst } from '../../util/index.js';
4
4
  import { isIdentifierName } from './sourceLiteral.js';
5
5
  /**
6
6
  * A `.d.ts` for the entities as registered, so a shape that only exists at runtime reaches the
@@ -14,8 +14,8 @@ export function entityTypesSource(entities) {
14
14
  const names = interfaceNames(metas);
15
15
  const interfaces = metas.map((meta) => {
16
16
  const members = [
17
- ...Object.entries(meta.fields).map(([key, field]) => fieldMember(key, field)),
18
- ...Object.entries(meta.relations).map(([key, rel]) => ` ${propertyName(key)}?: ${relationType(rel, names)};`),
17
+ ...definedEntries(meta.fields).map(([key, field]) => fieldMember(key, field)),
18
+ ...definedEntries(meta.relations).map(([key, rel]) => ` ${propertyName(key)}?: ${relationType(rel, names)};`),
19
19
  ];
20
20
  return `export interface ${names.get(meta.entity)} {\n${members.join('\n')}\n}`;
21
21
  });
@@ -52,13 +52,11 @@ function propertyName(key) {
52
52
  * A field as an entity class declares it: required where every read has it and an insert names it, a
53
53
  * key included, which an insert leaves out anyway; optional where a default fills it or a read skips it
54
54
  * (`eager: false`); `| null` where the column holds NULL; `readonly` where the database computes it.
55
+ * Typed as the DDL resolves it, so a foreign key reads as the key it points at.
55
56
  */
56
57
  function fieldMember(key, field) {
57
- const type = fieldType(field);
58
+ const type = canonicalToTypeScript(resolveColumnCanonicalType(field));
58
59
  const name = propertyName(key);
59
- if (!field) {
60
- return ` ${name}?: ${type};`;
61
- }
62
60
  const written = field.computed === undefined ? '' : 'readonly ';
63
61
  if (!declaresNotNull(field)) {
64
62
  return ` ${written}${name}?: ${type} | null;`;
@@ -66,19 +64,12 @@ function fieldMember(key, field) {
66
64
  const optional = !field.isId && (field.defaultValue !== undefined || field.onInsert !== undefined || field.eager === false);
67
65
  return ` ${written}${name}${optional ? '?' : ''}: ${type};`;
68
66
  }
69
- /**
70
- * The property type a column reads back as, resolved the way the DDL resolves it - so a foreign key
71
- * reports the type of the key it points at rather than the fallback its own options carry.
72
- */
73
- function fieldType(field) {
74
- return field ? canonicalToTypeScript(resolveColumnCanonicalType(field)) : 'unknown';
75
- }
76
67
  /**
77
68
  * A relation is the related interface, a list where the cardinality says so - and `unknown` where the
78
69
  * target is outside the set, since naming an interface the file does not declare would not compile.
79
70
  */
80
71
  function relationType(relation, names) {
81
- const target = relation && names.get(relation.entity());
72
+ const target = names.get(relation.entity());
82
73
  if (!target) {
83
74
  return 'unknown';
84
75
  }
@@ -1,6 +1,6 @@
1
1
  import type { AbstractSqlDialect } from '../../dialect/abstractSqlDialect.js';
2
2
  import { type IndexType } from '../../schema/types.js';
3
- import { type IndexColumnSchema, type IndexFeature, type IndexJsonArray, type IndexJsonPath, type IndexSchema } from '../../type/index.js';
3
+ import { type IndexColumnSchema, type IndexFeature, type IndexJsonPath, type IndexSchema } from '../../type/index.js';
4
4
  /** Refuses an index of a type `types` lacks, `hints` naming what to declare instead. */
5
5
  export declare function assertIndexType(index: IndexSchema, types: ReadonlySet<IndexType>, dialectName: string, hints?: ReadonlyMap<IndexType, string>): void;
6
6
  /** Refuses an index asking for a feature `features` lacks. */
@@ -52,11 +52,6 @@ export declare class IndexDdl<D extends AbstractSqlDialect = AbstractSqlDialect>
52
52
  protected indexColumnTarget(entry: IndexColumnSchema): string;
53
53
  /** The path read the way a query comparing it reads it, which is how the planner matches the two. */
54
54
  protected jsonPathIndexExpr(escapedColumn: string, json: IndexJsonPath): string;
55
- /**
56
- * One key per *element* of the JSON array, which is MySQL's multi-valued index and nothing else's -
57
- * every other dialect refuses `jsonArray` in {@link assertIndexFeatures} and never reaches this.
58
- */
59
- protected jsonArrayIndexExpr(_escapedColumn: string, _json: IndexJsonArray): string;
60
55
  /** Postgres-wire dialects put a vector or user-declared operator class here. */
61
56
  protected indexColumnOpsClass(_entry: IndexColumnSchema, _index: IndexSchema): string;
62
57
  /** `ASC` is every engine's default, so only `DESC` is worth emitting. */
@@ -109,22 +109,12 @@ export class IndexDdl {
109
109
  if (entry.jsonPath) {
110
110
  return `(${this.jsonPathIndexExpr(column, entry.jsonPath)})`;
111
111
  }
112
- if (entry.jsonArray) {
113
- return `(${this.jsonArrayIndexExpr(column, entry.jsonArray)})`;
114
- }
115
112
  return entry.length === undefined ? column : `${column}(${entry.length})`;
116
113
  }
117
114
  /** The path read the way a query comparing it reads it, which is how the planner matches the two. */
118
115
  jsonPathIndexExpr(escapedColumn, json) {
119
116
  return this.dialect.jsonPathExpr(escapedColumn, json.path, jsonTypeMode(json.type));
120
117
  }
121
- /**
122
- * One key per *element* of the JSON array, which is MySQL's multi-valued index and nothing else's -
123
- * every other dialect refuses `jsonArray` in {@link assertIndexFeatures} and never reaches this.
124
- */
125
- jsonArrayIndexExpr(_escapedColumn, _json) {
126
- throw new UqlUsageError(`${this.dialect.dialectName} has no multi-valued index`);
127
- }
128
118
  /** Postgres-wire dialects put a vector or user-declared operator class here. */
129
119
  indexColumnOpsClass(_entry, _index) {
130
120
  return '';
@@ -1,5 +1,5 @@
1
1
  import type { IndexType } from '../../schema/types.js';
2
- import type { IndexJsonArray, IndexJsonPath, IndexSchema } from '../../type/index.js';
2
+ import type { IndexColumnSchema, IndexJsonPath, IndexSchema } from '../../type/index.js';
3
3
  import { IndexDdl } from './indexDdl.js';
4
4
  /** `CREATE INDEX ... (cols) USING btree`, plus the types this family spells as a keyword instead. */
5
5
  export declare class MysqlLikeIndexDdl extends IndexDdl {
@@ -23,11 +23,11 @@ export declare class MySqlIndexDdl extends MysqlLikeIndexDdl {
23
23
  */
24
24
  protected jsonPathIndexExpr(escapedColumn: string, json: IndexJsonPath): string;
25
25
  /**
26
- * `CAST(col AS CHAR(64) ARRAY)`, over the column itself where the array is the whole document -
27
- * which is what `$all` reads, and what its `JSON_CONTAINS(col, ?)` is matched against. A `path`
28
- * indexes the array at that path instead, as `'tags.ids': { $all: [...] }` reads it.
26
+ * A JSON array entry is MySQL's multi-valued index, one key per element: `CAST(col AS CHAR(64) ARRAY)`,
27
+ * over the column itself where the array is the whole document, which is what `$all`'s
28
+ * `JSON_CONTAINS(col, ?)` is matched against. A `path` indexes the array at that path instead.
29
29
  */
30
- protected jsonArrayIndexExpr(escapedColumn: string, json: IndexJsonArray): string;
30
+ protected indexColumnTarget(entry: IndexColumnSchema): string;
31
31
  /**
32
32
  * MySQL 26.7 has `VECTOR` columns and `STRING_TO_VECTOR`, but no distance function outside
33
33
  * HeatWave, hence no vector index to build: `USING hnsw` is a syntax error, `VECTOR INDEX` MariaDB's.
@@ -51,13 +51,18 @@ export class MySqlIndexDdl extends MysqlLikeIndexDdl {
51
51
  return `CAST(${expr} AS CHAR(${json.length}) CHARACTER SET utf8mb4) COLLATE utf8mb4_bin`;
52
52
  }
53
53
  /**
54
- * `CAST(col AS CHAR(64) ARRAY)`, over the column itself where the array is the whole document -
55
- * which is what `$all` reads, and what its `JSON_CONTAINS(col, ?)` is matched against. A `path`
56
- * indexes the array at that path instead, as `'tags.ids': { $all: [...] }` reads it.
54
+ * A JSON array entry is MySQL's multi-valued index, one key per element: `CAST(col AS CHAR(64) ARRAY)`,
55
+ * over the column itself where the array is the whole document, which is what `$all`'s
56
+ * `JSON_CONTAINS(col, ?)` is matched against. A `path` indexes the array at that path instead.
57
57
  */
58
- jsonArrayIndexExpr(escapedColumn, json) {
59
- const source = json.path ? this.dialect.jsonPathExpr(escapedColumn, json.path, 'json') : escapedColumn;
60
- return `CAST(${source} AS ${arrayCastType(json)} ARRAY)`;
58
+ indexColumnTarget(entry) {
59
+ const json = entry.jsonArray;
60
+ if (!json) {
61
+ return super.indexColumnTarget(entry);
62
+ }
63
+ const column = this.dialect.escapeId(entry.column);
64
+ const source = json.path ? this.dialect.jsonPathExpr(column, json.path, 'json') : column;
65
+ return `(CAST(${source} AS ${arrayCastType(json)} ARRAY))`;
61
66
  }
62
67
  /**
63
68
  * MySQL 26.7 has `VECTOR` columns and `STRING_TO_VECTOR`, but no distance function outside
@@ -1,5 +1,6 @@
1
1
  import type { AbstractSqlDialect } from '../../dialect/abstractSqlDialect.js';
2
2
  import type { Alteration, ColumnSchema } from '../../type/index.js';
3
+ import { UqlUsageError } from '../../util/uqlError.js';
3
4
  /**
4
5
  * A column's type with the size it was read back with, unless its spelling already carries one:
5
6
  * introspection reports `VARCHAR` and `255` apart, where a type from an entity is already whole.
@@ -24,8 +25,11 @@ export declare class TableDdl {
24
25
  alterColumn(table: string, column: ColumnSchema, definition: string, from?: ColumnSchema): string[];
25
26
  /** The statements making `alterations` to one table, whose new definitions `render` writes. */
26
27
  alterColumns(table: string, alterations: readonly Alteration<ColumnSchema>[], render: (column: ColumnSchema) => string): string[];
27
- /** The `ALTER TABLE` clauses that change a column, as {@link alterColumn} takes it. */
28
- protected alterClauses(_column: ColumnSchema, definition: string, _from?: ColumnSchema): string[];
28
+ /**
29
+ * The `ALTER TABLE` clauses that change a column, as {@link alterColumn} takes it. None in the portable
30
+ * form: SQLite changes a column only by rebuilding its table, which a diff states as `rebuild`.
31
+ */
32
+ protected alterClauses(column: ColumnSchema, _definition: string, _from?: ColumnSchema): string[];
29
33
  /** One `ALTER TABLE` making every clause, and none for no clause. */
30
34
  protected alterTable(table: string, clauses: readonly string[]): string[];
31
35
  renameColumn(table: string, oldName: string, newName: string): string;
@@ -48,3 +52,5 @@ export declare class TableDdl {
48
52
  }
49
53
  /** `DROP INDEX <index> ON <table>`, for engines that scope index names per table: MySQL and SQL Server. */
50
54
  export declare function dropIndexOnTable(dialect: AbstractSqlDialect, table: string, index: string): string;
55
+ /** What an engine that changes a table only by rebuilding it says to `what`, done in place. */
56
+ export declare function rebuildRefusal(dialect: AbstractSqlDialect, what: string): UqlUsageError;
@@ -47,9 +47,12 @@ export class TableDdl {
47
47
  alterColumns(table, alterations, render) {
48
48
  return this.alterTable(table, alterations.flatMap(({ from, to }) => this.alterClauses(to, render(to), from)));
49
49
  }
50
- /** The `ALTER TABLE` clauses that change a column, as {@link alterColumn} takes it. */
51
- alterClauses(_column, definition, _from) {
52
- return [`ALTER COLUMN ${definition}`];
50
+ /**
51
+ * The `ALTER TABLE` clauses that change a column, as {@link alterColumn} takes it. None in the portable
52
+ * form: SQLite changes a column only by rebuilding its table, which a diff states as `rebuild`.
53
+ */
54
+ alterClauses(column, _definition, _from) {
55
+ throw rebuildRefusal(this.dialect, `Altering the column "${column.name}"`);
53
56
  }
54
57
  /** One `ALTER TABLE` making every clause, and none for no clause. */
55
58
  alterTable(table, clauses) {
@@ -95,3 +98,8 @@ export class TableDdl {
95
98
  export function dropIndexOnTable(dialect, table, index) {
96
99
  return `DROP INDEX ${dialect.escapeId(index)} ON ${dialect.escapeId(table)};`;
97
100
  }
101
+ /** What an engine that changes a table only by rebuilding it says to `what`, done in place. */
102
+ export function rebuildRefusal(dialect, what) {
103
+ return new UqlUsageError(`${dialect.dialectName}: ${what} rebuilds the table, which a migration generated from the entities does ` +
104
+ '(`uql-migrate generate:entities`) and a hand-written one cannot.');
105
+ }
@@ -124,8 +124,8 @@ function addAlterColumnDrifts(colDiff, drifts, opts) {
124
124
  const { changed } = colDiff;
125
125
  // Type drift needs a dialect to render both types.
126
126
  if (opts.checkTypes && opts.dialect && changed.includes('type')) {
127
- const expectedType = formatType(colDiff.to.type, opts.dialect);
128
- const actualType = formatType(colDiff.from.type, opts.dialect);
127
+ const expectedType = canonicalToSql(colDiff.to.type, opts.dialect);
128
+ const actualType = canonicalToSql(colDiff.from.type, opts.dialect);
129
129
  drifts.push({
130
130
  type: 'type_mismatch',
131
131
  severity: colDiff.isBreaking ? 'critical' : 'warning',
@@ -276,11 +276,3 @@ function createSummary(drifts) {
276
276
  info: drifts.filter((d) => d.severity === 'info').length,
277
277
  };
278
278
  }
279
- /**
280
- * Format type for display.
281
- */
282
- function formatType(type, dialect) {
283
- if (!dialect)
284
- return 'unknown';
285
- return canonicalToSql(type, dialect);
286
- }
@@ -31,7 +31,7 @@ export declare class SqliteSchemaIntrospector extends AbstractSqlSchemaIntrospec
31
31
  }): string;
32
32
  protected mapColumnsResult(read: TableRowReader, tableName: string, results: SqliteColumnRow[]): Promise<ColumnSchema[]>;
33
33
  protected mapIndexesResult(read: TableRowReader, _tableName: string, results: SqliteIndexRow[]): Promise<IndexSchema[]>;
34
- protected mapForeignKeysResult(_read: TableRowReader, tableName: string, results: SqliteForeignKeyRow[]): Promise<ForeignKeySchema[]>;
34
+ protected mapForeignKeysResult(_read: TableRowReader, _tableName: string, results: SqliteForeignKeyRow[]): Promise<ForeignKeySchema[]>;
35
35
  /** Every statement `sqlite_master` keeps for the table, its `CREATE TABLE` first. An automatic index has none. */
36
36
  protected getDefinition(read: TableRowReader, tableName: string): Promise<StoredDefinition[]>;
37
37
  protected mapPrimaryKeyResult(results: SqliteColumnRow[]): string[] | undefined;
@@ -1,4 +1,3 @@
1
- import { derivedForeignKeyName } from '../../util/sql.util.js';
2
1
  import { AbstractSqlSchemaIntrospector } from './abstractSqlSchemaIntrospector.js';
3
2
  /**
4
3
  * SQLite schema introspector
@@ -116,7 +115,7 @@ export class SqliteSchemaIntrospector extends AbstractSqlSchemaIntrospector {
116
115
  }
117
116
  return indexSchemas;
118
117
  }
119
- async mapForeignKeysResult(_read, tableName, results) {
118
+ async mapForeignKeysResult(_read, _tableName, results) {
120
119
  // Group by id to handle composite foreign keys
121
120
  const grouped = new Map();
122
121
  for (const row of results) {
@@ -128,10 +127,8 @@ export class SqliteSchemaIntrospector extends AbstractSqlSchemaIntrospector {
128
127
  return Array.from(grouped.entries()).map(([, rows]) => {
129
128
  const first = rows[0];
130
129
  const columns = rows.map((r) => r.from);
130
+ // Unnamed: `PRAGMA foreign_key_list` reports none, so the AST derives one from the columns, as the entity side does.
131
131
  return {
132
- // `PRAGMA foreign_key_list` reports no name, so one is derived the same way the entity side
133
- // derives it. Seeded from the columns, not the PRAGMA's row id, which nothing else knows.
134
- name: derivedForeignKeyName(tableName, columns),
135
132
  columns,
136
133
  references: { table: first.table, columns: rows.map((r) => r.to) },
137
134
  onDelete: this.normalizeReferentialAction(first.on_delete),
@@ -286,6 +283,6 @@ function scan(sql, visit) {
286
283
  }
287
284
  /** The name a column definition opens with, however it was quoted. */
288
285
  function leadingIdentifier(entry) {
289
- const [token = ''] = /^\s*(?:"[^"]*"|`[^`]*`|\[[^\]]*\]|[^\s(]+)/.exec(entry) ?? [];
290
- return token.trim().replace(/^["`[]|["`\]]$/g, '');
286
+ const token = entry.trimStart().replace(/^("[^"]*"|`[^`]*`|\[[^\]]*\]|[^\s(]*)[\s\S]*$/, '$1');
287
+ return token.replace(/^["`[]|["`\]]$/g, '');
291
288
  }
@@ -1,4 +1,4 @@
1
- import type { LoggingOptions, Migration, MigrationDefinition, MigrationResult, MigrationStorage, MigratorDialect, MigratorOptions, Querier, QuerierPool, SchemaDiff, SchemaGenerator, SchemaIntrospector, SqlQuerier, SyncOptions, Type } from '../type/index.js';
1
+ import type { Migration, MigrationDefinition, MigrationResult, MigrationStorage, MigratorDialect, MigratorOptions, Querier, QuerierPool, SchemaDiff, SchemaGenerator, SchemaIntrospector, SqlQuerier, SyncOptions, Type } from '../type/index.js';
2
2
  import { LoggerWrapper } from '../util/index.js';
3
3
  import type { IMigrationBuilder } from './builder/types.js';
4
4
  /**
@@ -8,9 +8,7 @@ export declare class Migrator {
8
8
  private readonly pool;
9
9
  readonly storage: MigrationStorage;
10
10
  readonly migrationsPath: string;
11
- private _logger;
12
- get logger(): LoggerWrapper;
13
- set logger(value: LoggingOptions);
11
+ readonly logger: LoggerWrapper;
14
12
  private readonly _entities?;
15
13
  get entities(): Type<object>[];
16
14
  /** The generator given, or this dialect's once {@link getSchemaGenerator} has loaded it. */
@@ -5,13 +5,14 @@ import { getEntities, getMeta } from '../entity/index.js';
5
5
  import { SchemaAST } from '../schema/index.js';
6
6
  import { columnRenames, tableRenameCandidates } from '../schema/schemaASTDiffer.js';
7
7
  import { hasTriggers } from '../util/field.util.js';
8
- import { LoggerWrapper } from '../util/index.js';
8
+ import { definedEntries, isRecord, LoggerWrapper } from '../util/index.js';
9
9
  import { UqlUsageError } from '../util/uqlError.js';
10
10
  import { withSqlQuerierForMigrations } from './acquireQuerierForMigrations.js';
11
11
  import { buildMigrationModule } from './codegen/migrationFile.js';
12
12
  import { introspectorFor } from './introspection/registry.js';
13
13
  import { migrationBuilderFor, migrationTargetFor } from './migrationTarget.js';
14
14
  import { dropped, lacksValue, newlyRequired, nonEmpty, reverseDiff, sides, withoutRebuild } from './schemaChange.js';
15
+ import { constraintNameOf } from './schemaGenerator.js';
15
16
  /**
16
17
  * Main class for managing database migrations
17
18
  */
@@ -19,13 +20,7 @@ export class Migrator {
19
20
  pool;
20
21
  storage;
21
22
  migrationsPath;
22
- _logger;
23
- get logger() {
24
- return this._logger;
25
- }
26
- set logger(value) {
27
- this._logger = new LoggerWrapper(value);
28
- }
23
+ logger;
29
24
  _entities;
30
25
  get entities() {
31
26
  return this._entities ?? getEntities();
@@ -39,7 +34,7 @@ export class Migrator {
39
34
  this.target = migrationTargetFor(pool, options.defaultForeignKeyAction);
40
35
  this.storage = options.storage ?? this.target.storage(options.tableName);
41
36
  this.migrationsPath = options.migrationsPath ?? './migrations';
42
- this._logger = new LoggerWrapper(options.logger, { logValues: options.logValues, slowQuery: options.slowQuery });
37
+ this.logger = new LoggerWrapper(options.logger, { logValues: options.logValues, slowQuery: options.slowQuery });
43
38
  this._entities = options.entities;
44
39
  this.schemaIntrospector = introspectorFor(pool);
45
40
  this.schemaGenerator = options.schemaGenerator;
@@ -392,9 +387,10 @@ export class Migrator {
392
387
  }
393
388
  }
394
389
  /** Every table dropped and recreated, the whole entity set at once, so foreign keys resolve and drop in graph order. */
395
- forceStatements(generator) {
390
+ async forceStatements(generator) {
391
+ const existing = await this.introspectEntities(this.entities);
396
392
  return [
397
- ...generator.generateDropSchema(this.entities, { ifExists: true, cascade: true }),
393
+ ...generator.generateDropSchema(this.entities, { ifExists: true, cascade: true, existing }),
398
394
  ...generator.generateCreateSchema(this.entities),
399
395
  ];
400
396
  }
@@ -507,7 +503,7 @@ export class Migrator {
507
503
  primaryKey: safe ? undefined : diff.primaryKey,
508
504
  columns: options.drop ? columns : nonEmpty((columns ?? []).filter((change) => change.to !== undefined)),
509
505
  indexes: additive('index', diff.indexes, (index) => index.name),
510
- foreignKeys: additive('foreign key', diff.foreignKeys, (foreignKey) => foreignKey.name ?? foreignKey.columns.join(', ')),
506
+ foreignKeys: additive('foreign key', diff.foreignKeys, (foreignKey) => constraintNameOf(diff.tableName, foreignKey)),
511
507
  };
512
508
  if (!diff.rebuild || !held) {
513
509
  return filtered;
@@ -566,6 +562,7 @@ export class Migrator {
566
562
  name: this.getMigrationName(fileName),
567
563
  up: migration.up.bind(migration),
568
564
  down: migration.down.bind(migration),
565
+ transaction: migration.transaction,
569
566
  };
570
567
  }
571
568
  this.logger.logWarn(`Warning: ${fileName} is not a valid migration`);
@@ -580,11 +577,7 @@ export class Migrator {
580
577
  * Check if an object is a valid migration
581
578
  */
582
579
  isMigration(obj) {
583
- return (typeof obj === 'object' &&
584
- obj !== undefined &&
585
- obj !== null &&
586
- typeof obj.up === 'function' &&
587
- typeof obj.down === 'function');
580
+ return isRecord(obj) && typeof obj['up'] === 'function' && typeof obj['down'] === 'function';
588
581
  }
589
582
  /**
590
583
  * Extract migration name from filename
@@ -635,9 +628,8 @@ export function defineBuilderMigration(migration) {
635
628
  }
636
629
  /** The entities `meta` points at, through a relation or a foreign key field. */
637
630
  function referencedEntities(meta) {
638
- const fields = Object.values(meta.fields).flatMap((field) => field?.references?.() ?? []);
639
- const relations = Object.values(meta.relations).flatMap((relation) => relation?.entity?.() ?? []);
640
- return [...fields, ...relations];
631
+ const fields = definedEntries(meta.fields).flatMap(([, field]) => field.references?.() ?? []);
632
+ return [...fields, ...definedEntries(meta.relations).map(([, relation]) => relation.entity())];
641
633
  }
642
634
  /** A diff's column renames, through the builder operation every SQL generator already renders. */
643
635
  function renameStatements(generator, { tableName, renamedColumns = [], rebuild }) {
@@ -187,6 +187,11 @@ export declare class SqlSchemaGenerator implements SchemaGenerator {
187
187
  */
188
188
  private assertAlterable;
189
189
  }
190
+ /**
191
+ * What a constraint is called: its own name, or one derived from its columns where nothing named it.
192
+ * Shared by the add and the drop so a `DROP CONSTRAINT` names exactly what an `ADD CONSTRAINT` made.
193
+ */
194
+ export declare function constraintNameOf(tableName: string, foreignKey: ForeignKeySchema): string;
190
195
  /**
191
196
  * The entities as an AST, named by `generator`'s resolvers rather than a naming strategy, which would
192
197
  * also rename an explicit `@Entity({ name })` and so compare each table under another name.