docs: rewrite for people running nxdns; query-history refusals name their remedy and a refused start gives no wrong hints
This commit is contained in:
@@ -92,7 +92,7 @@ Two SQLite files with opposite write profiles, isolated from each other:
|
||||
### 3.7 Upgrades: Auto-Migration (Decision J)
|
||||
|
||||
- `config.db`: numbered, sequential SQL migration steps compiled into the binary. At startup: read schema version row, apply newer steps inside a transaction, continue. Operator upgrade = install binary, restart. Before v0.1 the list holds one step — the baseline of §11.2, edited in place — because nxdns has no installs and a step exists only to reconcile a database somebody already has.
|
||||
- `querylog.db`: a logical version in `PRAGMA user_version`, migrated **in place** at startup by the same shape of compiled step list, inside one transaction and behind one `querylog.db.pre-migrate-<epoch>` backup (only the newest is kept). A healthy file is never renamed aside: a version this build cannot reach refuses the startup with instructions, and only corruption recreates. A deliberate break is still allowed, but it must be versioned, refused at startup, and disclosed in the changelog — the cut gate enforces that. See `docs/reference/query-log-lifecycle.md`.
|
||||
- `querylog.db`: a logical version in `PRAGMA user_version`, migrated **in place** at startup by the same shape of compiled step list, inside one transaction and behind one `querylog.db.pre-migrate-<epoch>` backup (only the newest is kept). A healthy file is never renamed aside: a version this build cannot reach refuses the startup with instructions, and only corruption recreates. A deliberate break is still allowed, but it must be versioned, refused at startup, and disclosed in the changelog — the cut gate enforces that.
|
||||
|
||||
### 3.8 Blocklist Storage (Decision A)
|
||||
|
||||
@@ -554,7 +554,7 @@ Scalars in `settings(key, value)`; ordered/structured items in dedicated tables.
|
||||
|
||||
### 13.2 OpenAPI
|
||||
|
||||
Hand-maintained `openapi.yaml`, served at `GET /api/openapi.yaml` and mirrored by hand in `docs/reference/api.md`. No renderer is vendored. Two drift guards fail the build instead: `src/web/openapi.zig` asserts every served route appears in the spec, and `src/docs_drift_test.zig` asserts every served route has its own table row in the reference page.
|
||||
Hand-maintained `openapi.yaml`, served at `GET /api/openapi.yaml`. No renderer is vendored, and the user docs carry no API reference: the API serves the admin UI. A drift guard fails the build instead: `src/web/openapi.zig` asserts every served route appears in the spec.
|
||||
|
||||
---
|
||||
|
||||
|
||||
Reference in New Issue
Block a user