Manage Habitat Builder data stored by PostgreSQL

This page describes how to back up Habitat Builder user and package data that’s managed by PostgreSQL.

Habitat Builder data overview

Habitat Builder’s data is lightweight, so backup and disaster recovery strategies are straightforward. On-Prem Builder has two types of data you should back up in case of a disaster:

PostgreSQL package and user metadata
MinIO Habitat artifacts

Ideally, coordinate the backup of the entire On-Prem Builder cluster at the same time. However, because Habitat Builder stores only metadata and artifacts, you have some flexibility in the timing of your backup operations. If a package’s metadata is missing from PostgreSQL, you can repopulate it by re-uploading the package with the --force flag, for example:

hab pkg upload <PATH_TO_HART_FILE> -u <ON_PREM_URL> --force

Back up the PostgreSQL database

Backing up Builder’s PostgreSQL database is the same as backing up any PostgreSQL database. The process uses pg_dump. If you already have a backup strategy for other production PostgreSQL instances, apply that pattern to the builder database. To back up your builder database manually, follow these steps:

Optional but recommended: Shut down the API to make sure there are no active transactions:
```
hab svc stop habitat/builder-api 
```
Switch to the hab user:
```
sudo su - hab 
```

Find your PostgreSQL password:

sudo cat /hab/svc/builder-api/config/config.toml

Export the password as an environment variable:
```
export PGPASSWORD=<PASSWORD> 
```

Create a backup of the database:

/hab/pkgs/core/postgresql/<VERSION>/<RELEASE>/bin/pg_dump --file=builder.dump --format=custom --host=<IP_OF_PG_HOST> --dbname=builder

Start the API and verify it’s running:
```
sudo hab svc start habitat/builder-api 
```

After the backup finishes, you’ll find the builder.dump file on your filesystem. Move and store this file according to your organization’s policies. Store the backup in a remote location—either physically or virtually—so you can access it in a disaster scenario. For example, you can use an AWS bucket or Azure storage. Use the same backup strategy you use for your other databases.

Restore the PostgreSQL database

Restoring a builder database is the same as restoring any other PostgreSQL database. If you already have a restoration strategy, use it to restore your builder database. To restore your builder database manually, follow these steps:

Switch to the hab user:
```
sudo su - hab 
```

Find your PostgreSQL password:

sudo cat /hab/svc/builder-api/config/config.toml

Export the password as an environment variable:
```
export PGPASSWORD=<PASSWORD> 
```
Create a new database called builder (if needed):
```
/hab/pkgs/core/postgresql/<VERSION>/<RELEASE>/bin/createdb -w -h <URL_OF_PG_HOST> -p <CONFIGURED_PG_PORT> -U hab builder 
```
If your version of PostgreSQL doesn’t have the createdb binary, connect to the database and run the create database command manually.

Verify connectivity to the new database instance:

/hab/pkgs/core/postgresql/<VERSION>/<RELEASE>/bin/psql --host=<URL_OF_PG_HOST> --dbname=builder

Restore the contents of the builder.dump backup file into the builder database:

/hab/pkgs/core/postgresql/<VERSION>/<RELEASE>/bin/pg_restore --host=<URL_OF_PG_HOST> --dbname=builder builder.dump

Start the Habitat On-Prem Builder services.

Your database data should now be restored and ready for use!