Database Maintenance
Purpose
Apply and validate Manager schema changes, and perform routine PostgreSQL care without inventing a DBA product.
Prerequisites
- PostgreSQL reachable with
database.*settings - Manager binary that matches the schema you intend
- Backup taken with backup_db.sh before
-migrateon an existing database
Required permissions: the Manager database role for migrate; a stronger role only for restore create/drop.
Manager flags
Scroll sideways to see the full table. Use the arrow keys when focused.
| Flag | Effect |
|---|---|
-config | path (Community default configs/manager.yaml if omitted in Community; Main default configs/manager.yml) |
-migrate | forward-only preflight + apply bootstrap/tracked migrations, then exit |
-init-db | deprecated alias for -migrate (logs a warning) |
-preflight-migrate | validate history and pending plan without apply |
-check-schema | validate recorded version and checksums without apply |
-migration-exec-preflight | validate migration executable/config/credential lifecycle without connecting |
-validate-runtime | Enterprise: credentials, schema, KEK, licensing without starting the server |
Choose only one of -migrate, -preflight-migrate, -check-schema, -migration-exec-preflight, -validate-runtime.
Enterprise customer path is not “run random flags.” Schema admission uses the admitted binary for preflight, migrate, and check-schema. Those installer steps are provided separately to Enterprise customers.
Database-only migration mode (-migration-config, -migration-from, -migration-to, -migration-expected-checksum) is a constrained installer path. Legacy-ledger transition flags are not a public operator cookbook.
Procedure — Community existing database
./scripts/backup_db.sh
./bin/manager -config /etc/zcs/manager.yml -preflight-migrate
./bin/manager -config /etc/zcs/manager.yml -migrate
./bin/manager -config /etc/zcs/manager.yml -check-schema
./bin/manager -config /etc/zcs/manager.ymlProcedure — Enterprise
Use --manager-database-only against the new verified bundle. Do not apply Community-built migrations to an Enterprise admitted schema or the reverse.
Procedure — PostgreSQL care (operator-owned)
The product does not ship a certified VACUUM schedule. Operators may run ordinary PostgreSQL maintenance on their own provided they:
- take a dump first
- do not drop
agents,admins,rules,schema_migrations - do not change encoding or ownership away from the Manager role the installer admitted
database.max_connections example 25, max_idle_connections 5, idle/lifetime timeouts exist in Manager config. Pool exhaustion alerts are optional (database.pool_monitoring).
POST /api/v1/maintenance/system with tasks cleanup_temp / optimize_db / clear_cache returns success strings without a verified VACUUM implementation. Do not use it as database maintenance.
Verification
-check-schemaexit 0GET /health/readydatabaseok- After migrate, console login still works (admin rows preserved)
Failure modes
Scroll sideways to see the full table. Use the arrow keys when focused.
| Symptom | Meaning | Action |
|---|---|---|
| SSL error | database.ssl_mode vs server | align require / verify-full / disable |
checksum mismatch on -check-schema | binary/schema skew | do not start; restore or complete admission |
| migrate applied, old binary will not start | forward-only | upgrade boundary |
| Community README 15+ vs Enterprise 16 | PostgreSQL version ambiguity | do not invent a public single major |
Security considerations
database.passwordstays in systemd credentials on Enterprise production (implemented, pending final security acceptance).- Dumps are confidential (Backup).
- Bootstrap (
--bootstrap-database) creates a login role without superuser/createdb/createrole/replication/bypassrls.
Limitations
- No PITR product.
- No certified connection-pool sizing.
- Restore contract is script-existence only.