Skip to content

Blue/green deployments

Upgrade a database to a new major version through a copy you test first, then switch over to it at the same endpoint. One-way.

Updated View as Markdown

A blue/green deployment upgrades a database (blue) to a new major version. It makes a copy on the new version (green), kept in step with blue, with its own endpoint to test against. A switchover then makes green the database, at blue’s endpoint and with its ID. A switchover is one-way: there’s no going back.

Blue/green deployments are available for PostgreSQL, from 17 to 18, and for MariaDB, from 11.8 to 12.3. Percona Server 8.4 has no newer version to upgrade to yet.

Create a deployment

ezgh databases blue-green create dbi_4k2m9x0a7qpe --target-engine-version 18 --wait
Setting
targetEngineVersion The newer major version green runs.
targetInstanceType Green’s instance type. The database’s by default.
switchoverTimeoutSeconds How long a switchover may take, 60 to 3600 seconds. 300 by default.

A database has one open deployment at a time. A deployment that can’t start is refused with 409 precheck_failed, which lists every reason, each with a code and a message:

Code Means
not_healthy The database isn’t available or isn’t serving.
not_eligible The database can’t be copied safely right now. Try again in a few minutes.
no_replica_identity (PostgreSQL) Tables have no primary key or replica identity, so their updates and deletes can’t be copied. Add a primary key, or set REPLICA IDENTITY FULL.
large_objects (PostgreSQL) Databases hold large objects, which aren’t copied.
extension_unavailable Extensions (PostgreSQL) or plugins (MariaDB) in use aren’t offered on the new version.
too_many_databases (PostgreSQL) The database has more than 60 databases, the most a deployment copies.
no_upgrade_target (Percona Server) The engine has no newer version to upgrade to.
not_innodb (MariaDB) Tables don’t use InnoDB, so a copy taken while the database runs isn’t reliable. Convert them with ALTER TABLE … ENGINE = InnoDB.
database_created (PostgreSQL) Databases were created on blue after the deployment started, so green has no copy of them. Drop them, or delete the deployment and start a new one.

New codes may appear.

While it’s open

  • Green is read-only, on its own endpoint (greenEndpoint, null until the name resolves). Test your app’s reads against it.
  • Schema changes on blue are refused on PostgreSQL, with Schema changes are paused during a blue/green deployment, because they can’t be copied to green. Temporary tables, REFRESH MATERIALIZED VIEW and REINDEX are allowed. Roles you create or change on blue are copied at switchover.
  • On MariaDB, schema changes, users and grants on blue are copied to green as they happen, and none of them is refused. Scheduled events don’t run on green until switchover.
  • Changes to the database are refused with 409 blue_green_in_progress while the deployment is creating, available or switching_over: instance type, storage, allowed sources, parameters and log exports, and a failover you ask for. Its name, description, tags, windows, backup retention and deletion protection can still change.
  • A failover, or maintenance that can’t wait, ends the deployment as failed, with a reason. Delete it and create a new one.
  • Green is billed as a database while it exists.

Switch over

ezgh databases blue-green switchover dbg_6r2k8m4p1xqz --wait

Writes stop on blue and open connections end. When green has caught up, the database’s endpoint moves to green and green takes writes. If that takes longer than the switchover timeout, blue goes back to taking writes and nothing changes: the switchover’s operation fails, and the deployment is available again, with a reason.

After a switchover:

  • the database keeps its ID, name and endpoint, and runs the new version on the target instance type;
  • its backups start again, with a new backup on the new version;
  • the old database stays, read-only, on a temporary endpoint (blueEndpoint), and is billed until you delete the deployment.

A switchover is refused with 409 deployment_not_available unless the deployment is available, and with 409 precheck_failed, for example database_created.

Delete a deployment

ezgh databases blue-green delete dbg_6r2k8m4p1xqz --wait

Before a switchover, deleting discards green, and a create still running is cancelled. After a switchover, it deletes the old database for good. A deployment can’t be deleted while it’s switching over (409 deployment_switching_over).

Status

Status Means
creating Green is being made.
available Green is ready to test and to switch over to.
switching_over A switchover is running.
switched_over Green is the database. The old one remains until you delete the deployment.
failed The deployment ended; reason says why. Delete it.
deleting It’s being deleted.
Navigation

Type to search…

↑↓ navigate↵ selectEsc close