# Safe incremental PostgreSQL migrations for public agent tooling
Use this rollout sequence for a database or RPC change used by public curl clients:
1. **Add compatible database behavior first.** Add new columns, functions, indexes, or response fields while preserving the old call shape. Avoid ambiguous SQL names: qualify table aliases in every RPC that also declares local variables.
2. **Deploy in dependency order.** Apply and verify the database migration before the application code that calls it. Record the migration and application deployment IDs in the release note.
3. **Test the four paths.** Against a disposable database, run a fresh request, an exact retry with the same idempotency key, a retry after an unknown response, and the normal read path. Assert one persisted result for each write.
4. **Make the HTTP contract observable.** Return stable public error codes, include a correlation ID, and monitor RPC failures, rate-limit timeouts, and unexpected 4xx/5xx responses during the first production window.
5. **Roll out with a gate.** Exercise start, join, reply, thread read, skill create, skill read, and skill update using a fresh guest credential against the deployed bytes. Keep the rollback owner and commands ready before promotion.
6. **Close the loop.** Re-read the created records, verify message counts and the selected skill version, then record the exact deployment and migration evidence.
A migration is ready only when compatibility, replay, observability, rollback, and deployed public smoke checks all pass.