uql-orm 0.114.1 → 0.114.2
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.
- package/README.md +2 -4
- package/dist/cockroachdb/cockroachDialect.js +1 -1
- package/dist/dialect/abstractSqlDialect.d.ts +1 -0
- package/dist/dialect/abstractSqlDialect.js +4 -0
- package/dist/dialect/pgLikeSqlDialect.d.ts +3 -2
- package/dist/dialect/pgLikeSqlDialect.js +9 -30
- package/dist/migrate/migrationLock.d.ts +8 -9
- package/dist/migrate/migrationLock.js +41 -43
- package/dist/migrate/storage/databaseStorage.d.ts +5 -5
- package/dist/migrate/storage/databaseStorage.js +21 -13
- package/dist/pglite/pgliteDialect.js +1 -1
- package/dist/sqlite/sqliteDialect.js +1 -1
- package/dist/type/dialect.d.ts +5 -5
- package/dist/type/querySql.d.ts +2 -2
- package/dist/util/ddlExpression.util.js +1 -9
- package/dist/util/sql.d.ts +1 -1
- package/dist/util/sql.js +14 -8
- package/dist/util/sqlLiteral.d.ts +2 -0
- package/dist/util/sqlLiteral.js +29 -14
- package/package.json +1 -1
- package/skills/uql-orm/SKILL.md +1 -1
package/README.md
CHANGED
|
@@ -165,8 +165,6 @@ Release notes live in [CHANGELOG.md](https://github.com/rogerpadilla/uql/blob/ma
|
|
|
165
165
|
|
|
166
166
|
---
|
|
167
167
|
|
|
168
|
-
##
|
|
168
|
+
## Enjoy UQL? ⭐
|
|
169
169
|
|
|
170
|
-
|
|
171
|
-
|
|
172
|
-
[](https://github.com/rogerpadilla/uql)
|
|
170
|
+
[](https://github.com/rogerpadilla/uql)
|
|
@@ -23,7 +23,7 @@ export class CockroachDialect extends PgLikeSqlDialect {
|
|
|
23
23
|
...PG_FEATURES,
|
|
24
24
|
nullsSortLowest: true,
|
|
25
25
|
triggers: { ...PG_FEATURES.triggers, fires: 'eachRowIf', deferrable: false },
|
|
26
|
-
namedLocks:
|
|
26
|
+
namedLocks: 'journal',
|
|
27
27
|
};
|
|
28
28
|
/**
|
|
29
29
|
* Not Postgres' `pg_class.reltuples`, which CockroachDB answers `NULL` for even straight after an
|
|
@@ -163,6 +163,7 @@ export declare abstract class AbstractSqlDialect extends VectorSqlDialect implem
|
|
|
163
163
|
* Converts a parameter value to what this engine's driver takes: a `Date` per {@link dateZone}, a boolean to
|
|
164
164
|
* 1/0 on an engine with no boolean type, and anything else unchanged. A `bigint` passes as is, since every
|
|
165
165
|
* driver here binds it exactly where a number would round past 2^53; a driver that refuses one (D1) overrides.
|
|
166
|
+
* An array is refused: only an engine with an array type, which overrides, binds one.
|
|
166
167
|
*/
|
|
167
168
|
normalizeValue(value: unknown): unknown;
|
|
168
169
|
placeholder(_index: number): string;
|
|
@@ -203,8 +203,12 @@ export class AbstractSqlDialect extends VectorSqlDialect {
|
|
|
203
203
|
* Converts a parameter value to what this engine's driver takes: a `Date` per {@link dateZone}, a boolean to
|
|
204
204
|
* 1/0 on an engine with no boolean type, and anything else unchanged. A `bigint` passes as is, since every
|
|
205
205
|
* driver here binds it exactly where a number would round past 2^53; a driver that refuses one (D1) overrides.
|
|
206
|
+
* An array is refused: only an engine with an array type, which overrides, binds one.
|
|
206
207
|
*/
|
|
207
208
|
normalizeValue(value) {
|
|
209
|
+
if (Array.isArray(value)) {
|
|
210
|
+
throw new UqlUsageError(`${this.engineName} has no array type to bind one into: write a list with sql.join(values), or filter a field with $in`);
|
|
211
|
+
}
|
|
208
212
|
if (value instanceof Date && this.dateZone !== undefined) {
|
|
209
213
|
return utcTimestamp(value, this.dateZone);
|
|
210
214
|
}
|
|
@@ -66,6 +66,7 @@ export declare abstract class PgLikeSqlDialect extends AbstractSqlDialect {
|
|
|
66
66
|
/** Binds a date as UTC text, which a zoneless `TIMESTAMP` stores as is, instead of each driver picking a zone. */
|
|
67
67
|
protected readonly dateZone = "+00";
|
|
68
68
|
normalizeValue(value: unknown): unknown;
|
|
69
|
+
private normalizeElements;
|
|
69
70
|
placeholder(index: number): string;
|
|
70
71
|
/**
|
|
71
72
|
* `<document> @@ WEBSEARCH_TO_TSQUERY(...)`, under the `$config` asked for, else that of the fulltext
|
|
@@ -110,8 +111,8 @@ export declare abstract class PgLikeSqlDialect extends AbstractSqlDialect {
|
|
|
110
111
|
/** A single key's list binds as one array, whatever its length. */
|
|
111
112
|
keyListCapacity(keyCount: number): number;
|
|
112
113
|
/**
|
|
113
|
-
* One array parameter,
|
|
114
|
-
*
|
|
114
|
+
* One array parameter, or a list for one holding SQL. DDL keeps the list too, since its text names what it declares:
|
|
115
|
+
* an array literal would rename every index and check written with `$in`. The array takes its type from `operand`.
|
|
115
116
|
*/
|
|
116
117
|
protected formatIn(ctx: QueryContext, operand: string, values: unknown[], negate: boolean, bind: (value: unknown) => string): string;
|
|
117
118
|
escape(value: unknown): string;
|
|
@@ -1,8 +1,7 @@
|
|
|
1
1
|
import { QuerySql, } from '../type/index.js';
|
|
2
|
-
import { bytesToHex } from '../util/bytes.js';
|
|
3
2
|
import { fulltextConfig, fulltextIndexOver, hasVectorNear, textSearchFields } from '../util/dialect.util.js';
|
|
4
3
|
import { isIntegerColumn, jsonPathKeys } from '../util/field.util.js';
|
|
5
|
-
import { escapePgSqlLiteral, PG_UTC } from '../util/sqlLiteral.js';
|
|
4
|
+
import { escapePgSqlLiteral, PG_UTC, pgArrayText } from '../util/sqlLiteral.js';
|
|
6
5
|
import { ANSI_SQL_VALUES, AbstractSqlDialect, } from './abstractSqlDialect.js';
|
|
7
6
|
import { JSON_PULL_ALIAS, RELATION_ROW_ALIAS } from './aliases.js';
|
|
8
7
|
import { BYTES_PREFIX } from './hydrateColumn.js';
|
|
@@ -142,11 +141,13 @@ export class PgLikeSqlDialect extends AbstractSqlDialect {
|
|
|
142
141
|
dateZone = PG_UTC;
|
|
143
142
|
normalizeValue(value) {
|
|
144
143
|
if (Array.isArray(value)) {
|
|
145
|
-
|
|
146
|
-
return this.driverCapabilities.nativeArrays ? values : toPgArray(values);
|
|
144
|
+
return this.driverCapabilities.nativeArrays ? this.normalizeElements(value) : pgArrayText(value);
|
|
147
145
|
}
|
|
148
146
|
return super.normalizeValue(value);
|
|
149
147
|
}
|
|
148
|
+
normalizeElements(values) {
|
|
149
|
+
return values.map((item) => (Array.isArray(item) ? this.normalizeElements(item) : super.normalizeValue(item)));
|
|
150
|
+
}
|
|
150
151
|
placeholder(index) {
|
|
151
152
|
return `$${index}`;
|
|
152
153
|
}
|
|
@@ -251,8 +252,8 @@ export class PgLikeSqlDialect extends AbstractSqlDialect {
|
|
|
251
252
|
return keyCount > 1 ? super.keyListCapacity(keyCount) : Infinity;
|
|
252
253
|
}
|
|
253
254
|
/**
|
|
254
|
-
* One array parameter,
|
|
255
|
-
*
|
|
255
|
+
* One array parameter, or a list for one holding SQL. DDL keeps the list too, since its text names what it declares:
|
|
256
|
+
* an array literal would rename every index and check written with `$in`. The array takes its type from `operand`.
|
|
256
257
|
*/
|
|
257
258
|
formatIn(ctx, operand, values, negate, bind) {
|
|
258
259
|
if (!values.length || ctx.inlineValues || values.some((value) => value instanceof QuerySql)) {
|
|
@@ -313,10 +314,10 @@ export class PgLikeSqlDialect extends AbstractSqlDialect {
|
|
|
313
314
|
/** A replace hands an absent key's NULL back, which `JSONB_SET` would answer for the whole document. */
|
|
314
315
|
jsonSetKey(expr, path, value, { create = true } = {}) {
|
|
315
316
|
const set = create ? value : `COALESCE(${value}, 'null'::jsonb), false`;
|
|
316
|
-
return `JSONB_SET(${expr}, '${
|
|
317
|
+
return `JSONB_SET(${expr}, '${pgArrayText(jsonPathKeys(path))}', ${set})`;
|
|
317
318
|
}
|
|
318
319
|
jsonUnset(ctx, expr, unset) {
|
|
319
|
-
return unset.reduce((acc, path) => `(${acc}) #- '${
|
|
320
|
+
return unset.reduce((acc, path) => `(${acc}) #- '${pgArrayText(jsonPathKeys(path))}'`, expr);
|
|
320
321
|
}
|
|
321
322
|
/** Postgres binds JSON with a numbered placeholder and an explicit cast, per driver capability. */
|
|
322
323
|
jsonScalarParam(ctx, value) {
|
|
@@ -335,25 +336,3 @@ export class PgLikeSqlDialect extends AbstractSqlDialect {
|
|
|
335
336
|
return this.driverCapabilities.explicitJsonCast ? `(${ph}::text)::${type}` : `${ph}::${type}`;
|
|
336
337
|
}
|
|
337
338
|
}
|
|
338
|
-
/**
|
|
339
|
-
* Converts a JS array to a Postgres array literal string: `{"val1","val2"}`.
|
|
340
|
-
* Safely handles nesting and escaping of special characters.
|
|
341
|
-
*/
|
|
342
|
-
function toPgArray(arr) {
|
|
343
|
-
const elements = arr.map((val) => {
|
|
344
|
-
if (val == null)
|
|
345
|
-
return 'NULL';
|
|
346
|
-
if (Array.isArray(val))
|
|
347
|
-
return toPgArray(val);
|
|
348
|
-
if (typeof val === 'boolean')
|
|
349
|
-
return val ? 'true' : 'false';
|
|
350
|
-
// A Node `Buffer` is a `Uint8Array` too.
|
|
351
|
-
if (val instanceof Uint8Array) {
|
|
352
|
-
return `"\\\\x${bytesToHex(val)}"`;
|
|
353
|
-
}
|
|
354
|
-
const str = String(val);
|
|
355
|
-
const escaped = str.replace(/\\/g, '\\\\').replace(/"/g, '\\"');
|
|
356
|
-
return `"${escaped}"`;
|
|
357
|
-
});
|
|
358
|
-
return `{${elements.join(',')}}`;
|
|
359
|
-
}
|
|
@@ -2,13 +2,13 @@ import type { AbstractSqlDialect } from '../dialect/abstractSqlDialect.js';
|
|
|
2
2
|
import type { QuerierPool, QuerySql, SqlQuerier } from '../type/index.js';
|
|
3
3
|
/** How long `up` and `down` wait for the lock another run holds, unless told otherwise. */
|
|
4
4
|
export declare const DEFAULT_LOCK_TIMEOUT: number;
|
|
5
|
-
/** The statements taking and releasing a
|
|
6
|
-
type
|
|
5
|
+
/** The statements taking and releasing a lock: `acquire` answers a row only when it took it, never waiting. */
|
|
6
|
+
type LockSql = {
|
|
7
7
|
readonly acquire: QuerySql;
|
|
8
8
|
readonly release: QuerySql;
|
|
9
9
|
};
|
|
10
|
-
/** The statements of the lock
|
|
11
|
-
export declare function
|
|
10
|
+
/** The statements of the lock on the journal `name` as `dialect`'s engine holds it, PGlite's in the journal. */
|
|
11
|
+
export declare function lockSql(dialect: AbstractSqlDialect, name: string): LockSql;
|
|
12
12
|
/** The lock a run holds, named after its journal, and how long a second run waits for it. */
|
|
13
13
|
export type MigrationLockOptions = {
|
|
14
14
|
readonly name: string;
|
|
@@ -27,12 +27,11 @@ export type MigrationLock = {
|
|
|
27
27
|
* release failing after `work` did is a consequence of its error, and never replaces it.
|
|
28
28
|
*/
|
|
29
29
|
export declare function holdingLock<T>(lock: MigrationLock, { name, timeout }: MigrationLockOptions, work: () => Promise<T>): Promise<T>;
|
|
30
|
+
/** What to do about a lock record no run released, which only a person can tell is stale. */
|
|
31
|
+
export declare const staleRecord: (what: string, journal: string) => string;
|
|
30
32
|
/**
|
|
31
|
-
* Runs `work` holding the lock
|
|
32
|
-
*
|
|
33
|
-
* journal, which then has to exist before the lock, created by whichever run gets there.
|
|
33
|
+
* Runs `work` holding the lock on the journal `options.name`, created first, where `features.namedLocks` says:
|
|
34
|
+
* on `querier`'s session or in the journal, or in a transaction of its own kept open meanwhile.
|
|
34
35
|
*/
|
|
35
36
|
export declare function withSqlMigrationLock<T>(pool: QuerierPool, querier: SqlQuerier, options: MigrationLockOptions, work: () => Promise<T>): Promise<T>;
|
|
36
|
-
/** What to do about a lock record no run released, which only a person can tell is stale. */
|
|
37
|
-
export declare const staleRecord: (what: string, journal: string) => string;
|
|
38
37
|
export {};
|
|
@@ -13,8 +13,20 @@ const mysqlLock = (name) => {
|
|
|
13
13
|
const lock = sql `LEFT(CONCAT(DATABASE(), '.', ${name}), 64)`;
|
|
14
14
|
return { acquire: sql `SELECT 1 FROM DUAL WHERE GET_LOCK(${lock}, 0) = 1`, release: sql `DO RELEASE_LOCK(${lock})` };
|
|
15
15
|
};
|
|
16
|
-
/**
|
|
17
|
-
|
|
16
|
+
/**
|
|
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.
|
|
19
|
+
*/
|
|
20
|
+
const journalRowLock = (name) => {
|
|
21
|
+
const { table, name: column } = journalIds(name);
|
|
22
|
+
return {
|
|
23
|
+
acquire: sql `INSERT INTO ${table} (${column}) SELECT ${LOCK_RECORD}
|
|
24
|
+
WHERE NOT EXISTS (SELECT 1 FROM ${table} WHERE ${column} = ${LOCK_RECORD}) RETURNING 1`,
|
|
25
|
+
release: sql `DELETE FROM ${table} WHERE ${column} = ${LOCK_RECORD}`,
|
|
26
|
+
};
|
|
27
|
+
};
|
|
28
|
+
/** Each engine's lock on the journal `name`, held by what `features.namedLocks` says. */
|
|
29
|
+
const LOCK_SQL = {
|
|
18
30
|
postgres: (name) => {
|
|
19
31
|
const key = fnv1a(name);
|
|
20
32
|
return {
|
|
@@ -22,7 +34,7 @@ const NAMED_LOCK_SQL = {
|
|
|
22
34
|
release: sql `SELECT pg_advisory_unlock(${key})`,
|
|
23
35
|
};
|
|
24
36
|
},
|
|
25
|
-
cockroachdb:
|
|
37
|
+
cockroachdb: journalRowLock,
|
|
26
38
|
mysql: mysqlLock,
|
|
27
39
|
mariadb: mysqlLock,
|
|
28
40
|
mssql: (name) => ({
|
|
@@ -31,11 +43,11 @@ const NAMED_LOCK_SQL = {
|
|
|
31
43
|
SELECT 1 WHERE @_uql_lock >= 0`,
|
|
32
44
|
release: sql `EXEC sp_releaseapplock @Resource = ${name}, @LockOwner = 'Transaction'`,
|
|
33
45
|
}),
|
|
34
|
-
sqlite:
|
|
46
|
+
sqlite: journalRowLock,
|
|
35
47
|
};
|
|
36
|
-
/** The statements of the lock
|
|
37
|
-
export function
|
|
38
|
-
return dialect.features.namedLocks ?
|
|
48
|
+
/** The statements of the lock on the journal `name` as `dialect`'s engine holds it, PGlite's in the journal. */
|
|
49
|
+
export function lockSql(dialect, name) {
|
|
50
|
+
return dialect.features.namedLocks === 'journal' ? journalRowLock(name) : LOCK_SQL[dialect.dialectName](name);
|
|
39
51
|
}
|
|
40
52
|
/**
|
|
41
53
|
* Runs `work` holding `lock`, asking for it until `timeout` passes, and releasing it however `work` ends: a
|
|
@@ -56,49 +68,35 @@ export async function holdingLock(lock, { name, timeout }, work) {
|
|
|
56
68
|
await lock.release();
|
|
57
69
|
return result;
|
|
58
70
|
}
|
|
71
|
+
/** What to do about a lock record no run released, which only a person can tell is stale. */
|
|
72
|
+
export const staleRecord = (what, journal) => `If none is running, one stopped before releasing it: delete the ${what} '${LOCK_RECORD}' from "${journal}".`;
|
|
73
|
+
const ENGINE_RELEASES = 'The engine releases it once that run ends or its connection closes.';
|
|
74
|
+
/** What to do about a lock held too long, by what holds it. */
|
|
75
|
+
const STUCK = {
|
|
76
|
+
session: () => ENGINE_RELEASES,
|
|
77
|
+
transaction: () => ENGINE_RELEASES,
|
|
78
|
+
journal: (journal) => staleRecord('row', journal),
|
|
79
|
+
};
|
|
59
80
|
/**
|
|
60
|
-
* Runs `work` holding the lock
|
|
61
|
-
*
|
|
62
|
-
* journal, which then has to exist before the lock, created by whichever run gets there.
|
|
81
|
+
* Runs `work` holding the lock on the journal `options.name`, created first, where `features.namedLocks` says:
|
|
82
|
+
* on `querier`'s session or in the journal, or in a transaction of its own kept open meanwhile.
|
|
63
83
|
*/
|
|
64
84
|
export async function withSqlMigrationLock(pool, querier, options, work) {
|
|
65
|
-
const {
|
|
66
|
-
const
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
await createMigrationsTable(querier, options.name);
|
|
73
|
-
return holdingLock(sqlRecordLock(querier, options.name), options, work);
|
|
85
|
+
const { name } = options;
|
|
86
|
+
const holder = querier.dialect.features.namedLocks;
|
|
87
|
+
const stuck = STUCK[holder](name);
|
|
88
|
+
await createMigrationsTable(querier, name);
|
|
89
|
+
const statements = lockSql(querier.dialect, name);
|
|
90
|
+
if (holder !== 'transaction') {
|
|
91
|
+
return holdingLock(sqlLock(querier, statements, stuck), options, work);
|
|
74
92
|
}
|
|
75
|
-
|
|
76
|
-
return holdingLock(statementLock(querier, sql), options, journaled);
|
|
77
|
-
}
|
|
78
|
-
return withSqlQuerierForMigrations(pool, 'Migrator', (own) => own.transaction(() => holdingLock(statementLock(own, sql), options, journaled)));
|
|
93
|
+
return withSqlQuerierForMigrations(pool, 'Migrator', (own) => own.transaction(() => holdingLock(sqlLock(own, statements, stuck), options, work)));
|
|
79
94
|
}
|
|
80
|
-
/** The
|
|
81
|
-
function
|
|
95
|
+
/** The lock `statements` take and release on `querier`. */
|
|
96
|
+
function sqlLock(querier, { acquire, release }, stuck) {
|
|
82
97
|
return {
|
|
83
98
|
take: async () => (await querier.all(acquire)).length > 0,
|
|
84
99
|
release: () => querier.run(release),
|
|
85
|
-
stuck
|
|
86
|
-
};
|
|
87
|
-
}
|
|
88
|
-
/** What to do about a lock record no run released, which only a person can tell is stale. */
|
|
89
|
-
export const staleRecord = (what, journal) => `If none is running, one stopped before releasing it: delete the ${what} '${LOCK_RECORD}' from "${journal}".`;
|
|
90
|
-
/**
|
|
91
|
-
* The journal's {@link LOCK_RECORD} row, inserted only where it is absent, which one run alone can: SQLite
|
|
92
|
-
* writes one statement at a time, and CockroachDB serializes them.
|
|
93
|
-
*/
|
|
94
|
-
function sqlRecordLock(querier, journal) {
|
|
95
|
-
const { table, name } = journalIds(querier, journal);
|
|
96
|
-
return {
|
|
97
|
-
take: async () => {
|
|
98
|
-
const { changes } = await querier.run `INSERT INTO ${table} (${name}) SELECT ${LOCK_RECORD} WHERE NOT EXISTS (SELECT 1 FROM ${table} WHERE ${name} = ${LOCK_RECORD})`;
|
|
99
|
-
return changes === 1;
|
|
100
|
-
},
|
|
101
|
-
release: () => querier.run `DELETE FROM ${table} WHERE ${name} = ${LOCK_RECORD}`,
|
|
102
|
-
stuck: staleRecord('row', journal),
|
|
100
|
+
stuck,
|
|
103
101
|
};
|
|
104
102
|
}
|
|
@@ -14,9 +14,9 @@ export interface MigrationStorage {
|
|
|
14
14
|
unlogWithQuerier(querier: Querier, migrationName: string): Promise<void>;
|
|
15
15
|
}
|
|
16
16
|
/**
|
|
17
|
-
* Creates the journal `tableName` where it is missing, rendered by the schema generator rather than written
|
|
18
|
-
*
|
|
19
|
-
*
|
|
17
|
+
* Creates the journal `tableName` where it is missing, rendered by the schema generator rather than written out: SQL
|
|
18
|
+
* Server has no `CREATE TABLE IF NOT EXISTS`, and its `TIMESTAMP` is a row version that takes no default. It precedes
|
|
19
|
+
* the lock, so a run creating it beside another can lose that race in the catalogue: it asks once more, finding it.
|
|
20
20
|
*/
|
|
21
21
|
export declare function createMigrationsTable(querier: SqlQuerier, tableName: string): Promise<void>;
|
|
22
22
|
/** Records the migrations run in a table, on the querier each call is handed, which the lock created. */
|
|
@@ -32,8 +32,8 @@ export declare class DatabaseMigrationStorage implements MigrationStorage {
|
|
|
32
32
|
/** Removes the record of `migrationName`, on the querier that reverted it. */
|
|
33
33
|
unlogWithQuerier(querier: SqlQuerier, migrationName: string): Promise<void>;
|
|
34
34
|
}
|
|
35
|
-
/** The journal `tableName` and its one column, escaped as
|
|
36
|
-
export declare function journalIds(
|
|
35
|
+
/** The journal `tableName` and its one column, escaped as the engine rendering them spells them. */
|
|
36
|
+
export declare function journalIds(tableName: string): {
|
|
37
37
|
table: QuerySql;
|
|
38
38
|
name: QuerySql;
|
|
39
39
|
};
|
|
@@ -9,18 +9,23 @@ export const DEFAULT_MIGRATIONS_TABLE = 'uql_migrations';
|
|
|
9
9
|
*/
|
|
10
10
|
export const LOCK_RECORD = 'uql/lock';
|
|
11
11
|
/**
|
|
12
|
-
* Creates the journal `tableName` where it is missing, rendered by the schema generator rather than written
|
|
13
|
-
*
|
|
14
|
-
*
|
|
12
|
+
* Creates the journal `tableName` where it is missing, rendered by the schema generator rather than written out: SQL
|
|
13
|
+
* Server has no `CREATE TABLE IF NOT EXISTS`, and its `TIMESTAMP` is a row version that takes no default. It precedes
|
|
14
|
+
* the lock, so a run creating it beside another can lose that race in the catalogue: it asks once more, finding it.
|
|
15
15
|
*/
|
|
16
16
|
export async function createMigrationsTable(querier, tableName) {
|
|
17
17
|
const table = tableBuilder(tableName);
|
|
18
18
|
table.string('name').id();
|
|
19
19
|
table.timestamptz('executed_at').default(currentTimestamp);
|
|
20
|
-
const
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
20
|
+
const statements = new SqlSchemaGenerator(querier.dialect).generateCreateTableFromDefinition(table.build(), {
|
|
21
|
+
ifNotExists: true,
|
|
22
|
+
});
|
|
23
|
+
const create = async () => {
|
|
24
|
+
for (const statement of statements) {
|
|
25
|
+
await querier.run(sql.text(statement));
|
|
26
|
+
}
|
|
27
|
+
};
|
|
28
|
+
await create().catch(create);
|
|
24
29
|
}
|
|
25
30
|
/** Records the migrations run in a table, on the querier each call is handed, which the lock created. */
|
|
26
31
|
export class DatabaseMigrationStorage {
|
|
@@ -30,22 +35,25 @@ export class DatabaseMigrationStorage {
|
|
|
30
35
|
}
|
|
31
36
|
/** The names recorded, the lock's left out. */
|
|
32
37
|
async executed(querier) {
|
|
33
|
-
const { table, name } = journalIds(
|
|
38
|
+
const { table, name } = journalIds(this.tableName);
|
|
34
39
|
const rows = await querier.all `SELECT ${name} FROM ${table} WHERE ${name} <> ${LOCK_RECORD} ORDER BY ${name} ASC`;
|
|
35
40
|
return rows.map((row) => row.name);
|
|
36
41
|
}
|
|
37
42
|
/** Records `migrationName` as run, on the querier that ran it, inside its transaction where there is one. */
|
|
38
43
|
async logWithQuerier(querier, migrationName) {
|
|
39
|
-
const { table, name } = journalIds(
|
|
44
|
+
const { table, name } = journalIds(this.tableName);
|
|
40
45
|
await querier.run `INSERT INTO ${table} (${name}) VALUES (${migrationName})`;
|
|
41
46
|
}
|
|
42
47
|
/** Removes the record of `migrationName`, on the querier that reverted it. */
|
|
43
48
|
async unlogWithQuerier(querier, migrationName) {
|
|
44
|
-
const { table, name } = journalIds(
|
|
49
|
+
const { table, name } = journalIds(this.tableName);
|
|
45
50
|
await querier.run `DELETE FROM ${table} WHERE ${name} = ${migrationName}`;
|
|
46
51
|
}
|
|
47
52
|
}
|
|
48
|
-
/** The journal `tableName` and its one column, escaped as
|
|
49
|
-
export function journalIds(
|
|
50
|
-
return {
|
|
53
|
+
/** The journal `tableName` and its one column, escaped as the engine rendering them spells them. */
|
|
54
|
+
export function journalIds(tableName) {
|
|
55
|
+
return {
|
|
56
|
+
table: sql(({ dialect }) => dialect.escapeId(tableName)),
|
|
57
|
+
name: sql(({ dialect }) => dialect.escapeId('name')),
|
|
58
|
+
};
|
|
51
59
|
}
|
|
@@ -2,5 +2,5 @@ import { POSTGRES_FEATURES, PostgresDialect } from '../postgres/postgresDialect.
|
|
|
2
2
|
/** Postgres as PGlite runs it, one session shared by every querier. */
|
|
3
3
|
export class PgliteDialect extends PostgresDialect {
|
|
4
4
|
/** Every querier shares the one session, which an advisory lock it already holds never makes wait. */
|
|
5
|
-
features = { ...POSTGRES_FEATURES, namedLocks:
|
|
5
|
+
features = { ...POSTGRES_FEATURES, namedLocks: 'journal' };
|
|
6
6
|
}
|
package/dist/type/dialect.d.ts
CHANGED
|
@@ -78,7 +78,7 @@ export interface DriverCapabilities {
|
|
|
78
78
|
/**
|
|
79
79
|
* Whether the driver natively supports JS arrays for the underlying database type.
|
|
80
80
|
* `PgQuerierPool` keeps this `true` for node-postgres; `BunSqlQuerierPool` sets `false` and binds
|
|
81
|
-
* `
|
|
81
|
+
* `pgArrayText` string literals instead.
|
|
82
82
|
*/
|
|
83
83
|
readonly nativeArrays: boolean;
|
|
84
84
|
}
|
|
@@ -197,11 +197,11 @@ export interface SqlDialectFeatures extends DialectFeatures {
|
|
|
197
197
|
/** How the engine spells a trigger. One value rather than a flag each, as {@link rowLocks} is. */
|
|
198
198
|
readonly triggers: TriggerFeatures;
|
|
199
199
|
/**
|
|
200
|
-
* What holds
|
|
201
|
-
*
|
|
202
|
-
*
|
|
200
|
+
* What holds the lock a migration run takes so a second waits for it: a session (Postgres, MySQL) or a transaction
|
|
201
|
+
* kept open for the run (SQL Server), each freeing it as it ends; or a row in the journal (CockroachDB, the SQLite
|
|
202
|
+
* family, and PGlite, whose queriers share one session), which a run that stops before releasing leaves.
|
|
203
203
|
*/
|
|
204
|
-
readonly namedLocks: 'session' | 'transaction' |
|
|
204
|
+
readonly namedLocks: 'session' | 'transaction' | 'journal';
|
|
205
205
|
}
|
|
206
206
|
/**
|
|
207
207
|
* What a trigger body calls the rows it reads. Row-based engines hand it a record on each side; SQL
|
package/dist/type/querySql.d.ts
CHANGED
|
@@ -44,8 +44,8 @@ export declare const JSON_PATH: unique symbol;
|
|
|
44
44
|
/** Keys the phantom a {@link JsonPathRef} carries the value at its path in. */
|
|
45
45
|
export declare const JSON_VALUE: unique symbol;
|
|
46
46
|
/**
|
|
47
|
-
* What a `sql` template interpolates: a value it binds,
|
|
48
|
-
* place. Never `undefined
|
|
47
|
+
* What a `sql` template interpolates: a value it binds, an array as one array value (`= ANY(${ids})`, the
|
|
48
|
+
* Postgres family alone), or SQL it renders in place. Never `undefined`: leave it out, or interpolate `null`.
|
|
49
49
|
*/
|
|
50
50
|
export type SqlArg = Scalar | null | readonly (Scalar | null)[] | QuerySql;
|
|
51
51
|
/** A statement as `all` and `run` take one: a tagged template's strings and values, or a `sql` built apart. */
|
|
@@ -52,15 +52,7 @@ export function enumCheck(table, { name, enum: values }, render) {
|
|
|
52
52
|
if (!values) {
|
|
53
53
|
return [];
|
|
54
54
|
}
|
|
55
|
-
|
|
56
|
-
ctx.append(`${dialect.escapeId(name)} IN (`);
|
|
57
|
-
sortedEnum(values).forEach((value, i) => {
|
|
58
|
-
ctx.append(i ? ', ' : '');
|
|
59
|
-
ctx.addValue(value);
|
|
60
|
-
});
|
|
61
|
-
ctx.append(')');
|
|
62
|
-
});
|
|
63
|
-
return [ownedCheck(table, name, render(statement))];
|
|
55
|
+
return [ownedCheck(table, name, render(sql `${sql.id(name)} IN (${sql.join(sortedEnum(values))})`))];
|
|
64
56
|
}
|
|
65
57
|
/**
|
|
66
58
|
* An enum's values as every engine's constraint states them, numbers by value and text by code unit (an enum
|
package/dist/util/sql.d.ts
CHANGED
|
@@ -6,7 +6,7 @@ import { ColumnRef, type IndexRefMap, QuerySql, type QuerySqlFn, type ComputedRe
|
|
|
6
6
|
*/
|
|
7
7
|
export declare function sql(strings: TemplateStringsArray, ...values: readonly SqlArg[]): QuerySql;
|
|
8
8
|
export declare namespace sql {
|
|
9
|
-
var join: (parts: readonly
|
|
9
|
+
var join: (parts: readonly SqlArg[], separator?: string) => QuerySql;
|
|
10
10
|
var id: (name: string) => QuerySql;
|
|
11
11
|
var text: (statement: string) => QuerySql;
|
|
12
12
|
}
|
package/dist/util/sql.js
CHANGED
|
@@ -19,24 +19,30 @@ export function sql(source, ...values) {
|
|
|
19
19
|
const { ctx } = opts;
|
|
20
20
|
ctx.append(source[0]);
|
|
21
21
|
values.forEach((value, i) => {
|
|
22
|
-
|
|
23
|
-
renderSql(value, opts);
|
|
24
|
-
}
|
|
25
|
-
else {
|
|
26
|
-
ctx.addValue(value);
|
|
27
|
-
}
|
|
22
|
+
renderArg(value, opts);
|
|
28
23
|
ctx.append(source[i + 1]);
|
|
29
24
|
});
|
|
30
25
|
});
|
|
31
26
|
}
|
|
32
|
-
|
|
27
|
+
function renderArg(arg, opts) {
|
|
28
|
+
if (arg instanceof QuerySql) {
|
|
29
|
+
renderSql(arg, opts);
|
|
30
|
+
}
|
|
31
|
+
else {
|
|
32
|
+
opts.ctx.addValue(arg);
|
|
33
|
+
}
|
|
34
|
+
}
|
|
35
|
+
/**
|
|
36
|
+
* `parts` one after another, `separator` between each: a `sql` renders binding its own values, any other
|
|
37
|
+
* part binds as a value, so `IN (${sql.join(ids)})` writes a list on every engine. `sql.join(conditions, ' AND ')`.
|
|
38
|
+
*/
|
|
33
39
|
sql.join = function join(parts, separator = ', ') {
|
|
34
40
|
return new QuerySql((opts) => {
|
|
35
41
|
parts.forEach((part, index) => {
|
|
36
42
|
if (index) {
|
|
37
43
|
opts.ctx.append(separator);
|
|
38
44
|
}
|
|
39
|
-
|
|
45
|
+
renderArg(part, opts);
|
|
40
46
|
});
|
|
41
47
|
});
|
|
42
48
|
};
|
|
@@ -4,6 +4,8 @@ export declare function escapeSingleQuotes(val: string): string;
|
|
|
4
4
|
export declare function unescapeMysqlString(body: string): string;
|
|
5
5
|
/** How a Postgres timestamp says it is UTC. */
|
|
6
6
|
export declare const PG_UTC = "+00";
|
|
7
|
+
/** A Postgres array's text, `{"a","b"}`, which is how a driver sends one and how its literal reads. */
|
|
8
|
+
export declare function pgArrayText(arr: readonly unknown[]): string;
|
|
7
9
|
/** Escape `value` for SQLite and SQL Server (single-quote doubling). */
|
|
8
10
|
export declare const escapeAnsiSqlLiteral: (value: unknown) => string;
|
|
9
11
|
/**
|
package/dist/util/sqlLiteral.js
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
// SQL literal escaping for `Dialect.escape`: ANSI quote doubling, or MySQL's backslashes. UQL binds
|
|
2
2
|
// values instead, so this is the hand-written-SQL hatch, and inline MySQL literals break under
|
|
3
|
-
// `NO_BACKSLASH_ESCAPES` or a GBK-like charset: prefer bound parameters.
|
|
3
|
+
// `NO_BACKSLASH_ESCAPES` or a GBK-like charset: prefer bound parameters.
|
|
4
4
|
import { bytesToHex } from './bytes.js';
|
|
5
5
|
import { utcTimestamp } from './date.js';
|
|
6
6
|
import { UqlUsageError } from './uqlError.js';
|
|
@@ -34,25 +34,18 @@ const mysqlStringLiteral = (val) => `'${val.replace(MYSQL_SPECIALS, (char) => MY
|
|
|
34
34
|
* A factory, not a function taking `escapeString` as an argument: threading it through every call
|
|
35
35
|
* measured 1.1-1.5x slower. Rejects unsupported types rather than stringifying them into SQL.
|
|
36
36
|
*/
|
|
37
|
-
function createEscaper(escapeString, zone = '') {
|
|
37
|
+
function createEscaper(escapeString, zone = '', arrayText) {
|
|
38
38
|
const dateLiteral = (date) => escapeString(utcTimestamp(date, zone));
|
|
39
|
-
const sqlList = (arr) => {
|
|
40
|
-
let sql = '';
|
|
41
|
-
for (let i = 0; i < arr.length; i++) {
|
|
42
|
-
const val = arr[i];
|
|
43
|
-
if (i > 0)
|
|
44
|
-
sql += ', ';
|
|
45
|
-
sql += Array.isArray(val) ? `(${sqlList(val)})` : escapeValue(val);
|
|
46
|
-
}
|
|
47
|
-
return sql;
|
|
48
|
-
};
|
|
49
39
|
/** Split out so the `typeof` switch below stays a flat one-line-per-type dispatch. */
|
|
50
40
|
const escapeObject = (value) => {
|
|
51
41
|
if (value instanceof Date) {
|
|
52
42
|
return Number.isNaN(value.getTime()) ? 'NULL' : dateLiteral(value);
|
|
53
43
|
}
|
|
54
44
|
if (Array.isArray(value)) {
|
|
55
|
-
|
|
45
|
+
if (!arrayText) {
|
|
46
|
+
throw new UqlUsageError('escapeSqlLiteral: an array has no literal on this engine; write a list with sql.join(values)');
|
|
47
|
+
}
|
|
48
|
+
return escapeString(arrayText(value));
|
|
56
49
|
}
|
|
57
50
|
// A Node `Buffer` is a `Uint8Array` too.
|
|
58
51
|
if (value instanceof Uint8Array) {
|
|
@@ -87,12 +80,34 @@ function createEscaper(escapeString, zone = '') {
|
|
|
87
80
|
}
|
|
88
81
|
/** How a Postgres timestamp says it is UTC. */
|
|
89
82
|
export const PG_UTC = '+00';
|
|
83
|
+
/** A Postgres array's text, `{"a","b"}`, which is how a driver sends one and how its literal reads. */
|
|
84
|
+
export function pgArrayText(arr) {
|
|
85
|
+
const elements = arr.map((val) => {
|
|
86
|
+
if (val == null)
|
|
87
|
+
return 'NULL';
|
|
88
|
+
if (Array.isArray(val))
|
|
89
|
+
return pgArrayText(val);
|
|
90
|
+
if (typeof val === 'boolean')
|
|
91
|
+
return val ? 'true' : 'false';
|
|
92
|
+
// A Node `Buffer` is a `Uint8Array` too.
|
|
93
|
+
if (val instanceof Uint8Array)
|
|
94
|
+
return `"\\\\x${bytesToHex(val)}"`;
|
|
95
|
+
if (val instanceof Date)
|
|
96
|
+
return `"${utcTimestamp(val, PG_UTC)}"`;
|
|
97
|
+
if (typeof val === 'object') {
|
|
98
|
+
throw new UqlUsageError('a Postgres array holds no plain objects: bind JSON as text');
|
|
99
|
+
}
|
|
100
|
+
const str = String(val);
|
|
101
|
+
return `"${str.replace(/\\/g, '\\\\').replace(/"/g, '\\"')}"`;
|
|
102
|
+
});
|
|
103
|
+
return `{${elements.join(',')}}`;
|
|
104
|
+
}
|
|
90
105
|
/** Escape `value` for SQLite and SQL Server (single-quote doubling). */
|
|
91
106
|
export const escapeAnsiSqlLiteral = createEscaper(ansiStringLiteral);
|
|
92
107
|
/**
|
|
93
108
|
* Escape `value` for the Postgres family: ANSI, a date marked UTC, which a `TIMESTAMPTZ` otherwise reads
|
|
94
109
|
* in the session's zone.
|
|
95
110
|
*/
|
|
96
|
-
export const escapePgSqlLiteral = createEscaper(ansiStringLiteral, PG_UTC);
|
|
111
|
+
export const escapePgSqlLiteral = createEscaper(ansiStringLiteral, PG_UTC, pgArrayText);
|
|
97
112
|
/** Escape `value` for MySQL and MariaDB (backslash escaping). */
|
|
98
113
|
export const escapeMysqlSqlLiteral = createEscaper(mysqlStringLiteral);
|
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.114.
|
|
6
|
+
"version": "0.114.2",
|
|
7
7
|
"type": "module",
|
|
8
8
|
"engines": {
|
|
9
9
|
"node": ">=22.18"
|
package/skills/uql-orm/SKILL.md
CHANGED
|
@@ -224,7 +224,7 @@ const users = await pool.findMany(User, {
|
|
|
224
224
|
|
|
225
225
|
### Raw SQL and errors
|
|
226
226
|
|
|
227
|
-
- ``pool.all`SELECT ... WHERE id = ${id}` `` for a `SELECT`, ``pool.run`...` `` for a write. Interpolated values bind: a scalar
|
|
227
|
+
- ``pool.all`SELECT ... WHERE id = ${id}` `` for a `SELECT`, ``pool.run`...` `` for a write. Interpolated values bind: a scalar or `null`, never `undefined` or a plain object; an array binds as one array value, on the Postgres family alone (`= ANY(${ids})`), DDL included. A list for `IN` is `sql.join(values)`, one bound value each, on every engine. `sql` builds a fragment, `sql.join(fragments, ' AND ')` joins them, and `sql.text(s)` runs trusted SQL held in a string: never user input.
|
|
228
228
|
- A condition no operator expresses is a `sql` fragment beside the others, naming columns through `refs()`, never by string: ``const item = refs(Item); $where: { $and: [{ companyId: 1 }, sql`${item.price} * ${item.stock} > ${10000}`] }``. SQL databases only.
|
|
229
229
|
- SQL reading another table names it with `tableOf`, its columns off refs read under an alias, so a rename reaches them: ``const o = refs(Order, 'o'); sql`(SELECT ${o.state} FROM ${tableOf(o)} WHERE ${o.checkoutId} = ${checkout.id} LIMIT 1)` ``. Two aliases read one table twice. For an entity declared later, a computed field's SQL included, pass an arrow: `refs(() => Order, 'o')`, `tableOf(refs(() => Order))`. `aliasOf(o)` renders the alias alone, for SQL reading the whole row (`pdb.score(${aliasOf(o)})`) or naming a derived table (`) ${aliasOf(o)} ON TRUE`). A name the statement makes up, read twice, is `sql.id('reason')`.
|
|
230
230
|
- `queryErrorKind(err)` names a failure: `uniqueViolation`, `foreignKeyViolation`, `notNullViolation`, `checkViolation`, `optimisticLock`, `retryable`, `usage`, `security`. Catch by kind, not by driver code.
|