Planning PostgreSQL migrations for Agent Rooms

The schema contains more than the conversation

The Room migration guide describes state for execution sessions, agent revisions, Handoffs, coordination, contributions, knowledge, plans, memberships, operational events and projection checkpoints.

Those records support different recovery and observation paths. A deployment that reads the base Room tables successfully has not demonstrated that the new coordination worker can operate. Treat the migration chain as a versioned dependency of the worker composition.

Prepare the upgrade before running the migration

The documented preparation includes a restore-tested backup, stopping older schema-dependent workers, installing one coordinated package version and configuring the same explicit schema for migrations and stores. Inspect migration status and resolve checksum drift.

In an illustrative staging rehearsal, record the observed schema version, worker build and expected target before applying changes. Restore a representative backup into an isolated environment and inspect both artifacts and operational records. This makes rollback assumptions testable rather than relying on the existence of a backup file.

Use the version-specific migration runner

The documented runner serializes migrations with an advisory lock. Failed transactions do not advance the recorded version, so correct the underlying cause and rerun the migration through the supported path.

Do not create an ad hoc schema patch just because a missing column appears in an error. That can leave migration history inconsistent with the application. Read the exact migration instructions for the package version you selected and preserve the resulting status output in your deployment record.

Coordinate worker startup with operational readiness

The guide's operational rollout requires its stated migration endpoint before the new worker cohort starts. Use one cohort per coordination scope and verify transactional intake, event progress and checkpoint progress.

The worker model relies on leases, stable operation identities and revision fencing. Confirm that these records remain usable after the upgrade. Watching only CPU usage and HTTP health misses whether queued domain work can actually advance.

Distinguish rollback from an ordinary retry

The migration documentation prefers forward fixes and identifies down migrations as destructive operations with explicit conditions. Older workers should not run alongside the new projection model merely because they can still read original tables.

The broader PostgreSQL operations guidance also calls for encrypted transport and storage, scoped roles, connection sizing and recovery observability. After restoring state, revalidate current membership, leases and fences. Restoring an old database snapshot does not automatically restore valid execution authority.

Keep the runbook specific to the observed version and deployment. This article explains the coordination concerns; the linked migration reference remains the authority for the actual commands and transition requirements.