While we've worked hard to make updates to newer versions of Neo4j as pleasant as possible, these are a few things to be aware of, particularly when switching to a major revision.

Neo4j 3.3 Upgrade FAQ

Upgrade FAQs for Neo4j 3.2 and earlier

What is in 3.3?

  • Write and read performance
    • Write performance of transactional writes have improved with on average 50% for typical graphs compared to Neo4j 3.2, and with over 100% compared to Neo4j 3.1.
    • Bulk writes at initial graph creation has an up to 40% smaller memory footprint
    • The new Cypher Slotted Runtime results in faster queries while using one third of the memory compared to the 3.2 Cypher Runtime
    • Least-connected load balancing strategy for clusters minimizes the effect on cluster performance when one server experiences heavy load
  • Enterprise Security
    • New support introduced for intra-cluster encryption, including multi-DC cluster communication encryption
  • Kernel improvements
    • Neo4j Enterprise now allows key configuration parameters to be changed on the fly, without needing to recycle a database instance.
    • Local Schema Locks automatically narrow the scope of locks, avoiding the need for the database to take a global schema lock when creating or changing a schema object or constraint.
    • Cache-hit ratio is now available at both a query and database level, as a new metric for helping to size one’s database cache.

Where are the Release Notes?

Release notes for all Neo4j releases can be found here: http://neo4j.com/release-notes/

Is 3.3 an API-Breaking Release?

No. Minor releases are a place to deprecate features and functionality, which includes public APIs. However, we will not remove deprecated functionality until a major release. Note: Upgrading from a version prior to Neo4j 3.0 means that the 3.0 Upgrade FAQs apply, and this would then be a breaking release. If you are upgrading from a 2.x release, see the Upgrade FAQ Archive.

A few things you should know about 3.3:

  • The new Slotted Runtime will be used for most Cypher queries. Use the PROFILE or EXPLAIN keywords to see which runtime is being used if unsure.
  • While Causal Clustering is the primary clustering architecture we are building on, HA still works as well.
  • Causal Clustering is still available for server only, not embedded at this time.
  • neo4j-shell is deprecated in favor of the new cypher-shell
  • neo4j-backup is deprecated in favor of neo4j-admin backup
  • Configuration settings that changed:
    • dbms.allow_format_migration is now dbms.allow_upgrade

Migrate configuration from a pre-3.0 version

When migrating to Neo4j 3.3 from a release prior to 3.0 please note that most configuration settings have been renamed to support a more consistent naming scheme. Also note that neo4j.properties and neo4j-server.properties have been merged into a single neo4j.conf file. Since many settings have been changed between Neo4j 2.x and Neo4j 3.x, it is advisable to use the config-migrator utility to migrate the config files and settings for you. The config-migrator can be found in the bin/tools directory of Neo4j 3.x, and can be invoked with a command like: java -jar config-migrator.jar path/to/neo4j2.3 path/to/neo4j3.3. Take note of any warnings printed, and manually review the edited config files produced. The warnings will alert you to deprecated settings, or settings it did not know about (spelling mistakes, etc) that require manual intervention.

Where in the Documentation Can I Learn More about Upgrades?

The Upgrade section of the Neo4j Operations Manual can be found here, and also covers upgrades specific to 3.3. The store upgrade happens by starting your Neo4j data store (after making the backup) with Neo4j 3.3 and the configuration dbms.allow_upgrade=true enabled in the configuration file conf/neo4j.conf

Are there any Backwards-Compatibility Options?

Yes. Cypher lets you specify what version of the Cypher compiler you would like to use. See Operations Manual for details. So it is possible to run 2.3 queries and newer without changing them. Of course you will eventually want to upgrade your queries to take advantage of the new features in Cypher and Neo4j 3.3. Also of note is the new Causal Clustering architecture introduced in 3.1 and further improved in 3.3. Note that 3.3 will continue to support the previous Master/Slave clustering architecture available in prior versions. You can upgrade an HA system to 3.3, and save the cluster changes for a later date to simplify the process.

Is the Store Upgrade Reversible?

No, once your data store is upgraded, it cannot be rolled back. For this reason, Neo4j makes a backup of each store file as part of the upgrade to 3.3. (And as an extra precaution, it doesn’t hurt to take a second backup before you start the upgrade process. Just make sure you have enough disk space to accommodate this.) Make sure you have at least double the size of your Neo4j store available as free space on your disk, before you upgrade. After the upgrade is successful, those backup files will be removed automatically.

How Long Will the Upgrade Take?

When you initiate the upgrade of your database to 3.3 for the first time, Neo4j will run through the store files and update them to the new format. How much time this takes depends on the size of your data store. We recommend you try this out in a test environment first, to get an idea of the timing, and help you plan your upgrade. Upgrading from 3.x to 3.3 should be quite fast, while upgrading from pre-3.0 to 3.x will take longer due to the Lucene upgrade. Don’t forget though that you will first need to test your application to make sure it works! Chances are that that you may have to make some changes. How much development time required to update your code will depend on your application and which version you are upgrading from. Applications using Neo4j’s native Java APIs will be affected more than others.

When Should I Upgrade?

Upgrading to Neo4j 3.3 from a 3.x version will be very straightforward and will yield immediate performance and governance benefits. You will also have the opportunity to take advantage of new features in the realms of causal clustering, security, governance, etc. If you are in the development and planning phase, then upgrade straight away! If you are already in production with Neo4j, or have a lot of dependencies, test it first and make sure that you have the upgrade steps and dependencies sorted out before upgrading production.

Are Rolling Upgrades Supported?

No. Rolling upgrades let you upgrade a cluster while it is running. While we do our best to support rolling upgrades between patch releases — the scope and nature of the changes made in major/minor versions is such that rolling upgrades are not yet possible. However, for Enterprise customers looking for guidance on minimizing the impact of this upgrade on your system, refer to the article Upgrading a Neo4j Cluster with Minimal Downtime

What Version Can I Upgrade From?

Neo4j 3.3 supports direct upgrades from 2.3 and newer. It is generally recommended to upgrade from the most recent patch of your current Neo4j release, as that is the tested upgrade path from pre-3.3 releases to 3.3. Previous versions, such as 1.9, have to be upgraded to 2.x first.

How Long Can I Continue Using 3.2?

3.2 will continue to be supported for at least 18 months following its release, until November 11, 2018, per the terms of your Support Agreement. Any fixes deemed applicable to the 3.2 release will be released in a 3.2.x release. As of the time of this writing, the latest stable 3.2.x release is 3.2.6. Commercial customers can view currently Supported Versions here.


Michael Colburn says:

There is a significant difference between the neo4j.conf for the Community Edition 3.2.0 and 3.3.0. Specifically, the addition of an entire section on SSL settings. But there is no FAQ about how to initially configure the SSL settings. For example, I have uncommented:


and set


But, neo4j crashes on startup.

Aileen Agricola says:

Hi Michael,

Our apologies for the issues you are experiencing. Please share your issue on our slack channel at: http://neo4j-users-slack-invite.herokuapp.com/
or log an issue on github: https://github.com/neo4j/neo4j/issues

Thank you. Aileen, web programs manager

Ioana says:

I have been trying to upgrade from 2.3.12 to 3.3.4 (community edition) , but the upgrade fails when the migration 4/5 starts.
part of log: ‘org.neo4j.server.database.LifecycleManagingDatabase@7c541c15’ was successfully initialized, but failed to start. Please see the attached cause exception “The node label update contained unsorted label ids [0, 47, 48, 49, 11, 12, 7]”. Starting Neo4j failed….
I have been trying to upgrade to 3.2.10 as an intermediary step, but it fails the same way. I removed all the indexes and node labels from the 2.3.12 version of the database, but it did not help… How can I get some support on this?

Leave a Reply

Your email address will not be published. Required fields are marked *