---
title: "Blue/green deployments"
description: "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."
---

> Documentation Index
> Fetch the complete documentation index at: https://docs.ezghcloud.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Blue/green deployments

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

```sh
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

```sh
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

```sh
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. |

Source: https://docs.ezghcloud.com/databases/blue-green/index.mdx
