
-------------------------------------------------------------------------------

Upgrading

-------------------------------------------------------------------------------
-------------------------------------------------------------------------------

Table of Contents

1. Automatic Upgrade
2. Explicit Upgrade
3. Upgrade 1.9 --> 2.0

    3.1. Cypher compatibility
    3.2. Embedded Java API
    3.3. Other significant changes

4. Upgrade 1.8 --> 1.9
5. Upgrade 1.7 --> 1.8
6. Upgrade 1.6 --> 1.7
7. Upgrade 1.5 --> 1.6
8. Upgrade 1.4 --> 1.5

A database can be upgraded from a minor version to the next, e.g. 1.1 --> 1.2,
and 1.2 --> 1.3, but you can not jump directly from 1.1 --> 1.3. For version
1.8 in particular, it is possible to upgrade directly from version 1.5.3 and
later, as an explicit upgrade. The upgrade process is a one way step; databases
cannot be downgraded.

For most upgrades, only small changes are required to the database store, and
these changes proceed automatically when you start up the database using the
newer version of Neo4j.

However, some upgrades require more significant changes to the database store.
In these cases, Neo4j will refuse to start without explicit configuration to
allow the upgrade.

The table below lists recent Neo4j versions, and the type of upgrade required.

Table 1. Upgrade process for Neo4j version

+--------------------------------------+
|From Version |To Version|Upgrade Type |
|-------------+----------+-------------|
|1.3          |1.4       |Automatic    |
|-------------+----------+-------------|
|1.4          |1.5       |Explicit     |
|-------------+----------+-------------|
|1.5          |1.6       |Explicit     |
|-------------+----------+-------------|
|1.6          |1.7       |Automatic    |
|-------------+----------+-------------|
|1.7          |1.8       |Automatic    |
|-------------+----------+-------------|
|1.8          |1.9       |Automatic    |
|-------------+----------+-------------|
|1.9          |2.0       |Explicit     |
+--------------------------------------+


Note

Downgrade is supported only between versions which do not have incompatible
store layouts. That means that if you did an upgrade where you didn’t have to
explicitly set the allow_store_upgrade flag to false then you can downgrade
without any problems to the previous version used. Otherwise downgrading is not
supported. In any case, downgrading currently cannot be done in a rolling
fashion, even in HA deployments. Instead, the whole cluster must be shutdown
and each machine downgraded individually and then the service can be resumed.


-------------------------------------------------------------------------------

1. Automatic Upgrade

-------------------------------------------------------------------------------

To perform a normal upgrade (for minor changes to the database store):

 1. Download the newer version of Neo4j.
 2. Cleanly shut down the database to upgrade, if it is running.
 3. Startup the database with the newer version of Neo4j.
 4. The upgrade will happen during startup and the process is done when the
    database has been successfully started.


-------------------------------------------------------------------------------

2. Explicit Upgrade

-------------------------------------------------------------------------------

To perform a special upgrade (for significant changes to the database store):

 1. Download the newer version of Neo4j.
 2. Cleanly shut down the database to upgrade, if it is running.
 3. Set the Neo4j configuration parameter allow_store_upgrade=true in your 
    neo4j.properties or embedded configuration.
 4. Startup the database with the newer version of Neo4j.
 5. The upgrade will happen during startup and the process is done when the
    database has been successfully started.
 6. The allow_store_upgrade configuration parameter should be removed, set to
    false or commented out.
 7. Information about the upgrade and progress indicator is printed in 
    messages.log.


-------------------------------------------------------------------------------

3. Upgrade 1.9 --> 2.0

-------------------------------------------------------------------------------

This edition adds a new store for labels and one for schema, an index for
labels, and also the format of the node store has changed. Note that we do not
currently support rolling upgrades between 1.9.x and 2.0.

For Neo4j 2.0, Java 7 is required. We recommend that you install the Java JDK 7
from the Oracle Website.

When upgrading, the following will happen and will both take some time, and
will require extra disk space:

 1. A new, empty schema store will be created.
 2. A new, empty label store will be created.
 3. A new, empty label scan index will be created.
 4. The node store will be converted, we need to enlarge each record to make
    space for labels — this will take time depending on the size of your
    database.


3.1. Cypher compatibility

--------------

Unless you set the statements to still use Cypher 1.9, they have to be updated
for the following changes:

Pattern syntax
    Parentheses are required around node patterns when labels are used. This
    means that when adding labels to a pattern like a-->b you should use
    something like (a:Person)-->(b:Company). It’s good practice to use
    parentheses in node patterns even where they are not strictly required, to
    enhance readability.
Optional relationships
    The syntax (a)-[?]->(x) for optional relationships has been removed. Use
    OPTIONAL MATCH instead (see the corresponding chapter in the Neo4j Manual).
The ! and ? property operators
    Expressions like node.property = "value" will not fail when a node without
    the property is encountered, and will instead return NULL. This is the same
    behavior as node.property! = "value" in Cypher 1.9. The ! property operator
    has been removed in 2.0. Support for expressions using the ? property
    operator, such as node.property? = "value", have also been removed. You can
    use not(has(node.property)) OR node.property = "value" instead, which is
    compatible with both 1.9 and 2.0.

CREATE syntax
    The CREATE a={foo:’bar’} syntax has been removed. Instead, use CREATE (a
    {foo:’bar’}).
Using DELETE to remove properties
    The DELETE a.prop syntax has been removed. Instead, use REMOVE a.prop.
Using parameters for index keys
    Parameters can not be used as the key in START clauses using indexes (for
    example START n=node:index({key}='value')). Use the literal key names
    instead.
Using parameters to identify nodes in patterns
    Parameters can not be used to identify nodes in a pattern (ie. MATCH
    ({node})-->(other))). Note that this form was only possible when mixing the
    embedded Java API and Cypher, and thus does not affect users of Neo4j
    Server.
Iteration syntax in FOREACH, EXTRACT, etc
    The iterating functions use a | instead of a : to separate the components
    of the statement. For example, EXTRACT(n in ns : n.prop) is replaced with
    EXTRACT(n in ns | n.prop). The iterating functions include FOREACH,
    EXTRACT, REDUCE, ANY, ALL, SINGLE and NONE.
Alternative WITH syntax
    The alternative WITH syntax, === <identifiers> ===, has been removed. Use
    the WITH keyword instead.
The Reference Node
    With the introduction of Labels in Neo4j 2.0 the Reference Node has become
    obsolete and has been removed. Instead, labeled nodes has become the
    well-known starting points in your graph. You can use a pattern like this
    to access a reference node: MATCH (ref:MyReference) RETURN ref. Simply use
    one label per such starting point you want to use. Note that this should be
    executed once during application initialization, to ensure that only a
    single reference node is created per label. When migrating a database with
    an existing reference node, add a label to it during migration, and then
    use it as per the previous pattern. This is how to add the label: START ref
    =node(0) SET ref:MyReference. In case you have altered the database so a
    different node is the reference node, substitute the node id in the
    statement.


3.2. Embedded Java API

--------------

Mandatory Transactions
    Transactions are now mandatory for read operations as well.
The Reference Node


3.3. Other significant changes

--------------

Plugins
    Plugins are no longer distributed with Neo4j. Please see individual
    maintainers about availability. For instance, the source for the Gremlin
    plugin will be available at: https://github.com/neo4j-contrib/
    gremlin-plugin


-------------------------------------------------------------------------------

4. Upgrade 1.8 --> 1.9

-------------------------------------------------------------------------------

There are no store format changes between these versions so upgrading
standalone instances simply consists of starting the database with the newer
version. In the case of High Availability (HA) installations, the communication
protocol and the master election algorithm have changed and a new "rolling
upgrade" feature has been added, removing the need to shut down the entire
cluster. For more information, refer to the "Upgrading a Neo4j HA Cluster"
chapter of the HA section of the Neo4j manual.


-------------------------------------------------------------------------------

5. Upgrade 1.7 --> 1.8

-------------------------------------------------------------------------------

There are no store format changes between these versions so upgrading
standalone instances simply consists of starting the database with the newer
version. In the case of High Availability (HA) installations, the communication
protocol and the master election algorithm have changed and a new "rolling
upgrade" feature has been added, removing the need to shut down the entire
cluster. For more information, refer to the "Upgrading a Neo4j HA Cluster"
chapter of the HA section of the Neo4j manual.


-------------------------------------------------------------------------------

6. Upgrade 1.6 --> 1.7

-------------------------------------------------------------------------------

There are no store format changes between these versions, which means there is
no particular procedure you need to upgrade a single instance.

In an HA environment these steps need to be performed:

 1. shut down all the databases in the cluster
 2. shut down the ZooKeeper cluster and clear the version-2 directories on all
    the ZooKeeper instances
 3. start the ZooKeeper cluster again
 4. remove the databases except the master and start the master database with
    1.7
 5. start up the other databases so that they get a copy from the master


-------------------------------------------------------------------------------

7. Upgrade 1.5 --> 1.6

-------------------------------------------------------------------------------

This upgrade changes lucene version from 3.1 to 3.5. The upgrade itself is done
by Lucene by loading an index.

In an HA environment these steps need to be performed:

 1. shut down all the databases in the cluster
 2. shut down the ZooKeeper cluster and clear the version-2 directories on all
    the ZooKeeper instances
 3. start the ZooKeeper cluster again
 4. start up the other databases so that they get a copy from the master


-------------------------------------------------------------------------------

8. Upgrade 1.4 --> 1.5

-------------------------------------------------------------------------------

This upgrade includes a significant change to the layout of property store
files, which reduces their size on disk, and improves IO performance. To
achieve this layout change, the upgrade process takes some time to process the
whole of the existing database. You should budget for several minutes per
gigabyte of data as part of your upgrade planning.

Warning

The upgrade process for this upgrade temporarily requires additional disk
space, for the period while the upgrade is in progress. Before starting the
upgrade to Neo4j 1.5, you should ensure that the machine performing the upgrade
has free space equal to the current size of of the database on disk. You can
find the current space occupied by the database by inspecting the store file
directory (data/graph.db is the default location in Neo4j server). Once the
upgrade is complete, this additional space is no longer required.

