Neo4j migration from 3.5 to 5.26 (enterprise) using docker

If you are reading this right now, I assume we have the same situation. I actually inherited a project that uses Laravel and Neo4j stack. It was an old project and in order to maintain its Security I had to upgrade the packages. all of them including the database versions.

I thought the project was hopeless because the primary package used that was Written by @vinelab was no longer maintained. Luckily, Danes (people of Denmark) has a Fork and continues to maintain the same package. A big thanks and shoutout to Ulobby.eu for the continued update of the package. With their updates, I was able to update upto Laravel 11 and Php 8.2.

FYI the project came from Laravel 7. Just Imagine the stress I have to go through.

Just recently Ulobby released neoeloquent v9.6 which now then uses the latest version of laudis/neo4j-php-client. Updating to the latest version just breaks the connection to The Neo4j Server which is still in version 3.5 so I have to find I way to upgrade it.

Strategy

upgrading from 3.5 to 4.4 is just a very straightforward process. You just replace the image from 3.5 to 4.4, and its done..

neo4j:
    image: neo4j:4.4.41-enterprise
    container_name: neo4j_server
    restart: unless-stopped
    environment:
      - NEO4J_AUTH=user/password
      - NEO4J_ACCEPT_LICENSE_AGREEMENT=yes
    volumes:
      - ./neo4j-data:/data
      - ./neo4j-data:/logs
      - ./neo4j-backups:/migration-backups
    ports:
      - "7474:7474"
      - "7687:7687"
    networks:
      - default
    command: "neo4j"

Though you can stop here at 4.4 since its an LTS. However, its end of support is Near as of the time I was writing this. So I have to strategize and atleast make it to 5.26 LTS to be able to stay a little bit longer before upgrading again.

The process of migrating from 4.4 to 5.26 is not that hard and not that simple, you might encounter errors not written in the official documentation. Since I cannot directly comment in the documentation, I will write this here for knowledge keeping.

What we have to do is backup->restore->migrate

Backup

I suggest you compress your whole neo4j /data directory for safekeeping, just incase anything goes haywire. you can comeback to where you started.

1. use docker exec to communicate with the docker container shell and use the neo4j-admin commands

You may shutdown the container and use

1. copy and paste this command

neo4j-admin backup --database=<databasename>  --backup-dir=/migration-backups --include-metadata=all

just replace with database name with graph.db or your database name if you just started the migration from 4.4 and not from 3.5 where multiple databases is already supported. and then repeat the process for each database. but since I only have graph.db I will stop there.

Notice that in my compose file above I mounted a specific directory to place migrations. I did that because of the following step.

1. Destroy the container. In my case its just docker compose down neo4j

2. Then delete the entire mount for /data in my case its neo4j

3. Replace the image with version 5.26-enterprise.
   

neo4j:
    image: neo4j:5-26-enterprise
    container_name: neo4j_server
    restart: unless-stopped
    environment:
      - NEO4J_AUTH=user/password
      - NEO4J_ACCEPT_LICENSE_AGREEMENT=yes
    volumes:
      - ./neo4j-data:/data
      - ./neo4j-data:/logs
      - ./neo4j-backups:/migration-backups
    ports:
      - "7474:7474"
      - "7687:7687"
    networks:
      - default
    command: ["/bin/sh", "-c", "while :; do sleep 2073600; done"]

1. Then start the container. In my case, its just docker compose up -d neo4j

notice the compose file doesnt automatically start the neo4j server?, its because we have to perform the migration manually, and turning off the neo4j service also shuts down the container.

1. use docker exec, and fireup the neo4j using neo4j start

for some reason, the initial auth doesnt get set in the ENVIRONMENT settings in docker you you might wanna visit the browser with localhost:7474 and then setup the authentication, neo4j's default user and password is neo4j/neo4j

then stop neo4j service with neo4j stop.
_This is why the command section in the compose file matters. _

1. then put into the docker exec shell neo4j-admin database restore neo4j --overwrite-destination --from-path=/migration-backups/graph.db

the --overwite-destination flag overwrites the default database neo4j but if you are restoring a different database name, that is unecessary.

1. after that neo4j-admin database migrate neo4j --force-btree-indexes-to-range migrate it with that code

Last Step: start the database service with neo4j start , you may now check your browser at localhost:7474 and see your data successfully migrated.

If you have encountered bizzare situation, feel free to comment it here and I will be answering them if I can. I am sure other experts are there as well to help us. Happy Coding!