Install Continuous Delivery (CD) with an external database

By default CD installs and manages its own PostgreSQL database in a container, managed mode. Instead, you can point CD at a PostgreSQL instance you provide and operate yourself, external mode. In external mode CD does not run a database container, does not create your schema or roles, and does not back up, restore, or perform maintenance on your database; those remain your responsibility.

Supported platforms:

  • Amazon RDS for PostgreSQL 17

  • Amazon Aurora (PostgreSQL-compatible) 17

  • Self-managed PostgreSQL 17

Known limitations:

  • Google Cloud SQL is not supported.

  • Password authentication only. IAM database authentication and mutual TLS (client certificates) are not supported.

  • One-way migration. You can migrate a managed install to external, but there is no automated migration back to managed.

  • Connection pool sizes are fixed and not configurable.

  • CD does not back up, restore, or maintain an external database. CD’s backup and restore plans still handle container volumes, but skip the database. Use your provider’s tools for database backups and point-in-time recovery.

Before you begin:

Prepare your database instance first. CD validates every item below before it touches the database.

  1. A PostgreSQL 17 instance, reachable from the CD host on its TCP port (default 5432), with TLS enabled. The server certificate must be valid for the hostname you configure and chain to a CA you can provide as a PEM file.

  2. Capacity for at least ~60 connections (max_connections). On RDS or Aurora, a db.t3.small or larger is sufficient.

  3. Two databases and two login roles, created by your DBA before install:

    DatabaseOwner roleUsed by
    cd4pecd4peCD backend
    queryqueryCD Nodes/query service

    Each role is LOGIN and owns its database (it does not need to be a superuser). A reference SQL script, files/external-postgres/setup.sql, ships with the cd4peadm module; run it once as your database’s master user to create the roles, databases, and required extensions. Record the two role passwords as you need them during the installation.

  4. If your instance restricts extensions (for example, RDS rds.allowed_extensions), allow pgcrypto and lo. CD installs these on the cd4pe database at install time.

Install CD with the external database:

Prior to installing CD with the external database, be sure to follow the installation instructions through creating the inventory.yaml file (and optionally copying your license file).

  1. Run generate_config in external mode. It records your database connection details in data/common.yaml.

    Copy 
    bolt plan run cd4peadm::generate_config \
      inventory_aio_target=<CD host target> \
      resolvable_hostname=<hostname users browse to> \
      admin_password=<CD admin password> \
      database_mode=external \
      external_db_host=<database host> \
      external_db_port=5432 \
      ca_cert_file=/path/to/ca.pem \
      cd4pe_db_password=<cd4pe role password> \
      query_db_password=<query role password>

    The passwords must match the role passwords configured on your database.

  2. Run the installer. 

    bolt plan run cd4peadm::install_from_config
Results

Install creates the pgcrypto and lo extensions on the cd4pe database, then runs validation, which checks connectivity, TLS, authentication, server version, privileges, extensions, and (on a fresh install) that the databases are empty. If a check fails, CD prints a one-line remediation hint. When install completes, confirm CD is healthy by loading the web console.