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 thegraph.db
folder underdatabases
folder tostellio
(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.