Upgrading a PostgreSQL policy database

To upgrade an existing PostgreSQL policy database, use the policy-db tool.

When a newer version of the Policy Editor is released, it will fail to start when pointing to a PostgreSQL database with older database objects. Running start-server will print a message like the following to the console:

The policy database at 'jdbc:postgresql://example.com:5432/pap_db' is older than this version of PingAuthorize Policy Editor (9.2.0.0).
Please use the policy-db tool to upgrade the database before running start-server again.

This message indicates that you must run the policy-db tool for this newer version of the Policy Editor to upgrade the database objects.

Follow these instructions to upgrade a PostgreSQL database for a manual upgrade of the Policy Editor. Be prepared to provide the database administration credentials and server runtime credentials you used to create the PostgreSQL database.

For containerized deployments, refer to Deploying PingAuthorize Server and Policy Editor using Docker.

Before you begin

Before you upgrade your PostgreSQL database, make sure that:

The PostgreSQL instance is reachable on the network from the Policy Editor host and listening for connections.
The Policy Editor uses both a PostgreSQL administration user and a server runtime user. Have a database administrator create both users before providing their credentials to the policy-db tool. The administration user must be able to create new databases. When new releases of the Policy Editor become available, continue using the same administration user to prevent database object ownership issues.

Learn more about creating new database users and configuring PostgreSQL to listen for remote connections securely in the PostgreSQL documentation.
The Policy Editor uses Java Database Connectivity (JDBC) to connect to PostgreSQL. Be prepared to provide the JDBC connection string in the following format: jdbc:postgresql://<host>:<port>/<name>. For example: jdbc:postgresql://example.com:5432/pap_db

Steps

Complete steps 1-3 of Upgrading the Policy Editor manually.

Run the following command:

$ bin/policy-db \
  --dbConnectionString "jdbc:postgresql://<host>:<port>/<name>" \
  --dbAppUsername  <server-runtime-username>  \
  --dbAppPassword  <server-runtime-password>

Alternatively, you can provide the server runtime password through the PING_DB_APP_PASSWORD environment variable.

Provide the database administration credentials when prompted.

Result

The policy-db tool connects to PostgreSQL and applies the upgrades.

Next steps

Complete steps 5-7 of Upgrading the Policy Editor manually.

Provide the Policy Editor with the same --dbConnectionString, --dbAppUsername, and server runtime password you used to create the PostgreSQL database.