User GuidesAPI ReferenceRelease Notes
Doc HomeHelp CenterLog In

Upgrading PostgreSQL

Starting with v2020.012, Tamr Core requires PostgreSQL 12. Upgrade to PostgreSQL 12 using the procedures in this section.

Postgres Upgrading Considerations

  • You can upgrade to PostgreSQL 12 beginning with Tamr Core v2020.004 or greater.
  • Starting with v2020.012, PostgreSQL 12 is required. Therefore, before you upgrade to Tamr v2020.012 or greater, you must upgrade PostgreSQL to 12.

Beginning with PostgreSQL 10, Postgres versioning changed. PostgreSQL 12 denotes a major version of PostgreSQL required by Tamr Core. Minor releases of PostgreSQL contain only bug and security fixes and are fully compatible with each other. Tamr recommends that you install or upgrade to the latest available minor version of PostgreSQL 12.

Note: If, before upgrading to Tamr Core v2020.012, you cannot upgrade your PostgreSQL instance to 12 for any reason in your environment and must use an earlier version, contact Tamr Support at [email protected] to obtain advice on the best course of action.

Upgrading Postgres to Version 12 on RHEL 7

These instructions rely on PostgreSQL instructions for upgrading using dumpall. This method allows you to dump data from one major version of PostgreSQL and reload it in another. You must use a logical backup utility, pg_dumpall, and not the system backup. For more information, see Upgrading Postgres with Dumpall in the PostgreSQL v12.x documentation.

To upgrade PostgreSQL to version 12 on RHEL 7:

  1. Stop Tamr Core and its dependencies. Use the following commands or see Restarting.
sudo su - <tamr-functional-user>
cd <tamr-home-directory>/tamr
./stop-unify.sh
./stop-dependencies.sh
  1. Install the PostgreSQL 12 client. The pg_dumpall command run subsequently uses the newer binaries.
sudo yum install postgresql12

For detailed PostgreSQL 12.x installation instructions, see Installing Postgres in this guide, or use the procedure outlined in the PostgreSQL YUM Repository.
3. Optional. Write the Tamr Core PostgreSQL user password <tamr-postgres-user-password> to a local hidden file and change permissions to avoid prompting for the password.

sudo echo "localhost:5432:*:tamr:<tamr-postgres-user-password>" > .pgpass 
sudo chmod 600 .pgpass
  1. Switch to the postgres user
sudo su - postgres
  1. Run the dumpall command on the Tamr Core database (which has a default name of doit). This creates the dumpfile. The dumpfile contains both postgres and the doit databases.
pg_dumpall -h localhost -l doit > dumpfile
  1. Stop the previously-installed PostgreSQL server. The following example commands use 9.4 as your current PostgreSQL version. If the current version is not 9.4, change the command appropriately.
sudo systemctl stop postgresql-9.4
  1. Install the PostgreSQL 12 server.
sudo yum install postgresql12-server
  1. Initialize the new version of PostgreSQL client and enable an automatic start.
sudo /usr/pgsql-12/bin/postgresql-12-setup initdb
sudo systemctl enable postgresql-12
sudo systemctl start postgresql-12
  1. Restore any previous pg_hba.conf and postgresql.conf modifications. Compare /var/lib/pgsql/9.4/data/pg_hba.conf and /var/lib/pgsql/12/data/pg_hba.conf and restore any non-default location for PG_DATA.
  2. Open postgresql.conf and add an entry to it as follows, to make the PostgreSQL instance listen on all addresses, and not only on the loopback address. Save the file.
listen_addresses = '*'
  1. Open the postgresql.conf again and confirm that the port for PostgreSQL is specified correctly as 5432.
    By default, PostgreSQL 12 binds the port 5432 after an upgrade when it takes over from PostgreSQL 9.4 or earlier. However, your instance of PostgreSQL 12 may not be configured to use port 5432 after restart. This may happen if the port 5432 is taken by the instance with the previous version of PostgreSQL, such as PostgreSQL 9.4, before that instance is dropped.
port = 5432
  1. Restart the database.
sudo systemctl restart postgresql-12
  1. Log into the upgraded instance of PostgreSQL as a PostgreSQL user and move the dumpfile.
sudo mv dumpfile /var/lib/pgsql 
  1. Make the dumpfile location accessible to the PostgreSQL user.
sudo chown postgres:postgres /var/lib/pgsql/dumpfile
  1. Switch to the PostgreSQL user, and use psql to restore from the dumpfile, as follows. The psql command restores the postgres and doit databases present in the dumpfile. You run it as the postgres user against the postgres database because, when the command starts on the upgraded instance, the Tamr Core functional user and the doit database do not yet exist on the instance. They are created during the restore process.
sudo su - postgres
psql -f /var/lib/pgsql/dumpfile
logout
  1. Verify that Tamr Core can connect to its database in this instance of PostgreSQL. The default Tamr Core database name is doit.
psql -h localhost -U tamr -d doit
  1. Start Tamr Core and its dependencies, and then upgrade Tamr Core to v2020.012.0 or greater. See Upgrading.
./start-dependencies.sh
./start-unify.sh
  1. Optional. Delete the dumpfile.
sudo rm /var/lib/pgsql/dumpfile
  1. Optional. Disable and uninstall the PostgreSQL client for the previous version. This step is recommended to avoid unintentional initialization of the previous version; however, it should only be performed if the previous version is not being used by any other applications.
sudo yum remove postgresql94

or

sudo systemctl disable postgresql-9.4

Upgrading Postgres to Version 12 on Ubuntu

These instructions assume that you are running a Tamr Core version released before v2020.012.0 and want to upgrade your PostgreSQL instance to v12.

  • If you are installing Tamr Core v2020.012.0 or greater for the first time, you must install PostgreSQL v12. See Installing Postgres in this documentation.
  • If you are upgrading to Tamr Core v2020.012.0 or greater, you must upgrade to PostgreSQL v12 using these instructions.

To upgrade your Instance of PostgreSQL to version 12:

  1. Stop Tamr Core and its dependencies. See Restarting.
cd /home/ubuntu/tamr
./stop-unify.sh
./stop-dependencies.sh
  1. Confirm that a single PostgreSQL cluster with version 9.4 exists.
sudo pg_lsclusters
  1. Install the PostgreSQL client version 12.
sudo apt install postgresql-12 postgresql-client-12
  1. List PostgreSQL clusters.
sudo pg_lsclusters

You should see two clusters running, with PostgreSQL versions 9.4 and 12.
5. Drop the PostgreSQL 12 cluster and stop it.

sudo pg_dropcluster 12 main --stop 
  1. List PostgreSQL clusters to verify that now the PostgreSQL 9.4 cluster is running.
sudo pg_lsclusters
  1. Upgrade the 9.4 cluster to PostgreSQL version 12.
sudo pg_upgradecluster -v 12 9.4 main
  1. List PostgreSQL clusters to verify that the PostgreSQL cluster with version 9.4 is present but stopped, and the PostgreSQL cluster with version 12 is running.
sudo pg_lsclusters
  1. Verify that PostgreSQL v12 is installed.
sudo psql --version
  1. Restore any previous pg_hba.conf and postgresql.conf modifications. Compare /var/lib/pgsql/9.4/data/pg_hba.conf and /var/lib/pgsql/12/data/pg_hba.conf and restore any non-default location for PG_DATA.

  2. Open postgresql.conf and add an entry to it as follows, to make the PostgreSQL instance listen on all addresses, and not only on the loopback address. Save the file.

listen_addresses = '*'
  1. Open the postgresql.conf again and confirm that the port for PostgreSQL is specified correctly as 5432.
    By default, PostgreSQL 12 binds the port 5432 after an upgrade when it takes over from PostgreSQL 9.4 or earlier. However, your instance of PostgreSQL 12 may not be configured to use port 5432 after restart. This may happen if the port 5432 is taken by the instance with the previous version of Postgres, such as PostgreSQL 9.4, before that instance is dropped.
port = 5432
  1. Verify that Tamr Core can connect to its database in this instance of PostgreSQL. The default database name is doit.
sudo psql -h localhost -U tamr -l doit
  1. Start Tamr Core and its dependencies, and then upgrade Tamr Core to v2020.012.0 or greater. See Upgrading.
./start-dependencies.sh
./start-unify.sh
  1. Run the Tamr Core backup to confirm that you have PostgreSQL 12 installed. For example, run:
cd utils
./unify-admin.sh upgrade --zipFile ~/unify-<version>.zip --installDir ~/ --nobackup

This command should succeed if everything is working as required.
Note: This command should fail if you are upgrading to a Tamr Core version before v2020.012, because of a PostgreSQL validation error caused by the PostgreSQL version being higher than required.
16. Confirm that there are no other validation errors and then run the upgrade without validation. See Upgrading and Validation.
For example, run:

./unify-admin.sh upgrade --zipFile ~/unify-<version>.zip --installDir ~/ --nobackup --skipEnvironmentValidation PGValidator
  1. Optional. Drop the PostgreSQL cluster for the previous version. This step is recommended to avoid unintentional initialization of the previous version; however, it should only be performed if the previous version is not being used by any other applications.
sudo pg_dropcluster 9.4 main