Migrate Continuous Delivery (CD) to an external PostgreSQL database

If CD is running against its managed database, you can move it to an external database you operate.

This is a one-way move, there is no plan that migrates back, so plan a maintenance window and read this page fully before you start. Do not use upgrade to change database modes; upgrading never switches modes.

Before you begin:

CD 5.15.1 or later.
Schedule a maintenance window. CD is unavailable during the migration. The migration plan stops CD before copying data and leaves it stopped until you run the cutover plan. There is no zero-downtime option.
Create and configure the external database first. After you’ve created the PostgreSQL instance, you can use the helper script in the cd4peadm module (/files/external-postgres/setup.sql) to prepare it for connection to CD.
Have the database’s CA certificate (PEM) on the machine where you run Bolt.

Run the migration plan.
Copy
```
bolt plan run cd4peadm::migrate_to_external_database \
  --params '{
    "external_host": "<database host>",
    "external_port": 5432,
    "external_cd4pe_db_password": "<cd4pe role password>",
    "external_query_db_password": "<query role password>",
    "ca_cert_path": "/path/to/ca.pem"
  }'
```
The migration plan confirms CD can connect to the external database, stops CD, copies the cd4pe and query databases to the external database, compares row counts on both sides to confirm the copy is complete, and records the external settings in data/common.yaml. Note that when this plan is finished, CD is still down and still using the managed database’s data.

Nothing in your configuration changes until the row-count check passes. If any step before that fails, your managed database and configuration are untouched and you can re-run the migration plan after fixing the problem.
Switch CD over.
```
bolt plan run cd4peadm::apply_configuration
```
Run this as a separate command — do not fold it into Step 1. Within a single Bolt run the configuration is read once at the start, so a combined run would bring CD back up still pointed at the old database while reporting success. When it finishes, confirm CD is healthy by loading the web UI.

If you need to return to the managed database

There is no automated path back once Step 1 records the external settings. To revert by hand:

Restore the configuration file from the backup the plan saved (or from your Bolt project’s git history)

Restart the managed database with:

bolt plan run cd4peadm::ctl --params '{"action":"start","service":"postgres"}'

Run apply_configuration. The managed data was never deleted.

Clean up the managed database

The managed database is stopped but kept, so you can fall back to it. Once you’re confident the migration succeeded, reclaim its disk space:

Copy

bolt plan run cd4peadm::cleanup_managed_postgres --params '{"dump_dir": "<dump_dir from the migration output>"}'

This deletes the stopped container, its data, and its on-disk configuration. If you pass dump_dir (printed by the migration plan), it also deletes the on-disk copy of your data the migration wrote, those files contain pipeline secrets and audit history, so don’t leave them longer than necessary. The plan asks for confirmation unless you pass "force": true, and refuses to run unless the migration has already recorded the external settings.