fastify-auto-sqlapi 0.5.0 → 1.0.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/AGENTS.md +5 -5
- package/AGENTS_BACKEND.md +166 -130
- package/AGENTS_FRONTEND.md +60 -38
- package/BREAKING_CHANGES.md +9 -893
- package/CHANGELOG.md +258 -15
- package/README.md +71 -45
- package/dist/bin/generate-schema.js +12 -12
- package/dist/bin/generate-tables.js +1 -2
- package/dist/bin/utils.d.ts +2 -6
- package/dist/bin/utils.d.ts.map +1 -1
- package/dist/bin/utils.js +13 -33
- package/dist/index.d.ts +13 -33
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +6 -37
- package/dist/lib/adapters/mysql-adapter.d.ts +5 -2
- package/dist/lib/adapters/mysql-adapter.d.ts.map +1 -1
- package/dist/lib/adapters/pg-adapter.d.ts +5 -2
- package/dist/lib/adapters/pg-adapter.d.ts.map +1 -1
- package/dist/lib/agent/manifest.d.ts +27 -10
- package/dist/lib/agent/manifest.d.ts.map +1 -1
- package/dist/lib/agent/manifest.js +43 -26
- package/dist/lib/agent/tool-schemas.d.ts +5 -4
- package/dist/lib/agent/tool-schemas.d.ts.map +1 -1
- package/dist/lib/agent/tool-schemas.js +5 -5
- package/dist/lib/cli/config.d.ts +37 -2
- package/dist/lib/cli/config.d.ts.map +1 -1
- package/dist/lib/cli/config.js +106 -16
- package/dist/lib/cli/mysql-introspect.d.ts +6 -1
- package/dist/lib/cli/mysql-introspect.d.ts.map +1 -1
- package/dist/lib/cli/mysql-introspect.js +15 -15
- package/dist/lib/cli/pg-introspect.d.ts +0 -1
- package/dist/lib/cli/pg-introspect.d.ts.map +1 -1
- package/dist/lib/cli/pg-introspect.js +2 -13
- package/dist/lib/cli/tables-codegen.d.ts +0 -4
- package/dist/lib/cli/tables-codegen.d.ts.map +1 -1
- package/dist/lib/cli/tables-codegen.js +24 -87
- package/dist/lib/db.d.ts +42 -17
- package/dist/lib/db.d.ts.map +1 -1
- package/dist/lib/db.js +114 -40
- package/dist/lib/dialect.d.ts +5 -0
- package/dist/lib/dialect.d.ts.map +1 -1
- package/dist/lib/dialect.js +3 -0
- package/dist/lib/engine/bulk/bulk-delete.d.ts +5 -0
- package/dist/lib/engine/bulk/bulk-delete.d.ts.map +1 -1
- package/dist/lib/engine/bulk/bulk-delete.js +66 -30
- package/dist/lib/engine/bulk/bulk-upsert.d.ts.map +1 -1
- package/dist/lib/engine/bulk/bulk-upsert.js +45 -26
- package/dist/lib/engine/read-hooks.d.ts +3 -3
- package/dist/lib/engine/read-hooks.d.ts.map +1 -1
- package/dist/lib/engine/read-hooks.js +3 -3
- package/dist/lib/engine/rest/delete.d.ts.map +1 -1
- package/dist/lib/engine/rest/delete.js +12 -18
- package/dist/lib/engine/rest/get.js +8 -8
- package/dist/lib/engine/rest/insert.d.ts.map +1 -1
- package/dist/lib/engine/rest/insert.js +31 -18
- package/dist/lib/engine/rest/update.d.ts.map +1 -1
- package/dist/lib/engine/rest/update.js +34 -17
- package/dist/lib/engine/search/aggregations.d.ts +3 -3
- package/dist/lib/engine/search/aggregations.d.ts.map +1 -1
- package/dist/lib/engine/search/aggregations.js +20 -16
- package/dist/lib/engine/search/conditions.d.ts +9 -5
- package/dist/lib/engine/search/conditions.d.ts.map +1 -1
- package/dist/lib/engine/search/conditions.js +31 -20
- package/dist/lib/engine/search/fields.d.ts +44 -11
- package/dist/lib/engine/search/fields.d.ts.map +1 -1
- package/dist/lib/engine/search/fields.js +94 -28
- package/dist/lib/engine/search/join-families.d.ts +7 -7
- package/dist/lib/engine/search/join-families.d.ts.map +1 -1
- package/dist/lib/engine/search/join-families.js +84 -75
- package/dist/lib/engine/search/joins.d.ts +15 -7
- package/dist/lib/engine/search/joins.d.ts.map +1 -1
- package/dist/lib/engine/search/joins.js +23 -13
- package/dist/lib/engine/search/order-by.d.ts +11 -12
- package/dist/lib/engine/search/order-by.d.ts.map +1 -1
- package/dist/lib/engine/search/order-by.js +24 -28
- package/dist/lib/engine/search/search.d.ts.map +1 -1
- package/dist/lib/engine/search/search.js +111 -62
- package/dist/lib/engine/validate.d.ts +21 -3
- package/dist/lib/engine/validate.d.ts.map +1 -1
- package/dist/lib/engine/validate.js +106 -16
- package/dist/lib/engine/write-helpers.d.ts +69 -16
- package/dist/lib/engine/write-helpers.d.ts.map +1 -1
- package/dist/lib/engine/write-helpers.js +257 -105
- package/dist/lib/errors.d.ts +42 -10
- package/dist/lib/errors.d.ts.map +1 -1
- package/dist/lib/errors.js +69 -15
- package/dist/lib/nullable.d.ts +3 -2
- package/dist/lib/nullable.d.ts.map +1 -1
- package/dist/lib/nullable.js +14 -5
- package/dist/lib/read-access.d.ts +33 -21
- package/dist/lib/read-access.d.ts.map +1 -1
- package/dist/lib/read-access.js +42 -23
- package/dist/lib/schema/bulk-delete.d.ts +13 -7
- package/dist/lib/schema/bulk-delete.d.ts.map +1 -1
- package/dist/lib/schema/bulk-delete.js +18 -8
- package/dist/lib/schema/bulk-upsert.d.ts +3 -3
- package/dist/lib/schema/bulk-upsert.d.ts.map +1 -1
- package/dist/lib/schema/bulk-upsert.js +9 -14
- package/dist/lib/schema/get.d.ts +1 -1
- package/dist/lib/schema/get.d.ts.map +1 -1
- package/dist/lib/schema/get.js +2 -2
- package/dist/lib/schema/helpers.d.ts +41 -23
- package/dist/lib/schema/helpers.d.ts.map +1 -1
- package/dist/lib/schema/helpers.js +80 -33
- package/dist/lib/schema/insert.d.ts +1 -1
- package/dist/lib/schema/insert.d.ts.map +1 -1
- package/dist/lib/schema/insert.js +12 -20
- package/dist/lib/schema/search.d.ts +2 -13
- package/dist/lib/schema/search.d.ts.map +1 -1
- package/dist/lib/schema/search.js +64 -61
- package/dist/lib/schema/update.d.ts +1 -1
- package/dist/lib/schema/update.d.ts.map +1 -1
- package/dist/lib/schema/update.js +6 -13
- package/dist/lib/sql-api.d.ts +47 -25
- package/dist/lib/sql-api.d.ts.map +1 -1
- package/dist/lib/sql-api.js +70 -27
- package/dist/lib/table-helpers.d.ts +92 -14
- package/dist/lib/table-helpers.d.ts.map +1 -1
- package/dist/lib/table-helpers.js +367 -128
- package/dist/lib/tenant.d.ts +16 -22
- package/dist/lib/tenant.d.ts.map +1 -1
- package/dist/lib/tenant.js +38 -54
- package/dist/lib/write-access.d.ts +15 -9
- package/dist/lib/write-access.d.ts.map +1 -1
- package/dist/lib/write-access.js +12 -4
- package/dist/routes/auto/agent-manifest.routes.d.ts +1 -1
- package/dist/routes/auto/agent-manifest.routes.js +2 -2
- package/dist/routes/auto/bulk-delete.routes.d.ts +2 -2
- package/dist/routes/auto/bulk-delete.routes.d.ts.map +1 -1
- package/dist/routes/auto/bulk-delete.routes.js +1 -7
- package/dist/routes/auto/bulk-upsert.routes.d.ts +2 -2
- package/dist/routes/auto/bulk-upsert.routes.d.ts.map +1 -1
- package/dist/routes/auto/bulk-upsert.routes.js +2 -2
- package/dist/routes/auto/delete.routes.d.ts +2 -2
- package/dist/routes/auto/delete.routes.d.ts.map +1 -1
- package/dist/routes/auto/delete.routes.js +8 -10
- package/dist/routes/auto/get.routes.d.ts +2 -2
- package/dist/routes/auto/get.routes.d.ts.map +1 -1
- package/dist/routes/auto/get.routes.js +5 -5
- package/dist/routes/auto/insert.routes.d.ts +2 -2
- package/dist/routes/auto/insert.routes.d.ts.map +1 -1
- package/dist/routes/auto/insert.routes.js +1 -7
- package/dist/routes/auto/plugin.d.ts +6 -0
- package/dist/routes/auto/plugin.d.ts.map +1 -1
- package/dist/routes/auto/plugin.js +60 -36
- package/dist/routes/auto/route-helpers.d.ts +26 -12
- package/dist/routes/auto/route-helpers.d.ts.map +1 -1
- package/dist/routes/auto/route-helpers.js +50 -19
- package/dist/routes/auto/search.routes.d.ts +2 -2
- package/dist/routes/auto/search.routes.d.ts.map +1 -1
- package/dist/routes/auto/search.routes.js +36 -24
- package/dist/routes/auto/update.routes.d.ts +2 -2
- package/dist/routes/auto/update.routes.d.ts.map +1 -1
- package/dist/routes/auto/update.routes.js +1 -8
- package/dist/routes/sql-api-decorator.d.ts +30 -12
- package/dist/routes/sql-api-decorator.d.ts.map +1 -1
- package/dist/routes/sql-api-decorator.js +44 -27
- package/dist/types/cli.d.ts +17 -6
- package/dist/types/cli.d.ts.map +1 -1
- package/dist/types/computed.d.ts +1 -1
- package/dist/types/computed.d.ts.map +1 -1
- package/dist/types/conditions.d.ts +3 -1
- package/dist/types/conditions.d.ts.map +1 -1
- package/dist/types/db.d.ts +44 -4
- package/dist/types/db.d.ts.map +1 -1
- package/dist/types/dml.d.ts +26 -17
- package/dist/types/dml.d.ts.map +1 -1
- package/dist/types/hooks.d.ts +62 -0
- package/dist/types/hooks.d.ts.map +1 -0
- package/dist/types/hooks.js +1 -0
- package/dist/types/join.d.ts +25 -8
- package/dist/types/join.d.ts.map +1 -1
- package/dist/types/plugin.d.ts +58 -19
- package/dist/types/plugin.d.ts.map +1 -1
- package/dist/types/plugin.js +2 -0
- package/dist/types/request.d.ts +2 -2
- package/dist/types/schema.d.ts +3 -3
- package/dist/types/schema.d.ts.map +1 -1
- package/dist/types/search.d.ts +28 -13
- package/dist/types/search.d.ts.map +1 -1
- package/dist/types/search.js +2 -1
- package/dist/types/table.d.ts +109 -94
- package/dist/types/table.d.ts.map +1 -1
- package/dist/types/table.js +7 -2
- package/dist/types/tenant.d.ts +28 -2
- package/dist/types/tenant.d.ts.map +1 -1
- package/dist/types/tenant.js +7 -1
- package/dist/types/validation.d.ts +69 -13
- package/dist/types/validation.d.ts.map +1 -1
- package/dist/types.d.ts +1 -0
- package/dist/types.d.ts.map +1 -1
- package/dist/types.js +1 -0
- package/docs/GLOSSARY.md +11 -5
- package/docs/adr/0003-bulk-not-transactional.md +2 -1
- package/docs/adr/0006-raw-db-errors.md +2 -1
- package/docs/adr/0013-sanitized-db-errors.md +2 -1
- package/docs/adr/0014-what-follows-a-write-join.md +1 -1
- package/docs/adr/0022-stay-on-0x-while-every-consumer-is-first-party.md +88 -0
- package/docs/adr/0023-a-write-runs-in-a-transaction-or-not-at-all.md +60 -0
- package/docs/adr/0024-the-consumer-maps-driver-codes-through-dberrors.md +78 -0
- package/docs/adr/0025-validatebulk-replaces-validate-in-a-bulk-upsert.md +46 -0
- package/docs/adr/0026-update-carries-its-primary-key-in-main.md +43 -0
- package/docs/adr/0027-the-1-0-contract.md +74 -0
- package/docs/adr/0028-select-star-is-the-default-projection.md +64 -0
- package/docs/adr/0029-a-write-names-its-child-rows-by-action.md +96 -0
- package/docs/adr/0030-a-child-row-is-validated-by-its-own-table.md +117 -0
- package/docs/adr/0031-an-insert-excluded-upsert-key-addresses-an-existing-row.md +58 -0
- package/docs/adr/0032-tenant-scope-names-schema-fields.md +56 -0
- package/docs/adr/README.md +12 -1
- package/docs/upgrading/0.x.md +906 -0
- package/docs/upgrading/1.0.md +628 -0
- package/package.json +4 -5
package/CHANGELOG.md
CHANGED
|
@@ -2,12 +2,253 @@
|
|
|
2
2
|
|
|
3
3
|
All notable changes to this project are documented here. This project follows
|
|
4
4
|
[Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and adheres to
|
|
5
|
-
[Semantic Versioning](https://semver.org/)
|
|
6
|
-
|
|
5
|
+
[Semantic Versioning](https://semver.org/): from 1.0, a breaking change bumps the major
|
|
6
|
+
([ADR 0027](./docs/adr/0027-the-1-0-contract.md)). Through 0.x, a breaking change bumped the
|
|
7
|
+
minor and never the patch ([ADR 0022](./docs/adr/0022-stay-on-0x-while-every-consumer-is-first-party.md)).
|
|
7
8
|
|
|
8
|
-
Migration instructions
|
|
9
|
+
Migration instructions, one guide per release line, indexed in
|
|
10
|
+
[BREAKING_CHANGES.md](./BREAKING_CHANGES.md): **[docs/upgrading/1.0.md](./docs/upgrading/1.0.md)**
|
|
11
|
+
from 0.5 to 1.0, [docs/upgrading/0.x.md](./docs/upgrading/0.x.md) for the 0.x releases.
|
|
9
12
|
|
|
10
|
-
## [
|
|
13
|
+
## [1.0.0] - 2026-11-18
|
|
14
|
+
|
|
15
|
+
The API made coherent in one breaking release: one name and one place for each concept, one
|
|
16
|
+
shape for each result, every retired key refused rather than ignored. **Upgrading from 0.5:
|
|
17
|
+
[docs/upgrading/1.0.md](./docs/upgrading/1.0.md)**, one guide for the whole release. The contract
|
|
18
|
+
of 1.0 — what is public, how it changes — is [ADR 0027](./docs/adr/0027-the-1-0-contract.md),
|
|
19
|
+
which supersedes ADR 0022.
|
|
20
|
+
|
|
21
|
+
1.0.0 follows 0.5.1. The 0.6.0 prepared after it, TypeBox 1.x and a first cleanup of the public
|
|
22
|
+
names, was never published: its changes are listed here and covered by the same guide.
|
|
23
|
+
|
|
24
|
+
### Added
|
|
25
|
+
|
|
26
|
+
- **`extendedCondition` receives `{ col }`**, its third argument: `col(field)` is the column
|
|
27
|
+
quoted for the dialect and qualified for the statement the condition lands in — the table in
|
|
28
|
+
the main search and in a side query, the alias inside a join's correlated subquery. A bare
|
|
29
|
+
`Schema.col()` was unquoted (a camelCase column failed on PostgreSQL) and a table-name prefix
|
|
30
|
+
bound to the outer row inside a self-relation's subquery. Typed by the schema's fields; a
|
|
31
|
+
name that is not one throws. Type `ExtendedConditionContext`.
|
|
32
|
+
- **`replace` in a write request** ([ADR 0029](./docs/adr/0029-a-write-names-its-child-rows-by-action.md)):
|
|
33
|
+
the complete set of child rows of an alias — the rows sent are upserted, every other child
|
|
34
|
+
row of the main row is deleted and reported under `deletions`, in the response and to
|
|
35
|
+
`afterInsert`/`afterUpdate`. `[]` removes them all. Needs the relation's `upsertKey`, which
|
|
36
|
+
the manifest now reports on each write join. In a bulk upsert, an item with a `replace` runs
|
|
37
|
+
its child rows in a transaction of its own.
|
|
38
|
+
- **The agent manifest reports a table's own `upsertKey`** (JSON and markdown, with its rule in
|
|
39
|
+
the legend): what every row of an insert or bulk upsert must carry, and that a
|
|
40
|
+
`serverGenerated` key only names an existing row. It already reported a write join's.
|
|
41
|
+
- **Every type a public signature names is exported**: `ApiReply`, `BuildRelationOptions`,
|
|
42
|
+
`JoinFetchRequest`, `JoinRefFilter`, `BulkUpsertOptions`, `ManifestField`, `ManifestJoin`,
|
|
43
|
+
`ValidatorResult` (what `validate` returns), `PrimaryKeyValue`, `WriteJoinSections`, and the
|
|
44
|
+
adapters' parameter types `PgQueryable` and `MysqlQueryable`, which a consumer could only
|
|
45
|
+
reach through another type before. The dependency types the public signatures name are
|
|
46
|
+
re-exported too, so a consumer needs no direct dependency on them: `TSchema`, `TObject`,
|
|
47
|
+
`TUnsafe` (TypeBox) and `ConditionValueOrUndefined` (node-condition-builder).
|
|
48
|
+
- **A secondary's `beforeInsert` sees the FK to the main row** already filled in, over the
|
|
49
|
+
client's value; the engine still fills it again after the hook, which cannot move it.
|
|
50
|
+
- **Bulk delete on a composite primary key.** `POST /bulk/:table/delete` and
|
|
51
|
+
`sqlApi.bulkDelete()` take one object per key, `{ ids: [{ postId: 1, tagId: 2 }] }`, matched
|
|
52
|
+
on every key column; the hooks receive the same objects, typed `PrimaryKeyValue`. A link
|
|
53
|
+
table (M:N) no longer needs a custom route. `get` and `delete` by `:id` stay unavailable on
|
|
54
|
+
such a table.
|
|
55
|
+
- **`dbErrors`**: driver error codes the consumer answers with an HTTP status and a code of
|
|
56
|
+
its own instead of the sanitized 500, keyed by `err.code` as the driver raises it:
|
|
57
|
+
`dbErrors: { '23505': { status: 409, code: 'duplicate' } }` (`'ER_DUP_ENTRY'` on
|
|
58
|
+
MySQL/MariaDB). The answer keeps the error envelope with `fields: [{ path: '', code }]`, and
|
|
59
|
+
no driver detail. The plugin ships no mapping (ADR 0024). An invalid entry fails
|
|
60
|
+
registration. Exported type `DbErrorMapping`.
|
|
61
|
+
- **One error envelope**, `{ statusCode, error, message, requestId, fields? }`, for every error
|
|
62
|
+
the routes return. `error` is the reason phrase, `requestId` the log's `reqId`, and every 400
|
|
63
|
+
carries `fields: [{ path, code, message }]` — the engine's rejections included, with a stable
|
|
64
|
+
code and the request path of the offending value. Codes and the path grammar are listed in
|
|
65
|
+
AGENTS_FRONTEND.md. `httpError(400, msg, { code, path })` is exported, for hooks.
|
|
66
|
+
- **Plugin option `operations`**: the operations a registration exposes, intersected with each
|
|
67
|
+
table's own. The agent manifest of the registration and `agentToolSchemas(…, { operations })`
|
|
68
|
+
follow it.
|
|
69
|
+
- **Plugin option `decorate`** (default `true`): `false` for every registration but the one
|
|
70
|
+
owning `app.sqlApi`.
|
|
71
|
+
- **`select` in search**: the fields to project, schema and computed alike, over HTTP and in
|
|
72
|
+
`sqlApi.search()`. The primary key, the keys the requested joins correlate on and, with
|
|
73
|
+
`distinctResults`, the ORDER BY fields are always projected. `'*'` stands for every readable
|
|
74
|
+
field: `['*', 'fullName']` adds a computed field without listing the others.
|
|
75
|
+
- **`compute` in search**: `{ min, max, sum, avg, count, distinctCount }`, several fields per
|
|
76
|
+
function, answered in a top-level `computed` over every matching row, with or without a
|
|
77
|
+
paginator.
|
|
78
|
+
- **`action: 'inserted' | 'updated'`** on the single insert response and on every item of the
|
|
79
|
+
bulk upsert response. Exported types `WriteAction`, `WrittenRow`.
|
|
80
|
+
- **`upsertKey`** on the table (main rows) and on `buildRelation` (the secondaries of a write
|
|
81
|
+
join), verified at startup (ADR 0021).
|
|
82
|
+
- **`target` on `buildRelation`**: the `dbTables` key whose config governs the joined table,
|
|
83
|
+
required when that table sits under several keys.
|
|
84
|
+
- **`TENANT_ADMIN`**: what `getTenantId` returns for unrestricted access. Exported types
|
|
85
|
+
`TenantAdmin`, `TenantResolution`, `GetTenantId`.
|
|
86
|
+
- **Hook context types**: `HookContext`, `WriteRecord`, `WriteHookContext`,
|
|
87
|
+
`AfterInsertContext`, `AfterUpdateContext`, `AfterReadContext`, `ReadSource`,
|
|
88
|
+
`DeleteHookContext`, `BulkDeleteHookContext`, `ValidateContext`, `BulkValidateContext`.
|
|
89
|
+
- **`QueryClient.supportsTransactions`**, and `Date` as a QueryClient value.
|
|
90
|
+
- **`createSqlApi` infers the table names** of the `dbTables` it is given: a misspelled one
|
|
91
|
+
fails at compile time.
|
|
92
|
+
- **Types** `TableDefinition` (what `defineTable` takes), `ValidationField`, `ComputeFn`,
|
|
93
|
+
`ComputeRequest`, `ComputedResult`, `RowsByAlias`, `SqlApiBulkDeleteParams`, `CliConfig`.
|
|
94
|
+
- **ADRs 0023–0032**: a write runs in a transaction or not at all; `dbErrors`; `validateBulk`
|
|
95
|
+
replaces `validate` in a bulk upsert; an update carries its primary key in `main`; the 1.0
|
|
96
|
+
contract; `*` is the default projection
|
|
97
|
+
([0028](./docs/adr/0028-select-star-is-the-default-projection.md)); a write names its child
|
|
98
|
+
rows by action; a child row is validated by its own table; an insert-excluded upsert key
|
|
99
|
+
addresses an existing row; tenant scope names schema fields.
|
|
100
|
+
- **`tenantScope` names schema fields**, like every other key of a table config
|
|
101
|
+
([ADR 0032](./docs/adr/0032-tenant-scope-names-schema-fields.md)): `column`, `anyOf` and
|
|
102
|
+
`through.localField` resolve through the table's schema, the indirect `column` and
|
|
103
|
+
`through.foreignField` through `through.schema`. The column of a field is accepted as written,
|
|
104
|
+
so a scope naming columns keeps working; any other name fails `defineTable` at startup, where a
|
|
105
|
+
misspelling used to fail as a 500 on the first query. The startup error for a field name is gone,
|
|
106
|
+
and the CLI `tables` template, which already wrote `localField` as a field, is now correct.
|
|
107
|
+
|
|
108
|
+
### Changed
|
|
109
|
+
|
|
110
|
+
Every entry below is breaking; [docs/upgrading/1.0.md](./docs/upgrading/1.0.md) has the migration for each.
|
|
111
|
+
|
|
112
|
+
- **TypeBox 1.x** ([`typebox`](https://www.npmjs.com/package/typebox)) replaces
|
|
113
|
+
`@sinclair/typebox` 0.34. `Type` and `Static` re-exported by this package now come from it.
|
|
114
|
+
Code that imports `Type` from `fastify-auto-sqlapi`, as the generated schema files do, needs
|
|
115
|
+
no change. Schemas built with `@sinclair/typebox` directly must move to `typebox` 1.x, or
|
|
116
|
+
their `Type.Optional` fields silently become required. Schemas from any `typebox` 1.x copy,
|
|
117
|
+
such as the one `@fastify/type-provider-typebox` 6 brings in, now mix freely with this
|
|
118
|
+
package's.
|
|
119
|
+
- **Plugin and `createSqlApi`**
|
|
120
|
+
- The plugin option `DbTables` is `dbTables`.
|
|
121
|
+
- `getTenantId` returning `null`/`undefined` is a 401 on every table with a tenant scope in
|
|
122
|
+
reach; unrestricted access is `TENANT_ADMIN`.
|
|
123
|
+
- A second registration in the same scope, or one over an application `sqlApi`, fails
|
|
124
|
+
unless it passes `decorate: false`.
|
|
125
|
+
- The plugin is the one way to mount the routes: the route plugins and `setupSwagger` are no
|
|
126
|
+
longer exported.
|
|
127
|
+
- `createSqlApi` takes the dialect from a QueryClient; a `dialect` option beside one throws.
|
|
128
|
+
- A write needs a `Queryable` with `connect()`: without it, inserts and updates throw instead
|
|
129
|
+
of running unprotected (ADR 0023).
|
|
130
|
+
- **Table configuration**
|
|
131
|
+
- `defineTable({ primary, schema, extraFilters, extendedCondition, … })` replaces the spread
|
|
132
|
+
of `exportTableInfo()`; the config carries `schema`, not `Schema`.
|
|
133
|
+
- `allowedReadJoins` / `allowedWriteJoins` are `readJoins` / `writeJoins`.
|
|
134
|
+
- `excludeFromCreation` is `insertExclude`, aligned with `readExclude` / `writeExclude`. Same
|
|
135
|
+
behaviour; the table generator writes the new name.
|
|
136
|
+
- The type `ITable` is `TableConfig`, as the glossary calls the concept.
|
|
137
|
+
- `upsertMap` and `buildUpsertRule(s)` are replaced by `upsertKey`.
|
|
138
|
+
- `defaultOrder` has the 1-part `orderBy` grammar, checked at startup; no raw SQL.
|
|
139
|
+
- `buildRelation({ selection })` is `{ select: [...] }`, checked against the joined schema.
|
|
140
|
+
- A relation over a table exposed under several keys must name its `target`.
|
|
141
|
+
- A `tenantScope` name that is neither a field of its schema nor the column of one fails at
|
|
142
|
+
startup; it was taken as a column (ADR 0032).
|
|
143
|
+
- Every pre-1.0 key throws at startup, naming its replacement.
|
|
144
|
+
- **Hooks**
|
|
145
|
+
- Every hook and validator receives one context object, `{ db, req, …data }`; `req` may be
|
|
146
|
+
`undefined`.
|
|
147
|
+
- `validate` and `validateBulk` return `{ path, code }` objects; tuples, a `message`, or a
|
|
148
|
+
result that is not an array are a programming error. `ValidationError` is gone.
|
|
149
|
+
- `ValidationField.message` is optional: absent on the fields a validator returned and on a
|
|
150
|
+
`dbErrors` answer, where it only repeated the code or the reason phrase.
|
|
151
|
+
- `beforeInsert` and `afterInsert` may return `void`, like every other hook; the secondaries
|
|
152
|
+
and deletions given to `afterInsert` and `afterUpdate` are typed `RowsByAlias`, not
|
|
153
|
+
`unknown`. Type-level only.
|
|
154
|
+
- **`sqlApi` and the QueryClient**
|
|
155
|
+
- `sqlApi.insert` / `update` take `{ main, … }`, the HTTP body; `record` throws.
|
|
156
|
+
- `sqlApi.bulkDelete` takes `{ ids }`.
|
|
157
|
+
- An unknown table in `sqlApi` throws an `Error`; it was a 400 `unknown_table`.
|
|
158
|
+
- The QueryClient upserts with `upsert` and `bulkUpsert`, both answering `{ pk, action }`;
|
|
159
|
+
`bulkUpsert` takes `{ chunkSize, immutableCols }`. `insertOrUpdate`,
|
|
160
|
+
`bulkInsertOrUpdate` and their `*WithAction` versions are gone.
|
|
161
|
+
- **Exports**: the package entry exports the public API only. Gone: the engines, the schema
|
|
162
|
+
builders, `SearchTableQuery` and `SearchTableQueryString`, the naming helpers,
|
|
163
|
+
`getDialect`/`SqlDialect`, `resolveTenant`/`TenantContext`, the engine parameter types,
|
|
164
|
+
`ColumnInfo`, `TableMap`, and `escapeIdent`, which escaped PostgreSQL identifiers only and was
|
|
165
|
+
wrong on MySQL (`db.qi()` replaces it). `SqlApiConfig` is `CliConfig`.
|
|
166
|
+
- **CLI**
|
|
167
|
+
- `sqlapi-generate-schema` connects through one URL whose scheme names the dialect, from
|
|
168
|
+
`--url`, `connection` in `sqlapi.config`, or `DATABASE_URL`, in this order; the `.env` of
|
|
169
|
+
the current directory is loaded before the config. `POSTGRES_*` / `MYSQL_*` are no longer
|
|
170
|
+
read, and with no URL the run fails: it used to fall back to the library's test database.
|
|
171
|
+
- `dialect` and `envFile` in the config and `--dialect` are refused, as is any unknown key or
|
|
172
|
+
option; a config that fails to load fails the run instead of falling back to the defaults.
|
|
173
|
+
- The schema CLI prints the database it introspects, password masked; MySQL credentials in
|
|
174
|
+
the URL are percent-decoded.
|
|
175
|
+
- **HTTP**
|
|
176
|
+
- The search request travels in the body only: `orderBy`, `page`, `itemsPerPage` and
|
|
177
|
+
`computeMin|Max|Sum|Avg` in the querystring are a 400 `retired_key`.
|
|
178
|
+
- `select` replaces `selectComputed` and a join's `selection`, both a 400 `retired_key`.
|
|
179
|
+
- `compute` answers in a top-level `computed`, not `pagination.computed`.
|
|
180
|
+
- `joinGroup` takes `by` and the functions directly, and always answers `{ rows: [...] }`
|
|
181
|
+
with `{ by, sum: { total } }` rows.
|
|
182
|
+
- `POST /bulk/:table/delete` takes `{ ids: [...] }`.
|
|
183
|
+
- A write names its child rows by action: `secondaries` is `upsert`, `deletions` is `delete`,
|
|
184
|
+
and the old keys are a 400 `retired_key`; the response keeps `secondaries` and `deletions`
|
|
185
|
+
for what was written and removed. `validate` receives `{ main, upsert, replace }` (ADR 0029).
|
|
186
|
+
- A child row written through a write join is validated by its own table: the child's
|
|
187
|
+
`validate` (or `validateBulk`, once per alias) runs before any SQL, with
|
|
188
|
+
`parent: { alias, main }`, and its errors answer at `upsert.<alias>.<i>.<field>`. A
|
|
189
|
+
required-FK rule guards on `!parent`: the FK is known only when the request names the
|
|
190
|
+
parent's key (ADR 0030).
|
|
191
|
+
- An alias under `upsert`, `delete` or `replace` not declared in `writeJoins` is a 400
|
|
192
|
+
`unknown_field`, and nothing is written: it was dropped in silence.
|
|
193
|
+
- `error` in an error response is the HTTP reason phrase for every status.
|
|
194
|
+
|
|
195
|
+
### Fixed
|
|
196
|
+
|
|
197
|
+
- **A response the Schema could not serialize leaked the stored value**: a column changed in the
|
|
198
|
+
database after its Schema was generated made the serializer refuse a row, and its message —
|
|
199
|
+
quoting the value — reached the client as the 500's `message`, unlogged. The error is raised
|
|
200
|
+
after the route handler, outside its sanitization; it is now the fixed 500 like any other
|
|
201
|
+
(ADR 0013), with the original in the log under the request's id and, under
|
|
202
|
+
`exposeDebugInfo`, in `debugInfo`.
|
|
203
|
+
- **An upsert by a key under `insertExclude` duplicated the rows it meant to update**
|
|
204
|
+
([ADR 0031](./docs/adr/0031-an-insert-excluded-upsert-key-addresses-an-existing-row.md)):
|
|
205
|
+
`upsertKey: ['id']` with the `insertExclude: ['id']` the CLI generates stripped the key, so
|
|
206
|
+
every row sent with an id was inserted again under a new one — main rows and the child rows
|
|
207
|
+
of a write join alike. The key now updates the row it names; a key naming no row is a 400
|
|
208
|
+
`not_found` at its path, and a row without the key is inserted as before.
|
|
209
|
+
- **`pgQueryable(new pg.Pool())` and `pgQueryable(fastify.pg)` did not compile** (TS2345): the
|
|
210
|
+
type of `connect()` required the checked-out client to have a `connect()` of the same type,
|
|
211
|
+
which pg's `PoolClient` does not. The checked-out client now needs only `query` and
|
|
212
|
+
`release`; `mysqlQueryable` is aligned. A `pg.Client` stays refused: its `connect()` opens
|
|
213
|
+
the connection, it does not check one out.
|
|
214
|
+
- **`app.sqlApi` was untyped for a consumer** (TS2339): the `FastifyInstance` augmentation sat
|
|
215
|
+
in a module the package's declarations reached only through a type-only import, which the
|
|
216
|
+
emitted `.d.ts` drops. It is now declared in the plugin module itself.
|
|
217
|
+
- **The 400 for an aggregation grouped by a non-FK column said "Cannot order by" in a condition
|
|
218
|
+
too**: its message now names the clause it was found in (path and code were already right).
|
|
219
|
+
- **A delete under an indirect tenant scope failed on MySQL and MariaDB** (error 1093): the
|
|
220
|
+
DELETE named its rows through a subquery reading the same table. It now tests the parent
|
|
221
|
+
with a correlated `EXISTS`, as the deletions of a write join already did;
|
|
222
|
+
`DELETE /rest/:table/:id` and bulk delete both work.
|
|
223
|
+
- **A search without a paginator was paginated.** The querystring schema declared a default
|
|
224
|
+
`itemsPerPage`, which Ajv injected before the handler: every search ran a `COUNT(*)` and
|
|
225
|
+
answered page 1 of 500 rows. It now returns up to `maxItemsPerPage` rows, without
|
|
226
|
+
`pagination`.
|
|
227
|
+
- **A second registration of the plugin ran its routes with the first one's configuration**:
|
|
228
|
+
its `dbTables`, `getTenantId` and table rules — a tenant scope declared only on the second
|
|
229
|
+
surface was not applied. Each registration's routes run through its own SqlApi.
|
|
230
|
+
- **A join target's config applied only when its `dbTables` key was the table name.**
|
|
231
|
+
Otherwise its `readExclude` fields were returned through `joinMultiple` and `joinLeft`.
|
|
232
|
+
- **An update on a table whose tenant column is camelCase failed with a 500** on PostgreSQL:
|
|
233
|
+
the tenant predicate named the column unquoted.
|
|
234
|
+
- **A search with computed fields and a JOIN on the main query returned the joined table's
|
|
235
|
+
columns in the main rows** (also fixed in 0.5.1).
|
|
236
|
+
- **`GET|DELETE /rest/:table/:id` validate `:id` against the primary key's type**: a 400 on
|
|
237
|
+
`id` instead of a 500, and the value reaches SQL with the key's type.
|
|
238
|
+
|
|
239
|
+
## [0.5.1]
|
|
240
|
+
|
|
241
|
+
### Fixed
|
|
242
|
+
|
|
243
|
+
- **A search with `selectComputed` and a JOIN on the main query returned the joined table's
|
|
244
|
+
columns in the main rows.** A filtered or ordered `joinLeft`, or a tenant scope with
|
|
245
|
+
`through`, adds a JOIN to the main statement; the `selectComputed` path built its
|
|
246
|
+
projection as a bare `*, <expr> AS "x"`, which bypassed the qualification `db.select`
|
|
247
|
+
applies to a plain `*`. On a column name shared with the joined table (`id`, `name`,
|
|
248
|
+
`createdAt`…) the driver keeps the last value read, so every main row carried the parent's
|
|
249
|
+
id and its extra columns. The main projection is now always `"table".*` or the table's
|
|
250
|
+
readable columns, qualified, whatever else is projected. Searches without `selectComputed`
|
|
251
|
+
were not affected.
|
|
11
252
|
|
|
12
253
|
## [0.5.0]
|
|
13
254
|
|
|
@@ -16,7 +257,7 @@ Migration instructions for breaking changes live in **[BREAKING_CHANGES.md](./BR
|
|
|
16
257
|
- **BREAKING: Node.js 22 or newer is required** (`engines.node` is now `>=22`, was `>=18`).
|
|
17
258
|
Node 18 and 20 are end-of-life, and Fastify 5 never supported Node 18. CI now runs the
|
|
18
259
|
full gate on Node 22, 24 and 26. See
|
|
19
|
-
[
|
|
260
|
+
[docs/upgrading/0.x.md](./docs/upgrading/0.x.md#breaking-change--nodejs-22-or-newer-is-required).
|
|
20
261
|
|
|
21
262
|
### Security
|
|
22
263
|
|
|
@@ -36,7 +277,7 @@ Migration instructions for breaking changes live in **[BREAKING_CHANGES.md](./BR
|
|
|
36
277
|
numeric columns, such mains now sort where the database puts NULL (PostgreSQL: last in ASC,
|
|
37
278
|
first in DESC; MySQL/MariaDB: first in ASC, last in DESC) instead of as 0, and a condition
|
|
38
279
|
like `max < 5` no longer matches them (`isNull` does). See
|
|
39
|
-
[
|
|
280
|
+
[docs/upgrading/0.x.md](./docs/upgrading/0.x.md#breaking-change--min-max-and-avg-of-a-main-row-without-children-are-null).
|
|
40
281
|
|
|
41
282
|
### Fixed
|
|
42
283
|
|
|
@@ -66,7 +307,7 @@ Migration instructions for breaking changes live in **[BREAKING_CHANGES.md](./BR
|
|
|
66
307
|
- the exported `SqlDialect` type loses `upsertSql()` and `upsertUpdateSet()`, replaced by
|
|
67
308
|
`onConflict?: { sql(), updateSet() }`, present on PostgreSQL only.
|
|
68
309
|
Regenerate the schemas; see
|
|
69
|
-
[
|
|
310
|
+
[docs/upgrading/0.x.md](./docs/upgrading/0.x.md#breaking-change--an-upsert-targets-a-unique-key-verified-at-startup).
|
|
70
311
|
|
|
71
312
|
### Fixed
|
|
72
313
|
|
|
@@ -120,7 +361,7 @@ Migration instructions for breaking changes live in **[BREAKING_CHANGES.md](./BR
|
|
|
120
361
|
manifest advertised a URL that did not exist. Routes are now `/search/<key>`,
|
|
121
362
|
`/rest/<key>`, `/bulk/<key>`, and the search response's `table` names the key too. Configs
|
|
122
363
|
generated by `sqlapi-generate-tables` use the table name as key and are unaffected. See
|
|
123
|
-
[
|
|
364
|
+
[docs/upgrading/0.x.md](./docs/upgrading/0.x.md#breaking-change--the-route-url-is-the-dbtables-key).
|
|
124
365
|
- **`fastify-plugin` 5 → 6.** The only runtime dependency bump: v6 renames its entry files and
|
|
125
366
|
drops the long-deprecated `PluginOptions` type (now `PluginMetadata`), neither of which this
|
|
126
367
|
library uses. No change for consumers; still Fastify 5.
|
|
@@ -409,7 +650,7 @@ Migration instructions for breaking changes live in **[BREAKING_CHANGES.md](./BR
|
|
|
409
650
|
one; it is still never called when nothing scoped is in reach. Tables that already declared
|
|
410
651
|
their own scope emit unchanged SQL. Migration — including the `getTenantId` body that now needs
|
|
411
652
|
to tolerate an unauthenticated request — in
|
|
412
|
-
[
|
|
653
|
+
[docs/upgrading/0.x.md](./docs/upgrading/0.x.md#breaking-change--the-tenant-follows-the-request-not-the-table-it-addresses).
|
|
413
654
|
|
|
414
655
|
- **Database errors no longer reach clients verbatim.** Any error escaping an auto-generated
|
|
415
656
|
route that the plugin did not raise itself now answers `{"statusCode":500,"error":"Internal
|
|
@@ -450,7 +691,7 @@ Migration instructions for breaking changes live in **[BREAKING_CHANGES.md](./BR
|
|
|
450
691
|
1024-character cap on the `orderBy` string), so Swagger advertises exactly what the engine
|
|
451
692
|
enforces. Both are exported as `MAX_CONDITIONS` and `MAX_ORDER_BY_PARTS`, and both are checked
|
|
452
693
|
**in the engine**, which is what covers `sqlApi.search()` — no schema validates a programmatic
|
|
453
|
-
caller. See [
|
|
694
|
+
caller. See [docs/upgrading/0.x.md](./docs/upgrading/0.x.md#breaking-change--request-limits-condition-arity-and-tenant-scope-inside-subqueries).
|
|
454
695
|
|
|
455
696
|
- **BREAKING: `paginator` is validated at runtime.** `page` and `itemsPerPage` are rendered
|
|
456
697
|
straight into `LIMIT`/`OFFSET`, and `Paginator` is a compile-time type only: nothing stopped a
|
|
@@ -526,7 +767,7 @@ Migration instructions for breaking changes live in **[BREAKING_CHANGES.md](./BR
|
|
|
526
767
|
and aggregations, which have always answered 400. The check lives in the engine, so it
|
|
527
768
|
covers `sqlApi.search()` as well as the HTTP routes. `undefined` values still mean "filter
|
|
528
769
|
not supplied" and are ignored; an explicit `null` still filters by `IS NULL`. See
|
|
529
|
-
[
|
|
770
|
+
[docs/upgrading/0.x.md](./docs/upgrading/0.x.md#breaking-change--unknown-filter-keys-are-rejected).
|
|
530
771
|
|
|
531
772
|
- **`joinLeft.<alias>.filters` no longer advertises the parent's `extraFilters`.** They were
|
|
532
773
|
present in the generated body schema and in Swagger, but `buildLeftJoinClauses` never runs
|
|
@@ -594,7 +835,7 @@ Migration instructions for breaking changes live in **[BREAKING_CHANGES.md](./BR
|
|
|
594
835
|
bulk upsert are unaffected — they already handled every PK column. If your composite table's
|
|
595
836
|
first PK column happens to be unique, these endpoints previously worked for you and are now
|
|
596
837
|
gone — see
|
|
597
|
-
[
|
|
838
|
+
[docs/upgrading/0.x.md](./docs/upgrading/0.x.md#breaking-change--by-single-id-operations-disabled-for-composite-primary-keys)
|
|
598
839
|
for the migration paths.
|
|
599
840
|
|
|
600
841
|
### Fixed
|
|
@@ -729,7 +970,7 @@ Migration instructions for breaking changes live in **[BREAKING_CHANGES.md](./BR
|
|
|
729
970
|
error. Computed fields that declare **no** bound values are unaffected — the majority case
|
|
730
971
|
(JSON extraction, `CONCAT`, `dateTrunc`, arithmetic) needs no change, and a literal `?` such
|
|
731
972
|
as the PostgreSQL jsonb operator keeps working.
|
|
732
|
-
See [
|
|
973
|
+
See [docs/upgrading/0.x.md](./docs/upgrading/0.x.md#breaking-change--computed-field-placeholders-use--markers).
|
|
733
974
|
|
|
734
975
|
### Added
|
|
735
976
|
|
|
@@ -780,11 +1021,13 @@ Migration instructions for breaking changes live in **[BREAKING_CHANGES.md](./BR
|
|
|
780
1021
|
## [0.1.3] and earlier
|
|
781
1022
|
|
|
782
1023
|
Released before this changelog was kept. See the git history for details: notable entries are
|
|
783
|
-
the join API redesign (documented in [
|
|
1024
|
+
the join API redesign (documented in [docs/upgrading/0.x.md](./docs/upgrading/0.x.md)), composite
|
|
784
1025
|
primary key support in updates, transactional insert/update with secondaries, the hook matrix,
|
|
785
1026
|
and bulk operations.
|
|
786
1027
|
|
|
787
|
-
[Unreleased]: https://github.com/LucaRainone/fastify-auto-sqlapi/compare/
|
|
1028
|
+
[Unreleased]: https://github.com/LucaRainone/fastify-auto-sqlapi/compare/v1.0.0...HEAD
|
|
1029
|
+
[1.0.0]: https://github.com/LucaRainone/fastify-auto-sqlapi/compare/v0.5.1...v1.0.0
|
|
1030
|
+
[0.5.1]: https://github.com/LucaRainone/fastify-auto-sqlapi/releases/tag/v0.5.1
|
|
788
1031
|
[0.5.0]: https://github.com/LucaRainone/fastify-auto-sqlapi/releases/tag/v0.5.0
|
|
789
1032
|
[0.4.1]: https://github.com/LucaRainone/fastify-auto-sqlapi/releases/tag/v0.4.1
|
|
790
1033
|
[0.4.0]: https://github.com/LucaRainone/fastify-auto-sqlapi/releases/tag/v0.4.0
|