Upgrading to 0.7.0

This note describes the necessary steps to upgrade to Stellio 0.7.0

Neo4j migration

Below the necessary steps to migrate a single instance from Neo4j 3.5.x to Neo4j 4.0.x.

Upgrading to neo4j 4.0.x from a 3.5.x version

Backup

The neo4j database is persisted in a docker volume.

The volume is declared as stellio-neo4j-storage in the docker-compose.yml file of the root folder and as stellio-entity-neo4j-storage in the docker-compose.yml file of the entity-service folder.

The choice depends on the docker-compose.yml file you already use to launch the services that you want to upgrade (in this note we will use the docker-compose.yml file of the root folder).

We need to make a backup of this volume that can be used if the migration goes wrong.

To list the docker volumes:

docker volume ls

As mentioned, we will use the stellio-context-broker_stellio-neo4j-storage volume (please consider working with your own volume name if you changed it in the docker-compose.yml file).

To locate the volume mountpoint:

docker volume inspect stellio-context-broker_stellio-neo4j-storage | jq '.[0].Mountpoint'

The mountpoint is the path of the data directory generated by the neo4j container.

Make a copy of this directory.

cp -r $neo4j_volume $destination_folder

Notes:

  • $neo4j_volume is the path of the data directory retrieved previously with the docker inspect command.
  • $destination_folder is an empty backup directory.

Migration

  • Update the service image in the docker-compose.yml file: Replace neo4j:3.5.14 by neo4j:4.0

  • Set the NEO4J_ALLOW_UPGRADE variable in entity service .env file to true (this enables upgrading the store format to the 4.x structure).

Note: Please consider using the .env file in the root folder or in the entity-service folder according to the docker-compose.yml file used previously.

As mentioned, we will use the docker-compose.yml and the .env files of the root folder.

  • Under the _data mounted folder, update the database name by renaming the graph.db folder under databases folder to stellio (stellio is the default database name set with the NEO4J_DEFAULT_DATABASE variable in the .env file).
mv $neo4j_volume/databases/graph.db $neo4j_volume/databases/stellio

Note: Please consider that the 4.x version add support for multiple databases that follow a naming convention without special characters including dots.

  • Recreate the neo4j container by running:
docker compose up -d

Note: Here we use the docker-compose.yml file of the root folder.

  • Once finished, the NEO4J_ALLOW_UPGRADE variable in the used .env file should be set to false.

Troubleshooting

In case of database connection problem, please consider adding the following environment variable to the entity service docker-compose.yml file:

NEO4J_dbms_recovery_fail__on__missing__files=false

and removing the neostore.transaction.db.0 file under the new stellio folder and recreating the container by running:

docker compose up -d

In case you encounter any problem during the migration process, please do create an issue on Github

Browser connection to neo4j

For browser connection to Neo4j, please make sure that the Connect URL uses the bolt protocol.