Upgrade Boundary and migrate the database

Upgrade a self-managed Boundary deployment by determining whether the release requires a database migration, backing up and migrating the PostgreSQL database when required, and upgrading the controllers and workers. Boundary only supports offline database migrations, so upgrades that change the database schema require downtime.

Requirements

Before you upgrade Boundary, complete the following tasks:

Review the release notes for the target version and every version between your current and target versions. Follow any version-specific upgrade instructions.
Download and verify the Boundary binary for the target version. Refer to Install Boundary for instructions.
Confirm that your PostgreSQL version meets the database requirements.
If the target release requires a database migration, schedule downtime and verify that you can restore the Boundary database from a backup. You must stop every controller before you back up and migrate the database. You cannot revert to an earlier Boundary version after you migrate the database.

Determine whether to migrate the database

Review the release notes for your target version and every version between your current and target versions. If the releases include database schema changes, follow the backup and migration procedure in this topic.

If the release notes confirm that the upgrade does not require a database migration, skip the backup and migration procedure. For example, Boundary 1.0.1 did not include database schema changes, so an upgrade from Boundary 1.0.0 to 1.0.1 does not require a database migration. Do not assume that other patch releases omit schema changes. Check the release notes for each upgrade.

For a Kubernetes deployment that uses the Boundary controller Helm chart, you can perform a rolling upgrade when no database migration is required. Follow the controller Helm chart upgrade procedure. The chart's rolling update settings keep controller pods available while Kubernetes replaces them.

Back up the database

PostgreSQL supports backups while applications continue to read from and write to the database. For this upgrade workflow, stop every Boundary controller before you create the final pre-upgrade backup. Stopping the controllers prevents Boundary from committing transactions after the backup begins and creates a clean recovery point immediately before the migration.

Stop every Boundary controller process so that no controller can write to the database. For example, stop the Boundary system service on each controller host, stop each controller container, or scale a Kubernetes controller deployment to zero replicas.
Back up the Boundary PostgreSQL database using your organization's backup process. For production environments, use an automated physical backup process configured for point-in-time recovery. Point-in-time recovery uses a base backup and archived PostgreSQL write-ahead log records to restore the database to a selected time, such as immediately before the migration. Refer to the PostgreSQL continuous archiving and point-in-time recovery documentation for requirements and instructions.
Verify that you can restore the backup.

Keep the backup until you verify that the upgraded deployment operates correctly. Do not restart the controllers until you migrate the database.

Upgrade the controllers and migrate the database

Replace the Boundary binary on every controller with the target version, but do not start the controllers.
From one controller, migrate the database using the target-version binary and the controller configuration file:
```
$ boundary database migrate -config=/etc/boundary.d/boundary-controller.hcl
```
The command reports Migrations successfully run. when the migration completes. Refer to the boundary database migrate command reference for additional options, including how to specify a separate migration database URL.
If the migration fails and the output or release notes instruct you to run a repair, rerun the migration with the provided repair migration version:
```
$ boundary database migrate -config=/etc/boundary.d/boundary-controller.hcl -repair=REPAIR_MIGRATION_VERSION
```
Do not use -repair unless Boundary provides the repair migration version. The flag repairs data required by a specific migration. It does not reverse a migration or downgrade the database schema. For Kubernetes deployments, follow the controller Helm chart repair migration procedure.
After the migration succeeds, start the Boundary service on each controller.
Verify that all controllers are running the target version and can connect to the database.
Verify that you can authenticate to Boundary and perform expected operations before you continue.

Upgrade the workers

Upgrade all workers to the same Boundary version as the controllers to maintain protocol compatibility.

For each worker:

Stop the Boundary worker process.
Replace the Boundary binary with the target version.
Start the Boundary service.
Verify that the worker reconnects to its upstream controller or worker and reports the target version.