How to Manually Backup Internally-Managed PostgreSQL Data

Steps

Introduction

Terraform Enterprise v202103-1 introduced logic to upgrade the internally-managed PostgreSQL data from PostgreSQL 9.5 to PostgreSQL 12. This change only affects Proof of Concept and Mounted Disk installations.

Use Case

Before Terraform Enterprise upgrades the PostgreSQL data from version 9.5 to 12, it creates an automatic backup to protect data integrity. For large datasets this backup may take a long time and can time out. To avoid delays, you can perform a manual backup before upgrading to Terraform Enterprise v202103-1. When the upgrade process detects a manual backup, it skips its own backup step.

This procedure supplements, not replaces, any existing backup processes you may have. Continue to run your regular backups in addition to the steps described here.

Note: If the file ${backup_path}/.pg_backup_done already exists, skip these steps. The presence of this file indicates that the upgrade’s backup step has completed. If the upgrade later fails, investigate other potential causes.

Procedure

The procedure determines the correct paths for your installation type and then runs the backup commands.

Step 1: Determine PostgreSQL Paths

Choose the set of commands that matches your Terraform Enterprise installation type.

For Proof of Concept Installations

1. Define the PostgreSQL data and backup paths.

   ## The PostgreSQL data path.
   docker_vol_pgdata="$(docker volume inspect --format='{{.Mountpoint}}' postgres)"
   pgdata_path="${docker_vol_pgdata}/pgdata"
   
   ## The PostgreSQL backup path.
   docker_vol_backup="$(docker volume inspect --format='{{.Mountpoint}}' postgres_backup)"
   backup_path="${docker_vol_backup}/9.5"

For Mounted Disk Installations

1. Define the PostgreSQL data and backup paths. The tr -d '\r' command removes any carriage return characters from the output.

   ## The mounted disk path.
   mounted_disk_path="$(replicatedctl app-config export --template '{{.disk_path.Value}}' | tr -d '\r')"
   
   ## The PostgreSQL data path.
   pgdata_path="${mounted_disk_path}/postgres/pgdata"
   
   ## The PostgreSQL backup path.
   backup_path="${mounted_disk_path}/postgres-backup/9.5"

Step 2: Perform the Manual Backup

After defining the pgdata_path and backup_path variables in the previous step, follow these steps to complete the backup.

1. Ensure the backup path directory exists.

   # mkdir -p "${backup_path}"

2. Confirm that the variables contain the correct paths.

   # echo "${pgdata_path}"
   # echo "${backup_path}"

3. Shut down the Terraform Enterprise application to stop writes to the database.

   # replicatedctl app stop

4. Back up the PostgreSQL 9.5 data.

   # cp -r "${pgdata_path}" "${backup_path}"

5. Create a file to signal to Terraform Enterprise that the backup is complete. This causes the upgrade process to skip its own backup step.

   # touch "${backup_path}/.pg_backup_done"

Outcome

You now have a manual backup of the PostgreSQL 9.5 data stored at the location defined by your ${backup_path} variable. You can now proceed to start or upgrade to Terraform Enterprise v202103-1 or a newer version.

Additional Information

• PostgreSQL 12 Upgrade Error: Timeout waiting for event PostgreSQL Upgraded