uql-orm 0.107.2 → 0.108.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/README.md +0 -1
- package/dist/browser/uql-browser.min.js +2 -2
- package/dist/browser/uql-browser.min.js.map +5 -5
- package/dist/cockroachdb/cockroachDialect.d.ts +1 -4
- package/dist/cockroachdb/cockroachDialect.js +1 -5
- package/dist/dialect/abstractSqlDialect.d.ts +84 -43
- package/dist/dialect/abstractSqlDialect.js +270 -192
- package/dist/dialect/aliases.d.ts +2 -0
- package/dist/dialect/aliases.js +2 -0
- package/dist/dialect/jsonSql.d.ts +9 -7
- package/dist/dialect/jsonSql.js +16 -10
- package/dist/dialect/mergeSqlDialect.d.ts +5 -7
- package/dist/dialect/mergeSqlDialect.js +20 -19
- package/dist/dialect/mysqlLikeSqlDialect.d.ts +12 -6
- package/dist/dialect/mysqlLikeSqlDialect.js +34 -12
- package/dist/dialect/operators.d.ts +7 -1
- package/dist/dialect/operators.js +37 -2
- package/dist/dialect/pgLikeSqlDialect.d.ts +4 -4
- package/dist/dialect/pgLikeSqlDialect.js +8 -7
- package/dist/entity/index.d.ts +1 -1
- package/dist/entity/index.js +1 -1
- package/dist/entity/metadata/definedFixture/author.d.ts +4 -4
- package/dist/entity/metadata/definedFixture/book.d.ts +5 -5
- package/dist/entity/metadata/definition.d.ts +2 -0
- package/dist/entity/metadata/definition.js +19 -11
- package/dist/index.d.ts +1 -1
- package/dist/index.js +1 -1
- package/dist/mariadb/mariaDialect.d.ts +2 -2
- package/dist/mariadb/mariaDialect.js +3 -2
- package/dist/migrate/codegen/fieldOptionsSource.js +28 -7
- package/dist/migrate/ddl/defaultSql.d.ts +3 -2
- package/dist/migrate/ddl/defaultSql.js +8 -12
- package/dist/migrate/ddl/mysqlTableDdl.js +1 -1
- package/dist/migrate/ddl/tableDdl.d.ts +1 -1
- package/dist/migrate/drift/driftDetector.js +10 -3
- package/dist/migrate/introspection/abstractSqlSchemaIntrospector.d.ts +2 -2
- package/dist/migrate/introspection/mssqlIntrospector.d.ts +2 -2
- package/dist/migrate/introspection/mysqlIntrospector.d.ts +2 -2
- package/dist/migrate/introspection/postgresIntrospector.d.ts +2 -2
- package/dist/migrate/introspection/sqliteIntrospector.d.ts +2 -2
- package/dist/migrate/migrator.js +2 -1
- package/dist/migrate/schemaChange.d.ts +0 -2
- package/dist/migrate/schemaChange.js +1 -4
- package/dist/migrate/schemaGenerator.d.ts +2 -2
- package/dist/migrate/triggerSql.js +11 -15
- package/dist/mongodb/mongoDialect.d.ts +6 -1
- package/dist/mongodb/mongoDialect.js +90 -46
- package/dist/mongodb/mongoSchemaGenerator.js +2 -2
- package/dist/mongodb/mongodbQuerier.d.ts +7 -9
- package/dist/mongodb/mongodbQuerier.js +54 -47
- package/dist/mssql/mssqlDialect.d.ts +9 -9
- package/dist/mssql/mssqlDialect.js +51 -28
- package/dist/mssql/mssqlWireTypes.d.ts +1 -4
- package/dist/mssql/mssqlWireTypes.js +19 -10
- package/dist/querier/abstractQuerier.d.ts +53 -29
- package/dist/querier/abstractQuerier.js +154 -102
- package/dist/querier/abstractSqlQuerier.d.ts +41 -10
- package/dist/querier/abstractSqlQuerier.js +145 -79
- package/dist/schema/declaredColumn.js +2 -2
- package/dist/schema/schemaASTDiffer.d.ts +3 -3
- package/dist/schema/sqlExpression.d.ts +7 -5
- package/dist/schema/sqlExpression.js +20 -16
- package/dist/schema/types.d.ts +8 -2
- package/dist/sqlite/sqliteDialect.js +1 -2
- package/dist/type/definedEntity.d.ts +5 -5
- package/dist/type/dialect.d.ts +26 -15
- package/dist/type/entity.d.ts +14 -8
- package/dist/type/query.d.ts +7 -2
- package/dist/type/queryAggregate.d.ts +4 -4
- package/dist/type/querySql.d.ts +4 -1
- package/dist/type/querySql.js +5 -1
- package/dist/type/queryWhere.d.ts +16 -11
- package/dist/type/universalQuerier.d.ts +7 -7
- package/dist/util/ddlExpression.util.d.ts +5 -0
- package/dist/util/ddlExpression.util.js +9 -2
- package/dist/util/dialect.util.d.ts +14 -6
- package/dist/util/dialect.util.js +17 -13
- package/dist/util/field.util.d.ts +12 -0
- package/dist/util/field.util.js +17 -1
- package/dist/util/fieldOption.util.js +5 -1
- package/dist/util/object.util.d.ts +4 -0
- package/dist/util/object.util.js +13 -0
- package/dist/util/query.util.d.ts +5 -3
- package/dist/util/query.util.js +7 -2
- package/dist/util/sql.d.ts +25 -7
- package/dist/util/sql.js +58 -18
- package/dist/util/triggerWrite.d.ts +7 -4
- package/dist/util/triggerWrite.js +5 -4
- package/package.json +1 -1
- package/skills/uql-orm/SKILL.md +118 -118
package/dist/util/sql.js
CHANGED
|
@@ -88,15 +88,41 @@ export const SQL_VALUES = {
|
|
|
88
88
|
};
|
|
89
89
|
/**
|
|
90
90
|
* The fields of `entity` as {@link ColumnRef}s, each rendering inside `sql` as its column: named the way
|
|
91
|
-
* the dialect names it, so the naming strategy and `.name()` apply, and qualified by the
|
|
92
|
-
* in scope. Metadata is read when a ref renders, so the map serves before the fields are registered.
|
|
91
|
+
* the dialect names it, so the naming strategy and `.name()` apply, and qualified by `alias`, or else by the
|
|
92
|
+
* alias in scope. Metadata is read when a ref renders, so the map serves before the fields are registered.
|
|
93
93
|
*/
|
|
94
|
-
export function refs(entity) {
|
|
95
|
-
|
|
94
|
+
export function refs(entity, alias) {
|
|
95
|
+
const qualifier = alias === undefined ? undefined : { alias };
|
|
96
|
+
return refMap((key) => columnRef(entity, key, qualifier), () => tableSql(entity, alias));
|
|
96
97
|
}
|
|
97
|
-
/**
|
|
98
|
-
|
|
99
|
-
|
|
98
|
+
/**
|
|
99
|
+
* The table `source` names, an entity or the refs read off one under their alias, `"order" "o"`, for raw SQL
|
|
100
|
+
* reading another table than its statement's: `sql`SELECT ${o.state} FROM ${tableOf(o)}``, `o = refs(Order, 'o')`.
|
|
101
|
+
*/
|
|
102
|
+
export function tableOf(source) {
|
|
103
|
+
if (typeof source === 'function') {
|
|
104
|
+
return tableSql(source);
|
|
105
|
+
}
|
|
106
|
+
const table = Reflect.get(source, TABLE);
|
|
107
|
+
if (!(table instanceof QuerySql)) {
|
|
108
|
+
throw new UqlUsageError(`tableOf takes an entity or the refs() read off one, not a definition's refs`);
|
|
109
|
+
}
|
|
110
|
+
return table;
|
|
111
|
+
}
|
|
112
|
+
/** `entity`'s table as its statements name it, under `alias` where one is given. */
|
|
113
|
+
function tableSql(entity, alias) {
|
|
114
|
+
return sql(({ ctx, dialect }) => {
|
|
115
|
+
ctx.append(dialect.tableRef(getMeta(entity), alias).ref);
|
|
116
|
+
});
|
|
117
|
+
}
|
|
118
|
+
/** Where a refs map keeps the table it reads, for {@link tableOf}: a symbol, so no field can shadow it. */
|
|
119
|
+
const TABLE = Symbol('table');
|
|
120
|
+
/**
|
|
121
|
+
* A map answering each string key with `ref(key)`, typed as the caller's map, whose keys say what it holds, and
|
|
122
|
+
* {@link TABLE} with what renders the table where it reads one. No other symbol, so nothing probing it sees more.
|
|
123
|
+
*/
|
|
124
|
+
function refMap(ref, table) {
|
|
125
|
+
return new Proxy({}, { get: (_, key) => (key === TABLE ? table?.() : typeof key === 'string' ? ref(key) : undefined) });
|
|
100
126
|
}
|
|
101
127
|
/**
|
|
102
128
|
* The refs a definition's callbacks read: a check's, a computed field's, a predicate's. A member decorator
|
|
@@ -162,33 +188,43 @@ function relationAggregate(spec) {
|
|
|
162
188
|
* {@link refs} are, so each names its own column wherever it renders, a write to another table included.
|
|
163
189
|
* Columns only: a relation's aggregate is a subquery, and a trigger fires on one row, not over a table.
|
|
164
190
|
*/
|
|
165
|
-
export function rowRefs(entity,
|
|
166
|
-
return
|
|
191
|
+
export function rowRefs(entity, row) {
|
|
192
|
+
return refMap((key) => columnRef(entity, key, { row }));
|
|
167
193
|
}
|
|
168
194
|
/**
|
|
169
|
-
* One field as SQL, against its own entity or, read off a definition, the entity rendering it
|
|
170
|
-
*
|
|
195
|
+
* One field as SQL, against its own entity or, read off a definition, the entity rendering it, read off the
|
|
196
|
+
* alias in scope unless a `qualifier` names another.
|
|
171
197
|
*/
|
|
172
198
|
export function columnRef(entity, key, qualifier) {
|
|
173
199
|
return new ColumnRef(key, (opts) => {
|
|
174
|
-
const owner = entity
|
|
175
|
-
|
|
176
|
-
|
|
200
|
+
const owner = refOwner(entity, key, opts);
|
|
201
|
+
const scope = opts.entity;
|
|
202
|
+
if (!qualifier && scope && scope !== owner && !(scope.prototype instanceof owner)) {
|
|
203
|
+
throw new UqlUsageError(`a ref of '${owner.name}' cannot render against '${scope.name}', the table in scope: ` +
|
|
204
|
+
`read it off its own alias, refs(${owner.name}, 'alias')`);
|
|
177
205
|
}
|
|
178
206
|
renderColumn(getMeta(owner), key, { ...opts, entity: owner }, qualifier);
|
|
179
|
-
});
|
|
207
|
+
}, entity);
|
|
208
|
+
}
|
|
209
|
+
/** The entity a ref of `key` reads its column of: its own, or, read off a definition, the entity in scope. */
|
|
210
|
+
export function refOwner(entity, key, scope) {
|
|
211
|
+
const owner = entity ?? scope.entity;
|
|
212
|
+
if (!owner) {
|
|
213
|
+
throw new UqlUsageError(`'${key}' was read off a definition's refs, so it renders only inside its entity's SQL`);
|
|
214
|
+
}
|
|
215
|
+
return owner;
|
|
180
216
|
}
|
|
181
217
|
/**
|
|
182
218
|
* A field's column, or the expression an inlined computed one stands for, as a `$where` on it reads it.
|
|
183
|
-
* Under a `qualifier` the column is read off that row rather than off the alias in scope
|
|
219
|
+
* Under a `qualifier` the column is read off that row or alias rather than off the alias in scope. A row is
|
|
184
220
|
* written verbatim: it is a record the engine declares, not an identifier to quote and case-fold.
|
|
185
221
|
*/
|
|
186
222
|
function renderColumn(meta, key, opts, qualifier) {
|
|
187
|
-
const scope = qualifier
|
|
223
|
+
const scope = qualifier ? { ...opts, ...qualifiedBy(qualifier, opts) } : opts;
|
|
188
224
|
const field = meta.fields[key];
|
|
189
225
|
if (field && isInlinedExpression(field)) {
|
|
190
226
|
// A relation aggregate is a subquery correlated to a table in scope, and a trigger's row is not one.
|
|
191
|
-
if (qualifier
|
|
227
|
+
if (qualifier?.row && aggregateOf(field)) {
|
|
192
228
|
throw new UqlUsageError(`'${entityName(meta)}.${key}' reads a relation, which a trigger's row cannot: it fires on one row, ` +
|
|
193
229
|
'with no table in scope to correlate a subquery to. Name the columns it is derived from instead.');
|
|
194
230
|
}
|
|
@@ -197,6 +233,10 @@ function renderColumn(meta, key, opts, qualifier) {
|
|
|
197
233
|
}
|
|
198
234
|
scope.ctx.append(scope.escapedPrefix + scope.dialect.escapeId(scope.dialect.columnOf(meta, key), true));
|
|
199
235
|
}
|
|
236
|
+
/** The prefix a `qualifier` reads columns off, as the render options spell one. */
|
|
237
|
+
function qualifiedBy({ row, alias }, { dialect }) {
|
|
238
|
+
return row ? { escapedPrefix: `${row}.` } : { prefix: alias, escapedPrefix: dialect.escapeId(alias, true, true) };
|
|
239
|
+
}
|
|
200
240
|
/**
|
|
201
241
|
* An inlined computed field's expression as every clause splices it: grouped, so a comparison inside cannot
|
|
202
242
|
* chain with one around it (`a <= b = ?`). A relation aggregate is a subquery, grouped already.
|
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
import { type EntityPredicate, type
|
|
1
|
+
import { type EntityPredicate, type QueryUpsert, type QuerySql, type TriggerWrite, type AbstractType, type UpdatePayload, type WritableKey, type WriteRow } from '../type/index.js';
|
|
2
2
|
/**
|
|
3
3
|
* A row inserted by a trigger's body, into any table: `insertInto(PostAudit, { postId: newRow.id })`.
|
|
4
4
|
* Each value is a literal or SQL, a row's ref most often, and every engine renders it, SQL Server's
|
|
@@ -6,10 +6,13 @@ import { type EntityPredicate, type QueryConflictPaths, type QuerySql, type Trig
|
|
|
6
6
|
*/
|
|
7
7
|
export declare function insertInto<E extends object>(entity: AbstractType<E>, row: WriteRow<E>): QuerySql;
|
|
8
8
|
/**
|
|
9
|
-
* A row inserted by a trigger's body, or what
|
|
10
|
-
* does: `upsertInto(Tally, { postId: true }, { postId: newRow.id, count: 1 },
|
|
9
|
+
* A row inserted by a trigger's body, or what `q.$conflict` finds taking `update` instead where it matches
|
|
10
|
+
* `q.$where`, as `upsertOne` does: `upsertInto(Tally, { $conflict: { postId: true } }, { postId: newRow.id, count: 1 },
|
|
11
|
+
* { count: { $inc: 1 } })`.
|
|
11
12
|
*/
|
|
12
|
-
export declare function upsertInto<E extends object>(entity: AbstractType<E>,
|
|
13
|
+
export declare function upsertInto<E extends object>(entity: AbstractType<E>, q: QueryUpsert<E> & {
|
|
14
|
+
readonly $where?: EntityPredicate<E>;
|
|
15
|
+
}, row: WriteRow<E>, update?: UpdatePayload<E, QuerySql, WritableKey<E>, never>): QuerySql;
|
|
13
16
|
/** The rows `q.$where` names updated by a trigger's body: `updateTable(Post, { $where: { id: newRow.postId } }, set)`. */
|
|
14
17
|
export declare function updateTable<E extends object>(entity: AbstractType<E>, q: {
|
|
15
18
|
readonly $where: EntityPredicate<E>;
|
|
@@ -8,11 +8,12 @@ export function insertInto(entity, row) {
|
|
|
8
8
|
return written({ kind: 'insert', entity, row });
|
|
9
9
|
}
|
|
10
10
|
/**
|
|
11
|
-
* A row inserted by a trigger's body, or what
|
|
12
|
-
* does: `upsertInto(Tally, { postId: true }, { postId: newRow.id, count: 1 },
|
|
11
|
+
* A row inserted by a trigger's body, or what `q.$conflict` finds taking `update` instead where it matches
|
|
12
|
+
* `q.$where`, as `upsertOne` does: `upsertInto(Tally, { $conflict: { postId: true } }, { postId: newRow.id, count: 1 },
|
|
13
|
+
* { count: { $inc: 1 } })`.
|
|
13
14
|
*/
|
|
14
|
-
export function upsertInto(entity,
|
|
15
|
-
return written({ kind: 'upsert', entity,
|
|
15
|
+
export function upsertInto(entity, q, row, update) {
|
|
16
|
+
return written({ kind: 'upsert', entity, q, row, update });
|
|
16
17
|
}
|
|
17
18
|
/** The rows `q.$where` names updated by a trigger's body: `updateTable(Post, { $where: { id: newRow.postId } }, set)`. */
|
|
18
19
|
export function updateTable(entity, q, set) {
|
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.108.0",
|
|
7
7
|
"type": "module",
|
|
8
8
|
"engines": {
|
|
9
9
|
"node": ">=22.18"
|
package/skills/uql-orm/SKILL.md
CHANGED
|
@@ -3,8 +3,8 @@ name: uql-orm
|
|
|
3
3
|
description: >
|
|
4
4
|
Write code with UQL (the uql-orm package), the TypeScript ORM whose queries are plain JSON objects,
|
|
5
5
|
on PostgreSQL, MySQL, MariaDB, SQLite, CockroachDB, SQL Server, MongoDB, Turso, Neon, D1 and PGlite.
|
|
6
|
-
Use when a project imports uql-orm, or when defining entities or
|
|
7
|
-
writing transactions, raw SQL or migrations with it. UQL is not Prisma, Drizzle, TypeORM or MikroORM:
|
|
6
|
+
Use when a project imports uql-orm, or when defining entities, triggers or filters (soft delete, multi-tenancy),
|
|
7
|
+
querying, populating relations, writing transactions, raw SQL or migrations with it. UQL is not Prisma, Drizzle, TypeORM or MikroORM:
|
|
8
8
|
their APIs do not carry over.
|
|
9
9
|
---
|
|
10
10
|
|
|
@@ -22,9 +22,7 @@ npm install uql-orm pg # or mysql2, mariadb, better-sqlite3, mongodb, @libsql/
|
|
|
22
22
|
|
|
23
23
|
ESM only. Needs Node 22.18+, Bun or an edge runtime, and TypeScript 5.7+.
|
|
24
24
|
|
|
25
|
-
Decorators are TC39 standard. Never enable `experimentalDecorators` or `emitDecoratorMetadata`, and never import `reflect-metadata`.
|
|
26
|
-
|
|
27
|
-
Node runs no decorators natively yet, so add `tsx` there (`npm i -D tsx`); `uql-migrate` loads `uql.config.ts` through it. A bundler that minifies class names needs `@Entity({ name: 'todo' })`, since the table name defaults to the class name.
|
|
25
|
+
Decorators are TC39 standard. Never enable `experimentalDecorators` or `emitDecoratorMetadata`, and never import `reflect-metadata`. Node runs no decorators natively yet, so add `tsx` there (`npm i -D tsx`); `uql-migrate` loads `uql.config.ts` through it. A bundler that minifies class names needs `@Entity({ name: 'todo' })`, since the table name defaults to the class name.
|
|
28
26
|
|
|
29
27
|
```ts
|
|
30
28
|
// uql.config.ts
|
|
@@ -39,8 +37,19 @@ export default { pool, entities: [User, Post] } satisfies Config;
|
|
|
39
37
|
|
|
40
38
|
Driver entry points: `uql-orm/postgres`, `mysql`, `mariadb`, `sqlite`, `mongodb`, `libsql`, `turso`, `neon`, `d1`, `pglite`, `bun-sql`, `mssql`, `cockroachdb`. Build the pool once per process and import it.
|
|
41
39
|
|
|
40
|
+
The pool's first argument is the driver's own config; set an acquire timeout there (`connectionTimeoutMillis` on the `pg` family), which otherwise waits forever. The second holds uql's options: `namingStrategy: new SnakeCaseNamingStrategy()` maps `createdAt` to `created_at` in queries and migrations alike (never name each column by hand), `logger: true` or a level list, `slowQuery: 200` (ms), and a default `schema`. Call `await pool.end()` on shutdown, except in serverless functions: https://uql-orm.dev/pool.md
|
|
41
|
+
|
|
42
42
|
## Entities
|
|
43
43
|
|
|
44
|
+
Two forms, mixable per entity, producing the same queries and types:
|
|
45
|
+
|
|
46
|
+
- **Decorators**: a named class type, and column-level foreign keys (`f.references`), so entities may reference each other in any order. Slightly stricter: a property may be typed narrower than its column (a branded id), and `mappedBy` must name a relation or foreign key at compile time. Each field is written twice (builder and property), and it needs the TC39 decorator transform.
|
|
47
|
+
- **`defineEntity`**: the row type is derived, nothing written twice; no transform, so it fits projects on legacy decorators (NestJS, Angular), and it can be built at run time. Cheaper to type-check. Relations come last, and the row type needs a `type X = InstanceType<typeof X>` alias. A shared set of fields spreads into `fields`.
|
|
48
|
+
|
|
49
|
+
`uql-codemod` cannot convert one form into the other. Details: https://uql-orm.dev/entities/define-entity.md
|
|
50
|
+
|
|
51
|
+
### Decorators
|
|
52
|
+
|
|
44
53
|
```ts
|
|
45
54
|
import { Entity, f, Field, ManyToOne, OneToMany } from 'uql-orm';
|
|
46
55
|
|
|
@@ -77,65 +86,26 @@ export class Post {
|
|
|
77
86
|
}
|
|
78
87
|
```
|
|
79
88
|
|
|
80
|
-
- A column is a builder: `f.string()`, `f.text()`, `f.uuid()`, `f.number()`, `f.bigint()`, `f.decimal(
|
|
81
|
-
- A column is NOT NULL unless `.nullable()
|
|
82
|
-
-
|
|
83
|
-
-
|
|
84
|
-
- A
|
|
85
|
-
-
|
|
86
|
-
- A class inherits its base's fields, relations, hooks, filters, indexes, checks and triggers. A base of fields alone needs no `@Entity()`; one declaring
|
|
87
|
-
- `
|
|
88
|
-
-
|
|
89
|
-
-
|
|
90
|
-
-
|
|
91
|
-
-
|
|
92
|
-
-
|
|
93
|
-
- Indexes, checks, filters and triggers are `@Entity` options, each entry made by the helper the callback is handed. Partial index: `@Entity({ indexes: (post, index) => [index([post.authorId], { where: { archived: { $ne: true } } })] })`; a string second argument is the index's name. Write the predicate as a query, not `sql`.
|
|
94
|
-
- JSON path index: read the path off the column's ref, `index([user.settings.theme])` for text, `index([{ column: user.settings.rating, type: Number }])` for any other value, `type: [String]` for an array's elements. MySQL keys a text path or element as `CHAR(n)`, `{ column: user.tags, type: [String], charLength: 64 }`, and a `TEXT` column by a prefix, `{ column: post.body, prefixLength: 64 }`.
|
|
95
|
-
- Triggers run in the database: `@Entity({ triggers: (post, trigger) => [trigger({ on: 'afterUpdate', of: [post.status], run })] })`, where `run` returns a body built from `insertInto`, `upsertInto`, `updateTable`, `deleteFrom` and `refuse(message)`. A trigger's writes skip uql's fills and entity filters. MongoDB has no triggers: https://uql-orm.dev/entities/triggers.md
|
|
96
|
-
|
|
97
|
-
### Choosing a form
|
|
98
|
-
|
|
99
|
-
Both forms are supported, mix them per entity, and produce the same queries and types.
|
|
100
|
-
|
|
101
|
-
- Decorators
|
|
102
|
-
- Pros
|
|
103
|
-
- A named class type shows on hover.
|
|
104
|
-
- A column can be a foreign key (`@Field(f.references(() => User))`), so entities may reference each other in any order.
|
|
105
|
-
- No `.relations()` ordering rules.
|
|
106
|
-
- Shared structure through base classes (`StampedEntity`, `WorkspaceScoped`) that carry fields and relations.
|
|
107
|
-
- The familiar form from TypeORM and MikroORM.
|
|
108
|
-
- Cons
|
|
109
|
-
- Each field is written twice, as a builder and as a TypeScript property (`@Field(f.string()) name!: string`).
|
|
110
|
-
- The TC39 decorator transform is required: Node needs `tsx`, and some bundlers need a Babel step.
|
|
111
|
-
- Without `@Entity({ name })`, the table name comes from the class name, which a minifier can change.
|
|
112
|
-
- Higher type-check cost on the benchmark model (9,297 vs 5,110 instantiations).
|
|
113
|
-
- Cannot be declared at run time.
|
|
114
|
-
- `uql-codemod` cannot convert it into `defineEntity`.
|
|
115
|
-
- `defineEntity`
|
|
116
|
-
- Pros
|
|
117
|
-
- The row type is derived from the builders, with nothing written twice.
|
|
118
|
-
- Shorter: 19 to 30% fewer lines in the two apps this was measured on.
|
|
119
|
-
- Lower type-check cost on the benchmark model.
|
|
120
|
-
- Shared relation helpers, and derived fields declared with their relations.
|
|
121
|
-
- Plain data: no transform, and it can be built at run time (a CMS content type).
|
|
122
|
-
- The form for projects that cannot enable TC39 decorators, such as legacy-decorator NestJS and Angular.
|
|
123
|
-
- Cons
|
|
124
|
-
- Relations are thunks declared after the columns, and `.relations()` comes last (only `.filters()` may follow it).
|
|
125
|
-
- No column-level foreign keys: a shared key is a relation helper, and an eager read across two entities can create an inference cycle (TS7022).
|
|
126
|
-
- Naming its row type as `X`, as a class does, takes a `type X = InstanceType<typeof X>` alias beside it.
|
|
127
|
-
- No class to annotate or extend: inheritance uses `extends` naming the base.
|
|
128
|
-
- Newer and less used.
|
|
89
|
+
- A column is a builder: `f.string()`, `f.text()`, `f.uuid()`, `f.number()`, `f.bigint()`, `f.decimal(precision?, scale?)`, `f.boolean()`, `f.date()`, `f.json(schema?)`, `f.jsonb(schema?)`, `f.vector(dimensions)`, `f.enum(values)`, `f.version()`, `f.column(type)` for any other type, and `f.references(() => Target)` for a foreign key typed as the target's key. Only the methods a column's type takes exist: `.length()` is a string's, `.precision()` a number's or a date's.
|
|
90
|
+
- A column is NOT NULL unless `.nullable()`. Declare a NOT NULL property `!` (`email!: string`), and `?` what an insert may omit: nullable columns (`title?: string | null`), `.eager(false)` and computed fields, relations, and the single-column key and version uql fills. A NOT NULL field a default fills (`.default()`, `.onInsert()`) stays `!` and is listed in the class's `[filledKey]?: 'stock' | 'createdAt'`: inserts may omit it, reads always have it.
|
|
91
|
+
- `.default()` takes a value of the field's type, or SQL the database evaluates per row: `currentTimestamp`, `currentDate`, `currentTime`, `uuid` (not SQLite), `uuidv7` (Postgres 18+, MariaDB 11.7+), or ``sql`...` ``. A plain string is always text, `'CURRENT_TIMESTAMP'` included. A JSON column defaults to a value, `.default({})` or `.default(0)`, never its JSON text (`'{}'`, `'0'` are refused); any other string there is a JSON string.
|
|
92
|
+
- `Date` is an instant, stored in UTC to the millisecond on every engine. `f.decimal()` is exact text (`price?: string | null`); `f.number().precision(10).scale(2)` opts into a rounding JS number.
|
|
93
|
+
- A JSON column's property is `Json<T>`: `settings?: Json<{ theme?: string }> | null`. A plain object type reads as a relation, which `$where`, `$sort` and the update operators refuse.
|
|
94
|
+
- `mappedBy` and `references` may be left out where only one member fits. `@ManyToMany({ entity: () => Tag, through: () => PostTag })` names the junction entity. `cascade: true` writes related rows with their row, in one transaction on SQL and, on MongoDB, inside one the caller opens; an update replaces a to-many's rows.
|
|
95
|
+
- A class inherits its base's fields, relations, hooks, filters, indexes, checks and triggers. A base of fields alone needs no `@Entity()`; one declaring entity options but no table is `@Entity({ abstract: true, ... }) abstract class`, which cannot be queried.
|
|
96
|
+
- Optimistic lock: `@Field(f.version())` with `[versionKey]?: 'version'` on the class. An update, and an upsert or save of a row that exists, must carry the version it read; a stale one throws `UqlOptimisticLockError`.
|
|
97
|
+
- Computed fields are `readonly`: ``@Computed((u) => f.string().as(sql`${u.first} || ' ' || ${u.last}`))``, `.stored()` for a generated column, or a relation aggregate, `@Computed((user) => user.posts.count())`.
|
|
98
|
+
- Indexes, checks, filters and triggers are `@Entity` options, each entry made by the helper the callback is handed. A partial index's predicate is a query: `indexes: (post, index) => [index([post.authorId], { where: { archived: { $ne: true } } })]`. A JSON path is indexed off the column's ref, `index([user.settings.theme])`: https://uql-orm.dev/entities/indexes.md
|
|
99
|
+
- Triggers run in the database: `triggers: (post, trigger) => [trigger({ on: 'afterUpdate', of: [post.status], run })]`, where `run` returns a body built from `insertInto`, `upsertInto`, `updateTable`, `deleteFrom` and `refuse(message)`. They skip entity filters and run no JavaScript: an insert fills an `.onInsert()` value or SQL, but an `insertInto` names every required column a callback fills (`.onInsert(() => crypto.randomUUID())`) where no database default does. MongoDB has none: https://uql-orm.dev/entities/triggers.md
|
|
100
|
+
- Hooks are methods with `this` bound to the payload: `@BeforeInsert()`, `@AfterInsert()`, and the same pairs for update, upsert and delete, plus `@AfterLoad()`. Changes to `this` in a before-hook are written. `upsert*` runs only the upsert pair, and `save*` the upsert pair for a row carrying its key. Each receives `{ querier, onCommit }`: send mail from `onCommit`, never straight from an after-hook.
|
|
101
|
+
- **MongoDB:** a `f.number()` key left to the database is refused, since MongoDB only generates ObjectIds. Declare it a string, or give it an `.onInsert()` generator.
|
|
129
102
|
|
|
130
103
|
### defineEntity
|
|
131
104
|
|
|
132
|
-
The same entities declared as data, the row type derived:
|
|
133
|
-
|
|
134
105
|
```ts
|
|
135
106
|
import { defineEntity, f, sql } from 'uql-orm';
|
|
136
107
|
import { z } from 'zod';
|
|
137
108
|
|
|
138
|
-
// Any Standard Schema types the payload: a Zod schema here.
|
|
139
109
|
const Settings = z.object({ theme: z.string(), bio: z.string().optional() });
|
|
140
110
|
|
|
141
111
|
export const Author = defineEntity({
|
|
@@ -147,16 +117,7 @@ export const Author = defineEntity({
|
|
|
147
117
|
},
|
|
148
118
|
}).relations(
|
|
149
119
|
(rel) => ({ books: () => rel.oneToMany(Book, { mappedBy: (book) => book.author }) }),
|
|
150
|
-
(author) => ({
|
|
151
|
-
bookCount: () => author.books.count(),
|
|
152
|
-
topStock: () => author.books.max((book) => book.stock),
|
|
153
|
-
// A derived field may also combine its own columns with an aggregate in one expression.
|
|
154
|
-
stockGap: () =>
|
|
155
|
-
f
|
|
156
|
-
.number()
|
|
157
|
-
.nullable()
|
|
158
|
-
.as(sql`${author.books.max((book) => book.stock)} - ${author.id}`),
|
|
159
|
-
}),
|
|
120
|
+
(author) => ({ bookCount: () => author.books.count() }),
|
|
160
121
|
);
|
|
161
122
|
export type Author = InstanceType<typeof Author>;
|
|
162
123
|
|
|
@@ -167,25 +128,54 @@ export const Book = defineEntity({
|
|
|
167
128
|
title: f.string(),
|
|
168
129
|
stock: f.number().default(0),
|
|
169
130
|
authorId: f.number(),
|
|
170
|
-
editorId: f.number().nullable(),
|
|
171
131
|
},
|
|
172
132
|
})
|
|
173
133
|
.computed((book) => ({ shout: f.string().as(sql`upper(${book.title})`) }))
|
|
174
134
|
.indexes((book, index) => [index([book.title])])
|
|
175
|
-
.hooks({ beforeInsert: [(book) => void (book.stock ??= 0)] })
|
|
176
135
|
.relations((rel) => ({
|
|
177
136
|
author: () => rel.manyToOne(Author, { references: (book) => book.authorId }),
|
|
178
|
-
editor: () => rel.manyToOne(Author, { references: (book) => book.editorId, onDelete: 'SET NULL' }),
|
|
179
137
|
}));
|
|
180
138
|
```
|
|
181
139
|
|
|
182
|
-
-
|
|
183
|
-
-
|
|
184
|
-
-
|
|
185
|
-
-
|
|
186
|
-
- A hook is a function of the row and `{ querier, onCommit }`.
|
|
187
|
-
|
|
188
|
-
|
|
140
|
+
- Columns are the same builders. No `!`, `?` or brands to write: a `.nullable()` column reads `| null`, a default makes it optional on insert, `f.enum()` gives the literal union.
|
|
141
|
+
- `defineEntity` takes `name` (the table derives from it), `table`, `schema`, `extends`, `abstract` and `fields`. Every other option is a section chained after it, each called at most once: `computed`, `indexes`, `checks`, `triggers`, `filters`, `hooks`, then `relations` last; only a `filters` reading through relations follows it.
|
|
142
|
+
- A relation is a thunk, so entities pointing at each other can sit in any order and file. A foreign key is a plain field that a `manyToOne` names as `references`, checked against the target's key type. `relations`' second callback declares aggregate fields: aggregates over a to-many, or expressions mixing them with columns.
|
|
143
|
+
- A JSON column's payload is any Standard Schema (Zod, Valibot, ArkType), typed by its output. uql never runs it, so a write is not validated.
|
|
144
|
+
- A hook is a function of the row and `{ querier, onCommit }`. Behaviour is a plain function of the row (`label(author: Author)`): a row reads back as a plain object, so a method would never be there.
|
|
145
|
+
|
|
146
|
+
### Filters, soft delete and tenants
|
|
147
|
+
|
|
148
|
+
A filter is a named `$where` fragment applied to every read, update and delete of its entity, so never repeat it in a query.
|
|
149
|
+
|
|
150
|
+
```ts
|
|
151
|
+
import { Entity, f, Field, withContext } from 'uql-orm';
|
|
152
|
+
|
|
153
|
+
declare module 'uql-orm' {
|
|
154
|
+
interface UqlContext {
|
|
155
|
+
tenantId?: number;
|
|
156
|
+
}
|
|
157
|
+
}
|
|
158
|
+
|
|
159
|
+
@Entity({
|
|
160
|
+
filters: {
|
|
161
|
+
active: { where: { status: 'active' }, default: false },
|
|
162
|
+
tenant: { where: (ctx) => (ctx?.tenantId != null ? { companyId: ctx.tenantId } : undefined), security: true },
|
|
163
|
+
},
|
|
164
|
+
})
|
|
165
|
+
export class Invoice {
|
|
166
|
+
@Field(f.number().id()) id?: number;
|
|
167
|
+
@Field(f.number()) companyId!: number;
|
|
168
|
+
@Field(f.string().nullable()) status?: string | null;
|
|
169
|
+
@Field(f.date().nullable().softDelete()) deletedAt?: Date | null;
|
|
170
|
+
}
|
|
171
|
+
|
|
172
|
+
await withContext({ tenantId: 42 }, () => pool.findMany(Invoice, {}));
|
|
173
|
+
```
|
|
174
|
+
|
|
175
|
+
- A filter is on unless `default: false`. A `$where` naming its field wins over it. Per call, the options argument takes `{ filters: false }`, `{ filters: { softDelete: false } }` or `{ filters: { active: true } }`.
|
|
176
|
+
- `.softDelete()` on one field turns a delete into a stamp (`new Date()`, or the value or callback given), and registers a `softDelete` filter hiding stamped rows. `withDeleted()` as the options reads both; `restoreOneById` and `restoreMany` undo it; `{ hardDelete: true }` removes rows for good. A restore does not cascade.
|
|
177
|
+
- A `where` may be a function of the context `withContext(ctx, fn)` sets, which follows `await`, `Promise.all` and transactions but not emitters, timers or queues: wrap those callbacks with `captureContext()`. Its keys are typed by augmenting `UqlContext`, as above.
|
|
178
|
+
- `security: true` makes a filter always apply, ignore bypasses, AND-merge with any `$where`, and throw `UqlSecurityError` when `where` returns `undefined`. It scopes writes too, so new rows need no tenant set by hand. For a trusted cross-tenant job, give `where` a branch returning `{}` (`ctx?.system ? {} : ...`) and run it under `withContext({ system: true }, fn)`: https://uql-orm.dev/multi-tenancy.md
|
|
189
179
|
|
|
190
180
|
## Queries
|
|
191
181
|
|
|
@@ -203,37 +193,47 @@ const users = await pool.findMany(User, {
|
|
|
203
193
|
});
|
|
204
194
|
```
|
|
205
195
|
|
|
206
|
-
- Query keys: `$select`, `$where`, `$populate`, `$count`, `$distinct`, `$sort`, `$skip`, `$limit`. `$count: { posts: true }` counts a to-many under `_count` without loading it. `$select: { password: false }` reads every field but `password`.
|
|
207
196
|
- 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, or the query's `$entity`. Signatures: https://uql-orm.dev/querying/methods.md
|
|
208
|
-
-
|
|
209
|
-
-
|
|
210
|
-
- `$
|
|
211
|
-
- `$
|
|
197
|
+
- Query keys: `$select`, `$where`, `$populate`, `$count`, `$distinct`, `$sort`, `$skip`, `$limit`, `$lock`. `$select: { password: false }` reads every field but `password`. `$count: { posts: true }` counts a to-many under `_count` without loading it.
|
|
198
|
+
- Results are narrowed to what the query selected and populated, at every depth. Reading an unselected field is a compile error. Name a shape with `QueryFindResult<User, 'id' | 'email'>`, or `QueryFindResult<User, typeof query>` for a query declared `as const satisfies Query<User>`. A function forwarding a query keeps the narrowing typed `<E extends object, const Q extends Query<E>>(entity: Type<E>, q: Captured<Query<E>, Q>): Promise<QueryFindResult<E, Q>[]>`.
|
|
199
|
+
- `$populate` loads relations in the same statement. Nothing is lazy: an unpopulated relation is absent. A populated to-many is always a list. A to-one is optional unless `$required: true`, which keeps only the parents that have one.
|
|
200
|
+
- `$sort` takes `'asc'`/`1`, `'desc'`/`-1`, or `'ascNullsLast'`, `'ascNullsFirst'`, `'descNullsFirst'`, `'descNullsLast'`, which behave the same on every engine.
|
|
201
|
+
- `findManyPage(User, { $sort: { createdAt: -1, id: 1 }, $limit: 20, $after })` pages by cursor, so page 1,000 costs what page 1 does, and returns `{ items, startCursor, endCursor, hasNextPage, hasPrevPage }`. `$sort` must end in the key or a unique NOT NULL field; no `$skip`.
|
|
202
|
+
- `$lock: true` locks the rows a read returns, inside an open transaction; `{ $wait: 'skip' | 'nowait' }` says what to do about a row someone else holds. The SQLite family and MongoDB refuse it.
|
|
203
|
+
|
|
204
|
+
### `$where`
|
|
205
|
+
|
|
206
|
+
- `$where` takes a value for equality, a list as an implicit `$in`, or an operator map: `$eq`, `$ne`, `$lt`, `$lte`, `$gt`, `$gte`, `$between`, `$in`, `$nin`, `$isNull`, `$isNotNull`, `$not`. Combine with `$and`, `$or`, `$not`, `$nor`. A field takes only the operators its type allows.
|
|
207
|
+
- Text: `$like`, `$startsWith`, `$endsWith`, `$includes`, each with a case-insensitive `i` form (`$ilike`, `$istartsWith`, ...). `$like` reads `%`, `_` and `\` the same on every engine; the other three take their text literally. `$regex` is case-sensitive unless the pattern opens with `(?i)`.
|
|
208
|
+
- Arrays and JSON: `$all: ['a', 'b']`, `$size: 3` or `{ $gte: 2 }`, `$elemMatch: { city: 'NYC', zip: { $startsWith: '10' } }`. A JSON path filters like a field: `{ 'settings.billing.plan': 'pro' }`.
|
|
209
|
+
- A relation key keeps the parents with a matching related row, as an `EXISTS`, never duplicating them: `{ posts: { title: { $iincludes: 'orm' } } }`, or by count: `{ posts: { $size: { $gte: 5 } } }`. For a subquery no relation covers, `$exists` / `$nexists` take a `sql` fragment.
|
|
210
|
+
- Full-text: `$where: { $text: { $value: 'wireless keyboard' } }` searches the entity's fulltext index; `$sort: { $text: 'desc' }` ranks by relevance.
|
|
211
|
+
- Vectors: `$sort: { embedding: { $vector: v } }` with a `$limit` returns the nearest; `$where: { embedding: { $near: { $vector: v, $lt: 0.35 } } }` keeps only close rows; `$candidates` tunes ANN recall.
|
|
212
212
|
- An `undefined` anywhere in `$where` throws. Leave the key out to skip the filter (`...(email && { email })`), or name `null`.
|
|
213
|
-
-
|
|
214
|
-
|
|
215
|
-
|
|
216
|
-
|
|
217
|
-
-
|
|
218
|
-
-
|
|
219
|
-
-
|
|
220
|
-
-
|
|
213
|
+
- On SQL, `$ne`, `$nin`, `$not` and `$nor` drop NULL rows, where MongoDB keeps them. To keep them, name NULL: `{ $or: [{ col: { $ne: 'a' } }, { col: null }] }`.
|
|
214
|
+
|
|
215
|
+
### Writes
|
|
216
|
+
|
|
217
|
+
- Without options, inserts and upserts resolve to ids, updates and deletes to a count. A last argument `{ returning: { id: true } }` resolves to those rows instead.
|
|
218
|
+
- `upsertOne(Entity, { $conflict: { email: true }, $where? }, row, update?)`: a conflicting row matching `$where` takes `update` (an update payload), else the payload but keeping its own key; one not matching stays as it is. `upsertInto` in a trigger takes the same query. On MySQL and MariaDB, a `$where` may read only one column the update sets.
|
|
219
|
+
- `updateMany` and `deleteMany` that name no rows (no `$where` holding a value, no `$limit`) throw. Pass `{ unfiltered: true }` to mean the whole table.
|
|
220
|
+
- Update operators: `{ stock: { $inc: -1 } }` or `$mul`, with NULL counted as 0. A guard in `$where` (`stock: { $gte: 1 }`) makes a decrement race-safe. JSON fields take `$pull`, `$set`, `$push`, `$addToSet`, then `$unset`, applied in that order; `$set` and `$unset` take dotted paths and create parents: `settings: { $set: { 'billing.plan': 'pro' } }`.
|
|
221
|
+
|
|
222
|
+
### Raw SQL and errors
|
|
223
|
+
|
|
224
|
+
- ``pool.all`SELECT ... WHERE id = ${id}` `` for a `SELECT`, ``pool.run`...` `` for a write. Interpolated values bind: a scalar, `null` or a list, never `undefined` or a plain object. `sql` builds a fragment, `sql.join(fragments, ' AND ')` joins them, and `sql.text(s)` runs trusted SQL held in a string: never user input.
|
|
225
|
+
- An operator compares a field with another column through its ref, wherever it takes a value: `{ effectiveTo: { $gt: rate.effectiveFrom } }` off `refs(Rate)` or a check's refs, `$between`, `$in` and `$ne` alike, on every engine, MongoDB included. A JSON path compared with one reads as that column's type. A ref names a column of the entity in scope: one of another entity is refused, and reads off its own alias, `refs(Other, 'o')`.
|
|
226
|
+
- 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.
|
|
227
|
+
- 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.
|
|
221
228
|
- `queryErrorKind(err)` names a failure the same on every engine: `uniqueViolation`, `foreignKeyViolation`, `notNullViolation`, `checkViolation`, `optimisticLock`, `retryable`, `usage`, `security`. Catch by kind, not by driver code.
|
|
222
|
-
- Raw SQL: ``pool.all`SELECT ... WHERE id = ${id}` `` for a `SELECT`, ``pool.run`...` `` for a write. Interpolated values bind: a scalar, `null` or a list, never `undefined` or a plain object. `sql` builds a fragment, and `sql.join(fragments, ' AND ')` joins them. `sql.text(s)` runs trusted SQL held in a string. Never build it from user input.
|
|
223
229
|
|
|
224
230
|
## Aggregates
|
|
225
231
|
|
|
226
|
-
Compute in SQL, not in code
|
|
232
|
+
Compute in SQL, not in code: loading rows to dedupe, count or sum them in JavaScript costs a round trip and every row.
|
|
227
233
|
|
|
228
234
|
```ts
|
|
229
|
-
import { Post } from './entities.js';
|
|
230
|
-
import { pool } from './uql.config.js';
|
|
231
|
-
|
|
232
235
|
// Distinct values: a $group with no $select returns each once.
|
|
233
|
-
const titles = await pool.aggregate(Post, {
|
|
234
|
-
$group: { title: true },
|
|
235
|
-
$sort: { title: 1 },
|
|
236
|
-
});
|
|
236
|
+
const titles = await pool.aggregate(Post, { $group: { title: true }, $sort: { title: 1 } });
|
|
237
237
|
|
|
238
238
|
// Tallies per group, in one statement.
|
|
239
239
|
const counts = await pool.aggregate(Post, {
|
|
@@ -242,16 +242,15 @@ const counts = await pool.aggregate(Post, {
|
|
|
242
242
|
});
|
|
243
243
|
```
|
|
244
244
|
|
|
245
|
-
- `$select` takes `$count` (`'*'` or a field), `$countDistinct`, `$sum`, `$avg`, `$min` and `$max`. Over no rows a count is `0` and the others
|
|
246
|
-
- `$where`
|
|
247
|
-
- `$having` and `$sort` name a grouped column or a `$select` alias
|
|
248
|
-
- A `$group` key can reach a to-one relation's field
|
|
249
|
-
- A per-row count belongs on the entity as a
|
|
250
|
-
- Details: https://uql-orm.dev/querying/aggregate.md
|
|
245
|
+
- `$select` takes `$count` (`'*'` or a field), `$countDistinct`, `$sum`, `$avg`, `$min` and `$max`. Over no rows a count is `0` and the others `null`.
|
|
246
|
+
- The query's `$where` filters rows before grouping. An operator's own `$where` filters only what it reads, pivoting rows into columns in one query: `{ $count: '*', $where: { published: true } }`.
|
|
247
|
+
- `$having` and `$sort` name a grouped column or a `$select` alias.
|
|
248
|
+
- A `$group` key can reach a to-one relation's field (`{ orderId: { transaction: { orderId: true } } }`), never a to-many's.
|
|
249
|
+
- A per-row count belongs on the entity as a computed field, or on a read as `$count`, not in an aggregate. Details: https://uql-orm.dev/querying/aggregate.md
|
|
251
250
|
|
|
252
251
|
## Connections and transactions
|
|
253
252
|
|
|
254
|
-
Every method is on the pool and on a querier. A pool call takes a connection for that call.
|
|
253
|
+
Every method is on the pool and on a querier. A pool call takes a connection for that call. For several operations on one connection, or atomically:
|
|
255
254
|
|
|
256
255
|
```ts
|
|
257
256
|
await pool.transaction(async (querier) => {
|
|
@@ -260,27 +259,28 @@ await pool.transaction(async (querier) => {
|
|
|
260
259
|
});
|
|
261
260
|
```
|
|
262
261
|
|
|
263
|
-
The callback commits when it returns and rolls back when it throws. Inside it, `pool` calls run on its querier. A nested `transaction()` is a savepoint; MongoDB refuses it.
|
|
264
|
-
|
|
265
|
-
A
|
|
262
|
+
- The callback commits when it returns and rolls back when it throws. Inside it, `pool` calls run on its querier. A nested `transaction()` is a savepoint; MongoDB refuses it.
|
|
263
|
+
- `querier.onCommit(fn)` runs `fn` after the outermost commit, never on rollback: use it for mail and queued jobs.
|
|
264
|
+
- A transaction opened in one place and ended in another uses `beginTransaction`, `commitTransaction` and `rollbackTransaction`. A querier from `pool.getQuerier()` is yours to release: bind it with `await using`.
|
|
265
|
+
- A `findManyStream` holds its querier until the loop ends, refusing other statements meanwhile: run them after the loop, or on another connection.
|
|
266
266
|
|
|
267
267
|
## Migrations
|
|
268
268
|
|
|
269
|
-
Upgrading an existing project: `npx uql-codemod --dry-run`, then `npx uql-codemod`, which rewrites what it can and reports the rest. What changed by version: https://uql-orm.dev/upgrade-guide.md
|
|
270
|
-
|
|
271
269
|
`npx uql-migrate` reads `uql.config.ts` (`bun --bun uql-migrate` on Bun):
|
|
272
270
|
|
|
273
|
-
- `sync`: applies what the entities imply. Development only.
|
|
274
|
-
- `generate:entities`: writes the diff as a migration file to review. A renamed column is a drop and an add, unless a naming strategy maps it or you write `renameColumn(table, from, to)`. It refuses a required column with no default on a table
|
|
275
|
-
- `up` and `down`: each migration
|
|
271
|
+
- `sync`: applies what the entities imply. Development only. `sync --dry-run` prints only the SQL, for another tool to apply.
|
|
272
|
+
- `generate:entities`: writes the diff as a migration file to review. A renamed column is a drop and an add, unless a naming strategy maps it or you write `renameColumn(table, from, to)`. It refuses a required column with no default on a table holding rows.
|
|
273
|
+
- `up` and `down`: each migration in its own transaction, under a lock so concurrent instances run it once. From code: `await new Migrator(pool, { migrationsPath }).up()` before the app starts.
|
|
276
274
|
- `generate:from-db`: writes entity classes from an existing database.
|
|
277
275
|
- `drift:check`: fails when the database no longer matches the entities.
|
|
278
|
-
|
|
276
|
+
|
|
277
|
+
Upgrading uql itself: `npx uql-codemod --dry-run`, then `npx uql-codemod`, which rewrites what it can and reports the rest. Breaking changes: https://uql-orm.dev/upgrade-guide.md
|
|
279
278
|
|
|
280
279
|
## Where to read more
|
|
281
280
|
|
|
282
281
|
- Operators and per-dialect SQL: https://uql-orm.dev/querying/comparison-operators.md
|
|
283
|
-
- Relations and deep `$populate`: https://uql-orm.dev/querying/relations.md
|
|
284
|
-
-
|
|
282
|
+
- Relations, relation filters and deep `$populate`: https://uql-orm.dev/querying/relations.md
|
|
283
|
+
- JSON paths and operators: https://uql-orm.dev/querying/json.md
|
|
284
|
+
- Full-text and vector search: https://uql-orm.dev/querying/full-text.md, https://uql-orm.dev/querying/semantic-search.md
|
|
285
|
+
- Computed fields: https://uql-orm.dev/entities/computed-fields.md
|
|
285
286
|
- Coming from Prisma, Drizzle, TypeORM, MikroORM or Mongoose: https://uql-orm.dev/switching-to-uql.md
|
|
286
|
-
- Breaking changes by version: https://uql-orm.dev/upgrade-guide.md
|