Files
canina/scripts/stage-schema/README.md
T

3.6 KiB

Stage-only SEO schema operation

Normal develop/main deployment remains code-only. Gitea 1.22.6 supports the push event; this workflow uses only ops/seo-schema-stage-rehearse and ops/seo-schema-stage-apply, disjoint from application refs. No workflow_dispatch assumption, Production access, generic Prisma migration, seed, reset, or operational checkout edit.

Run after safety review

  1. Freeze/review exact operation commit, including workflow, operation.py, catalog.py, SQL and tests. Apply requires repository secret STAGE_SCHEMA_REVIEWED_SHA set through authorized repository-secret administration to that full commit SHA. This is a technical immutable-source binding, not a new business authorization requirement. Never log credentials. Rehearsal does not require this secret.
  2. Transfer the committed source through the already pinned SSH host transport into an isolated server repository, never the dirty operational checkout. Inspect authoritative refs and push the exact commit non-force to refs/heads/ops/seo-schema-stage-rehearse. Do not push application develop/main. CI fetches the immutable event SHA through HTTPS (runner read-only transport verified).
  3. Inspect actual terminal Gitea Actions log at exact SHA. The rehearsal restores a schema-only sanitized dump of actual Stage into isolated PostgreSQL16, applies exact digest twice and checks complete scoped typed catalog. It is not full-data recovery proof.
  4. After parent review, provision exact reviewed-SHA secret and non-force push the identical commit to refs/heads/ops/seo-schema-stage-apply. This operation first takes a private full Stage dump, restores all data into an isolated clone, rehearses SQL, checks complete scoped types/defaults/nullability/enum/constraints/indexes, and only then applies bounded transactional SQL to canino_db_stage / caninodb_stage. Never set CI flags in SSH to bypass the supported path.
  5. Inspect actual terminal log, restricted receipt and live typed catalog. Do not retry ambiguous DDL outcomes blindly. SQL is additive and reentrant; the runner never restores over Stage or drops live tables. Backup/restore uses no-owner/no-acl: it proves data recovery, not role/ACL or cluster disaster recovery.

Ledger and backup retention

Historical _prisma_migrations remains byte-for-byte JSON equal before/after; no historical entries are synthesized, and no migration is marked applied. The incomplete baseline makes generic migrate deploy unsafe. A separate private receipt binds SHA, exact SQL digest, backup checksum/size and typed catalog hash. Reconcile this ledger policy before any future generic migration tooling use.

CI prints only its restricted private evidence directory. Dumps are mode600 in a mode700 directory, never artifacts or Git. Retain backup and receipt through Stage acceptance; authorized retention cleanup must remove only that exact directory after recovery requirements are met. Disposable containers alone are cleaned by captured IDs. Existing configs, secrets, cron, database containers, application containers and catalog-mode commerce flags are untouched. Shared host deployment flock prevents overlap with app CI; existing lock helpers fail closed.

Local diagnosis (read-only Stage plus disposable clone, never live DDL): python scripts/stage-schema/operation.py rehearse --sha <HEAD> --ssh-rehearsal --evidence <new-private-directory>

Tests: python -m unittest discover -s scripts/stage-schema -v. Unit safety/typed tests do not substitute for actual CI execution or full-data restore. The operation pins the observed Stage PostgreSQL image ID and fails if unavailable; it never pulls an unreviewed replacement.