Before an upgrade
- Identify the deployed application and schema revisions. Read the additive migration and behavior changes.
- Back up PostgreSQL and preserve the connector encryption keys separately through your established secure process.
- Test fresh initialization and a populated upgrade on a disposable database.
- Coordinate writers for data migrations; do not run old and new migration-incompatible binaries together.
- Check accounts, bindings, decisions, source counts and credential availability before enabling refresh.
Schema verification commands
Run from an authorized source checkout with the configured operator database connection. Never paste a connection string into a ticket or the public docs.
python database.py current
python database.py check
# Apply only the reviewed release migration path:
python database.py upgradeUse catproof_alembic_version. Constructors do not perform schema changes; do not stamp unknown history to bypass a failed upgrade.
Incident triage
| Symptom | Inspect first |
|---|---|
| Duplicate-looking agents | Source-qualified IDs, configured scopes, current bindings, provenance and review state. |
| Link disabled | Last-seen validity, source health/enabled state, presence/staleness; release 708b5af also reports retired-record blockers. |
| 409 on confirm | Current fingerprint, previous review revision, binding revision and destination business fields. |
| Source inventory drops | Provider completeness, pagination, permission changes and adapter-specific absence behavior. |
| Owner seems changed | Business update history versus source-reported owner; do not conflate the two. |
| Undo rejected | Intervening binding moves or a newer pair decision; inspect current state. |
Recovery and evidence
Record sanitized workspace/source identifiers, application revision, source status, timestamps, review revision, rule version and error class. Exclude credentials and raw private payloads. Restore only through a reviewed backup procedure. Older database events may exist beyond the UI’s recent-event window. Reconciliation audit rows are ordinary database data, so backup and retention policy matter.
Post-deployment acceptance
- Confirm the migrated schema is current and existing bindings still resolve.
- Use fictional fixtures to exercise Separate, Defer, Link and conditional Reverse.
- Verify viewer denial, workspace isolation and safe provider-read failure behavior.
- Inspect source refresh independently of decision persistence.
- Check conflict and rollback behavior before claiming the release healthy.