PM2 Cluster Mode and Database Schema Migration Interoperability

Recommended coordination strategy

1. Deploy a one‑off migration job (e.g., a PM2 app named "migrator" or a CI step) that runs the schema change.
2. Make the migration script idempotent and, if possible, use an advisory lock (e.g., Knex pg advisory lock) so that only one instance can execute it.
3. Wait for the migration job to finish successfully before triggering the PM2 reload.
4. After migration success, run pm2 reload (or pm2 restart) to roll the new code through the cluster.
5. Optionally, have workers check a migration‑status flag (e.g., a row in a control table) at startup and refuse to serve traffic until the flag indicates the latest schema is applied.

What PM2 provides

PM2’s zero‑downtime reload sequentially restarts workers but does not expose a hook to pause the sequence for an external health check or migration flag. There is no built‑in "wait‑for‑migration" option; you must orchestrate the pause outside of PM2 (e.g., via a deployment script, CI pipeline, or a small wrapper that calls pm2 reload only after the migration succeeds).

Likely explanation

Because each worker shares the same database connection pool, running migrations inside every worker would cause concurrent attempts to alter the same schema, leading to lock timeouts, duplicate‑key errors, or partially applied changes. Executing the migration once, before any worker restarts, guarantees a consistent schema for all instances.

When the recommendation changes

If the schema change is purely additive (e.g., adding a nullable column or new table) and the migration tool is safe to run concurrently, you could allow workers to run migrations during the reload window. In that case you would need to know whether the change is destructive or additive to decide if a separate migration step is required.