uql-orm 0.102.5 → 0.102.7
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 +1 -1
- package/dist/browser/uql-browser.min.js +2 -2
- package/dist/browser/uql-browser.min.js.map +3 -3
- package/dist/bunSql/bunSqlQuerier.d.ts +9 -3
- package/dist/bunSql/bunSqlQuerier.js +7 -15
- package/dist/d1/d1Querier.d.ts +18 -14
- package/dist/d1/d1Querier.js +21 -8
- package/dist/d1/d1SqliteDialect.d.ts +2 -0
- package/dist/d1/d1SqliteDialect.js +3 -0
- package/dist/dialect/abstractDialect.d.ts +3 -0
- package/dist/dialect/abstractDialect.js +6 -2
- package/dist/dialect/abstractSqlDialect.d.ts +24 -5
- package/dist/dialect/abstractSqlDialect.js +86 -57
- package/dist/dialect/mysqlLikeSqlDialect.js +6 -1
- package/dist/dialect/operators.d.ts +9 -3
- package/dist/dialect/operators.js +32 -9
- package/dist/dialect/vectorSqlDialect.js +2 -2
- package/dist/entity/index.d.ts +1 -1
- package/dist/entity/index.js +1 -1
- package/dist/entity/metadata/definition.d.ts +16 -1
- package/dist/entity/metadata/definition.js +26 -1
- package/dist/index.d.ts +2 -1
- package/dist/index.js +2 -1
- package/dist/mariadb/mariadbQuerier.d.ts +5 -2
- package/dist/mariadb/mariadbQuerier.js +5 -10
- package/dist/migrate/ddl/defaultSql.js +1 -1
- package/dist/migrate/ddl/indexDdl.d.ts +3 -3
- package/dist/migrate/ddl/indexDdl.js +7 -7
- package/dist/migrate/ddl/mysqlIndexDdl.js +2 -2
- package/dist/migrate/ddl/tableDdl.js +2 -2
- package/dist/migrate/indexPredicate.d.ts +4 -3
- package/dist/migrate/indexPredicate.js +5 -5
- package/dist/migrate/introspection/abstractSqlSchemaIntrospector.js +2 -6
- package/dist/migrate/schemaGenerator.js +1 -1
- package/dist/migrate/triggerSql.js +7 -5
- package/dist/mongodb/mongoDialect.js +17 -41
- package/dist/mongodb/mongoSchemaGenerator.js +12 -12
- package/dist/mongodb/mongodbQuerier.d.ts +4 -3
- package/dist/mongodb/mongodbQuerier.js +75 -102
- package/dist/mssql/mssqlDialect.js +2 -7
- package/dist/mssql/mssqlQuerier.d.ts +9 -3
- package/dist/mssql/mssqlQuerier.js +9 -11
- package/dist/mysql/mysql2Querier.d.ts +11 -2
- package/dist/mysql/mysql2Querier.js +4 -7
- package/dist/neon/index.d.ts +2 -0
- package/dist/neon/index.js +2 -0
- package/dist/neon/neonDialect.d.ts +7 -0
- package/dist/neon/neonDialect.js +8 -0
- package/dist/neon/neonQuerier.d.ts +26 -0
- package/dist/neon/neonQuerier.js +47 -0
- package/dist/neon/neonQuerierPool.d.ts +12 -2
- package/dist/neon/neonQuerierPool.js +22 -3
- package/dist/pglite/pgliteQuerier.d.ts +9 -5
- package/dist/pglite/pgliteQuerier.js +7 -11
- package/dist/postgres/pgExecution.d.ts +8 -0
- package/dist/postgres/pgExecution.js +3 -0
- package/dist/postgres/pgQuerier.d.ts +3 -6
- package/dist/postgres/pgQuerier.js +3 -7
- package/dist/querier/abstractQuerier.d.ts +24 -20
- package/dist/querier/abstractQuerier.js +79 -58
- package/dist/querier/abstractSqlQuerier.d.ts +42 -28
- package/dist/querier/abstractSqlQuerier.js +134 -116
- package/dist/querier/queryError.d.ts +2 -0
- package/dist/querier/queryError.js +9 -0
- package/dist/querier/transaction.js +2 -6
- package/dist/schema/canonicalType.d.ts +3 -3
- package/dist/schema/canonicalType.js +4 -10
- package/dist/sqlite/bindValues.d.ts +10 -0
- package/dist/sqlite/bindValues.js +8 -0
- package/dist/sqlite/hranaQuerier.d.ts +17 -11
- package/dist/sqlite/hranaQuerier.js +16 -5
- package/dist/sqlite/index.d.ts +1 -1
- package/dist/sqlite/index.js +0 -1
- package/dist/sqlite/localSqliteQuerierPool.js +19 -9
- package/dist/sqlite/sqliteQuerier.d.ts +9 -4
- package/dist/sqlite/sqliteQuerier.js +14 -8
- package/dist/turso/tursoSessionQuerier.d.ts +19 -7
- package/dist/turso/tursoSessionQuerier.js +31 -20
- package/dist/type/dialect.d.ts +3 -0
- package/dist/type/querier.d.ts +12 -0
- package/dist/type/querier.js +10 -0
- package/dist/type/vector.d.ts +2 -1
- package/dist/type/vector.js +2 -2
- package/dist/util/dialect.util.d.ts +21 -6
- package/dist/util/dialect.util.js +34 -9
- package/dist/util/filters.util.d.ts +5 -4
- package/dist/util/filters.util.js +4 -7
- package/dist/util/logger.js +2 -6
- package/dist/util/object.util.d.ts +7 -0
- package/dist/util/object.util.js +17 -0
- package/dist/util/query.util.d.ts +3 -2
- package/dist/util/sql.js +1 -1
- package/dist/util/sql.util.d.ts +15 -15
- package/dist/util/sql.util.js +5 -5
- package/package.json +7 -7
- package/skills/uql-orm/SKILL.md +58 -51
- package/dist/sqlite/abstractSqliteQuerier.d.ts +0 -28
- package/dist/sqlite/abstractSqliteQuerier.js +0 -36
package/skills/uql-orm/SKILL.md
CHANGED
|
@@ -10,9 +10,9 @@ description: >
|
|
|
10
10
|
|
|
11
11
|
# UQL
|
|
12
12
|
|
|
13
|
-
Entities are classes
|
|
13
|
+
Entities are classes. A query is a JSON object checked key by key against the entity, and it runs the same on every supported database. There is no schema file, no generated client and no query builder.
|
|
14
14
|
|
|
15
|
-
|
|
15
|
+
Full docs are Markdown: the index at https://uql-orm.dev/llms.txt, and each page at its URL plus `.md`. Read the page for the task before guessing an option. The whole site is one file at https://uql-orm.dev/llms-full.txt (about 530 KB), too large to load for one task.
|
|
16
16
|
|
|
17
17
|
## Setup
|
|
18
18
|
|
|
@@ -20,11 +20,11 @@ The full docs are Markdown at https://uql-orm.dev/llms.txt, one page per URL. Re
|
|
|
20
20
|
npm install uql-orm pg # or mysql2, mariadb, better-sqlite3, mongodb, @libsql/client, ...
|
|
21
21
|
```
|
|
22
22
|
|
|
23
|
-
ESM only (a CommonJS app loads it through `require(esm)`). Node 22.18+, Bun or an edge runtime, TypeScript 5.7+.
|
|
23
|
+
ESM only (a CommonJS app loads it through `require(esm)`). Needs Node 22.18+, Bun or an edge runtime, and TypeScript 5.7+.
|
|
24
24
|
|
|
25
|
-
|
|
25
|
+
Decorators are TC39 standard. Never enable `experimentalDecorators` or `emitDecoratorMetadata`, and never import `reflect-metadata`. In `tsconfig.json`, `module` is `nodenext` or `preserve`, and `target` is dated (`es2022`+), not `esnext`. A project already on legacy decorators (NestJS, Angular) keeps its config and defines entities with `defineEntity`. NestJS: https://uql-orm.dev/nestjs.md
|
|
26
26
|
|
|
27
|
-
Node's type stripping runs no decorators
|
|
27
|
+
Node's type stripping runs no decorators, so on Node add `tsx` (`npm i -D tsx`); `uql-migrate` loads `uql.config.ts` through it. Next.js needs `@babel/plugin-proposal-decorators` at `version: '2023-11'` in `babel.config.json`. A bundler that minifies class names needs `@Entity({ name: 'todo' })`, since the table name defaults to the class name.
|
|
28
28
|
|
|
29
29
|
```ts
|
|
30
30
|
// uql.config.ts
|
|
@@ -37,7 +37,7 @@ export const pool = new PgQuerierPool({ connectionString: process.env.DATABASE_U
|
|
|
37
37
|
export default { pool, entities: [User, Post] } satisfies Config;
|
|
38
38
|
```
|
|
39
39
|
|
|
40
|
-
|
|
40
|
+
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
41
|
|
|
42
42
|
## Entities
|
|
43
43
|
|
|
@@ -72,20 +72,21 @@ export class Post {
|
|
|
72
72
|
}
|
|
73
73
|
```
|
|
74
74
|
|
|
75
|
-
- A class inherits
|
|
76
|
-
- Every `@Field` states its `type`: `String`, `Number`, `Boolean`, `Date`, `BigInt`, or a column type such as `'uuid'`, `'text'`, `'jsonb'`. A foreign key takes `references`
|
|
77
|
-
- A column is nullable unless it says `nullable: false
|
|
78
|
-
-
|
|
79
|
-
-
|
|
80
|
-
- `defaultValue` is a value of the field's type
|
|
81
|
-
- `currentTimestamp` is the database clock, UTC to the millisecond on every engine
|
|
82
|
-
-
|
|
83
|
-
-
|
|
84
|
-
-
|
|
85
|
-
-
|
|
86
|
-
-
|
|
87
|
-
- `@Field({
|
|
88
|
-
-
|
|
75
|
+
- A class inherits its base's fields, relations, hooks, filters, indexes, checks and triggers. The base needs no `@Entity()` unless it is a table. A child entry with the same name replaces the base's.
|
|
76
|
+
- Every `@Field` states its `type`: `String`, `Number`, `Boolean`, `Date`, `BigInt`, or a column type such as `'uuid'`, `'text'`, `'jsonb'`. A foreign key takes `references` and inherits the target's type. A field read off `refs(Entity)` carries its type too. A JSON column of no fixed shape is a bare `Json`.
|
|
77
|
+
- A column is nullable unless it says `nullable: false`. Its property must admit `null`: `title?: string | null`. A property without `| null` on a nullable column is a compile error.
|
|
78
|
+
- `Date` is an instant, stored in UTC to the millisecond on every engine; `precision` sets other fractional digits. `'decimal'` is exact text (`price?: string | null`). `type: Number` with `precision`/`scale` opts into a rounding JS number.
|
|
79
|
+
- Declare a `nullable: false` column with `!` (`email!: string`). Declare `?` for anything an insert may omit: nullable, `onInsert`, `defaultValue`, `eager: false`, `computed` fields, and relations. A single-column key and a `version` are filled by uql.
|
|
80
|
+
- `defaultValue` is 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.
|
|
81
|
+
- `currentTimestamp` is the database clock, UTC to the millisecond on every engine. Use it for defaults, stamps, `onUpdate` and `$where`, not a raw `CURRENT_TIMESTAMP`.
|
|
82
|
+
- An engine's own column type is a `sql` constant: ``columnType: sql`tsvector` ``.
|
|
83
|
+
- Members are named by callbacks, never strings: `mappedBy: (post) => post.author`, `references: (post) => post.authorId`.
|
|
84
|
+
- `@ManyToMany({ entity: () => Tag, through: () => PostTag })` names the junction entity.
|
|
85
|
+
- `cascade: true` writes related rows in the same transaction. A to-one holding the key takes `'persist'`, and `{ id }` links an existing row. An update replaces a to-many's rows: listed ones are saved or kept, the rest removed.
|
|
86
|
+
- Partial index: `@Index((post) => [post.authorId], { where: { archived: { $ne: true } } })`. Write the predicate as a query, not `sql`, so the planner can match it. An unnamed partial index carries a hash of its `where` in its name, so editing the predicate replaces it.
|
|
87
|
+
- Optimistic lock: `@Field({ type: Number, version: true })` with `[versionKey]?: 'version'` on the class. An update must carry the version it read (a compile error otherwise). A stale one throws `UqlOptimisticLockError` (kind `optimisticLock`, HTTP 409). A versioned update names one row by its id. Save and upsert are refused for such an entity.
|
|
88
|
+
- Computed: `@Field({ computed })` on a `readonly` property, as SQL over the row ``(u) => sql`${u.first} || ' ' || ${u.last}` `` or a relation aggregate `(order) => order.items.count()`. `stored: true` makes a generated column. `stored: ['insert', 'update']` makes a stamp that a database trigger writes whoever writes the row. `onUpdate` covers only uql's own writes.
|
|
89
|
+
- `@Trigger({ on: 'afterUpdate', of: (post) => [post.status], where: { $old: { status: 'draft' } }, run })` is a trigger the database fires. `run(newRow, oldRow)` returns a body built from `insertInto`, `upsertInto`, `updateTable`, `deleteFrom` and `refuse(message)`, or raw `sql`. The builders are typed by the entity written and render on every engine. `deferred: true` fires an after trigger at commit, on Postgres only. A trigger's writes skip uql's fills and entity filters. A `deleteFrom` in a trigger deletes outright, even on a soft-delete entity: write a soft delete as an `updateTable`. MongoDB has no triggers. Details: https://uql-orm.dev/entities/triggers.md
|
|
89
90
|
- `defineEntity` defines the same entity without decorators: https://uql-orm.dev/entities/imperative.md
|
|
90
91
|
|
|
91
92
|
## Queries
|
|
@@ -104,28 +105,30 @@ const users = await pool.findMany(User, {
|
|
|
104
105
|
});
|
|
105
106
|
```
|
|
106
107
|
|
|
107
|
-
-
|
|
108
|
-
-
|
|
109
|
-
-
|
|
110
|
-
- `$
|
|
111
|
-
-
|
|
112
|
-
-
|
|
113
|
-
- `$
|
|
114
|
-
-
|
|
115
|
-
- `$
|
|
116
|
-
-
|
|
117
|
-
-
|
|
118
|
-
- `upsertOne(Entity, { email: true }, row, update?)`: a conflicting row takes `update`, an update
|
|
119
|
-
-
|
|
120
|
-
-
|
|
121
|
-
-
|
|
122
|
-
-
|
|
123
|
-
-
|
|
124
|
-
-
|
|
108
|
+
- Query keys: `$select`, `$exclude`, `$where`, `$populate`, `$count`, `$distinct`, `$sort`, `$skip`, `$limit`. `$count: { posts: true }` counts a to-many under `_count` without loading it.
|
|
109
|
+
- 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
|
|
110
|
+
- Results are narrowed to what the query selected and populated. Reading an unselected field is a compile error. Name a shape with `QueryFindResult<User, 'id' | 'email'>`.
|
|
111
|
+
- `$populate` loads relations in the same statement. Nothing is lazy: an unpopulated relation is absent.
|
|
112
|
+
- In code generic over its entity, `{ [key]: 'asc' }` widens to an index signature. Take the member as a selector, `since: (keys: KeyMap<E>) => K`, read it with `keyOf(since)`, and sort with `sortOf<E>([[key, 'asc']])`. A selector follows a rename; a string key does not. `$where` and writes by a constant have no such builder: take a callback the caller writes against its own entity, `(state) => ({ state })`.
|
|
113
|
+
- `$sort` takes `'asc'`/`1` or `'desc'`/`-1`, plus `'ascNullsLast'`, `'ascNullsFirst'`, `'descNullsFirst'`, `'descNullsLast'`, which behave the same on every engine. Unqualified, each engine keeps its own null order.
|
|
114
|
+
- `$where` takes a value for equality or an operator map: `$eq`, `$ne`, `$lt`, `$lte`, `$gt`, `$gte`, `$in`, `$nin`, `$between`, `$like`, `$ilike`, `$regex`, `$startsWith`, `$endsWith`, `$includes`, `$isNull`, `$isNotNull`. Combine with `$and`, `$or`, `$not`, `$nor`. `$regex` is case-sensitive unless the pattern opens with `(?i)`.
|
|
115
|
+
- An `undefined` anywhere in `$where` throws. Leave the key out to skip the filter (`...(email && { email })`), or name `null`.
|
|
116
|
+
- NULL compares as the engine does: 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 }] }`. Ask for NULL with `{ col: null }` and its absence with `{ col: { $ne: null } }`.
|
|
117
|
+
- Full-text: `$text: { $value }` in `$where`, through an `@Index(..., { type: 'fulltext', config })`. `$sort: { $text: 'desc' }` ranks by relevance, and `{ $text: { $project: 'score' } }` returns the score, typed `WithProjection<E, 'score'>`.
|
|
118
|
+
- `findManyPage(User, { $sort: { createdAt: -1, id: 1 }, $limit: 20, $after })` pages by cursor, so page 1,000 costs what page 1 does. It returns `{ items, startCursor, endCursor, hasNextPage, hasPrevPage }`. Pass `endCursor` as `$after`, or `startCursor` as `$before`. `$sort` must end in the key or a unique `nullable: false` field, and takes no `$skip`. A nullable leading sort key pages correctly but cannot use an index.
|
|
119
|
+
- `upsertOne(Entity, { email: true }, row, update?)`: a conflicting row takes `update`, an update payload with operators (`{ uses: { $inc: 1 } }`). An empty `{}` leaves a conflicting row alone. Without `update`, a conflicting row takes the payload and its `onUpdate` fills, but keeps its own key: the payload's key, and its `onInsert` fills, apply only to a row it inserts. Cascaded relations write on either branch. Resolves to the row's id.
|
|
120
|
+
- Writes take `{ returning: { id: true } }` as their last argument and resolve to those rows, read back in the same transaction. Without it, inserts and upserts resolve to ids, and updates and deletes to a count. An update or delete writes exactly the rows it reports. One that reads its rows first holds them, so a racing writer waits for the commit. SQLite and MongoDB have no row locks and fail the racing writer with a retryable error instead.
|
|
121
|
+
- A query is plain data, so it can be sent from a browser to `uql-orm/http`. Its handler serves only the entities its required `include` names.
|
|
122
|
+
- `updateMany` and `deleteMany` that name no rows throw: no `$where` holding a value, and no `$limit`. Pass `{ unfiltered: true }` to mean the whole table.
|
|
123
|
+
- Updates use operators in the statement: `{ stock: { $inc: -1 } }` or `$mul`, with NULL counted as 0. Put a guard in `$where` (`stock: { $gte: 1 }`) to make a decrement race-safe. On SQL the step can be a ref or `sql` (`{ total: { $inc: newRow.amount } }` in a trigger).
|
|
124
|
+
- JSON fields take `$pull`, `$set`, `$push`, `$addToSet`, then `$unset`, applied in that order on one value. `$set` and `$unset` take keys or dotted paths and create parents: `settings: { $set: { 'billing.plan': 'pro' } }`. A JSON array (`tags?: Json<string[]>`) takes lists: `{ tags: { $pull: ['old'], $addToSet: ['new'] } }`.
|
|
125
|
+
- `$lock: true` locks the rows a read returns, and `{ $wait: 'skip' | 'nowait' }` says what to do about a row someone else holds. It needs an open transaction. SQLite, libSQL, Turso, D1 and MongoDB have no row lock and refuse it.
|
|
126
|
+
- `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. Every error UQL raises is a `UqlError`.
|
|
127
|
+
- 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 (bind `JSON.stringify(doc)`). `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. `sql` is a tag: ``sql(`...`)`` does not compile. `raw` is its deprecated name.
|
|
125
128
|
|
|
126
129
|
## Connections and transactions
|
|
127
130
|
|
|
128
|
-
Every method is on
|
|
131
|
+
Every method is on the pool and on a querier. A pool call takes a connection for that call. To run several operations on one connection, or atomically, use a transaction:
|
|
129
132
|
|
|
130
133
|
```ts
|
|
131
134
|
await pool.transaction(async (querier) => {
|
|
@@ -134,29 +137,33 @@ await pool.transaction(async (querier) => {
|
|
|
134
137
|
});
|
|
135
138
|
```
|
|
136
139
|
|
|
137
|
-
The callback commits when it returns and rolls back when it throws
|
|
140
|
+
The callback commits when it returns and rolls back when it throws. Inside it, `pool` calls run on its querier. A transaction holds its connection: a statement from outside its callback waits for it. A nested `transaction()` is a savepoint, whose failure undoes its own writes alone; MongoDB refuses it. For a transaction that opens in one place and ends in another, use `beginTransaction`, `commitTransaction` and `rollbackTransaction`. `{ readOnly: true }` opens a read-only transaction: Postgres, CockroachDB, MySQL and MariaDB refuse its writes, and libSQL and Turso skip the write lock they take at `BEGIN`. `querier.onCommit(fn)` runs `fn` after the outermost commit and never on rollback: use it for mail and queued jobs. A querier from `pool.getQuerier()` is yours to release: bind it with `await using`.
|
|
138
141
|
|
|
139
|
-
A
|
|
142
|
+
A call uql splits into several statements (an `insertMany` past the engine's bind cap, an `upsertMany` of mixed shapes) runs them all or none: one request on D1, libSQL, Turso and Neon (over HTTP), a transaction elsewhere, joining an open one.
|
|
143
|
+
|
|
144
|
+
A `findManyStream` holds its querier until the loop ends, and other statements on it are refused 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, 32,767 on Neon) is refused: split a long `$in`.
|
|
140
145
|
|
|
141
146
|
## Migrations
|
|
142
147
|
|
|
143
148
|
`npx uql-migrate` reads `uql.config.ts` (`bun --bun uql-migrate` on Bun):
|
|
144
149
|
|
|
145
|
-
- `sync
|
|
146
|
-
- `generate:entities
|
|
147
|
-
- `up` and `down
|
|
148
|
-
- `generate:from-db
|
|
149
|
-
- `drift:check
|
|
150
|
-
- `sync --dry-run
|
|
150
|
+
- `sync`: applies what the entities imply. Development only.
|
|
151
|
+
- `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 (`firstName` to `first_name`), or you write `renameColumn(table, from, to)`. It refuses a required column with no default on a table that holds rows.
|
|
152
|
+
- `up` and `down`: each migration runs 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. It rejects with the first failing migration's error; the ones before it stay applied. `down()` reverts the last one, and `down({ step: Infinity })` reverts every one.
|
|
153
|
+
- `generate:from-db`: writes entity classes from an existing database.
|
|
154
|
+
- `drift:check`: fails when the database no longer matches. Index expressions and stored computed expressions are not compared, so change those by hand in the migration.
|
|
155
|
+
- `sync --dry-run`: prints only SQL on stdout, for a migration file another tool applies, such as wrangler on Cloudflare D1 (https://uql-orm.dev/cloudflare-d1.md).
|
|
156
|
+
|
|
157
|
+
In a migration, ``querier.run /*sql*/ `CREATE TABLE ...` `` marks the SQL: the comment is what es6-string-html highlights.
|
|
151
158
|
|
|
152
|
-
Checks,
|
|
159
|
+
Checks, enums and triggers are part of the diff. uql owns the `_uql_`-prefixed checks and triggers and never touches another. On MongoDB, checks and enums are the collection's validator, which uql owns whole: a check fails a document that lacks the field it compares.
|
|
153
160
|
|
|
154
161
|
## Where to read more
|
|
155
162
|
|
|
156
|
-
- Operators
|
|
163
|
+
- Operators and per-dialect SQL: https://uql-orm.dev/querying/comparison-operators.md
|
|
157
164
|
- Relations and deep `$populate`: https://uql-orm.dev/querying/relations.md
|
|
158
165
|
- Computed fields and stamps: https://uql-orm.dev/entities/computed-fields.md
|
|
159
166
|
- Triggers: https://uql-orm.dev/entities/triggers.md
|
|
160
|
-
-
|
|
161
|
-
-
|
|
167
|
+
- Coming from Prisma, Drizzle, TypeORM, MikroORM or Mongoose: https://uql-orm.dev/switching-to-uql.md
|
|
168
|
+
- Moving data off MongoDB: https://uql-orm.dev/mongodb.md#moving-to-sql
|
|
162
169
|
- Breaking changes by version: https://uql-orm.dev/upgrade-guide.md
|
|
@@ -1,28 +0,0 @@
|
|
|
1
|
-
import { AbstractSqlQuerier } from '../querier/index.js';
|
|
2
|
-
import type { RawRow } from '../type/index.js';
|
|
3
|
-
/** What every SQLite driver binds. No `boolean`, which the drivers refuse and the dialect writes as an integer. */
|
|
4
|
-
export type SqliteBindValue = null | string | number | bigint | Uint8Array;
|
|
5
|
-
/** What a statement came back with on a SQLite driver: the rows it read, and how many rows it changed. */
|
|
6
|
-
export type SqliteExecution = {
|
|
7
|
-
readonly rows: RawRow[];
|
|
8
|
-
readonly changes: number;
|
|
9
|
-
};
|
|
10
|
-
/**
|
|
11
|
-
* Querier for every SQLite driver. Each supplies {@link execute}, and {@link iterate} where it steps a
|
|
12
|
-
* statement row by row; what they share - the values bound as SQLite takes them, the wide-integer
|
|
13
|
-
* decode, and a RETURNING statement counted by its rows - is written once here.
|
|
14
|
-
*/
|
|
15
|
-
export declare abstract class AbstractSqliteQuerier extends AbstractSqlQuerier {
|
|
16
|
-
/** Runs one statement, answering its rows as the driver read them. */
|
|
17
|
-
protected abstract execute(query: string, values: SqliteBindValue[]): Promise<SqliteExecution>;
|
|
18
|
-
/** A statement's rows as the driver answers them: read whole, unless it steps them one at a time. */
|
|
19
|
-
protected iterate(query: string, values: SqliteBindValue[]): Promise<Iterable<RawRow> | AsyncIterable<RawRow>>;
|
|
20
|
-
internalAll<T>(query: string, values?: unknown[]): Promise<T[]>;
|
|
21
|
-
internalRun(query: string, values?: unknown[]): Promise<import("../type/query.js").QueryUpdateResult>;
|
|
22
|
-
internalStream(query: string, values?: unknown[]): AsyncGenerator<RawRow, void, unknown>;
|
|
23
|
-
/**
|
|
24
|
-
* SQLite drivers hold a single shared handle rather than a connection from a pool, so releasing
|
|
25
|
-
* a querier returns nothing at all. Drivers owning a closable per-querier connection override this.
|
|
26
|
-
*/
|
|
27
|
-
internalRelease(): Promise<void>;
|
|
28
|
-
}
|
|
@@ -1,36 +0,0 @@
|
|
|
1
|
-
import { AbstractSqlQuerier } from '../querier/index.js';
|
|
2
|
-
import { decodeBigInts } from '../util/wideNumber.js';
|
|
3
|
-
/**
|
|
4
|
-
* Querier for every SQLite driver. Each supplies {@link execute}, and {@link iterate} where it steps a
|
|
5
|
-
* statement row by row; what they share - the values bound as SQLite takes them, the wide-integer
|
|
6
|
-
* decode, and a RETURNING statement counted by its rows - is written once here.
|
|
7
|
-
*/
|
|
8
|
-
export class AbstractSqliteQuerier extends AbstractSqlQuerier {
|
|
9
|
-
/** A statement's rows as the driver answers them: read whole, unless it steps them one at a time. */
|
|
10
|
-
async iterate(query, values) {
|
|
11
|
-
return (await this.execute(query, values)).rows;
|
|
12
|
-
}
|
|
13
|
-
async internalAll(query, values) {
|
|
14
|
-
const { rows } = await this.execute(query, toBindValues(values));
|
|
15
|
-
return rows.map(decodeBigInts);
|
|
16
|
-
}
|
|
17
|
-
async internalRun(query, values) {
|
|
18
|
-
const { rows, changes } = await this.execute(query, toBindValues(values));
|
|
19
|
-
// A driver's own count is unreliable for a RETURNING statement (Hrana answers 0), so its rows answer.
|
|
20
|
-
return this.buildUpdateResult({ rows: rows.map(decodeBigInts), changes: rows.length || changes });
|
|
21
|
-
}
|
|
22
|
-
async *internalStream(query, values) {
|
|
23
|
-
for await (const row of await this.iterate(query, toBindValues(values))) {
|
|
24
|
-
yield decodeBigInts(row);
|
|
25
|
-
}
|
|
26
|
-
}
|
|
27
|
-
/**
|
|
28
|
-
* SQLite drivers hold a single shared handle rather than a connection from a pool, so releasing
|
|
29
|
-
* a querier returns nothing at all. Drivers owning a closable per-querier connection override this.
|
|
30
|
-
*/
|
|
31
|
-
async internalRelease() { }
|
|
32
|
-
}
|
|
33
|
-
/** The compiler hands values over untyped, which the dialect has already normalized to what SQLite binds. */
|
|
34
|
-
function toBindValues(values = []) {
|
|
35
|
-
return values;
|
|
36
|
-
}
|