3.10. Database Migrations

Although we try our best to automatically migrate your server when upgrading versions, there are times when this is simply not possible. In this section we will attempt to cover some of the most common migrations you might encounter when running our software yourself via a Docker container.

Do not attempt to upgrade beyond more than two major GeoPrism Registry versions at a time.

The general steps for performing any sort of migration can be broken down as follows:

1. Create a clone environment of your production server where we will test these steps

2. Perform all required steps as outlined in the "Orient DB Migration" and/or "PostgreSQL Migration" sections below on the cloned environment, keeping track of the exact commands relevant for your environment and making note of any issues or cavaets.

3. Set your docker-compose.yml file (in the test environment) to the new GeoPrism Registry / Postgres / OrientDB versions and run docker compose down then docker compose pull. Then do a docker compose up. When the GeoPrism Registry boots, it will automatically run any additional patches or migration scripts as necessary. Be patient as this step can take time.

4. Check the logs for any errors and make sure the test server is operational and responding.

5. Allocate a "downtime window" for your server so as to disturb users as little as possible

6. Perform a snapshot / backup of your production server

7. Stop the webserver with docker stop georegistry

8. Perform the steps exactly as they were performed on the test environment, except this time on the live production environment

Orient DB Migration

If a newer version of the GeoPrism Registry requires a major upgrade of your Orient DB software, a manual data migration must be performed.

The official OrientDB migration documentation can be found here:

http://www.orientdb.com/docs/last/release/Upgrade.html

Since the official OrientDB migration documentation can be either confusing, lacking in detail, or simply not targeted towards the way we use their software, we will walk you through the detailed steps here.

1. Stop the webserver with docker stop georegistry

2. Create a database dump of the Orient DB server. This command includes variables (starting with $) which must be replaced before running. docker exec georegistry-orientdb bash -c 'bin/console.sh "connect remote:localhost/georegistry $ORIENTDB_ROOT_USER $ORIENTDB_ROOT_PASS; export database /orientdb/backup/$ORIENTDB_MAJOR_VERSION.json"'

   1. The default orientdb root username is 'root'

   2. The default orientdb root password is 'root'

   3. The OrientDB major version should not include the fix version. For example, '3.2'.

3. Kill the Orient DB server docker rm -f georegistry-orientdb

4. Remove all data inside the mounted volume rm -rf data/orientdb/databases/*

5. Run Orient DB of the new version. This command includes variables (starting with $) which must be replaced before running. docker run --name georegistry-orientdb2 -e ORIENTDB_ROOT_PASSWORD="$ORIENTDB_ROOT_PASS" -e ORIENTDB_OPTS_MEMORY="-Xms512M -Xmx2G" -d -v /data/orientdb/databases:/orientdb/databases -v /data/orientdb/backup:/orientdb/backup orientdb:$ORIENTDB_MAJOR_VERSION

6. Import the backup into the new Orient DB. This command includes variables (starting with $) which must be replaced before running. docker exec georegistry-orientdb2 bash -c 'bin/console.sh "CREATE DATABASE remote:localhost/georegistry $ORIENTDB_ROOT_USER $ORIENTDB_ROOT_PASS; connect remote:localhost/georegistry $ORIENTDB_ROOT_USER $ORIENTDB_ROOT_PASS; import database /orientdb/backup/$ORIENTDB_MAJOR_VERSION.json.gz"'

7. Kill the temporary Orient DB server docker rm -f georegistry-orientdb2

PostgreSQL Migration

Upgrading PostgreSQL is fairly straightforward and reliable.

The official PostgreSQL migration documenation can be found here:

https://www.postgresql.org/docs/current/upgrading.html#UPGRADING-VIA-PGDUMPALL

The basic steps for performing an upgrade on our default docker compose environment are as follows:

1. Stop the webserver with docker stop georegistry

2. Run a new Postgres of the new version. This command includes variables (starting with $) which must be replaced before running. docker run --name georegistry-postgres2 -d -p 5482:5432 --network $CGR_DOCKER_NETWORK --link georegistry-postgres -v /data/postgres-migrate:/var/lib/postgresql/data -e POSTGRES_PASSWORD=$POSTGRES_ROOT_PASSWORD postgis/postgis:$NEW_POSTGRES_VERSION

   1. The default postgres root username is postgres.

   2. The default postgres root password is georegistry.

   3. The NEW_POSTGRES_VERSION variable is a Docker image tag and should also include a PostGIS version. For example, '14-3.2'.

   4. The value for the CGR_DOCKER_NETWORK variable can be found by running docker inspect georegistry-postgres. The georegistry network name is autogenerated and will be listed in the "Networks" section of the inspect output.

3. Restore old Postgres into new Postgres. This command includes variables (starting with $) which must be replaced before running. docker exec -t georegistry-postgres2 bash -c "(PGPASSWORD=$POSTGRES_ROOT_PASSWORD pg_dumpall --host georegistry-postgres --port 5432 --username postgres --no-password && echo -e \"\n\nALTER ROLE postgres PASSWORD '$POSTGRES_ROOT_PASSWORD';\" && echo -e \"\n\nALTER ROLE georegistry PASSWORD '$POSTGRES_APP_PASSWORD';\") | psql -d postgres --host 127.0.0.1 --port 5432 --username postgres --no-password"

   1. The default Postgres app password is georegistry.

4. Delete temporary Postgres containers docker rm -f georegistry-postgres && docker rm -f georegistry-postgres2

5. Delete the old Postgres data directory rm -rf /data/postgres

6. Copy the postgres data from the new version to the standard directory mv /data/postgres-migrate /data/postgres