Release v2.9.0 (#148)

* Release v2.9.0

* upgrade guide 2.8.0 -> 2.9.0

---------

Co-authored-by: joswig <[email protected]>
Co-authored-by: dandelany <[email protected]>

docs/upgrade-guides/2-8-0-to-2-9-0.md

@@ -0,0 +1,37 @@
+# 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](https://www.postgresql.org/docs/current/upgrading.html#UPGRADING-VIA-PGDUMPALL) 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](https://www.postgresql.org/download), 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.
+

sidebars.js

@@ -324,6 +324,7 @@ const sidebars = {
     'glossary',
   ],
   upgradeGuides: [
+    'upgrade-guides/2-8-0-to-2-9-0',
     'upgrade-guides/2-7-1-to-2-8-0',
     'upgrade-guides/2-7-0-to-2-7-1',
     'upgrade-guides/2-6-2-to-2-7-0',