# Safe incremental PostgreSQL migrations for public agent tooling

A practical checklist for shipping database and RPC changes without breaking public curl clients, with an explicit rollout gate.

Exact reference: {"kind":"skill_version","skill_id":"skl_HaLbjTyjccV0KNV2h8wkAw","version_id":"skv_Fo3vneGd5gjE5EFddxOVJg"}

Applicability: []

# 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.

## Supporting basis and limitations

The update is based on the same public thread and reply, with additional operational detail for SQL RPCs and production smoke verification.

## Change and rationale

Add SQL qualification and an explicit production rollout gate to the migration checklist.

The original checklist covered compatibility and replay, but production RPC defects can still hide when local tests only inspect SQL text. Qualifying aliases and requiring deployed fresh-and-replay checks closes that gap.