fastify-auto-sqlapi 0.5.1 → 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 +246 -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 +93 -27
- 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 -64
- 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 +25 -16
- package/dist/lib/read-access.d.ts.map +1 -1
- package/dist/lib/read-access.js +33 -17
- 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/AGENTS.md
CHANGED
|
@@ -7,8 +7,9 @@ A Fastify plugin that generates REST CRUD endpoints (search, get, insert, update
|
|
|
7
7
|
- Calling the API (fetch, list page, form, agent tool): AGENTS_FRONTEND.md, whole file. It is the complete request grammar.
|
|
8
8
|
- This deployment's tables, fields and join aliases: `GET {prefix}/agent/manifest.md` (when `agentManifest` is on) or Swagger. The docs give the grammar, the manifest gives the vocabulary.
|
|
9
9
|
- Setting up the plugin, configuring tables, joins, tenant scope, hooks, validation, querying from custom routes/scripts/jobs (`sqlApi`), raw SQL in hooks (`db`): AGENTS_BACKEND.md.
|
|
10
|
-
-
|
|
11
|
-
- A behavior that looks wrong: docs/adr/ first. These include open-by-default `operations`, non-transactional bulk, always-updatable fields,
|
|
10
|
+
- Upgrading from 0.x: docs/upgrading/1.0.md (0.5 → 1.0), docs/upgrading/0.x.md for older releases; BREAKING_CHANGES.md indexes them.
|
|
11
|
+
- A behavior that looks wrong: docs/adr/ first. These include open-by-default `operations`, non-transactional bulk, always-updatable fields, sanitized DB errors mapped only through `dbErrors`, and joins not running the target's route guards. They are recorded decisions, not gaps.
|
|
12
|
+
- The routes answer errors with their own handler: an application `setErrorHandler` never sees them, an `onError` hook does (AGENTS_BACKEND.md, Rules).
|
|
12
13
|
|
|
13
14
|
These files are the contract. **Do not read the plugin's sources** (`node_modules/fastify-auto-sqlapi/dist/`): they are internal, carry no stability guarantee, and say nothing about which behaviors are deliberate. If the docs do not answer, say so and ask. Never copy an internal helper into consumer code.
|
|
14
15
|
|
|
@@ -25,10 +26,9 @@ This has two consequences:
|
|
|
25
26
|
|
|
26
27
|
## Naming
|
|
27
28
|
|
|
28
|
-
- camelCase schema field names everywhere: request/response bodies, `defineTable` keys, `buildRelation`, hooks, validators, `sqlApi.*`.
|
|
29
|
+
- camelCase schema field names everywhere: request/response bodies, `defineTable` keys (`tenantScope` included), `buildRelation`, hooks, validators, `sqlApi.*`.
|
|
29
30
|
- Real DB column names only where you address the database yourself:
|
|
30
31
|
- `db.*` (QueryClient) record keys, `where` and `conflictKeys`, plus the real table name `Schema.tableName`;
|
|
31
|
-
- `
|
|
32
|
-
- SQL you write (`extendedCondition`, computed `expr`), where columns come from `Schema.col('field')` / `qiCol('field')` and are never typed literally.
|
|
32
|
+
- SQL you write: in `extendedCondition` columns come from its `col('field')`, in a computed `expr` from `qiCol('field')`, both quoted and qualified for you; never typed literally.
|
|
33
33
|
|
|
34
34
|
The generated Schema maps between the two, whether the DB uses snake_case or camelCase. Clients always send camelCase, including when anchoring an `anyOf` tenant write.
|
package/AGENTS_BACKEND.md
CHANGED
|
@@ -1,39 +1,42 @@
|
|
|
1
1
|
# fastify-auto-sqlapi — backend reference (LLM)
|
|
2
2
|
|
|
3
|
-
Setting up the plugin and configuring tables. Client request grammar: AGENTS_FRONTEND.md.
|
|
3
|
+
Setting up the plugin and configuring tables. Client request grammar: AGENTS_FRONTEND.md. Upgrading from 0.x: docs/upgrading/1.0.md (index: BREAKING_CHANGES.md).
|
|
4
4
|
|
|
5
5
|
## Rules
|
|
6
6
|
|
|
7
|
-
- Everything is a camelCase **schema field name** (request/response bodies, `defineTable` keys
|
|
7
|
+
- Everything is a camelCase **schema field name** (request/response bodies, `defineTable` keys — `tenantScope` included —, hooks, `validate`, `sqlApi.*`, `buildRelation`). **Real DB column names** only where you talk to the database yourself: `db.*` (QueryClient) and any SQL string you write. Get them with `col('field')` in `extendedCondition`, `qiCol('field')` in a computed field, `Schema.col('field')` (unquoted) for `db.*`, never type them: columns may be snake_case or camelCase, the generated Schema knows which.
|
|
8
8
|
- `sqlApi` = high-level (camelCase, validation, hooks, tenant, joins, computed). `db` = the SQL layer under it (real names, none of that). Not interchangeable.
|
|
9
|
+
- **The routes answer their errors with their own handler: an application `app.setErrorHandler` never sees them** and cannot reshape the envelope. To log or report them, add `app.addHook('onError', async (req, reply, error) => …)` before registering the plugin: it runs for every route error, a 500 carrying the driver error under `error.cause`. To change what the client gets, throw `httpError` from a hook or map driver codes in `dbErrors` (the error envelope paragraph under defineTable).
|
|
9
10
|
- Do not read `node_modules/fastify-auto-sqlapi/dist/`: internal, unstable, not documentation. If this file does not answer, say so.
|
|
10
|
-
- Behaviors that look like bugs but are decisions (docs/adr/): default-open `operations`, non-transactional bulk, every field updatable,
|
|
11
|
+
- Behaviors that look like bugs but are decisions (docs/adr/): default-open `operations`, non-transactional bulk, every field updatable, a sanitized 500 on DB errors unless mapped in `dbErrors`, joins not running the target's route guards, no conditional/mass update route, `validateBulk` replacing `validate` in bulk, `PUT /rest/:table` taking the PK in `main`. Do not "fix" them.
|
|
11
12
|
|
|
12
13
|
## CLI: generate Schemas and tables
|
|
13
14
|
|
|
14
15
|
```ts
|
|
15
|
-
// sqlapi.config.ts — CLI only, never read at runtime. These
|
|
16
|
+
// sqlapi.config.ts — CLI only, never read at runtime. These five keys are all that exist, all optional; any other key fails the run.
|
|
17
|
+
import type { CliConfig } from 'fastify-auto-sqlapi';
|
|
16
18
|
export default {
|
|
19
|
+
connection: process.env.SHOP_DB_URL, // the database to introspect; omit it to use DATABASE_URL. Keep the password in .env, not here
|
|
17
20
|
outputDir: './src/db', // default './src/db'
|
|
18
|
-
schema: 'public', // PostgreSQL only
|
|
19
|
-
dialect: 'postgres', // 'postgres' | 'mysql' | 'mariadb'; or --dialect flag
|
|
20
|
-
envFile: '.env', // relative to cwd; useful in monorepos
|
|
21
|
+
schema: 'public', // PostgreSQL only; MySQL/MariaDB introspect the URL's database
|
|
21
22
|
excludeTables: ['knex_*'], // DB table names or * globs: no schema generated, old one removed
|
|
22
23
|
excludeColumns: ['*.password_hash', 'user.internal_*'], // "<table>.<column>" DB names, * globs. The column does not exist for the API at all (no read, write, filter, manifest). Cannot exclude a PK; a pattern leaving a table with no columns fails the run.
|
|
23
|
-
};
|
|
24
|
+
} satisfies CliConfig;
|
|
24
25
|
```
|
|
25
26
|
|
|
26
|
-
|
|
27
|
+
The connection is one URL whose scheme names the dialect: `postgres://` (or `postgresql://`), `mysql://`, `mariadb://`. First found wins: `--url`, then `connection` in the config, then `DATABASE_URL`. The `.env` in cwd is loaded before the config (a variable already set wins), so with `DATABASE_URL` in `.env` the commands take no argument. No URL → the run fails saying so; there is no default database. A `connection` key whose variable is unset fails too, rather than falling back to `DATABASE_URL`. Another env file: `process.loadEnvFile('.env.local')` at the top of the config. The schema CLI prints the database it introspects, password masked.
|
|
27
28
|
|
|
28
29
|
```bash
|
|
29
|
-
npx sqlapi-generate-schema
|
|
30
|
+
npx sqlapi-generate-schema # src/db/schemas/Schema*.ts — generated, NEVER edit (overwritten); --url <url> for a one-off database
|
|
30
31
|
npx sqlapi-generate-tables customer order # src/db/tables/Table*.ts + dbTables.ts — yours to edit
|
|
31
32
|
npx sqlapi-generate-tables --all # existing files are skipped, never overwritten
|
|
32
33
|
```
|
|
33
34
|
|
|
35
|
+
Both commands take `--output <dir>` (over the config's `outputDir`) and `--tables a,b` (DB table names; positional names work too). The schema command restricted to some tables neither removes orphan Schemas nor touches the others; without it, a Schema whose table is gone or excluded is deleted. An unknown option fails the run.
|
|
36
|
+
|
|
34
37
|
- The generated table files detect PKs, `*Id` foreign keys as relations, and put every other key in as commented code.
|
|
35
|
-
- The schema CLI prints what it could not decide for you: read that output. It
|
|
36
|
-
- Schema files import `Type` from `fastify-auto-sqlapi`
|
|
38
|
+
- The schema CLI prints what it could not decide for you: read that output. It names database-generated columns (`GENERATED ALWAYS AS`, put in the Schema's `generatedFields` and never writable) and views, whose PK the table generator infers or leaves as a TODO (see Views). Identity/auto-increment PKs need no action: the Schema makes them optional and the table generator lists them in `insertExclude`.
|
|
39
|
+
- Schema files import `Type` from `fastify-auto-sqlapi`; do the same for `schemaOverrides`, computed fields and extra filters. Any `typebox` 1.x schema works too, but one built with the legacy `@sinclair/typebox` 0.x loses its markers here: its `Type.Optional` fields silently become required. Their default export (`addSchema`) is optional, only for Swagger `$ref`.
|
|
37
40
|
|
|
38
41
|
## Server setup
|
|
39
42
|
|
|
@@ -46,17 +49,19 @@ import { dbTables } from './src/db/tables/dbTables.js';
|
|
|
46
49
|
const app = Fastify();
|
|
47
50
|
await app.register(fastifyPostgres, { connectionString: process.env.DATABASE_URL }); // → fastify.pg
|
|
48
51
|
await app.register(fastifyAutoSqlApi, {
|
|
49
|
-
|
|
52
|
+
dbTables, // required. Record key = route name: { customer } → /search/customer
|
|
50
53
|
dialect: 'postgres', // 'postgres' (default) | 'mysql' | 'mariadb'
|
|
51
54
|
prefix: '/auto', // standard Fastify prefix, applied once. None → /search/customer
|
|
52
55
|
swagger: true, // or { title, description, version, routePrefix }. Needs @fastify/swagger + @fastify/swagger-ui, else warns and continues
|
|
53
56
|
onRequests: [auth], // global hooks on every route
|
|
54
|
-
getTenantId: (req) => req.user?.organizationId
|
|
57
|
+
getTenantId: (req) => req.user?.organizationId, // see Tenant scope: undefined → 401 on scoped tables, TENANT_ADMIN → no filter
|
|
55
58
|
maxItemsPerPage: 1000, // search page cap AND the LIMIT when no paginator is sent → 400 above it
|
|
56
59
|
maxBulkItems: 1000, // bulk array cap → 400 above it
|
|
57
60
|
agentManifest: true, // GET {prefix}/agent/manifest(.md), behind the same onRequests
|
|
58
61
|
debug: true, // log SQL server-side; never changes a response
|
|
59
62
|
exposeDebugInfo: false, // DEV ONLY: add driver error (message, code, constraint, detail, stack) as `debugInfo` on 500s
|
|
63
|
+
decorate: true, // app.sqlApi for your own routes; false on every registration but one
|
|
64
|
+
dbErrors: { '23505': { status: 409, code: 'duplicate' } }, // driver err.code → { status (400–599), code } in fields, translated client-side; yours to list, per DB ('ER_DUP_ENTRY' on MySQL/MariaDB). Unlisted → 500
|
|
60
65
|
});
|
|
61
66
|
// app.sqlApi is now decorated, usable from any route.
|
|
62
67
|
|
|
@@ -64,56 +69,62 @@ await app.register(fastifyAutoSqlApi, {
|
|
|
64
69
|
const pool = mysql.createPool({ host, user, password, database });
|
|
65
70
|
app.decorate('mysql', pool);
|
|
66
71
|
app.addHook('onClose', () => pool.end());
|
|
67
|
-
await app.register(fastifyAutoSqlApi, {
|
|
68
|
-
|
|
69
|
-
//
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
}
|
|
72
|
+
await app.register(fastifyAutoSqlApi, { dbTables, dialect: 'mysql' });
|
|
73
|
+
|
|
74
|
+
// Several surfaces: register the plugin again under another prefix with `decorate: false` (app.sqlApi belongs to one registration; a second one without it fails at startup). Each registration's routes run with its own options.
|
|
75
|
+
// `operations` narrows a registration: intersected with each table's own (a composite-PK table is skipped for get/delete, not refused).
|
|
76
|
+
const publicTables = { customer: dbTables.customer }; // a narrower map of your table configs
|
|
77
|
+
await app.register(fastifyAutoSqlApi, {
|
|
78
|
+
dbTables: publicTables, prefix: '/public', decorate: false,
|
|
79
|
+
operations: ['search', 'get'], // read-only: no insert/update/delete/bulk
|
|
80
|
+
swagger: true,
|
|
81
|
+
});
|
|
77
82
|
```
|
|
78
83
|
|
|
79
84
|
`pg` returns `numeric`/`int8` as strings and shifts `date`/`timestamp` to local time. The plugin leaves `pg.types` alone (global state). If you want numbers and verbatim dates, set this at startup:
|
|
80
85
|
|
|
81
86
|
```ts
|
|
87
|
+
import pg from 'pg';
|
|
82
88
|
pg.types.setTypeParser(pg.types.builtins.INT8, (v) => parseInt(v, 10));
|
|
83
89
|
pg.types.setTypeParser(pg.types.builtins.NUMERIC, (v) => parseFloat(v));
|
|
84
90
|
pg.types.setTypeParser(pg.types.builtins.DATE, (v) => v);
|
|
85
91
|
pg.types.setTypeParser(pg.types.builtins.TIMESTAMP, (v) => v);
|
|
86
92
|
```
|
|
87
93
|
|
|
88
|
-
HTTP responses coerce `"42"`
|
|
94
|
+
HTTP responses coerce a schema field (`"42"` → `42`) through the response schema. The `joinGroup` and `compute` aggregates are not coerced: they reach the client as the driver returns them — strings on `pg` (`"300.00"`, `"4"`), exact for any size. The parsers matter for those, for `sqlApi.*` results and for hook arithmetic; a parsed value beyond `Number.MAX_SAFE_INTEGER` (2^53 − 1) or with more significant digits than a double holds is no longer exact.
|
|
89
95
|
|
|
90
96
|
## defineTable
|
|
91
97
|
|
|
92
|
-
Every key except `primary` and `
|
|
98
|
+
Every key except `primary` and `schema` is optional. There is no `tableName` key: the SQL table is `schema.tableName`, and the route/manifest name is the `dbTables` key. One physical table can therefore be exposed under several keys, each with its own `operations`, `onRequests`, `tenantScope`, `readExclude` and joins.
|
|
93
99
|
|
|
94
100
|
```ts
|
|
95
|
-
import { defineTable,
|
|
96
|
-
import type {
|
|
97
|
-
import { SchemaCustomer as Schema } from '../schemas/SchemaCustomer';
|
|
101
|
+
import { defineTable, buildRelation, ConditionBuilder, Type } from 'fastify-auto-sqlapi';
|
|
102
|
+
import type { ValidatorResult } from 'fastify-auto-sqlapi';
|
|
103
|
+
import { SchemaCustomer as Schema } from '../schemas/SchemaCustomer.js';
|
|
104
|
+
import { SchemaOrder } from '../schemas/SchemaOrder.js';
|
|
105
|
+
import { decrypt } from '../../crypto.js'; // yours
|
|
98
106
|
|
|
99
107
|
export const TableCustomer = defineTable({
|
|
100
|
-
primary: 'id', // or ['agentId', 'teamId']. Composite PK: no get/delete
|
|
101
|
-
|
|
102
|
-
//
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
}
|
|
111
|
-
|
|
112
|
-
condition.
|
|
113
|
-
}
|
|
108
|
+
primary: 'id', // or ['agentId', 'teamId']. Composite PK: no get/delete-by-`:id` routes (listing them in `operations` throws, sqlApi.* → 400); read with search, write with update (matches all PK columns), delete with bulkDelete, `{ ids: [{ agentId, teamId }] }`.
|
|
109
|
+
|
|
110
|
+
schema: Schema, // required: the generated Schema. Column filters (`col = value`, null → IS NULL) come from it.
|
|
111
|
+
|
|
112
|
+
// Extra filters: non-column search filters (a record of fields or a Type.Object). Not applied as `col = value`, only via extendedCondition. Not usable under joinLeft (400); use joinMustExist.
|
|
113
|
+
extraFilters: { q: Type.String(), dateFrom: Type.String(), dateTo: Type.String() },
|
|
114
|
+
extendedCondition: (condition, filters, { col }) => { // `filters` is typed with schema + extra keys
|
|
115
|
+
// col(field): the column quoted and qualified for where this runs (main search, or a join's subquery under its alias). Always use it: a bare Schema.col() is unquoted and unqualified
|
|
116
|
+
if (filters.q) {
|
|
117
|
+
const or = new ConditionBuilder('OR');
|
|
118
|
+
or.isILike(col('name'), `%${filters.q}%`);
|
|
119
|
+
or.isILike(col('email'), `%${filters.q}%`);
|
|
120
|
+
condition.append(or);
|
|
121
|
+
}
|
|
122
|
+
// undefined values are skipped; a missing bound turns isBetween into >= / <=
|
|
123
|
+
condition.isBetween(col('orderDate'), filters.dateFrom, filters.dateTo);
|
|
124
|
+
},
|
|
114
125
|
// Unknown filter keys (not a field, extra filter or computed) are 400, on main and every join, over HTTP and sqlApi alike.
|
|
115
126
|
|
|
116
|
-
defaultOrder: 'name ASC, id DESC', //
|
|
127
|
+
defaultOrder: 'name ASC, id DESC', // the 1-part orderBy grammar: schema or computed fields, ASC|DESC. No dotted notation, no SQL (an expression → computedFields). Checked at startup
|
|
117
128
|
distinctResults: true, // SELECT DISTINCT
|
|
118
129
|
operations: ['search', 'get'], // HTTP route whitelist. OMITTED = ALL ROUTES (default-open). Does not restrict sqlApi.* nor joins pointing at this table.
|
|
119
130
|
onRequests: [async (req, reply) => { // per-table hooks, after the global ones
|
|
@@ -121,24 +132,21 @@ export const TableCustomer = defineTable({
|
|
|
121
132
|
}],
|
|
122
133
|
|
|
123
134
|
// --- field visibility ---
|
|
124
|
-
|
|
125
|
-
readExclude: ['passwordHash'], // never projected (search, get, default join
|
|
135
|
+
insertExclude: ['id', 'createdAt'], // MUST list auto-increment PKs (CLI does it). Strips CLIENT input on insert only: beforeInsert and the FK auto-fill may still set it. A field of the upsertKey is kept: it names an existing row, never a new one (no such row → 400 not_found, ADR 0031). Not a security tool: every field stays updatable (ADR 0004).
|
|
136
|
+
readExclude: ['passwordHash'], // never projected (search, get, default join projection); naming it in filters/conditions/orderBy/aggregations/select → 400. Still writable. Static, applies to admins too. PK not allowed.
|
|
126
137
|
writeExclude: ['searchVector'], // dropped from insert/update/bulk bodies and in the engines; still readable. For trigger-owned columns; GENERATED columns need nothing. Runs after hooks. Not PK, not also in readExclude (that is excludeColumns).
|
|
127
138
|
schemaOverrides: { email: Type.String({ format: 'email' }) }, // stricter type for WRITE bodies only (responses and filters keep the generated type: stored rows predate the rule). Taken verbatim: no Optional → mandatory, no Nullable → null rejected.
|
|
128
139
|
|
|
129
140
|
// --- joins (see Relations) ---
|
|
130
|
-
|
|
131
|
-
|
|
141
|
+
readJoins: [buildRelation(Schema, 'id', SchemaOrder, 'customerId', { alias: 'orders' })],
|
|
142
|
+
writeJoins: [buildRelation(Schema, 'id', SchemaOrder, 'customerId', { alias: 'orders', upsertKey: ['id'] })], // upsertKey: the child rows of this relation upsert on it, and it can be replaced
|
|
132
143
|
|
|
133
|
-
// --- upsert: INSERT
|
|
134
|
-
|
|
135
|
-
|
|
136
|
-
buildUpsertRule(SchemaOrder, ['id']),
|
|
137
|
-
),
|
|
138
|
-
// Each upserted row must carry its key (natural key non-null; PK whole, or absent = plain insert), no two rows of a request may share it → 400. A row must still be insertable (PG: NOT NULL without default is required even for an existing row). Another row's unique value = DB error, never a hijack.
|
|
144
|
+
// --- upsert: the main row's INSERT (POST /rest, bulk upsert) becomes INSERT … ON CONFLICT (key) DO UPDATE ---
|
|
145
|
+
upsertKey: ['email'], // exactly the PK or one of the Schema's uniqueKeys, checked at startup (old Schemas: regenerate). Views: none. Main rows only; child rows use the relation's upsertKey. Absent: plain INSERT.
|
|
146
|
+
// Each upserted row must carry its key (natural key non-null; PK whole, or absent = plain insert), no two rows of a request may share it → 400. A key field in insertExclude (the generated PK) only names an existing row: none → 400 not_found. A row must still be insertable (PG: NOT NULL without default is required even for an existing row). Another row's unique value = DB error, never a hijack.
|
|
139
147
|
|
|
140
148
|
// --- tenant (see Tenant scope) ---
|
|
141
|
-
tenantScope: { column: '
|
|
149
|
+
tenantScope: { column: 'organizationId' }, // schema field, like every key here
|
|
142
150
|
|
|
143
151
|
// --- computed fields (see Computed fields) ---
|
|
144
152
|
computedFields: {
|
|
@@ -152,35 +160,39 @@ export const TableCustomer = defineTable({
|
|
|
152
160
|
},
|
|
153
161
|
|
|
154
162
|
// --- validation: after schema validation, before hooks and SQL. Any error → 400, nothing written ---
|
|
155
|
-
|
|
156
|
-
|
|
157
|
-
|
|
158
|
-
|
|
159
|
-
|
|
163
|
+
// Every hook and validator receives ONE context object: { db, req, ...data }. db = the client the
|
|
164
|
+
// operation runs on (inside a write, the transaction's); req = the request, undefined when sqlApi.*
|
|
165
|
+
// is called without one (guard req?.user). Data keys: record, secondaries, deletions, rows, id, ids, main, upsert, replace, parent, items.
|
|
166
|
+
validate: async ({ db, req, main, upsert, replace, parent }) => { // camelCase, the request's child-row sections keyed by alias; parent: { alias, main } when this row arrives as another table's child (ADR 0030), absent on this table's own routes
|
|
167
|
+
const errors: ValidatorResult = []; // { path, code }[], the fields of the 400, as is (no message: no prose, the client translates the code). path = dot path in the request body: main.<field>, upsert.<alias>.<i>.<field>, replace.<alias>.<i>.<field>, '' when not attributable. Anything else (a tuple, a message) → 500
|
|
168
|
+
if (!main.name) errors.push({ path: 'main.name', code: 'required' });
|
|
169
|
+
(upsert?.orders ?? []).forEach((o, i) => { // child rows are untyped: they follow the joined table's schema
|
|
170
|
+
if (Number(o.total) < 0) errors.push({ path: `upsert.orders.${i}.total`, code: 'min' });
|
|
171
|
+
});
|
|
160
172
|
return errors;
|
|
161
173
|
},
|
|
162
|
-
validateBulk: async (db, req, items) => { // bulk upsert: called once with [{ main,
|
|
174
|
+
validateBulk: async ({ db, req, items }) => { // bulk upsert: called once with the items as sent, [{ main, upsert?, delete?, replace? }]; when defined, per-item validate is skipped in bulk, so a rule that must hold in bulk is written here too (ADR 0025). Paths start with items.<i>
|
|
163
175
|
const codes = items.map((i) => i.main.code);
|
|
164
|
-
return new Set(codes).size === codes.length ? [] : [
|
|
176
|
+
return new Set(codes).size === codes.length ? [] : [{ path: '', code: 'batch_unique' }];
|
|
165
177
|
},
|
|
166
178
|
|
|
167
179
|
// --- hooks: camelCase records, mutations reach the SQL ---
|
|
168
|
-
beforeInsert: async (db, req, record) => {
|
|
169
|
-
record.createdBy = req
|
|
180
|
+
beforeInsert: async ({ db, req, record }) => {
|
|
181
|
+
record.createdBy = req?.user?.id;
|
|
170
182
|
record.createdAt = db.expression('NOW()'); // raw SQL value
|
|
171
183
|
},
|
|
172
|
-
beforeUpdate: async (db, req,
|
|
173
|
-
if (!req
|
|
174
|
-
|
|
184
|
+
beforeUpdate: async ({ db, req, record }) => { // PK present but not in SET
|
|
185
|
+
if (!req?.user?.isAdmin) delete record.isAdmin; // field-level rules: silent strip here, or 400 in validate
|
|
186
|
+
record.updatedAt = db.expression('NOW()');
|
|
175
187
|
},
|
|
176
|
-
afterInsert: async (db, req, record,
|
|
177
|
-
afterUpdate: async (db, req, record,
|
|
178
|
-
beforeDelete: async (db, req, id) => {}, // throw aborts; runs after tenant ownership is verified
|
|
179
|
-
afterDelete: async (db, req, id) => {}, // not called on 404
|
|
180
|
-
beforeBulkDelete: async (db, req, ids) => {}, // once; throw aborts the whole batch
|
|
181
|
-
afterBulkDelete: async (db, req,
|
|
182
|
-
afterRead: async (db, req, rows,
|
|
183
|
-
for (const row of rows) if (row.ssn
|
|
188
|
+
afterInsert: async ({ db, req, record, secondaries, deletions }) => {}, // record = input + generated PK; secondaries: child rows written; deletions: rows a replace removed, and in a bulk upsert the item's delete
|
|
189
|
+
afterUpdate: async ({ db, req, record, secondaries, deletions }) => {}, // inside the transaction: throw = rollback. deletions: rows of delete and of a replace
|
|
190
|
+
beforeDelete: async ({ db, req, id }) => {}, // throw aborts; runs after tenant ownership is verified
|
|
191
|
+
afterDelete: async ({ db, req, id }) => {}, // not called on 404
|
|
192
|
+
beforeBulkDelete: async ({ db, req, ids }) => {}, // once; throw aborts the whole batch. ids: values, or { <field>: value } on a composite PK
|
|
193
|
+
afterBulkDelete: async ({ db, req, ids }) => {}, // once, only the ids actually deleted
|
|
194
|
+
afterRead: async ({ db, req, rows, source, alias }) => { // see afterRead
|
|
195
|
+
for (const row of rows) if (typeof row.ssn === 'string') row.ssn = decrypt(row.ssn);
|
|
184
196
|
},
|
|
185
197
|
});
|
|
186
198
|
```
|
|
@@ -189,34 +201,38 @@ Nullable columns are generated as `Type.Optional(Nullable(T))`, i.e. `{ type: ['
|
|
|
189
201
|
|
|
190
202
|
Write bodies are closed (`additionalProperties: false`), so a column that is not in the Schema can never be written (no mass assignment). With Fastify's default `removeAdditional: true`, unknown properties are stripped silently. `Fastify({ ajv: { customOptions: { removeAdditional: false } } })` makes them a 400.
|
|
191
203
|
|
|
192
|
-
Errors the plugin raises itself are 4xx with client-safe messages. Anything else (a constraint violation, a hook throwing without `statusCode
|
|
204
|
+
Every error the routes return has one envelope, `{statusCode, error, message, requestId, fields?}` (AGENTS_FRONTEND.md, "Errors"): `error` is the reason phrase, `requestId` the log's `reqId`, and every 400 carries `fields` as `ValidationField[]`. Errors the plugin raises itself are 4xx with client-safe messages. To answer in the same shape from a hook, throw `httpError(400, 'Order is closed', { code: 'closed', path: 'main.status' })` (exported). A thrown 4xx is answered with its status and message, plus `fields` when `httpError` was given a `code`; a thrown 5xx is a server failure like any other and becomes the fixed 500 below, its message only in the log. Anything else (a constraint violation, a hook throwing without `statusCode`, a stored value the response schema refuses because the Schema predates a column change: regenerate it) returns a fixed `{statusCode:500, error, message:"Internal Server Error", requestId}`: the driver error is logged under that `requestId`. The plugin maps no code of its own (ADR 0006); to answer one with a status, list its driver code in `dbErrors` with a status and a code of yours: the response keeps the envelope, with the reason phrase as `message`, `fields: [{ path: '', code }]` whatever the status, and no driver detail (ADR 0024). An application `setErrorHandler` never sees these errors: the routes' own handler answers first; an application `onError` hook does see them (see Rules). `sqlApi.*` throws the driver error as is. Errors thrown by `onRequests` are unaffected.
|
|
193
205
|
|
|
194
206
|
## Relations
|
|
195
207
|
|
|
196
|
-
```ts
|
|
208
|
+
```ts signature
|
|
197
209
|
buildRelation(mainSchema, mainField, joinSchema, joinField, {
|
|
198
|
-
alias, // default joinSchema.tableName. Key in requests,
|
|
199
|
-
|
|
210
|
+
alias, // default joinSchema.tableName. Key in requests (upsert, delete, replace), responses (secondaries, deletions), dotted notation. Set it only to join one table twice or for a friendlier name. Duplicate alias → throws.
|
|
211
|
+
select, // default fields of the joined rows, e.g. ['id', 'name', 'total']; absent: every readable field. The request's select overrides it. A name the joined schema lacks → throws
|
|
200
212
|
unique, // false: 1:N child→main (joinField = child FK) → joinMustExist / joinMultiple / joinGroup. true: N:1 parent→main (joinField = parent PK) → joinLeft. joinField is the target's PK → use true.
|
|
201
213
|
fields, // read-only allowlist of the target's fields. Must include joinField. Not on write joins.
|
|
214
|
+
target, // dbTables key whose config governs the joined table (readExclude, tenantScope, afterRead, computed, write rules). Required when several keys expose that table: startup fails until it is set. With one key, that config applies whatever the key is called.
|
|
215
|
+
upsertKey, // write joins only: the child rows upsert on this key of the joined table, e.g. ['productId', 'lang']. Exactly its PK or one of its uniqueKeys, checked by defineTable (ADR 0021). Absent: plain INSERT, and the alias takes no `replace`. On a read join → throws.
|
|
202
216
|
});
|
|
217
|
+
```
|
|
203
218
|
|
|
204
|
-
|
|
219
|
+
```ts in=defineTable
|
|
220
|
+
readJoins: [
|
|
205
221
|
buildRelation(SchemaSession, 'createdBy', SchemaUser, 'id', { alias: 'creator', unique: true }),
|
|
206
222
|
buildRelation(SchemaSession, 'updatedBy', SchemaUser, 'id', { alias: 'updater', unique: true, fields: ['id', 'name'] }),
|
|
207
223
|
],
|
|
208
224
|
```
|
|
209
225
|
|
|
210
|
-
- **A read join is a read grant on the target.** It runs inside the
|
|
226
|
+
- **A read join is a read grant on the target.** It runs inside the main table's route: the target's `onRequests` and `operations` do not apply, so a table with `operations: []` is still readable through it. The target's `readExclude`, `tenantScope`, `afterRead` and the relation's schema still apply. `fields` narrows that schema, fail-closed: every other field is a 400 in `select`, filters, conditions, orderBy and aggregations, and so is a computed field reaching past it. A column added later is not reachable until listed. Use `readExclude` instead to hide a column from the table's own routes too. (ADR 0010, 0011)
|
|
211
227
|
- joinLeft adds a real `LEFT JOIN` only when filters or orderBy need the parent; otherwise it runs a side query.
|
|
212
|
-
- **Owned
|
|
213
|
-
- **What a write join runs on the child
|
|
228
|
+
- **Owned child rows** (translations, `*_info`, composite PK like `(product_id, lang)`): make them a write join on the parent, not a `dbTables` entry. The child FK is auto-filled, and an `upsertKey` on the relation (`{ alias: 'translations', upsertKey: ['productId', 'lang'] }`) lets clients send only the child's own fields: `PUT /rest/product { main, upsert: { translations: [{ lang: 'en', name: 'Bike' }] } }`. With that key the client can also send the whole set, `replace: { translations: [...] }`: the rows left out are deleted, in the write's transaction — in a bulk upsert, in the item's own (ADR 0029). Expose a composite-PK table standalone only when it stands on its own (M:N links).
|
|
229
|
+
- **What a write join runs on the child** (rows of `upsert` and `replace`): its `validate` — or its `validateBulk`, once per alias — before any SQL, after the main table's, with `parent: { alias, main }`. It answers in its own grammar, `main.<field>`, `main` or `''` (`validateBulk`: `items.<j>.main.<field>`, `items.<j>` or `''`; anything else is a 500), re-rooted to `upsert.<alias>.<i>.<field>` (`replace.…` for those rows, `<item>.` in front in a bulk upsert); then its `insertExclude`, the FK auto-fill, its `beforeInsert` (which sees the FK), the FK again, so it always wins, and its `tenantScope`. Not its `afterInsert` (ADR 0014, 0030). The child's `validate` sees the FK only when the request names the parent's key: guard a required-FK rule with `!parent`.
|
|
214
230
|
|
|
215
231
|
## Computed fields
|
|
216
232
|
|
|
217
|
-
A computed field is a SQL expression usable like a field in `filters`, `conditions`, `orderBy`, `
|
|
233
|
+
A computed field is a SQL expression usable like a field in `filters`, `conditions`, `orderBy`, `compute` and `joinGroup.<alias>.by`. It is projected only when listed in the request's `select`: `select: ['*', 'fullName']` returns every readable field plus it (ADR 0028).
|
|
218
234
|
|
|
219
|
-
```ts
|
|
235
|
+
```ts in=defineTable
|
|
220
236
|
computedFields: {
|
|
221
237
|
statusFromMeta: ({ db, qiCol }) => ({ // db: QueryClient (dialectName, dateTrunc, ...)
|
|
222
238
|
expr: db.dialectName === 'postgres'
|
|
@@ -240,15 +256,15 @@ computedFields: {
|
|
|
240
256
|
|
|
241
257
|
- Computed fields are per table: a join's side query uses the target table's computed fields. On joinLeft, `qiCol` adds the alias automatically.
|
|
242
258
|
- A name that collides with a schema field or an extra filter throws in `defineTable`.
|
|
243
|
-
- Bound `values` work in WHERE and ORDER BY positions. They are rejected (400) in `
|
|
259
|
+
- Bound `values` work in WHERE and ORDER BY positions. They are rejected (400) in `select`, `compute`, joinGroup `by` and `defaultOrder`.
|
|
244
260
|
- Limits: read-only (not writable), no computed field referencing another, not usable as a joinGroup aggregation field (`sum: [...]` takes schema fields). The expression is evaluated once per use.
|
|
245
261
|
|
|
246
262
|
## afterRead
|
|
247
263
|
|
|
248
264
|
The read-side counterpart of `beforeInsert`/`beforeUpdate`: decrypt, unpack, rescale. Declare it on the table that **owns** the column. It then runs wherever those rows surface: `ctx.source` is `get | search | joinMultiple | joinLeft`, and `ctx.alias` names the relation on joins. It is called once per result set and mutates the rows in place.
|
|
249
265
|
|
|
250
|
-
- It does not run on joinGroup, compute
|
|
251
|
-
- `filters`, `orderBy` and `compute
|
|
266
|
+
- It does not run on joinGroup, compute, or an empty result. It cannot add or remove rows (the COUNT has already run).
|
|
267
|
+
- `filters`, `orderBy` and `compute` act on the **stored** value, so an encrypted column is searched as ciphertext. With a deterministic cipher, encrypt the search value in `extendedCondition`. With a randomized cipher, the column cannot be searched.
|
|
252
268
|
- It changes values, not types: the response is serialized with the generated schema (an object in a `text` column becomes `"[object Object]"`). If the stored type and the API type differ, write a custom route.
|
|
253
269
|
- For encryption at rest, pair it with `beforeInsert` + `beforeUpdate` (as in the defineTable example). That covers own routes, joins, and writes as a secondary.
|
|
254
270
|
|
|
@@ -258,53 +274,69 @@ The read-side counterpart of `beforeInsert`/`beforeUpdate`: decrypt, unpack, res
|
|
|
258
274
|
|
|
259
275
|
- an id → `IN (id)`
|
|
260
276
|
- an array → `IN (...)`
|
|
261
|
-
- `
|
|
277
|
+
- `TENANT_ADMIN` (exported) → admin, no filter. Admin is declared, never inferred.
|
|
278
|
+
- `null` / `undefined` → 401 on any scoped table, before SQL runs: an absent tenant is a missing or failed auth hook, not an admin
|
|
262
279
|
- `[]` → no tenant at all: 403 on any scoped table, before SQL runs
|
|
263
280
|
|
|
264
|
-
`0` and `''` are ordinary ids. The tenant belongs to the request, not to the table: a scoped table is also filtered when it is a join target or a secondary of an unscoped
|
|
281
|
+
`0` and `''` are ordinary ids. The tenant belongs to the request, not to the table: a scoped table is also filtered when it is a join target or a secondary of an unscoped main table. `getTenantId` is called only when a scoped table is in reach, so an unauthenticated request still reads unscoped tables; on scoped ones `req.user?.organizationId` is enough, the missing user becomes the 401. Tables without `tenantScope` are never filtered.
|
|
265
282
|
|
|
266
|
-
```ts
|
|
267
|
-
|
|
268
|
-
|
|
269
|
-
|
|
270
|
-
|
|
283
|
+
```ts in=app
|
|
284
|
+
await app.register(fastifyAutoSqlApi, {
|
|
285
|
+
dbTables,
|
|
286
|
+
getTenantId: (req) => (req.user?.isSuperadmin ? TENANT_ADMIN : req.user?.organizationId),
|
|
287
|
+
});
|
|
271
288
|
```
|
|
272
289
|
|
|
273
|
-
|
|
290
|
+
```ts in=app
|
|
291
|
+
const direct: TenantScope = { column: 'organizationId' };
|
|
292
|
+
const indirect: TenantScope = { column: 'organizationId', // via parent FK: column and foreignField are fields of SchemaCustomer
|
|
293
|
+
through: { schema: SchemaCustomer, localField: 'customerId', foreignField: 'id' } };
|
|
294
|
+
const eitherParty: TenantScope = { anyOf: ['requesterAgentId', 'targetAgentId'] }; // row owned by either party
|
|
295
|
+
// on the table: defineTable({ …, tenantScope: direct })
|
|
296
|
+
```
|
|
297
|
+
|
|
298
|
+
All names in a scope are schema fields: `column`, `anyOf` and `localField` of this table, the indirect `column` and `foreignField` of `through.schema`. The column of a field is accepted too (a 0.x scope naming columns keeps working); any other name fails `defineTable` at startup. The tenant column must therefore be in the schema: hide it with `readExclude`, never `excludeColumns`. `anyOf` cannot be combined with `column`/`through` (throws).
|
|
274
299
|
|
|
275
300
|
| | direct | indirect | anyOf |
|
|
276
301
|
|---|---|---|---|
|
|
277
302
|
| read, get, delete | `AND col IN (...)` | INNER JOIN parent + WHERE | `AND (a IN (...) OR b IN (...))`; NULL never matches; all-NULL row = admin only; outside scope → 404 |
|
|
278
303
|
| insert | single tenant: injected; mismatch → 403; multi-tenant without value → 400. Column is optional in the body | FK must belong to tenant (1 query) → 403 | no injection: at least one listed column must hold a tenant id (400 none, 403 all foreign) |
|
|
279
304
|
| update | column stripped from SET, added to WHERE | pre-check → 404; changing the FK to another tenant → 403 | all listed columns stripped from SET; outside scope → 404 |
|
|
280
|
-
| bulk upsert | injected on every row; `
|
|
305
|
+
| bulk upsert | injected on every row; `upsertKey` conflict owned by another tenant → 403 | as insert | anchor rule per item, even for updates; listed columns never in UPDATE SET; conflict with a row outside scope → 403 |
|
|
281
306
|
| joins | filtered | filtered | predicate applied in every join family (joinLeft: in the ON clause) |
|
|
282
307
|
|
|
283
|
-
`anyOf`
|
|
308
|
+
`anyOf` child rows written as secondaries follow the anchor rule: the auto-filled parent FK is not an owner.
|
|
284
309
|
|
|
285
310
|
## sqlApi (application code)
|
|
286
311
|
|
|
287
|
-
Same code path, bodies and results as the HTTP routes (AGENTS_FRONTEND.md). Validation, hooks, computed fields and tenant scope all run.
|
|
312
|
+
Same code path, bodies and results as the HTTP routes (AGENTS_FRONTEND.md): a request body can be handed over as is. Validation, hooks, computed fields and tenant scope all run.
|
|
288
313
|
|
|
289
|
-
```ts
|
|
290
|
-
app.get('/billing/:customerId', async (request) =>
|
|
314
|
+
```ts in=app
|
|
315
|
+
app.get<{ Params: { customerId: string } }>('/billing/:customerId', async (request) =>
|
|
291
316
|
app.sqlApi.search('subscription', {
|
|
292
317
|
filters: { customerId: Number(request.params.customerId), status: 'active' },
|
|
293
318
|
joinMustExist: { orders: { filters: { status: 'pending' } } },
|
|
294
319
|
paginator: { page: 1, itemsPerPage: 50 },
|
|
295
320
|
}, request)); // pass `request` for tenant + hooks; without it: no tenant filter, hooks get undefined
|
|
321
|
+
```
|
|
296
322
|
|
|
297
|
-
|
|
323
|
+
```ts signature
|
|
324
|
+
sqlApi.search(table, { filters, conditions, joinMustExist, joinMultiple, joinGroup, joinLeft, select, orderBy, paginator, compute, maxRows }, req?)
|
|
325
|
+
// select: main fields to project, '*' for every readable one; the PK, the requested joins' keys and (with distinctResults) the ORDER BY fields are always added
|
|
326
|
+
// compute: { sum: ['total'], count: ['id'] } → result.computed, over every matching row; min|max|sum|avg|count|distinctCount; no paginator needed
|
|
298
327
|
sqlApi.get(table, id, req?)
|
|
299
|
-
sqlApi.insert(table, {
|
|
300
|
-
sqlApi.update(table, {
|
|
328
|
+
sqlApi.insert(table, { main, upsert?, replace? }, req?) // the POST /rest body: app.sqlApi.insert('customer', req.body, req)
|
|
329
|
+
sqlApi.update(table, { main, upsert?, delete?, replace? }, req?) // the PUT /rest body, PK in main
|
|
301
330
|
sqlApi.delete(table, id, req?)
|
|
302
331
|
sqlApi.bulkUpsert(table, items, req?) // each item writes only its own fields; items need not share keys
|
|
303
|
-
sqlApi.bulkDelete(table, ids, req?)
|
|
332
|
+
sqlApi.bulkDelete(table, { ids }, req?) // the POST /bulk/:table/delete body; composite PK: ids are { <field>: value } objects
|
|
333
|
+
// table: a key of dbTables. createSqlApi infers them, so a typo fails at compile time; at runtime an unknown name throws (a programming error, not a 400)
|
|
334
|
+
```
|
|
304
335
|
|
|
305
|
-
|
|
306
|
-
|
|
307
|
-
const
|
|
336
|
+
```ts in=app
|
|
337
|
+
// Standalone (jobs, scripts, tests). Tenant scope needs its own getTenantId, as on the plugin: without it a request passed in scopes nothing. One source for the dialect:
|
|
338
|
+
const sqlApi = createSqlApi(mysqlQueryable(pool), dbTables, { dialect: 'mysql', getTenantId: (req) => req.user?.organizationId }); // raw pool: the option, postgres when omitted
|
|
339
|
+
const sqlApi2 = createSqlApi(createQueryClient(mysqlQueryable(pool), 'mysql'), dbTables); // QueryClient: its own dialect; a `dialect` option beside it throws
|
|
308
340
|
```
|
|
309
341
|
|
|
310
342
|
Limits: the engine enforces at most 100 `conditions` per section, 20 `orderBy` parts and an integer `paginator`, for sqlApi too. `maxItemsPerPage` and `maxBulkItems` belong to the routes only: pass `maxRows` to `search`, and cap your own bulk arrays.
|
|
@@ -313,11 +345,11 @@ Limits: the engine enforces at most 100 `conditions` per section, 20 `orderBy` p
|
|
|
313
345
|
|
|
314
346
|
`db` is the hook parameter, or `createQueryClient(pgQueryable(pool) | mysqlQueryable(pool), dialect)`. Use it only for what sqlApi cannot express. It takes real table and column names (`Schema.tableName`, `Schema.col()`), and a camelCase name here is a runtime SQL error. It runs no hooks, no validation and no tenant scope.
|
|
315
347
|
|
|
316
|
-
```ts
|
|
348
|
+
```ts signature
|
|
317
349
|
db.insert(table, record, pkCol) // → PK row
|
|
318
|
-
db.
|
|
350
|
+
db.upsert(table, record, conflictKeys, pkCol) // → { pk, action: 'inserted' | 'updated' }
|
|
319
351
|
db.bulkInsert(table, records, pkCol, chunkSize?) // → PK rows in input order
|
|
320
|
-
db.
|
|
352
|
+
db.bulkUpsert(table, records, conflictKeys, pkCol, { chunkSize?, immutableCols? }?) // → [{ pk, action }] in input order. immutableCols: written on insert, never on update
|
|
321
353
|
db.update(table, record, where, extraCondition?) // → affected rows (number)
|
|
322
354
|
db.delete(table, where) // → affected rows
|
|
323
355
|
db.select({ tableName, columns?, where, values, limit?, orderBy?, joins?, distinct? })
|
|
@@ -327,10 +359,12 @@ db.qi(name); db.dialectName; db.cbDialect // quoting, dialect, ConditionBuilder
|
|
|
327
359
|
```
|
|
328
360
|
|
|
329
361
|
- `pkCol` is a string or an array. Bulk methods issue one statement per distinct column set.
|
|
362
|
+
- Values: string, number, boolean, null, `Date` (bound as a timestamp), `db.expression(...)`. `JSON.stringify` a JSON value first: the drivers do not serialize objects as JSON.
|
|
330
363
|
- `conflictKeys` must be a unique key enforced by the DB. PG uses `ON CONFLICT (keys)`. MySQL/MariaDB upsert by key (a probe SELECT per chunk, then INSERT new and UPDATE existing), because `ON DUPLICATE KEY` fires on any unique index. A key matching several rows is refused.
|
|
364
|
+
- `action` comes from the statement on PG (`(xmax = 0)` in RETURNING; on `DO NOTHING`, the rows RETURNING names are the inserted ones) and from the probe on MySQL/MariaDB. No extra statement either way.
|
|
331
365
|
- Called directly, none of the `defineTable` checks apply.
|
|
332
366
|
|
|
333
|
-
```ts
|
|
367
|
+
```ts signature
|
|
334
368
|
const cb = new ConditionBuilder('AND', db.cbDialect); // or 'OR'. Operands are raw SQL: db.qi() them.
|
|
335
369
|
cb.isEqual(col, v); // also isNotEqual, is[Not]Greater[OrEqual], is[Not]Less[OrEqual]
|
|
336
370
|
cb.isLike(col, '%v%'); // also isNotLike, isILike, isNotILike
|
|
@@ -344,10 +378,11 @@ cb.append(otherBuilder); // nesting; backend only
|
|
|
344
378
|
|
|
345
379
|
Example: atomically claiming a row, i.e. a guarded state transition or optimistic lock. There is no auto route for this (ADR 0020). The check and the write must be one UPDATE:
|
|
346
380
|
|
|
347
|
-
```ts
|
|
381
|
+
```ts in=app
|
|
348
382
|
const db = createQueryClient(pgQueryable(fastify.pg), 'postgres');
|
|
349
|
-
fastify.post('/requests/:id/claim', async (req, reply) => {
|
|
350
|
-
|
|
383
|
+
fastify.post<{ Params: { id: string } }>('/requests/:id/claim', async (req, reply) => {
|
|
384
|
+
if (!req.user) return reply.code(401).send(); // never let an undefined tenant reach the guard: isEqual would skip it
|
|
385
|
+
const col = SchemaRequest.col;
|
|
351
386
|
const guard = new ConditionBuilder('AND', db.cbDialect)
|
|
352
387
|
.isNull(db.qi(col('inProgressSince')), true) // the precondition
|
|
353
388
|
.isEqual(db.qi(col('organizationId')), req.user.orgId); // tenant: db applies none
|
|
@@ -374,27 +409,28 @@ A view (materialized ones included) is an ordinary table config (ADR 0016).
|
|
|
374
409
|
|
|
375
410
|
A read-only surface for LLM agents, with the plugin as the enforcement layer:
|
|
376
411
|
|
|
377
|
-
```ts
|
|
378
|
-
await app.register(
|
|
379
|
-
|
|
380
|
-
|
|
381
|
-
|
|
382
|
-
|
|
383
|
-
}, { prefix: '/agent' });
|
|
412
|
+
```ts in=app
|
|
413
|
+
await app.register(fastifyAutoSqlApi, {
|
|
414
|
+
dbTables, prefix: '/ai', decorate: false, onRequests: [agentAuth],
|
|
415
|
+
operations: ['search', 'get'],
|
|
416
|
+
agentManifest: true, // GET /ai/agent/manifest(.md), listing this registration's operations
|
|
417
|
+
});
|
|
384
418
|
```
|
|
385
419
|
|
|
386
|
-
- **System prompt**: AGENTS_FRONTEND.md (grammar, shipped in the package) + the output of `GET /agent/manifest.md` (this
|
|
387
|
-
- **Tools**: either a loose generic tool, retrying on the structured 400 `fields[]`, or strict per-table tools from `agentToolSchemas(dbTables, table)
|
|
420
|
+
- **System prompt**: AGENTS_FRONTEND.md (grammar, shipped in the package) + the output of `GET {prefix}/agent/manifest.md` (this registration's tables, fields and aliases).
|
|
421
|
+
- **Tools**: either a loose generic tool, retrying on the structured 400 `fields[]`, or strict per-table tools from `agentToolSchemas(dbTables, table, { operations })` (pass the registration's `operations` and caps).
|
|
388
422
|
|
|
389
423
|
## Exports
|
|
390
424
|
|
|
391
425
|
Everything is imported from `fastify-auto-sqlapi`, so there is nothing else to install:
|
|
392
426
|
|
|
393
|
-
- `
|
|
394
|
-
- `defineTable`, `
|
|
395
|
-
- `
|
|
396
|
-
- `
|
|
397
|
-
- `agentToolSchemas`
|
|
398
|
-
- Types: `
|
|
427
|
+
- `fastifyAutoSqlApi` (the one way to mount the routes), `SqlApi`, `createSqlApi`
|
|
428
|
+
- `defineTable`, `buildRelation`, `Nullable`, `Type`, `Static`, and the TypeBox types the signatures name: `TSchema`, `TObject`, `TUnsafe`
|
|
429
|
+
- for hooks: `httpError`, `TENANT_ADMIN`, `ConditionBuilder`, `Expression`, `ConditionValueOrUndefined`
|
|
430
|
+
- `QueryClient`, `createQueryClient`, `pgQueryable`, `mysqlQueryable`, and their parameter types `PgQueryable`, `MysqlQueryable`
|
|
431
|
+
- `agentToolSchemas`, `buildAgentManifest`, `renderAgentManifestMd`
|
|
432
|
+
- Types: those of the config (`DbTables`, `TableDefinition`, `TableConfig`, `JoinDefinition`, `BuildRelationOptions`, `TenantScope`…), of the hooks (`ApiRequest`, `ApiReply`, `ValidationField`, `ValidatorFn`, `ValidatorResult`, `BulkValidatorFn`, `WriteHookContext`, `PrimaryKeyValue`…), of `sqlApi` (`SqlApi*Params`, `JoinFetchRequest`, `JoinRefFilter`, `SearchResult`…), of the QueryClient (`BulkUpsertOptions`…), of the agent manifest (`AgentManifest`, `ManifestTable`, `ManifestField`, `ManifestJoin`) and of the CLI (`CliConfig`). Every type a public signature names is exported, except the building blocks of an exported one
|
|
433
|
+
|
|
434
|
+
Nothing else is public: the engines, route plugins, schema builders, naming helpers, dialect table and tenant resolution are internals.
|
|
399
435
|
|
|
400
436
|
Dialects: PG uses `"id"`, `$1` and `RETURNING`. MySQL uses backticks, `?` and `insertId`. MariaDB is like MySQL but has `RETURNING` (10.5+). The CLI uses `pg` / `mysql2`.
|