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

Neo4j 3.0 Upgrade FAQ

What is in 3.0?

Neo4j 3.0 substantially improves installation, application development, and operational management. On disk, Neo4j has a reorganized directory layout which is easier to understand and work with; take note of the new locations and names. Application development has been vastly simplified and optimized, featuring a single, coherent, high-speed programming interface called Bolt. With Cypher’s new ability to mix queries and calls to Java Stored Procedures, even Java developers will love working over-the-wire.

Where are the Release Notes?

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

Is 3.0 an API-Breaking Release?

Yes. Major releases are the time when we remove features that were marked deprecated in earlier releases. Further: to benefit from the upgrade to Neo4j 3.0, you will need to change your code to take advantage of the new features, such as the new language drivers over the Bolt protocol.

A few things you should know about 3.0:

Migrate configuration

When migrating to Neo4j 3.0 from a previous release, 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.0, 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.0, and can be invoked with a command like: java -jar config-migrator.jar path/to/neo4j2.3 path/to/neo4j3.0. 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.

Also note that the following configuration settings have been removed between Neo4j 2.3 and 3.0:

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.0. The store upgrade happens by starting your Neo4j data store (after making the backup) with Neo4j 3.0 and the configuration dbms.allow_format_migration=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 your 2.x queries 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.0.

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 2.x store file as part of the upgrade to 3.0. (And as an extra precaution, it doesn’t hurt to take a second backup before you start the upgrade process.) 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.There is a new store format option to remove the upper limits for numbers of nodes, relationships, and properties in a single graph. The default format is the previous, standard format. To enable the new high limit format, set dbms.record_format=high_limit in conf/neo4j.conf. Note: Once you start the database with the high limit format, you cannot revert back!

How Long Will the Upgrade Take?

When you initiate the upgrade of your database to 3.0 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. Don’t forget though that you will first need to test your application to make sure it works! Chances are that that you will have to make some changes. How much development time required to update your code will depend on your application. Applications using Neo4j’s native Java APIs will be affected more than others. Beyond the changes required to upgrade, leveraging new features such as the new language drivers and Bolt binary protocol, will may take more or less time depending on your application.

When Should I Upgrade?

If you are planning a new release of your app, and adding new features, then we recommend you upgrade now: since you are likely to save a lot of time with the new features. Even if you aren’t adding features, we suggest you start planning your upgrade soon, in the coming months, as the 2.2 and prior releases will now be going into maintenance mode. As far as when to schedule your upgrade? Upgrading an already-running application to 3.0 just for the sake of it may not yield huge benefits right now. One good reason to start planning an upgrade besides new features is the upcoming 3.1 release. Neo4j 3.1 is planned to be a minor/API-compatible release of Neo4j 3.x, focused primarily on scalability and security. Neo4j 3.1 is expected mid-late 2016, and like 3.0, will require a store upgrade. Customers not in a hurry to upgrade, and/or seeking to minimize their Neo4j upgrade overhead in 2016, might want to start developing on 3.0 and go live with 3.1. As always, we encourage you to contact Support to discuss your actual situation. We are happy to offer advice as to when to time your upgrade.

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 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.0 supports direct upgrades from 2.0 and newer. It is generally recommended to upgrade from a recent patch, as that is the tested upgrade path from pre-3.0 releases to 3.0. Previous versions, such as 1.9, have to be upgraded to 2.x first.

How Long Can I Continue Using 2.3?

2.3 will continue to be supported for at least 6 months in parallel to 3.0, according to the terms of your Support Agreement. Any critical fixes deemed important enough will be released in a 2.3.x release. As of the time of this writing, the latest stable 2.3.x release is 2.3.3.

Faster than 2.3?

One major improvement in 3.0 is the introduction of unified language drivers and the Bolt binary protocol. In addition to giving a clean, concise and controlled driver interface across languages, the Bolt protocol is an improvement over the REST API in terms of overhead and performance. In addition, 3.0 introduces a cost-based optimizer for write queries, to complement the cost-based optimizer for reads introduced in Neo4j 2.2. You can expect write queries to particularly benefit from this release. Also, if you handled reads and writes in separate transactions to make sure reads used the cost-based planner, that extra code is no longer needed. On top of that, Neo4j 3.0 includes an upgrade of Lucene to version 5, so index writes are optimized.


[…] Neo4j 1.9 users may upgrade directly to this release, and are recommended to do so carefully. We strongly encourage verifying the syntax and validating all responses from your Cypher scripts, REST calls, and Java code before upgrading any production system. For information about upgrading from Neo4j 1.9, please see our Upgrading to Neo4j 2 FAQ. […]

Iyke says:

I’m just wondering if there is any change on Loading CSV into Neo4j 3.0 . I copied my Load data statement that runs very well in 2.3 version to load the same data into Neo4j 3.0 . It could not just load it. Below is the statement that worked well in 2.3 version.

load csv with headers from “file:C:/Data/agency.csv” as agency
create (a:Agency {agencyID:agency.agency_id,agName:agency.agency_name, agUrl:agency.agency_url, AgTimezone:agency.agency_timezone});

And it says “URI is not hierarchical”
Then when I tried “file:///C:/Data/agency.csv” it says “Couldn’t load the external resource at: file:/C:/TTGTFS3.0/import/Data/agency.csv”

Dave Gordon says:

Hi lyke,

There is a config setting in Neo4j 3.0 to improve security of files being ingested by Neo4j. The setting is in conf/neo4j.conf:

# This setting constrains all `LOAD CSV` import files to be under the `import` directory. Remove or uncomment it to
# allow files to be loaded from anywhere in filesystem; this introduces possible security problems. See the `LOAD CSV`
# section of the manual for details.

You can comment this out to remove this restriction, or move your CSV file into the import directory within the Neo4j installation.

Hope this helps.

Lior says:

Hi, is there a list of the breaking changes?
Also is rest api still going to work?

David Gordon says:

There is no complete list of breaking changes. In general, nearly all config settings have changed, file locations within the Neo4j install have changed, and the Java API has changed, so please read the javadoc.

Regarding the REST API, yes it will continue to work in parallel with Bolt.

Thanks for asking!

Also the issue with the slow LOAD CSV (using periodic commit has been fixed in 3.0.2)

Anup says:

load csv with headers from “file:///C:/Users/amunavalli/Desktop/airport.csv” as airports create (a1:Airport {label: airports.label, city: airports.city, state:airports.state})

This one still not working after performing the above mentioned steps

Daniel says:

> Cypher lets you specify what version of the Cypher compiler you would like to use.

It would worth to specify in this article, that it should be done here:

echo ‘
‘ >> /etc/neo4j/neo4j.conf

David Gordon says:

Thanks for the suggestion. I have added a link to the appropriate section in the document to cover this. In general, you will want to use this on individual queries instead of system-wide, unless you know all of your queries need it.

1 Trackback

Leave a Reply

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