uql-orm 0.101.6 → 0.102.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.
- package/dist/dialect/abstractSqlDialect.d.ts +12 -3
- package/dist/dialect/abstractSqlDialect.js +24 -14
- package/dist/dialect/mysqlLikeSqlDialect.d.ts +2 -2
- package/dist/dialect/mysqlLikeSqlDialect.js +5 -2
- package/dist/dialect/pgLikeSqlDialect.js +1 -0
- package/dist/libsql/libsqlDialect.d.ts +5 -0
- package/dist/libsql/libsqlDialect.js +5 -0
- package/dist/mongodb/mongoDialect.js +1 -0
- package/dist/mssql/mssqlDialect.d.ts +4 -4
- package/dist/mssql/mssqlDialect.js +7 -4
- package/dist/querier/abstractQuerier.d.ts +52 -17
- package/dist/querier/abstractQuerier.js +140 -79
- package/dist/querier/abstractSqlQuerier.d.ts +5 -1
- package/dist/querier/abstractSqlQuerier.js +16 -1
- package/dist/sqlite/hranaQuerier.d.ts +2 -2
- package/dist/sqlite/hranaQuerier.js +2 -2
- package/dist/sqlite/sqliteDialect.d.ts +4 -3
- package/dist/sqlite/sqliteDialect.js +5 -1
- package/dist/type/dialect.d.ts +6 -0
- package/dist/type/querier.d.ts +6 -0
- package/package.json +1 -1
- package/skills/uql-orm/SKILL.md +2 -2
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
import { type ColumnFamily, type SavepointCommand, type DdlRenderOptions, type EntityData, type EntityMeta, type EntityWhereMeta, type FieldKey, type FieldOptions, type IsolationLevel, type JsonColumnType, type JsonUpdateOp, type Query, type QueryAggMap, type QueryAggregate, type QueryBuildFn, type QueryComparisonOptions, type QueryConflictPaths, type QueryContext, type QueryContextOptions, type QueryExclude, type QueryGroupMap, type QueryGroupOp, type QueryHavingMap, type QueryRenderOptions, type QueryPage, type QueryPager, QuerySql, type QuerySqlFnOptions, type QuerySearch, type QuerySelectValue, type QuerySizeComparisonOps, type QueryTextSearchOptions, type QueryWhere, type QueryWhereArray, type QueryWhereFieldOp, type QueryWhereOptions, type RelationAggregateSpec, type RelationMeta, type SqlDialectName, type SqlQueryDialect, type SqlValues, type TriggerRows, type TriggerWrite, type Type, type UpdatePayload } from '../type/index.js';
|
|
1
|
+
import { type ColumnFamily, type SavepointCommand, type DdlRenderOptions, type EntityData, type EntityMeta, type EntityWhereMeta, type FieldKey, type FieldOptions, type IsolationLevel, type TransactionOptions, type JsonColumnType, type JsonUpdateOp, type Query, type QueryAggMap, type QueryAggregate, type QueryBuildFn, type QueryComparisonOptions, type QueryConflictPaths, type QueryContext, type QueryContextOptions, type QueryExclude, type QueryGroupMap, type QueryGroupOp, type QueryHavingMap, type QueryRenderOptions, type QueryPage, type QueryPager, QuerySql, type QuerySqlFnOptions, type QuerySearch, type QuerySelectValue, type QuerySizeComparisonOps, type QueryTextSearchOptions, type QueryWhere, type QueryWhereArray, type QueryWhereFieldOp, type QueryWhereOptions, type RelationAggregateSpec, type RelationMeta, type SqlDialectName, type SqlQueryDialect, type SqlValues, type TriggerRows, type TriggerWrite, type Type, type UpdatePayload } from '../type/index.js';
|
|
2
2
|
import { type SortDirection } from '../util/index.js';
|
|
3
3
|
import type { HydrateKind } from './hydrateColumn.js';
|
|
4
4
|
import { type JsonAccessMode, type JsonSlot } from './jsonSql.js';
|
|
@@ -117,7 +117,6 @@ export declare abstract class AbstractSqlDialect extends VectorSqlDialect implem
|
|
|
117
117
|
* MariaDB accept the same statement, where it means a database.
|
|
118
118
|
*/
|
|
119
119
|
createSchemaSql(schema: string): string;
|
|
120
|
-
readonly isolationLevelStrategy: 'inline' | 'setBefore' | 'none';
|
|
121
120
|
readonly booleanLiteral: 'native' | 'integer';
|
|
122
121
|
readonly sqlValues: SqlValues;
|
|
123
122
|
/** The most values one statement binds: a statement past it is refused, and a list the ORM builds is split. */
|
|
@@ -131,7 +130,8 @@ export declare abstract class AbstractSqlDialect extends VectorSqlDialect implem
|
|
|
131
130
|
* update, is spread over nested calls. No cap binds unless a dialect declares one.
|
|
132
131
|
*/
|
|
133
132
|
readonly maxFunctionArgs: number;
|
|
134
|
-
|
|
133
|
+
/** The statements opening a transaction, its modes inline in the `BEGIN` as the Postgres family takes them. */
|
|
134
|
+
getBeginTransactionStatements({ isolationLevel, readOnly }?: TransactionOptions): string[];
|
|
135
135
|
createContext(options?: QueryContextOptions): QueryContext;
|
|
136
136
|
/** A statement as it is sent: the SQL `build` writes, or a `sql` renders, and the values it binds. */
|
|
137
137
|
compile(build: QueryBuildFn | QuerySql): {
|
|
@@ -162,6 +162,11 @@ export declare abstract class AbstractSqlDialect extends VectorSqlDialect implem
|
|
|
162
162
|
placeholder(_index: number): string;
|
|
163
163
|
/** `RETURNING <id column> id`, or nothing on a composite key, whose every column the payload already names. */
|
|
164
164
|
returningId<E>(meta: EntityMeta<E>): string;
|
|
165
|
+
/**
|
|
166
|
+
* ` RETURNING` the fields `keys` names, after an `UPDATE` or `DELETE` this context holds, projected and read as
|
|
167
|
+
* a read's are: the terms its rows answer under. Only where `features.writeReturning`.
|
|
168
|
+
*/
|
|
169
|
+
returning<E>(ctx: QueryContext, entity: Type<E>, keys: readonly FieldKey<E>[]): readonly SelectTerm[];
|
|
165
170
|
/** What the returned row is read off, for an engine that names it: SQL Server's `INSERTED.`. */
|
|
166
171
|
protected readonly returnedRowPrefix: string;
|
|
167
172
|
/** `<id column> AS id` on its own, for a statement composing a `RETURNING` list of several items. */
|
|
@@ -221,6 +226,8 @@ export declare abstract class AbstractSqlDialect extends VectorSqlDialect implem
|
|
|
221
226
|
* projects.
|
|
222
227
|
*/
|
|
223
228
|
protected projection<E>(ctx: QueryContext, entity: Type<E>, q: Query<E>, opts: SelectOptions, joins: QueryJoins): SelectTerm[];
|
|
229
|
+
/** A projection's list of terms. */
|
|
230
|
+
private termsSql;
|
|
224
231
|
/** A term as a projection writes it, aliased unless its SQL already answers under its key. */
|
|
225
232
|
private termSql;
|
|
226
233
|
/** What a `$sort` projects, each under the name it asked for: a vector's distance, the `$text` relevance. */
|
|
@@ -767,3 +774,5 @@ export declare abstract class AbstractSqlDialect extends VectorSqlDialect implem
|
|
|
767
774
|
/** Reads extracted JSON text as a number, which every engine spells its own way. */
|
|
768
775
|
protected abstract numericCast(expr: string): string;
|
|
769
776
|
}
|
|
777
|
+
/** `begin` after the statement setting the level, as T-SQL and the MySQL family take it, having no inline form. */
|
|
778
|
+
export declare function isolationSetBefore(isolationLevel: IsolationLevel | undefined, begin: string): string[];
|
|
@@ -2,7 +2,7 @@ import { fieldOf, getMeta, relationOf } from '../entity/index.js';
|
|
|
2
2
|
import { COUNT_RESULT_KEY, parseQueryLock, QuerySql, RAW_ALIAS, } from '../type/index.js';
|
|
3
3
|
import { utcTimestamp } from '../util/date.js';
|
|
4
4
|
import { isExactDecimal, isInlinedExpression, jsonKey, jsonPathKeys } from '../util/field.util.js';
|
|
5
|
-
import { isSelectList, assertNonNegativeInteger, assertNoUndefined, assertWhere, definedEntries, escapeSqlId, fillOnFields, filterFieldKeys, getInsertFieldKeys, getKeys, getRelationRequestSummary, getSoftDeleteValue, hasKeys, idOnlyQuery, whereAnd, columnFamily, fieldFamily, countedRelations, fieldUpdateOf, fulltextIndexOver, fulltextWeights, isFieldUpdateOp, isJsonObject, isJsonUpdateOp, isOperatorMap, isOperatorKey, isVectorSearch, normalizeScalarFieldSelection, parentJoins, rankedTextSearch, targetJoins, textSearchFields, textSortOf, textWeightSteps, parseGroupMap, parseRelationAtKey, parseRelationSize, parseSortDirection, populatesRelations, aggregateOf, sql, refs, throwUnknownAggregateColumn, withoutSoftDeleteFilter, } from '../util/index.js';
|
|
5
|
+
import { isSelectList, assertNonNegativeInteger, assertNoUndefined, assertWhere, definedEntries, escapeSqlId, fillOnFields, filterFieldKeys, getInsertFieldKeys, getKeys, getRelationRequestSummary, getSoftDeleteValue, hasKeys, idOnlyQuery, keySet, whereAnd, columnFamily, fieldFamily, countedRelations, fieldUpdateOf, fulltextIndexOver, fulltextWeights, isFieldUpdateOp, isJsonObject, isJsonUpdateOp, isOperatorMap, isOperatorKey, isVectorSearch, normalizeScalarFieldSelection, parentJoins, rankedTextSearch, targetJoins, textSearchFields, textSortOf, textWeightSteps, parseGroupMap, parseRelationAtKey, parseRelationSize, parseSortDirection, populatesRelations, aggregateOf, sql, refs, throwUnknownAggregateColumn, withoutSoftDeleteFilter, } from '../util/index.js';
|
|
6
6
|
import { escapeAnsiSqlLiteral } from '../util/sqlLiteral.js';
|
|
7
7
|
import { kindOf, UqlUsageError } from '../util/uqlError.js';
|
|
8
8
|
import { AGGREGATE_PAGE_ALIAS, AGGREGATE_VALUE_ALIAS, ROWS_ALIAS, JSON_ELEM_ALIAS, JSON_PULL_ALIAS, relationSortColumn, } from './aliases.js';
|
|
@@ -121,7 +121,6 @@ export class AbstractSqlDialect extends VectorSqlDialect {
|
|
|
121
121
|
createSchemaSql(schema) {
|
|
122
122
|
return `CREATE SCHEMA IF NOT EXISTS ${this.escapeId(schema, true)}`;
|
|
123
123
|
}
|
|
124
|
-
isolationLevelStrategy = 'inline';
|
|
125
124
|
booleanLiteral = 'native';
|
|
126
125
|
sqlValues = ANSI_SQL_VALUES;
|
|
127
126
|
/** The most rows one `INSERT ... VALUES` takes, which a narrow row can reach before the bind budget. */
|
|
@@ -135,17 +134,11 @@ export class AbstractSqlDialect extends VectorSqlDialect {
|
|
|
135
134
|
* update, is spread over nested calls. No cap binds unless a dialect declares one.
|
|
136
135
|
*/
|
|
137
136
|
maxFunctionArgs = Infinity;
|
|
138
|
-
|
|
139
|
-
|
|
140
|
-
const
|
|
141
|
-
|
|
142
|
-
|
|
143
|
-
}
|
|
144
|
-
if (strategy === 'inline') {
|
|
145
|
-
return [`${this.beginTransactionCommand} ISOLATION LEVEL ${level}`];
|
|
146
|
-
}
|
|
147
|
-
// 'setBefore' - MySQL/MariaDB pattern
|
|
148
|
-
return [`SET TRANSACTION ISOLATION LEVEL ${level}`, this.beginTransactionCommand];
|
|
137
|
+
/** The statements opening a transaction, its modes inline in the `BEGIN` as the Postgres family takes them. */
|
|
138
|
+
getBeginTransactionStatements({ isolationLevel, readOnly } = {}) {
|
|
139
|
+
const modes = [isolationLevel && `ISOLATION LEVEL ${isolationLevel.toUpperCase()}`, readOnly && 'READ ONLY'];
|
|
140
|
+
const inline = modes.filter((mode) => typeof mode === 'string');
|
|
141
|
+
return [inline.length ? `${this.beginTransactionCommand} ${inline.join(', ')}` : this.beginTransactionCommand];
|
|
149
142
|
}
|
|
150
143
|
createContext(options = {}) {
|
|
151
144
|
return new SqlQueryContext(this, [], undefined, options.inlineValues);
|
|
@@ -217,6 +210,15 @@ export class AbstractSqlDialect extends VectorSqlDialect {
|
|
|
217
210
|
const expression = this.returningIdExpression(meta);
|
|
218
211
|
return expression ? `RETURNING ${expression}` : '';
|
|
219
212
|
}
|
|
213
|
+
/**
|
|
214
|
+
* ` RETURNING` the fields `keys` names, after an `UPDATE` or `DELETE` this context holds, projected and read as
|
|
215
|
+
* a read's are: the terms its rows answer under. Only where `features.writeReturning`.
|
|
216
|
+
*/
|
|
217
|
+
returning(ctx, entity, keys) {
|
|
218
|
+
const terms = this.selectTerms(ctx, entity, keySet(keys));
|
|
219
|
+
ctx.append(` RETURNING ${this.termsSql(terms)}`);
|
|
220
|
+
return terms;
|
|
221
|
+
}
|
|
220
222
|
/** What the returned row is read off, for an engine that names it: SQL Server's `INSERTED.`. */
|
|
221
223
|
returnedRowPrefix = '';
|
|
222
224
|
/** `<id column> AS id` on its own, for a statement composing a `RETURNING` list of several items. */
|
|
@@ -360,7 +362,7 @@ export class AbstractSqlDialect extends VectorSqlDialect {
|
|
|
360
362
|
}
|
|
361
363
|
ctx.append(q.$distinct ? 'SELECT DISTINCT ' : 'SELECT ');
|
|
362
364
|
ctx.append(this.selectModifier(q));
|
|
363
|
-
ctx.append(
|
|
365
|
+
ctx.append(this.termsSql(columns));
|
|
364
366
|
ctx.append(` FROM ${ref}${this.lockHint(q)}`);
|
|
365
367
|
this.selectRelationJoins(ctx, meta, alias, joins);
|
|
366
368
|
return { terms, order: carried?.order };
|
|
@@ -382,6 +384,10 @@ export class AbstractSqlDialect extends VectorSqlDialect {
|
|
|
382
384
|
...this.selectSortProjections(ctx, meta, q, opts.prefix),
|
|
383
385
|
];
|
|
384
386
|
}
|
|
387
|
+
/** A projection's list of terms. */
|
|
388
|
+
termsSql(terms) {
|
|
389
|
+
return terms.map((term) => this.termSql(term)).join(', ');
|
|
390
|
+
}
|
|
385
391
|
/** A term as a projection writes it, aliased unless its SQL already answers under its key. */
|
|
386
392
|
termSql({ sql, key, bare }) {
|
|
387
393
|
return bare || key === undefined ? sql : `${sql} ${this.escapeId(key, true)}`;
|
|
@@ -2131,3 +2137,7 @@ export class AbstractSqlDialect extends VectorSqlDialect {
|
|
|
2131
2137
|
return `${operand} ${negate ? 'NOT IN' : 'IN'} (${phs})`;
|
|
2132
2138
|
}
|
|
2133
2139
|
}
|
|
2140
|
+
/** `begin` after the statement setting the level, as T-SQL and the MySQL family take it, having no inline form. */
|
|
2141
|
+
export function isolationSetBefore(isolationLevel, begin) {
|
|
2142
|
+
return isolationLevel ? [`SET TRANSACTION ISOLATION LEVEL ${isolationLevel.toUpperCase()}`, begin] : [begin];
|
|
2143
|
+
}
|
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
import type { EntityMeta, InsertIdSource, Query, QueryConflictPaths, QueryContext, QueryOptions, QueryTextSearchOptions, RowLockFeatures, SqlDialectFeatures, SqlDialectName, SqlValues, Type, UpdatePayload } from '../type/index.js';
|
|
1
|
+
import type { EntityMeta, InsertIdSource, Query, QueryConflictPaths, QueryContext, QueryOptions, QueryTextSearchOptions, RowLockFeatures, SqlDialectFeatures, SqlDialectName, SqlValues, Type, UpdatePayload, TransactionOptions } from '../type/index.js';
|
|
2
2
|
import { AbstractSqlDialect, type DerivedRelation, type RelationRows, type SelectTerm } from './abstractSqlDialect.js';
|
|
3
3
|
import { type JsonSlot } from './jsonSql.js';
|
|
4
4
|
/** Declared apart so MariaDB, which has no `FOR UPDATE OF`, can restate that one part of it. */
|
|
@@ -25,7 +25,7 @@ export declare abstract class MysqlLikeSqlDialect extends AbstractSqlDialect {
|
|
|
25
25
|
readonly autoIncrementSuffix = "AUTO_INCREMENT";
|
|
26
26
|
readonly escapeIdChar = "`";
|
|
27
27
|
readonly beginTransactionCommand = "START TRANSACTION";
|
|
28
|
-
|
|
28
|
+
getBeginTransactionStatements({ isolationLevel, readOnly }?: TransactionOptions): string[];
|
|
29
29
|
readonly booleanLiteral = "integer";
|
|
30
30
|
readonly sqlValues: SqlValues;
|
|
31
31
|
readonly insertIdSource: InsertIdSource;
|
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
import { getMeta } from '../entity/index.js';
|
|
2
2
|
import { textSearchFields } from '../util/index.js';
|
|
3
3
|
import { escapeMysqlSqlLiteral } from '../util/sqlLiteral.js';
|
|
4
|
-
import { ANSI_SQL_VALUES, AbstractSqlDialect, } from './abstractSqlDialect.js';
|
|
4
|
+
import { ANSI_SQL_VALUES, AbstractSqlDialect, isolationSetBefore, } from './abstractSqlDialect.js';
|
|
5
5
|
import { AGGREGATE_VALUE_ALIAS } from './aliases.js';
|
|
6
6
|
import { BYTES_PREFIX } from './hydrateColumn.js';
|
|
7
7
|
import { jsonPath } from './jsonSql.js';
|
|
@@ -29,6 +29,7 @@ export const MYSQL_FEATURES = {
|
|
|
29
29
|
serverSideCursors: false,
|
|
30
30
|
correlatedWrites: true,
|
|
31
31
|
rowLocks: MYSQL_ROW_LOCKS,
|
|
32
|
+
writeReturning: false,
|
|
32
33
|
nullsSortLowest: true,
|
|
33
34
|
nullsOrdering: 'expression',
|
|
34
35
|
textScoreIndexes: true,
|
|
@@ -90,7 +91,9 @@ export class MysqlLikeSqlDialect extends AbstractSqlDialect {
|
|
|
90
91
|
autoIncrementSuffix = 'AUTO_INCREMENT';
|
|
91
92
|
escapeIdChar = '`';
|
|
92
93
|
beginTransactionCommand = 'START TRANSACTION';
|
|
93
|
-
|
|
94
|
+
getBeginTransactionStatements({ isolationLevel, readOnly } = {}) {
|
|
95
|
+
return isolationSetBefore(isolationLevel, `${this.beginTransactionCommand}${readOnly ? ' READ ONLY' : ''}`);
|
|
96
|
+
}
|
|
94
97
|
booleanLiteral = 'integer';
|
|
95
98
|
sqlValues = MYSQL_SQL_VALUES;
|
|
96
99
|
// No `RETURNING` support, so multi-row insert IDs are inferred from the header - see the
|
|
@@ -10,6 +10,11 @@ export declare const LIBSQL_FEATURES: SqlDialectFeatures;
|
|
|
10
10
|
*/
|
|
11
11
|
export declare class LibsqlDialect extends SqliteDialect {
|
|
12
12
|
readonly features: SqlDialectFeatures;
|
|
13
|
+
/**
|
|
14
|
+
* Every transaction a write one, as `@libsql/client`'s `transaction('write')` opens it: a deferred one that
|
|
15
|
+
* reads, then writes, cannot upgrade while another connection writes, and fails rather than waiting.
|
|
16
|
+
*/
|
|
17
|
+
readonly beginTransactionCommand = "BEGIN IMMEDIATE";
|
|
13
18
|
/** libSQL's built-in vector functions, and the metric its DiskANN index names; no `inner` (only the Rust engine has it) and no `l1`. */
|
|
14
19
|
readonly vectorMetrics: ReadonlyMap<VectorDistance, VectorMetric>;
|
|
15
20
|
}
|
|
@@ -9,6 +9,11 @@ export const LIBSQL_FEATURES = { ...SQLITE_FEATURES, orderedJsonAggregates: fals
|
|
|
9
9
|
*/
|
|
10
10
|
export class LibsqlDialect extends SqliteDialect {
|
|
11
11
|
features = LIBSQL_FEATURES;
|
|
12
|
+
/**
|
|
13
|
+
* Every transaction a write one, as `@libsql/client`'s `transaction('write')` opens it: a deferred one that
|
|
14
|
+
* reads, then writes, cannot upgrade while another connection writes, and fails rather than waiting.
|
|
15
|
+
*/
|
|
16
|
+
beginTransactionCommand = 'BEGIN IMMEDIATE';
|
|
12
17
|
/** libSQL's built-in vector functions, and the metric its DiskANN index names; no `inner` (only the Rust engine has it) and no `l1`. */
|
|
13
18
|
vectorMetrics = new Map([
|
|
14
19
|
['cosine', { fn: 'vector_distance_cos', index: 'cosine' }],
|
|
@@ -28,6 +28,7 @@ export const mongoDialectFeatures = {
|
|
|
28
28
|
serverSideCursors: false,
|
|
29
29
|
correlatedWrites: false,
|
|
30
30
|
rowLocks: false, // its concurrency control is the transaction plus atomic document updates
|
|
31
|
+
writeReturning: false,
|
|
31
32
|
nullsSortLowest: true,
|
|
32
33
|
};
|
|
33
34
|
/** What `toWireId` converts: the hex spelling of an `ObjectId`, and nothing looser. */
|
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
import { type RelationRows, type SelectTerm } from '../dialect/abstractSqlDialect.js';
|
|
2
2
|
import { type JsonAccessMode, type JsonSlot } from '../dialect/jsonSql.js';
|
|
3
3
|
import { MergeSqlDialect } from '../dialect/mergeSqlDialect.js';
|
|
4
|
-
import type { EntityMeta, SavepointCommand, FieldOptions, Query, QueryConflictPaths, QueryContext, QueryOptions, QueryPager, SqlDialectFeatures, SqlValues, TriggerRows, Type, UpdatePayload, VectorDistance, VectorMetric } from '../type/index.js';
|
|
4
|
+
import type { EntityMeta, SavepointCommand, FieldOptions, Query, QueryConflictPaths, QueryContext, QueryOptions, QueryPager, SqlDialectFeatures, SqlValues, TriggerRows, Type, UpdatePayload, VectorDistance, VectorMetric, TransactionOptions } from '../type/index.js';
|
|
5
5
|
/** Microsoft SQL Server 2017 and up. Identifiers are `"`-quoted, the ANSI spelling `tedious` enables. */
|
|
6
6
|
export declare class MsSqlDialect extends MergeSqlDialect {
|
|
7
7
|
#private;
|
|
@@ -14,10 +14,10 @@ export declare class MsSqlDialect extends MergeSqlDialect {
|
|
|
14
14
|
/** SQL Server saves a transaction under a name and rolls back to it, and releases none: the commit does. */
|
|
15
15
|
savepointStatement(command: SavepointCommand, name: string): string;
|
|
16
16
|
/**
|
|
17
|
-
* T-SQL has no inline form, so the level is set before the `BEGIN
|
|
18
|
-
* as statements would run; `MsSqlQuerier` opens its transactions through the driver
|
|
17
|
+
* T-SQL has no inline form, so the level is set before the `BEGIN`, and no read-only transaction. What a
|
|
18
|
+
* driver that sends these as statements would run; `MsSqlQuerier` opens its transactions through the driver.
|
|
19
19
|
*/
|
|
20
|
-
|
|
20
|
+
getBeginTransactionStatements({ isolationLevel }?: TransactionOptions): string[];
|
|
21
21
|
readonly booleanLiteral = "integer";
|
|
22
22
|
/**
|
|
23
23
|
* The clock in UTC, since `CURRENT_TIMESTAMP` is local time in the server's zone. No v7: `NEWSEQUENTIALID()` is
|
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
import { ANSI_SQL_VALUES, fromRows, relationTermKey, } from '../dialect/abstractSqlDialect.js';
|
|
1
|
+
import { ANSI_SQL_VALUES, fromRows, relationTermKey, isolationSetBefore, } from '../dialect/abstractSqlDialect.js';
|
|
2
2
|
import { AGGREGATE_VALUE_ALIAS, JSON_PULL_ALIAS } from '../dialect/aliases.js';
|
|
3
3
|
import { BYTES_PREFIX } from '../dialect/hydrateColumn.js';
|
|
4
4
|
import { jsonArraySlotArgs, jsonPath, jsonSlotArgs } from '../dialect/jsonSql.js';
|
|
@@ -30,6 +30,7 @@ const MSSQL_FEATURES = {
|
|
|
30
30
|
serverSideCursors: false,
|
|
31
31
|
correlatedWrites: true,
|
|
32
32
|
rowLocks: { of: true, withWindow: true, placement: 'tableHint' },
|
|
33
|
+
writeReturning: false,
|
|
33
34
|
nullsSortLowest: true,
|
|
34
35
|
nullsOrdering: 'case',
|
|
35
36
|
textScoreIndexes: false,
|
|
@@ -90,10 +91,12 @@ export class MsSqlDialect extends MergeSqlDialect {
|
|
|
90
91
|
return statements[command];
|
|
91
92
|
}
|
|
92
93
|
/**
|
|
93
|
-
* T-SQL has no inline form, so the level is set before the `BEGIN
|
|
94
|
-
* as statements would run; `MsSqlQuerier` opens its transactions through the driver
|
|
94
|
+
* T-SQL has no inline form, so the level is set before the `BEGIN`, and no read-only transaction. What a
|
|
95
|
+
* driver that sends these as statements would run; `MsSqlQuerier` opens its transactions through the driver.
|
|
95
96
|
*/
|
|
96
|
-
|
|
97
|
+
getBeginTransactionStatements({ isolationLevel } = {}) {
|
|
98
|
+
return isolationSetBefore(isolationLevel, this.beginTransactionCommand);
|
|
99
|
+
}
|
|
97
100
|
booleanLiteral = 'integer';
|
|
98
101
|
/**
|
|
99
102
|
* The clock in UTC, since `CURRENT_TIMESTAMP` is local time in the server's zone. No v7: `NEWSEQUENTIALID()` is
|
|
@@ -9,6 +9,11 @@ import { type TransactionScope } from './transaction.js';
|
|
|
9
9
|
*/
|
|
10
10
|
/** What an upsert reports of a row: the value a driver answers for a lone key, or the key the read back names. */
|
|
11
11
|
export type UpsertedId<E> = PrimaryKey | WrittenId<E>;
|
|
12
|
+
/** An `UPDATE` and a `DELETE` of one statement each, reporting the rows they wrote with the fields `keys` names. */
|
|
13
|
+
export type WritesReturning = {
|
|
14
|
+
update<E extends object>(entity: Type<E>, q: QuerySearch<E>, payload: UpdatePayload<E>, opts: QueryOptions, keys: readonly FieldKey<E>[]): Promise<E[]>;
|
|
15
|
+
delete<E extends object>(entity: Type<E>, q: QuerySearch<E>, opts: QueryOptions, keys: readonly FieldKey<E>[]): Promise<E[]>;
|
|
16
|
+
};
|
|
12
17
|
/** Base class for all database queriers. */
|
|
13
18
|
export declare abstract class AbstractQuerier implements Querier {
|
|
14
19
|
#private;
|
|
@@ -114,10 +119,10 @@ export declare abstract class AbstractQuerier implements Querier {
|
|
|
114
119
|
* transaction with only the fields it lists.
|
|
115
120
|
*/
|
|
116
121
|
private writeReturning;
|
|
117
|
-
/** The rows `q` matches with the fields `keys` names and their keys, through `afterLoad` as a read's are. */
|
|
118
|
-
private readReturning;
|
|
119
122
|
/** The rows `ids` names, in their order, each with only the fields `keys` names. */
|
|
120
123
|
private readWritten;
|
|
124
|
+
/** What `returning` reports of `rows`: each through `afterLoad`, as a read's are, then only the fields `keys` names. */
|
|
125
|
+
private returned;
|
|
121
126
|
/**
|
|
122
127
|
* Writes `rows` and their relations: the to-ones they hold the keys of first, so each row inserts
|
|
123
128
|
* pointing at its own, then the rows, then their children by the keys the rows got. An insert, and the
|
|
@@ -129,15 +134,25 @@ export declare abstract class AbstractQuerier implements Querier {
|
|
|
129
134
|
updateOneById<E extends object, const S extends FieldKey<E> = never, const V extends BooleanLike = true>(entity: Type<E>, id: EntityId<E>, payload: UpdateWrite<E>, opts?: QueryOptions & WriteOptions<E, S, V>): Promise<ReturningResult<S, number, QueryFindResult<E, S, V> | undefined>>;
|
|
130
135
|
updateMany<E extends object, const S extends FieldKey<E> = never, const V extends BooleanLike = true>(entity: Type<E>, q: QuerySearch<E>, payload: UpdateWrite<E>, opts?: QueryOptions & WriteOptions<E, S, V>): Promise<ReturningResult<S, number, QueryFindResult<E, S, V>[]>>;
|
|
131
136
|
/**
|
|
132
|
-
* The number of rows the update changed, or the rows `returning` reads back:
|
|
133
|
-
*
|
|
137
|
+
* The number of rows the update changed, or the rows `returning` reads back: settled first and held, so the
|
|
138
|
+
* update writes those rows and no other, whatever a payload or another writer does to what `$where` reads.
|
|
134
139
|
*/
|
|
135
140
|
private updateWhere;
|
|
136
|
-
/**
|
|
141
|
+
/**
|
|
142
|
+
* An update of one statement reporting the rows it wrote, between the update hooks. A payload writing no
|
|
143
|
+
* column writes nothing, so the rows it names are read instead.
|
|
144
|
+
*/
|
|
145
|
+
private updateReturning;
|
|
146
|
+
/**
|
|
147
|
+
* Updates the rows `q` matches, or the ones `settled` already names, between the update hooks, atomically
|
|
148
|
+
* where the payload writes relations too.
|
|
149
|
+
*/
|
|
137
150
|
private updateMatching;
|
|
138
151
|
/**
|
|
139
152
|
* The write every update runs, matching the version `lockKey` names where one is being held. Only a
|
|
140
|
-
* restore passes none: it writes no content, so there is no update of anyone's to lose.
|
|
153
|
+
* restore passes none: it writes no content, so there is no update of anyone's to lose. A versioned row is
|
|
154
|
+
* named by its one id in `q`, so the lock path writes `q` and ignores `settled`. Elsewhere `settled` names
|
|
155
|
+
* the rows to write, in batches the engine's bind budget allows.
|
|
141
156
|
*/
|
|
142
157
|
private updateRows;
|
|
143
158
|
/**
|
|
@@ -147,6 +162,8 @@ export declare abstract class AbstractQuerier implements Querier {
|
|
|
147
162
|
* still costs one statement. Best effort by nature - the row can change again while we ask.
|
|
148
163
|
*/
|
|
149
164
|
private throwStaleVersion;
|
|
165
|
+
/** What every update does to its row before its statement: writes the to-ones it holds, fills and guards it. */
|
|
166
|
+
private prepareUpdate;
|
|
150
167
|
/** The UPDATE, skipped where the payload writes no column, reporting `unwritten` instead. */
|
|
151
168
|
private updateColumns;
|
|
152
169
|
/**
|
|
@@ -155,14 +172,22 @@ export declare abstract class AbstractQuerier implements Querier {
|
|
|
155
172
|
*/
|
|
156
173
|
protected settlesWrite<E extends object>(entity: Type<E>, q: QuerySearch<E>): boolean;
|
|
157
174
|
/**
|
|
158
|
-
* `write` over `rows` in lists of as many as one statement names by `keyCount` keys, summing what each changed
|
|
159
|
-
*
|
|
175
|
+
* `write` over `rows` in lists of as many as one statement names by `keyCount` keys, summing what each changed,
|
|
176
|
+
* inside its caller's transaction, so a write split to fit the engine still lands whole.
|
|
160
177
|
*/
|
|
161
|
-
|
|
178
|
+
private writeBatches;
|
|
162
179
|
/** Runs a write of several statements as one: in a transaction of its own, or the one already open. */
|
|
163
180
|
protected atomically<T>(write: () => Promise<T>): Promise<T>;
|
|
164
|
-
/** The ids `q` matches, in its own order and page. */
|
|
165
|
-
|
|
181
|
+
/** The ids `q` matches, in its own order and page, held as {@link readForWrite} holds them. */
|
|
182
|
+
private settleIds;
|
|
183
|
+
/**
|
|
184
|
+
* The rows a write reads before it writes, held until the open transaction ends where the engine has row
|
|
185
|
+
* locks, so a racing writer waits for the commit; outside a transaction a lock would hold nothing. Elsewhere
|
|
186
|
+
* the transaction is the guard: libSQL and Turso take the write lock at `BEGIN`, SQLite and MongoDB fail the racer.
|
|
187
|
+
*/
|
|
188
|
+
private readForWrite;
|
|
189
|
+
/** How the engine writes rows and reports them in one statement, or `undefined` where a write reads them first. */
|
|
190
|
+
protected get writesReturning(): WritesReturning | undefined;
|
|
166
191
|
/** Runs one UPDATE over `q`, which names its rows by id wherever {@link updateMany} settled them. */
|
|
167
192
|
protected abstract internalUpdateMany<E extends object>(entity: Type<E>, q: QuerySearch<E>, payload: UpdatePayload<E>, opts?: QueryOptions): Promise<number>;
|
|
168
193
|
restoreOneById<E extends object>(entity: Type<E>, id: EntityId<E>): Promise<number>;
|
|
@@ -177,7 +202,8 @@ export declare abstract class AbstractQuerier implements Querier {
|
|
|
177
202
|
/**
|
|
178
203
|
* An upsert as a read, then writes: the rows the conflict names are read through the filters, those found update
|
|
179
204
|
* as `updateMany` does and the rest insert, so either branch writes its relations and a guarded row stays its
|
|
180
|
-
* tenant's. A row inserted concurrently fails on its key. See
|
|
205
|
+
* tenant's. A found row is held until the write, and a row inserted concurrently fails on its key. See
|
|
206
|
+
* architecture/security-filter-writes.md.
|
|
181
207
|
*/
|
|
182
208
|
private readThenUpsert;
|
|
183
209
|
/** Upserts `payload`, answering each row's key in payload order where the engine reports every one. */
|
|
@@ -188,8 +214,15 @@ export declare abstract class AbstractQuerier implements Querier {
|
|
|
188
214
|
$entity: Type<E>;
|
|
189
215
|
}, opts?: QueryOptions): Promise<number>;
|
|
190
216
|
deleteMany<E extends object, const S extends FieldKey<E> = never, const V extends BooleanLike = true>(entity: Type<E>, q: QuerySearch<E>, opts?: QueryOptions & WriteOptions<E, S, V>): Promise<ReturningResult<S, number, QueryFindResult<E, S, V>[]>>;
|
|
191
|
-
/** The number of rows deleted, or the rows `returning` reads as they were
|
|
217
|
+
/** The number of rows deleted, or the rows `returning` reads as they were: held before the delete, which deletes those. */
|
|
192
218
|
private deleteWhere;
|
|
219
|
+
/** Whether an update is its one statement over `q`: no version to lock, relation to write or page to settle first. */
|
|
220
|
+
private updatesByFilter;
|
|
221
|
+
/** Whether a delete is its one statement over `q`: no hook, cascade or page needs its rows read first. */
|
|
222
|
+
private deletesByFilter;
|
|
223
|
+
/** Whether a delete hook listens on the entity, so a delete reads each row whole to hand it over. */
|
|
224
|
+
private watchesDelete;
|
|
225
|
+
/** Deletes the rows `q` matches, or the ones `read` holds, reading them first where a hook, cascade or page needs them. */
|
|
193
226
|
private deleteRows;
|
|
194
227
|
/** Runs one DELETE (or soft-delete stamp) over `q`, which names its rows by id wherever {@link deleteMany} settled them. */
|
|
195
228
|
protected abstract internalDeleteMany<E extends object>(entity: Type<E>, q: QuerySearch<E>, opts?: QueryOptions): Promise<number>;
|
|
@@ -210,7 +243,8 @@ export declare abstract class AbstractQuerier implements Querier {
|
|
|
210
243
|
private insertChildren;
|
|
211
244
|
/**
|
|
212
245
|
* Makes `value` the children of each parent `ids` names, which it owns: the rows it lists are saved,
|
|
213
|
-
* keeping what each does not write, and the parent's other children (a junction's other links) go.
|
|
246
|
+
* keeping what each does not write, and the parent's other children (a junction's other links) go. Inside
|
|
247
|
+
* the transaction the update holds.
|
|
214
248
|
*/
|
|
215
249
|
private replaceChildren;
|
|
216
250
|
/** A many-to-many's links: the targets are saved, the parent's links to any other go, and the missing ones are added. */
|
|
@@ -281,9 +315,10 @@ export declare abstract class AbstractQuerier implements Querier {
|
|
|
281
315
|
*/
|
|
282
316
|
private emitLoaded;
|
|
283
317
|
/**
|
|
284
|
-
* The ids of `rows`, read through the filters by the columns an upsert matches them on
|
|
285
|
-
* statement that could not report them in payload order, or before a
|
|
286
|
-
* read row matches, or that two do, keeps `undefined`: a missing id is honest
|
|
318
|
+
* The ids of `rows`, read through the filters by the columns an upsert matches them on, and held as
|
|
319
|
+
* {@link readForWrite} holds them: after a statement that could not report them in payload order, or before a
|
|
320
|
+
* guarded upsert. A row that no read row matches, or that two do, keeps `undefined`: a missing id is honest
|
|
321
|
+
* where a guessed one is not.
|
|
287
322
|
*/
|
|
288
323
|
protected idsByConflict<E extends object>(entity: Type<E>, conflictPaths: QueryConflictPaths<E>, rows: EntityData<E>[]): Promise<(WrittenId<E> | undefined)[]>;
|
|
289
324
|
/**
|
|
@@ -139,6 +139,10 @@ function returnedKeys(meta, returning) {
|
|
|
139
139
|
function deletableRows(opts) {
|
|
140
140
|
return opts?.hardDelete ? { ...opts, filters: withoutSoftDeleteFilter(opts.filters) } : opts;
|
|
141
141
|
}
|
|
142
|
+
/** Whether an update of `row` writes a column, its `onUpdate` fills included: one that writes none sends nothing. */
|
|
143
|
+
function writesColumns(meta, row) {
|
|
144
|
+
return filterFieldKeys(meta, row, 'onUpdate').length > 0;
|
|
145
|
+
}
|
|
142
146
|
/** `row` with only the fields `keys` names. */
|
|
143
147
|
function pickFields(row, keys) {
|
|
144
148
|
const picked = {};
|
|
@@ -376,15 +380,6 @@ export class AbstractQuerier {
|
|
|
376
380
|
const keys = returnedKeys(getMeta(entity), opts?.returning);
|
|
377
381
|
return keys ? this.atomically(async () => this.readWritten(entity, await write(), keys)) : write();
|
|
378
382
|
}
|
|
379
|
-
/** The rows `q` matches with the fields `keys` names and their keys, through `afterLoad` as a read's are. */
|
|
380
|
-
async readReturning(entity, q, keys, opts) {
|
|
381
|
-
const $select = keySet([...keys, ...getMeta(entity).ids]);
|
|
382
|
-
const rows = await this.internalFindMany(entity, { ...q, $select }, opts);
|
|
383
|
-
if (this.hasHook(entity, 'afterLoad')) {
|
|
384
|
-
await this.emitHook(entity, 'afterLoad', rows);
|
|
385
|
-
}
|
|
386
|
-
return rows;
|
|
387
|
-
}
|
|
388
383
|
/** The rows `ids` names, in their order, each with only the fields `keys` names. */
|
|
389
384
|
async readWritten(entity, ids, keys, opts) {
|
|
390
385
|
const meta = getMeta(entity);
|
|
@@ -397,15 +392,19 @@ export class AbstractQuerier {
|
|
|
397
392
|
}
|
|
398
393
|
// The rows this write wrote, whatever a filter says of them: a soft-deleted one inserted is still written.
|
|
399
394
|
const read = { ...opts, filters: withoutSoftDeleteFilter(opts?.filters) };
|
|
395
|
+
const $select = keySet([...keys, ...meta.ids]);
|
|
400
396
|
const rows = [];
|
|
401
397
|
for (const batch of chunk(known, this.dialect.keyListCapacity(meta.ids.length))) {
|
|
402
|
-
rows.push(...(await this.
|
|
398
|
+
rows.push(...(await this.internalFindMany(entity, { $select, $where: whereIds(meta, batch) }, read)));
|
|
403
399
|
}
|
|
404
400
|
const byKey = new Map(rows.map((row) => [rowKey(row, meta.ids), row]));
|
|
405
|
-
|
|
406
|
-
|
|
407
|
-
|
|
408
|
-
|
|
401
|
+
const ordered = known.flatMap((id) => byKey.get(rowKey(whereIds(meta, id), meta.ids)) ?? []);
|
|
402
|
+
return this.returned(entity, ordered, keys);
|
|
403
|
+
}
|
|
404
|
+
/** What `returning` reports of `rows`: each through `afterLoad`, as a read's are, then only the fields `keys` names. */
|
|
405
|
+
async returned(entity, rows, keys) {
|
|
406
|
+
await this.emitLoaded(entity, rows, undefined);
|
|
407
|
+
return rows.map((row) => pickFields(row, keys));
|
|
409
408
|
}
|
|
410
409
|
/**
|
|
411
410
|
* Writes `rows` and their relations: the to-ones they hold the keys of first, so each row inserts
|
|
@@ -429,8 +428,8 @@ export class AbstractQuerier {
|
|
|
429
428
|
return this.updateWhere(entity, q, payload, opts);
|
|
430
429
|
}
|
|
431
430
|
/**
|
|
432
|
-
* The number of rows the update changed, or the rows `returning` reads back:
|
|
433
|
-
*
|
|
431
|
+
* The number of rows the update changed, or the rows `returning` reads back: settled first and held, so the
|
|
432
|
+
* update writes those rows and no other, whatever a payload or another writer does to what `$where` reads.
|
|
434
433
|
*/
|
|
435
434
|
async updateWhere(entity, q, payload, opts) {
|
|
436
435
|
assertNamesRows(entity, 'updateMany', q, opts);
|
|
@@ -440,27 +439,49 @@ export class AbstractQuerier {
|
|
|
440
439
|
if (!keys) {
|
|
441
440
|
return this.updateMatching(entity, q, payload, opts);
|
|
442
441
|
}
|
|
442
|
+
const { writesReturning } = this;
|
|
443
|
+
if (writesReturning && this.updatesByFilter(entity, q, payload)) {
|
|
444
|
+
return this.updateReturning(writesReturning, entity, q, payload, rest, keys);
|
|
445
|
+
}
|
|
443
446
|
return this.atomically(async () => {
|
|
444
447
|
const ids = await this.settleIds(entity, q, rest);
|
|
445
|
-
await this.updateMatching(entity, q, payload, rest);
|
|
448
|
+
await this.updateMatching(entity, q, payload, rest, ids);
|
|
446
449
|
return this.readWritten(entity, ids, keys, rest);
|
|
447
450
|
});
|
|
448
451
|
}
|
|
449
|
-
/**
|
|
450
|
-
|
|
452
|
+
/**
|
|
453
|
+
* An update of one statement reporting the rows it wrote, between the update hooks. A payload writing no
|
|
454
|
+
* column writes nothing, so the rows it names are read instead.
|
|
455
|
+
*/
|
|
456
|
+
updateReturning(writes, entity, q, payload, opts, keys) {
|
|
457
|
+
const meta = getMeta(entity);
|
|
458
|
+
const read = [...keys, ...meta.ids];
|
|
459
|
+
return this.hooked(entity, 'Update', [payload], async ([row]) => {
|
|
460
|
+
await this.prepareUpdate(entity, row);
|
|
461
|
+
const rows = writesColumns(meta, row)
|
|
462
|
+
? await writes.update(entity, q, row, opts, read)
|
|
463
|
+
: await this.internalFindMany(entity, { ...q, $select: keySet(read) }, opts);
|
|
464
|
+
return this.returned(entity, rows, keys);
|
|
465
|
+
});
|
|
466
|
+
}
|
|
467
|
+
/**
|
|
468
|
+
* Updates the rows `q` matches, or the ones `settled` already names, between the update hooks, atomically
|
|
469
|
+
* where the payload writes relations too.
|
|
470
|
+
*/
|
|
471
|
+
updateMatching(entity, q, payload, opts, settled) {
|
|
451
472
|
const meta = getMeta(entity);
|
|
452
|
-
const update = () => this.hooked(entity, 'Update', [payload], ([row]) => this.updateRows(entity, q, row, opts, meta.version));
|
|
473
|
+
const update = () => this.hooked(entity, 'Update', [payload], ([row]) => this.updateRows(entity, q, row, opts, meta.version, settled));
|
|
453
474
|
return writesRelations(meta, [payload]) ? this.atomically(update) : update();
|
|
454
475
|
}
|
|
455
476
|
/**
|
|
456
477
|
* The write every update runs, matching the version `lockKey` names where one is being held. Only a
|
|
457
|
-
* restore passes none: it writes no content, so there is no update of anyone's to lose.
|
|
478
|
+
* restore passes none: it writes no content, so there is no update of anyone's to lose. A versioned row is
|
|
479
|
+
* named by its one id in `q`, so the lock path writes `q` and ignores `settled`. Elsewhere `settled` names
|
|
480
|
+
* the rows to write, in batches the engine's bind budget allows.
|
|
458
481
|
*/
|
|
459
|
-
async updateRows(entity, q, row, opts, lockKey) {
|
|
482
|
+
async updateRows(entity, q, row, opts, lockKey, settled) {
|
|
460
483
|
const meta = getMeta(entity);
|
|
461
|
-
await this.
|
|
462
|
-
fillOnFields(meta, [row], 'onUpdate');
|
|
463
|
-
guardWrite(meta, [row], 'update');
|
|
484
|
+
await this.prepareUpdate(entity, row);
|
|
464
485
|
const relKeys = ownedRelations(meta).filter((key) => Object.hasOwn(row, key));
|
|
465
486
|
const settles = !!relKeys.length || this.settlesWrite(entity, q);
|
|
466
487
|
if (lockKey) {
|
|
@@ -470,18 +491,20 @@ export class AbstractQuerier {
|
|
|
470
491
|
const changes = await this.updateColumns(entity, lock.q, row, opts, 0);
|
|
471
492
|
return changes || this.throwStaleVersion(entity, lockKey, q, lock.expected, opts);
|
|
472
493
|
}
|
|
473
|
-
if (!settles) {
|
|
494
|
+
if (!settles && !settled) {
|
|
474
495
|
return this.updateColumns(entity, q, row, opts, 0);
|
|
475
496
|
}
|
|
476
|
-
|
|
477
|
-
|
|
478
|
-
|
|
479
|
-
|
|
480
|
-
|
|
481
|
-
|
|
482
|
-
|
|
483
|
-
|
|
484
|
-
|
|
497
|
+
return this.atomically(async () => {
|
|
498
|
+
const ids = settled ?? (await this.settleIds(entity, q, opts));
|
|
499
|
+
if (!ids.length) {
|
|
500
|
+
return 0;
|
|
501
|
+
}
|
|
502
|
+
const changes = await this.writeBatches(ids, meta.ids.length, (batch) => this.updateColumns(entity, { $where: whereIds(meta, batch) }, row, opts, batch.length));
|
|
503
|
+
for (const relKey of relKeys) {
|
|
504
|
+
await this.replaceChildren(entity, relKey, ids, row[relKey]);
|
|
505
|
+
}
|
|
506
|
+
return changes;
|
|
507
|
+
});
|
|
485
508
|
}
|
|
486
509
|
/**
|
|
487
510
|
* Why an update matched no row. The filter named the row by its id, so reading by that id alone
|
|
@@ -500,10 +523,16 @@ export class AbstractQuerier {
|
|
|
500
523
|
: `'${entityName(meta)}' moved on: the payload carries '${key}' ${String(expected)}, the row is at ${String(actual)}`;
|
|
501
524
|
throw new UqlOptimisticLockError(message, expected, actual);
|
|
502
525
|
}
|
|
526
|
+
/** What every update does to its row before its statement: writes the to-ones it holds, fills and guards it. */
|
|
527
|
+
async prepareUpdate(entity, row) {
|
|
528
|
+
const meta = getMeta(entity);
|
|
529
|
+
await this.writeHeldReferences(entity, [row]);
|
|
530
|
+
fillOnFields(meta, [row], 'onUpdate');
|
|
531
|
+
guardWrite(meta, [row], 'update');
|
|
532
|
+
}
|
|
503
533
|
/** The UPDATE, skipped where the payload writes no column, reporting `unwritten` instead. */
|
|
504
534
|
async updateColumns(entity, q, row, opts, unwritten) {
|
|
505
|
-
|
|
506
|
-
return writes ? this.internalUpdateMany(entity, q, row, opts) : unwritten;
|
|
535
|
+
return writesColumns(getMeta(entity), row) ? this.internalUpdateMany(entity, q, row, opts) : unwritten;
|
|
507
536
|
}
|
|
508
537
|
/**
|
|
509
538
|
* Whether a write has to name the rows `q` matches by their ids: no engine pages or orders an update or
|
|
@@ -514,30 +543,39 @@ export class AbstractQuerier {
|
|
|
514
543
|
return isPagedQuery(q) || (!dialect.features.correlatedWrites && dialect.constrainsRelations(entity, q.$where));
|
|
515
544
|
}
|
|
516
545
|
/**
|
|
517
|
-
* `write` over `rows` in lists of as many as one statement names by `keyCount` keys, summing what each changed
|
|
518
|
-
*
|
|
546
|
+
* `write` over `rows` in lists of as many as one statement names by `keyCount` keys, summing what each changed,
|
|
547
|
+
* inside its caller's transaction, so a write split to fit the engine still lands whole.
|
|
519
548
|
*/
|
|
520
549
|
async writeBatches(rows, keyCount, write) {
|
|
521
|
-
|
|
522
|
-
const
|
|
523
|
-
|
|
524
|
-
|
|
525
|
-
|
|
526
|
-
}
|
|
527
|
-
return changes;
|
|
528
|
-
};
|
|
529
|
-
return batches.length > 1 ? this.atomically(each) : each();
|
|
550
|
+
let changes = 0;
|
|
551
|
+
for (const batch of chunk(rows, this.dialect.keyListCapacity(keyCount))) {
|
|
552
|
+
changes += await write(batch);
|
|
553
|
+
}
|
|
554
|
+
return changes;
|
|
530
555
|
}
|
|
531
556
|
/** Runs a write of several statements as one: in a transaction of its own, or the one already open. */
|
|
532
557
|
atomically(write) {
|
|
533
558
|
return this.scopeHere() ? write() : this.transaction(write);
|
|
534
559
|
}
|
|
535
|
-
/** The ids `q` matches, in its own order and page. */
|
|
560
|
+
/** The ids `q` matches, in its own order and page, held as {@link readForWrite} holds them. */
|
|
536
561
|
async settleIds(entity, q, opts) {
|
|
537
562
|
const meta = getMeta(entity);
|
|
538
|
-
const rows = await this.
|
|
563
|
+
const rows = await this.readForWrite(entity, idOnlyQuery(meta, q), opts);
|
|
539
564
|
return rows.map((row) => idOf(meta, row));
|
|
540
565
|
}
|
|
566
|
+
/**
|
|
567
|
+
* The rows a write reads before it writes, held until the open transaction ends where the engine has row
|
|
568
|
+
* locks, so a racing writer waits for the commit; outside a transaction a lock would hold nothing. Elsewhere
|
|
569
|
+
* the transaction is the guard: libSQL and Turso take the write lock at `BEGIN`, SQLite and MongoDB fail the racer.
|
|
570
|
+
*/
|
|
571
|
+
readForWrite(entity, q, opts) {
|
|
572
|
+
const held = this.dialect.features.rowLocks && this.scopeHere() ? { ...q, $lock: true } : q;
|
|
573
|
+
return this.internalFindMany(entity, held, opts);
|
|
574
|
+
}
|
|
575
|
+
/** How the engine writes rows and reports them in one statement, or `undefined` where a write reads them first. */
|
|
576
|
+
get writesReturning() {
|
|
577
|
+
return undefined;
|
|
578
|
+
}
|
|
541
579
|
async restoreOneById(entity, id) {
|
|
542
580
|
assertIdValue(entity, id);
|
|
543
581
|
return this.restoreMany(entity, { $where: whereIds(getMeta(entity), id) });
|
|
@@ -580,7 +618,8 @@ export class AbstractQuerier {
|
|
|
580
618
|
/**
|
|
581
619
|
* An upsert as a read, then writes: the rows the conflict names are read through the filters, those found update
|
|
582
620
|
* as `updateMany` does and the rest insert, so either branch writes its relations and a guarded row stays its
|
|
583
|
-
* tenant's. A row inserted concurrently fails on its key. See
|
|
621
|
+
* tenant's. A found row is held until the write, and a row inserted concurrently fails on its key. See
|
|
622
|
+
* architecture/security-filter-writes.md.
|
|
584
623
|
*/
|
|
585
624
|
async readThenUpsert(entity, conflictPaths, rows, update) {
|
|
586
625
|
const meta = getMeta(entity);
|
|
@@ -589,7 +628,7 @@ export class AbstractQuerier {
|
|
|
589
628
|
return [];
|
|
590
629
|
}
|
|
591
630
|
const keys = getKeys(conflictPaths);
|
|
592
|
-
|
|
631
|
+
return this.atomically(async () => {
|
|
593
632
|
const ids = await this.idsByConflict(entity, conflictPaths, rows);
|
|
594
633
|
for (const [index, row] of rows.entries()) {
|
|
595
634
|
// An empty `update` leaves a found row as it is, as `DO NOTHING` does.
|
|
@@ -606,10 +645,7 @@ export class AbstractQuerier {
|
|
|
606
645
|
}
|
|
607
646
|
// A found row's key is adopted by the caller; an inserted one carries the key its insert wrote.
|
|
608
647
|
return ids;
|
|
609
|
-
};
|
|
610
|
-
return rows.length > 1 || writesRelations(meta, [...rows, ...(update ? [update] : [])])
|
|
611
|
-
? this.atomically(write)
|
|
612
|
-
: write();
|
|
648
|
+
});
|
|
613
649
|
}
|
|
614
650
|
async deleteOneById(entity, id, opts) {
|
|
615
651
|
assertIdValue(entity, id);
|
|
@@ -620,7 +656,7 @@ export class AbstractQuerier {
|
|
|
620
656
|
const [entity, q, opts] = entityArgs(args);
|
|
621
657
|
return this.deleteWhere(entity, q, opts);
|
|
622
658
|
}
|
|
623
|
-
/** The number of rows deleted, or the rows `returning` reads as they were
|
|
659
|
+
/** The number of rows deleted, or the rows `returning` reads as they were: held before the delete, which deletes those. */
|
|
624
660
|
async deleteWhere(entity, q, opts) {
|
|
625
661
|
assertNamesRows(entity, 'deleteMany', q, opts);
|
|
626
662
|
const meta = getMeta(entity);
|
|
@@ -629,27 +665,51 @@ export class AbstractQuerier {
|
|
|
629
665
|
if (!keys) {
|
|
630
666
|
return this.deleteRows(entity, q, opts);
|
|
631
667
|
}
|
|
668
|
+
const read = [...keys, ...meta.ids];
|
|
669
|
+
// A soft delete stamps the rows, which a `RETURNING` would report stamped rather than as they were.
|
|
670
|
+
const { writesReturning } = this;
|
|
671
|
+
if (writesReturning && (rest.hardDelete || !meta.softDelete) && this.deletesByFilter(entity, q)) {
|
|
672
|
+
return this.returned(entity, await writesReturning.delete(entity, q, rest, read), keys);
|
|
673
|
+
}
|
|
674
|
+
// A delete hook receives whole rows; without one, only the keys `returning` names and the ids are read.
|
|
675
|
+
const $select = this.watchesDelete(entity) ? undefined : keySet(read);
|
|
632
676
|
return this.atomically(async () => {
|
|
633
|
-
const rows = await this.
|
|
634
|
-
|
|
635
|
-
|
|
677
|
+
const rows = await this.readForWrite(entity, { ...q, $select }, deletableRows(rest));
|
|
678
|
+
// `afterLoad` sees copies, as a read's rows, so a delete hook still gets each row as it was read.
|
|
679
|
+
const reported = await this.returned(entity, clone(rows), keys);
|
|
680
|
+
await this.deleteRows(entity, q, rest, rows);
|
|
681
|
+
return reported;
|
|
636
682
|
});
|
|
637
683
|
}
|
|
638
|
-
|
|
684
|
+
/** Whether an update is its one statement over `q`: no version to lock, relation to write or page to settle first. */
|
|
685
|
+
updatesByFilter(entity, q, payload) {
|
|
639
686
|
const meta = getMeta(entity);
|
|
640
|
-
|
|
641
|
-
|
|
642
|
-
|
|
687
|
+
return !meta.version && !writesRelations(meta, [payload]) && !this.settlesWrite(entity, q);
|
|
688
|
+
}
|
|
689
|
+
/** Whether a delete is its one statement over `q`: no hook, cascade or page needs its rows read first. */
|
|
690
|
+
deletesByFilter(entity, q) {
|
|
691
|
+
const meta = getMeta(entity);
|
|
692
|
+
return !this.watchesDelete(entity) && !cascadingRelations(meta, 'delete').length && !this.settlesWrite(entity, q);
|
|
693
|
+
}
|
|
694
|
+
/** Whether a delete hook listens on the entity, so a delete reads each row whole to hand it over. */
|
|
695
|
+
watchesDelete(entity) {
|
|
696
|
+
return this.hasHook(entity, 'beforeDelete') || this.hasHook(entity, 'afterDelete');
|
|
697
|
+
}
|
|
698
|
+
/** Deletes the rows `q` matches, or the ones `read` holds, reading them first where a hook, cascade or page needs them. */
|
|
699
|
+
async deleteRows(entity, q, opts, read) {
|
|
700
|
+
const meta = getMeta(entity);
|
|
701
|
+
if (!read && this.deletesByFilter(entity, q)) {
|
|
643
702
|
return this.internalDeleteMany(entity, q, opts);
|
|
644
703
|
}
|
|
645
|
-
const
|
|
646
|
-
|
|
647
|
-
|
|
648
|
-
|
|
649
|
-
|
|
650
|
-
|
|
651
|
-
|
|
652
|
-
|
|
704
|
+
const cascades = cascadingRelations(meta, 'delete').length > 0;
|
|
705
|
+
const watched = this.watchesDelete(entity);
|
|
706
|
+
return this.atomically(async () => {
|
|
707
|
+
// A hook receives the rows themselves; the ids read off them name the same rows a second read might not.
|
|
708
|
+
const doomed = read ?? (await this.readForWrite(entity, watched ? q : idOnlyQuery(meta, q), deletableRows(opts)));
|
|
709
|
+
if (!doomed.length) {
|
|
710
|
+
return 0;
|
|
711
|
+
}
|
|
712
|
+
const ids = doomed.map((row) => idOf(meta, row));
|
|
653
713
|
await this.emitHook(entity, 'beforeDelete', doomed);
|
|
654
714
|
const changes = await this.writeBatches(ids, meta.ids.length, async (batch) => {
|
|
655
715
|
// Children first: they hold the foreign key, which a schema without `ON DELETE CASCADE` enforces.
|
|
@@ -660,8 +720,7 @@ export class AbstractQuerier {
|
|
|
660
720
|
});
|
|
661
721
|
await this.emitHook(entity, 'afterDelete', doomed);
|
|
662
722
|
return changes;
|
|
663
|
-
};
|
|
664
|
-
return cascades ? this.atomically(remove) : remove();
|
|
723
|
+
});
|
|
665
724
|
}
|
|
666
725
|
async saveOne(entity, payload, opts) {
|
|
667
726
|
const [written] = await this.writeReturning(entity, () => this.saveIds(entity, [payload]), opts);
|
|
@@ -754,7 +813,8 @@ export class AbstractQuerier {
|
|
|
754
813
|
}
|
|
755
814
|
/**
|
|
756
815
|
* Makes `value` the children of each parent `ids` names, which it owns: the rows it lists are saved,
|
|
757
|
-
* keeping what each does not write, and the parent's other children (a junction's other links) go.
|
|
816
|
+
* keeping what each does not write, and the parent's other children (a junction's other links) go. Inside
|
|
817
|
+
* the transaction the update holds.
|
|
758
818
|
*/
|
|
759
819
|
async replaceChildren(entity, relKey, ids, value) {
|
|
760
820
|
const relOpts = relationOf(getMeta(entity), relKey);
|
|
@@ -1011,9 +1071,10 @@ export class AbstractQuerier {
|
|
|
1011
1071
|
await this.emitHook(entity, 'afterLoad', rows);
|
|
1012
1072
|
}
|
|
1013
1073
|
/**
|
|
1014
|
-
* The ids of `rows`, read through the filters by the columns an upsert matches them on
|
|
1015
|
-
* statement that could not report them in payload order, or before a
|
|
1016
|
-
* read row matches, or that two do, keeps `undefined`: a missing id is honest
|
|
1074
|
+
* The ids of `rows`, read through the filters by the columns an upsert matches them on, and held as
|
|
1075
|
+
* {@link readForWrite} holds them: after a statement that could not report them in payload order, or before a
|
|
1076
|
+
* guarded upsert. A row that no read row matches, or that two do, keeps `undefined`: a missing id is honest
|
|
1077
|
+
* where a guessed one is not.
|
|
1017
1078
|
*/
|
|
1018
1079
|
async idsByConflict(entity, conflictPaths, rows) {
|
|
1019
1080
|
const meta = getMeta(entity);
|
|
@@ -1024,7 +1085,7 @@ export class AbstractQuerier {
|
|
|
1024
1085
|
const found = [];
|
|
1025
1086
|
for (const batch of chunk(distinct, this.dialect.keyListCapacity(keys.length))) {
|
|
1026
1087
|
const q = { $select: keySet([...meta.ids, ...keys]), $where: whereKeysIn(keys, batch) };
|
|
1027
|
-
found.push(await this.
|
|
1088
|
+
found.push(await this.readForWrite(entity, q, { filters: withoutSoftDeleteFilter(undefined) }));
|
|
1028
1089
|
}
|
|
1029
1090
|
const byConflict = new Map();
|
|
1030
1091
|
for (const row of found.flat()) {
|
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
import type { AbstractSqlDialect } from '../dialect/index.js';
|
|
2
2
|
import type { EntityData, ExtraOptions, Query, QueryAggMap, QueryAggregate, QueryAggregateResult, QueryConflictPaths, QueryPage, QueryGroupMap, QueryOptions, QuerySearch, QueryUpdateResult, RawRow, SavepointCommand, SqlQuerier, SqlStatement, TransactionOptions, Type, UpdatePayload } from '../type/index.js';
|
|
3
3
|
import type { BuildUpdateResultPayload } from '../util/sql.util.js';
|
|
4
|
-
import { AbstractQuerier, type UpsertedId } from './abstractQuerier.js';
|
|
4
|
+
import { AbstractQuerier, type UpsertedId, type WritesReturning } from './abstractQuerier.js';
|
|
5
5
|
export declare abstract class AbstractSqlQuerier extends AbstractQuerier implements SqlQuerier {
|
|
6
6
|
#private;
|
|
7
7
|
readonly dialect: AbstractSqlDialect;
|
|
@@ -83,6 +83,10 @@ export declare abstract class AbstractSqlQuerier extends AbstractQuerier impleme
|
|
|
83
83
|
protected internalAggregate<E extends object, G extends QueryGroupMap<E>, A extends QueryAggMap<E>>(entity: Type<E>, q: QueryAggregate<E, G, A>, opts?: QueryOptions): Promise<QueryAggregateResult<E, G, A>[]>;
|
|
84
84
|
internalInsertMany<E extends object>(entity: Type<E>, rows: EntityData<E>[]): Promise<void>;
|
|
85
85
|
internalUpdateMany<E extends object>(entity: Type<E>, q: QuerySearch<E>, payload: UpdatePayload<E>, opts?: QueryOptions): Promise<number>;
|
|
86
|
+
/** `UPDATE` and `DELETE` with a `RETURNING` read as a read's rows are, where the engine has it. */
|
|
87
|
+
protected get writesReturning(): WritesReturning | undefined;
|
|
88
|
+
/** The rows the write `build` renders reports, `RETURNING` the fields `keys` names. */
|
|
89
|
+
private reportedRows;
|
|
86
90
|
protected internalUpsertMany<E extends object>(entity: Type<E>, conflictPaths: QueryConflictPaths<E>, payload: E[], update?: UpdatePayload<E>): Promise<(UpsertedId<E> | undefined)[] | undefined>;
|
|
87
91
|
private runUpsert;
|
|
88
92
|
protected internalDeleteMany<E extends object>(entity: Type<E>, q: QuerySearch<E>, opts?: QueryOptions): Promise<number>;
|
|
@@ -278,6 +278,21 @@ export class AbstractSqlQuerier extends AbstractQuerier {
|
|
|
278
278
|
const { changes = 0 } = await this.exec((ctx) => this.dialect.update(ctx, entity, q, payload, opts));
|
|
279
279
|
return changes;
|
|
280
280
|
}
|
|
281
|
+
/** `UPDATE` and `DELETE` with a `RETURNING` read as a read's rows are, where the engine has it. */
|
|
282
|
+
get writesReturning() {
|
|
283
|
+
return this.dialect.features.writeReturning ? this.#returningWrites : undefined;
|
|
284
|
+
}
|
|
285
|
+
#returningWrites = {
|
|
286
|
+
update: (entity, q, payload, opts, keys) => this.reportedRows(entity, keys, (ctx) => this.dialect.update(ctx, entity, q, payload, opts)),
|
|
287
|
+
delete: (entity, q, opts, keys) => this.reportedRows(entity, keys, (ctx) => this.dialect.delete(ctx, entity, q, opts)),
|
|
288
|
+
};
|
|
289
|
+
/** The rows the write `build` renders reports, `RETURNING` the fields `keys` names. */
|
|
290
|
+
reportedRows(entity, keys, build) {
|
|
291
|
+
return this.readRows((ctx) => {
|
|
292
|
+
build(ctx);
|
|
293
|
+
return this.dialect.returning(ctx, entity, keys);
|
|
294
|
+
});
|
|
295
|
+
}
|
|
281
296
|
async internalUpsertMany(entity, conflictPaths, payload, update) {
|
|
282
297
|
if (!payload.length) {
|
|
283
298
|
return [];
|
|
@@ -364,7 +379,7 @@ export class AbstractSqlQuerier extends AbstractQuerier {
|
|
|
364
379
|
* case it overrides all three. The bookkeeping around them stays above, written once.
|
|
365
380
|
*/
|
|
366
381
|
async internalBegin(opts) {
|
|
367
|
-
for (const sql of this.dialect.getBeginTransactionStatements(opts
|
|
382
|
+
for (const sql of this.dialect.getBeginTransactionStatements(opts)) {
|
|
368
383
|
await this.runTransactionCommand(sql);
|
|
369
384
|
}
|
|
370
385
|
}
|
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
import type { ExtraOptions, RawRow } from '../type/index.js';
|
|
1
|
+
import type { ExtraOptions, RawRow, TransactionOptions } from '../type/index.js';
|
|
2
2
|
import { AbstractSqliteQuerier, type SqliteBindValue } from './abstractSqliteQuerier.js';
|
|
3
3
|
import type { SqliteDialect } from './sqliteDialect.js';
|
|
4
4
|
export type HranaInValue = SqliteBindValue | ArrayBuffer | Date;
|
|
@@ -47,7 +47,7 @@ export declare class HranaQuerier extends AbstractSqliteQuerier {
|
|
|
47
47
|
rows: RawRow[];
|
|
48
48
|
changes: number;
|
|
49
49
|
}>;
|
|
50
|
-
protected internalBegin(): Promise<void>;
|
|
50
|
+
protected internalBegin(opts?: TransactionOptions): Promise<void>;
|
|
51
51
|
/**
|
|
52
52
|
* Both drop the handle before the call, not after: one that outlived a failed commit would carry
|
|
53
53
|
* every later statement into a transaction the server may already have ended.
|
|
@@ -21,8 +21,8 @@ export class HranaQuerier extends AbstractSqliteQuerier {
|
|
|
21
21
|
const res = await (this.tx ?? this.client).execute({ sql: query, args: values });
|
|
22
22
|
return { rows: res.rows, changes: res.rowsAffected };
|
|
23
23
|
}
|
|
24
|
-
async internalBegin() {
|
|
25
|
-
this.tx = await this.client.transaction('write');
|
|
24
|
+
async internalBegin(opts) {
|
|
25
|
+
this.tx = await this.client.transaction(opts?.readOnly ? 'read' : 'write');
|
|
26
26
|
}
|
|
27
27
|
/**
|
|
28
28
|
* Both drop the handle before the call, not after: one that outlived a failed commit would carry
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
import { AbstractSqlDialect, type DerivedRelation, type RelationRows, type SelectTerm } from '../dialect/abstractSqlDialect.js';
|
|
2
2
|
import { type JsonAccessMode, type JsonSlot } from '../dialect/jsonSql.js';
|
|
3
|
-
import { type EntityMeta, type FieldOptions, type Query, type QueryContext, type QueryTextSearchOptions, type QueryWhere, type SqlDialectFeatures, type SqlValues, type VectorDistance, type VectorMetric } from '../type/index.js';
|
|
3
|
+
import { type EntityMeta, type FieldOptions, type Query, type QueryContext, type QueryTextSearchOptions, type QueryWhere, type SqlDialectFeatures, type SqlValues, type VectorDistance, type VectorMetric, type TransactionOptions } from '../type/index.js';
|
|
4
4
|
/** What SQLite and the engines derived from it have. */
|
|
5
5
|
export declare const SQLITE_FEATURES: SqlDialectFeatures;
|
|
6
6
|
export declare class SqliteDialect extends AbstractSqlDialect {
|
|
@@ -8,8 +8,9 @@ export declare class SqliteDialect extends AbstractSqlDialect {
|
|
|
8
8
|
readonly dialectName = "sqlite";
|
|
9
9
|
readonly escapeIdChar = "`";
|
|
10
10
|
readonly autoIncrementSuffix = "PRIMARY KEY AUTOINCREMENT";
|
|
11
|
-
readonly beginTransactionCommand
|
|
12
|
-
|
|
11
|
+
readonly beginTransactionCommand: string;
|
|
12
|
+
/** No level to set: SQLite serializes writers. A read-only transaction defers its lock to its first write. */
|
|
13
|
+
getBeginTransactionStatements({ readOnly }?: TransactionOptions): string[];
|
|
13
14
|
readonly booleanLiteral = "integer";
|
|
14
15
|
/**
|
|
15
16
|
* The clock and today in the same text as a bound `Date`, where `CURRENT_TIMESTAMP` writes whole seconds and
|
|
@@ -31,6 +31,7 @@ export const SQLITE_FEATURES = {
|
|
|
31
31
|
serverSideCursors: false,
|
|
32
32
|
correlatedWrites: true,
|
|
33
33
|
rowLocks: false,
|
|
34
|
+
writeReturning: true,
|
|
34
35
|
nullsSortLowest: true,
|
|
35
36
|
nullsOrdering: 'clause',
|
|
36
37
|
textScoreIndexes: false,
|
|
@@ -56,7 +57,10 @@ export class SqliteDialect extends AbstractSqlDialect {
|
|
|
56
57
|
escapeIdChar = '`';
|
|
57
58
|
autoIncrementSuffix = 'PRIMARY KEY AUTOINCREMENT';
|
|
58
59
|
beginTransactionCommand = 'BEGIN TRANSACTION';
|
|
59
|
-
|
|
60
|
+
/** No level to set: SQLite serializes writers. A read-only transaction defers its lock to its first write. */
|
|
61
|
+
getBeginTransactionStatements({ readOnly } = {}) {
|
|
62
|
+
return [readOnly ? 'BEGIN DEFERRED' : this.beginTransactionCommand];
|
|
63
|
+
}
|
|
60
64
|
booleanLiteral = 'integer';
|
|
61
65
|
/**
|
|
62
66
|
* The clock and today in the same text as a bound `Date`, where `CURRENT_TIMESTAMP` writes whole seconds and
|
package/dist/type/dialect.d.ts
CHANGED
|
@@ -134,6 +134,12 @@ export interface DialectFeatures {
|
|
|
134
134
|
* such a write reads the ids of the rows it names first.
|
|
135
135
|
*/
|
|
136
136
|
readonly correlatedWrites: boolean;
|
|
137
|
+
/**
|
|
138
|
+
* Whether an `UPDATE` and a `DELETE` report the rows they wrote (`RETURNING`), so a write `returning` them
|
|
139
|
+
* in one statement reads them off it: the Postgres and SQLite families. MariaDB returns from a `DELETE`
|
|
140
|
+
* only, and SQL Server's `OUTPUT` fails on a table with a trigger, so both read their rows first.
|
|
141
|
+
*/
|
|
142
|
+
readonly writeReturning: boolean;
|
|
137
143
|
/**
|
|
138
144
|
* What the engine's row locks can do, or `false` where it has none: the SQLite family locks the
|
|
139
145
|
* database and MongoDB has no row lock at all, so both refuse `$lock` rather than ignoring it. One
|
package/dist/type/querier.d.ts
CHANGED
|
@@ -21,6 +21,12 @@ export type TransactionOptions = {
|
|
|
21
21
|
* failed start leaves it on the connection: set it per transaction that needs it.
|
|
22
22
|
*/
|
|
23
23
|
readonly isolationLevel?: IsolationLevel;
|
|
24
|
+
/**
|
|
25
|
+
* A transaction that only reads, so the engine refuses its writes where it has the mode (Postgres,
|
|
26
|
+
* CockroachDB, MySQL, MariaDB, libSQL's client), and the SQLite family takes no write lock for it.
|
|
27
|
+
* SQL Server and MongoDB have no such mode and ignore it.
|
|
28
|
+
*/
|
|
29
|
+
readonly readOnly?: boolean;
|
|
24
30
|
};
|
|
25
31
|
export type DialectName = SqlDialectName | 'mongodb';
|
|
26
32
|
/**
|
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.
|
|
6
|
+
"version": "0.102.0",
|
|
7
7
|
"type": "module",
|
|
8
8
|
"engines": {
|
|
9
9
|
"node": ">=22.18"
|
package/skills/uql-orm/SKILL.md
CHANGED
|
@@ -116,7 +116,7 @@ const users = await pool.findMany(User, {
|
|
|
116
116
|
- A query is plain data, so it can be built dynamically, stored, or sent from a browser to `uql-orm/http`, whose handler serves only the entities its required `include` names.
|
|
117
117
|
- Methods: `findMany`, `findOne`, `findOneById`, `findManyAndCount`, `findManyPage`, `findManyStream`, `count`, `exists`, `aggregate`, `insertOne`, `insertMany`, `updateOneById`, `updateMany`, `saveOne`, `saveMany`, `upsertOne`, `upsertMany`, `deleteOneById`, `deleteMany`. Each takes the entity class first.
|
|
118
118
|
- `upsertOne(Entity, { email: true }, row, update?)`: a conflicting row takes `update`, an update's payload with its operators (`{ uses: { $inc: 1 } }`), instead of `row`; a new one inserts `row`. An empty `{}` leaves a conflicting row as it is: insert if absent. Cascaded relations write on either branch, a found row's replaced, as `updateMany` does. It resolves to the row's id.
|
|
119
|
-
- Every write takes `{ returning: { id: true, createdAt: true } }` as its last argument and then resolves to those rows (an update or delete by id: the row or `undefined`), read back in the same transaction; without it, inserts, saves and upserts resolve to ids, updates and deletes to a count.
|
|
119
|
+
- Every write takes `{ returning: { id: true, createdAt: true } }` as its last argument and then resolves to those rows (an update or delete by id: the row or `undefined`), read back in the same transaction; without it, inserts, saves and upserts resolve to ids, updates and deletes to a count. An update or delete writes exactly the rows it reports: on Postgres, CockroachDB and the SQLite family a plain one is a single statement whose `RETURNING` reports them; elsewhere, or paged, through a relation, versioned, or with hooks or cascades on a delete, it reads them first in a transaction that holds them, so a racing writer waits for the commit (SQLite and MongoDB fail it with a retryable error instead).
|
|
120
120
|
- `updateMany` and `deleteMany` naming no rows - no `$where` holding a value (an empty group holds none), no `$limit` - throw; `{ unfiltered: true }` means the whole table.
|
|
121
121
|
- An update takes `{ stock: { $inc: -1 } }` to add, or `$mul` to multiply, in the statement, a NULL counting as 0, so a guard in `$where` (`stock: { $gte: 1 }`) makes a decrement race-safe. On SQL the step may be a ref or `sql` of the field's type (`{ total: { $inc: newRow.amount } }` in a trigger). JSON fields take `$set`, `$unset`, `$push`, `$pull`.
|
|
122
122
|
- `$lock: true` locks the rows a read returns (`{ $wait: 'skip' | 'nowait' }` says what to do about a row someone else holds) and needs an open transaction; SQLite, libSQL, Turso, D1 and MongoDB have no row lock and refuse it.
|
|
@@ -134,7 +134,7 @@ await pool.transaction(async (querier) => {
|
|
|
134
134
|
});
|
|
135
135
|
```
|
|
136
136
|
|
|
137
|
-
The callback commits when it returns and rolls back when it throws; `beginTransaction` / `commitTransaction` / `rollbackTransaction` are for a transaction that opens in one place and ends in another. Inside the callback, a `pool` call runs on the callback's querier, so it is part of the transaction. A `transaction()` inside another is a savepoint, whose failure undoes its own writes alone (MongoDB, with none, refuses it). A transaction holds its connection: a statement from outside its callback waits for it. `querier.onCommit(fn)` (or a hook's `onCommit`) runs `fn` after the outermost commit, never on a rollback: use it for mails and queued jobs. A querier from `pool.getQuerier()` is yours to release: bind it with `await using`.
|
|
137
|
+
The callback commits when it returns and rolls back when it throws; `beginTransaction` / `commitTransaction` / `rollbackTransaction` are for a transaction that opens in one place and ends in another. Inside the callback, a `pool` call runs on the callback's querier, so it is part of the transaction. A `transaction()` inside another is a savepoint, whose failure undoes its own writes alone (MongoDB, with none, refuses it). A transaction holds its connection: a statement from outside its callback waits for it. `{ readOnly: true }` opens a transaction that only reads: Postgres, CockroachDB, MySQL and MariaDB refuse its writes, and libSQL and Turso skip the write lock they otherwise take at `BEGIN`. `querier.onCommit(fn)` (or a hook's `onCommit`) runs `fn` after the outermost commit, never on a rollback: use it for mails and queued jobs. A querier from `pool.getQuerier()` is yours to release: bind it with `await using`.
|
|
138
138
|
|
|
139
139
|
A `findManyStream` holds its querier until the loop ends, which refuses any other statement meanwhile: inside the loop, run them on another connection; inside a transaction, or on SQLite and PGlite (one shared connection), run them after the loop. That includes an `@AfterLoad` querying through its `querier` on a streamed row. A statement binding more values than the engine takes (100 on D1, 2098 on SQL Server) is refused too: split a long `$in`.
|
|
140
140
|
|