Migrating from Pact Broker

If you have previously used the open source Pact Broker with a PostgreSQL database it is possible to migrate that data to PactFlow On-Premises, keeping everything and making it available in PactFlow On-Premises. The migration process uses the existing Pact Broker database. Database migrations are then performed to add additional tables and data used for PactFlow On-Premises features.

Note

Migration is only supported for a Pact Broker running a PostgreSQL database.

Single Pact Broker Instance

Follow the existing documentation for setting up your new PactFlow On-Premises. When you reach the section regarding setting up a Database follow these steps to migrate instead of creating a new database:

  1. Re-use your existing Pact Broker environment variables, updating the names to read PACTFLOW_* instead of PACT_BROKER_*. A full list of the PactFlow On-Premises environment variables can be found here.

    Tip

    It is crucial that all PACT_BROKER_DATABASE_* environment variables are renamed to PACTFLOW_DATABASE_* while their values remain the same. This is because your existing Pact Broker database will be used, and updated for use with PactFlow On-Premises as part of the process.

  2. If you previously set the environment variables PACT_BROKER_AUTO_MIGRATE_DB and PACT_BROKER_AUTO_MIGRATE_DB_DATA remove these and replace them with a new environment variable named PACTFLOW_DATABASE_AUTO_MIGRATE. Set its value to true. This environment variable will allow your existing database to be updated with the required structures and data to support PactFlow On-Premises, and maintain any existing data.You do not need to add the new variable if you did not previously set PACT_BROKER_AUTO_MIGRATE_DB and PACT_BROKER_AUTO_MIGRATE_DB_DATA.

  3. When the PactFlow On-Premises instance starts up the migrations will run automatically. The migrations can be run manually instead if needed. See details here.

Multiple Pact Broker instances

It is not currently possible to combine multiple Pact Broker databases into a single database for use with PactFlow On-Premises. Instead one Pact Broker database can be used in the migration, and the others ran in parallel with the new PactFlow On-Premises instance until sufficient data is transferred. The PactFlow On-Premises instance must contain all production versions of all services used in the contract test before it can safely take over all 'can-i-deploy' checks.

The recommended steps are as follows:

  1. Select one of the Pact Broker databases to update and use going forwards.

  2. Follow the instructions above to set up PactFlow using this database.

  3. The Pact Broker instances that were used in the upgrade process were decommissioned, as the database and its contents are now available in PactFlow On-Premises.

  4. Run the PactFlow On-Premises instance and any other existing Pact Broker instances in parallel. Duplicate the pact publication and pact verification tasks in your pipeline. The duplicated task should use the new PactFlow instance details. In this way all new data can gradually added to PactFlow while ensuring can-i-deploy still has access to production versions of all services.

  5. Continue to run PactFlow On-Premises and Pact Brokers in parallel. Once the PactFlow On-Premises instance contains all the production versions for all the services used in the contract tests the old Pact Broker instances can be safely decommissioned. This will allow PactFlow On-Premises to be the sole source of data for 'can-i-deploy'.

  6. Clean up any code and API calls that were used to run PactFlow On-Premises and existing Pact Brokers in parallel. The pact publication and pact verification steps in your pipeline that used the old Pact Brokers can be removed.

In this section:
© 2025
Publication date: