Skip to main content

2.8.0 to 2.9.0

This document describes the upgrade instructions from 2.8.0 to 2.9.0.

PostgreSQL 16.2 update​

Aerie 2.9.0 uses PostgreSQL 16.2, which is a major version upgrade from our previous version (PostgreSQL 14.8). Due to changes in PG's internal data representation, an additional data transfer process is required in order to properly migrate your data forward. If you want to preserve & migrate your data, you must follow the instructions below or data corruption may occur.

PostgreSQL data transfer (dump & restore)​

The safest method for transferring data in a major PostgreSQL version upgrade is to "dump" the data out to a file using the old version, and then restoring the database from the file in the new version. For reference, these instructions are adapted from this PostgreSQL documentation and modified to work with our Docker containers.

Before you upgrade to Aerie 2.9.0, follow these steps on your existing Aerie instance:

  1. Check that you have version 16.2 of PostgreSQL installed locally by running psql --version on your terminal, and install it if not. a. Mac users can run brew install libpq to install. b. For other platforms, download the Postgres installer, and uncheck "PostgreSQL Server" when installing
  2. Make sure your Aerie services are running.
  3. Run the following command to dump your database to a local file called dump.sql. Modify this command as necessary to specify your database options: a. PGPASSWORD=<POSTGRES PASSWORD> pg_dumpall -h localhost -p 5432 -U <POSTGRES USERNAME> > dump.sql
  4. Run docker compose down to bring down your Aerie services.
  5. Run docker volume remove aerie_postgres_data to remove your old database volume.

At this point, follow whatever process you usually use to upgrade your deployment to the new Aerie version (eg. copying/extracting the files to your server) but do not start Aerie yet, you must perform the following steps on the Aerie 2.9.0 files first:

  1. Open your docker-compose.yml file and add a # at the beginning of the line - ./deployment/postgres-init-db:/docker-entrypoint-initdb.d (under postgres.volumes) to temporarily comment it out and avoid Aerie attempting to create a fresh database.
  2. Run docker compose up -d postgres to bring up the Aerie postgres container only.
  3. From the directory containting your dump.sql file, run the following command to restore your data, modifying as necessary with your DB options: a. PGPASSWORD=<POSTGRES PASSWORD> psql -h localhost -p 5432 -U <POSTGRES USERNAME> -f dump.sql -d postgres b. The output of this should be a lot of SQL commands but no errors. If you see errors, you may have accidentally started other Aerie services and should retry from Step 5 above. If you're still getting errors, ask in our Slack channel for assistance.
  4. Now run docker compose up (with optional -d flag) to start the rest of the Aerie services.
  5. You can now safely remove the comment in your docker-compose.yml added in Step 1.

Congratulations! You should now be running Aerie 2.9.0 with PostgreSQL 16.2 and your data has been preserved.

aerie_db_migration.py changes​

There have been some recent changes to the file aerie_db_migration.py in the Aerie deployment folder. Some users may be using modified versions of this file - if so, make sure to bring your file up to date with the latest version from the deployment. If you're using this file as-is with no modifications, no action is needed.