Upgrade Guide

This guide outlines changes to major version of the Neo4j.rb gems. For more detail about version changes, see the neo4j gem CHANGELOG and the neo4j-core gem CHANGELOG.

Note that starting with version 9.0 of the neo4j gem and version 8.0 of the neo4j-core gem, a new practice has been enacted to release a new major / minor change in accordance with Semantic Versioning as soon as it is warranted. While older versions followed semantic versioning, they would contain more changes rolled up into a single version.

This upgrade guide does not cover changes before version 8.0 of the neo4j gem and version 7.0 of the neo4j-core gem. Changes in previous versions weren’t as significant and are covered in the CHANGELOG files for the respective projects.

The neo4j gem from 8.x to 9.x

The enum functionality for ActiveNode and ActiveRel has been changed to be case-insensitive by default.

The neo4j-core gem from 8.x to 9.x

The neo4j-rake_tasks gem is no longer a dependency of the neo4j-core gem (which is, in turn, a dependency of the neo4j gem). To use the rake tasks, you will need to specify the neo4j-rake_tasks gem yourself.

The neo4j gem from 7.x to 8.x and the neo4j-core gem from 6.x to 7.x

Version 8.0 of the neo4j gem and version 7.0 of the neo4j-core gem introduce the most significant change to the Neo4j.rb project since version 3.0 when we introduced support for the HTTP protocol. With this update comes a number of breaking changes which will be outlined on this page

What has changed

The Neo4j.rb project was origionally created just to support accessing Neo4j’s embedded mode Java APIs via jRuby. In version 3.0 HTTP support was introduced, but the resulting code has been showing it’s age. An entirely new API has been created in the neo4j-core gem. The goal of this new API is only to support making Cypher queries to Neo4j either via HTTP, Bolt (Neo4j 3.0’s new binary protocol), or embedded mode in jRuby. The old code is still around to support connecting to Neo4j via it’s Java APIs, but we would like to later replace it with something simpler (perhaps in another gem).

The neo4j gem (which provides the ActiveNode and ActiveRel modules) has been refactored to use the new API in neo4j-core. Because of this if you are using ActiveNode/ActiveRel not much should change.

Before upgrading, the first thing that you should do is to upgrade to the latest 7.1.x version of the neo4j gem and the latest 6.1.x version of the neo4j-core gem. The upgrade from any previous gem > 3.0 should not be too difficult, but we are always happy to help on Gitter or Stackoverflow if you are having trouble

The neo4j-core gem

If you are using the neo4j-core gem without the neo4j gem, you should be able to continue using it as you have previously. It is recommended, however, that you refactor your code to use the new API. Some advantages of the new API:

  • The new binary protocol (“Bolt”) is supported
  • You can make multiple queries at a time
  • The interface is simpler
  • Node and relationship objects don’t change depending on the underlying query mechanism (Bolt/HTTP/embedded)
  • Path objects are now returned

One thing to note is that Node and Relationship objects in the new API are, by design, simple objects. In the old API you could get relationships and other information by calling methods on node or relationship objects. In the new API you must create Cypher queries for all data access.

The new API

To make a new session, you must first create an adaptor object and then provide it to the session new method:

require 'neo4j/core/cypher_session/adaptors/http'
neo4j_adaptor = Neo4j::Core::CypherSession::Adaptors::HTTP.new('http://user:pass@host:port', options)
# or
require 'neo4j/core/cypher_session/adaptors/bolt'
neo4j_adaptor = Neo4j::Core::CypherSession::Adaptors::Bolt.new('bolt://user:pass@host:port', options)
# or
require 'neo4j/core/cypher_session/adaptors/embedded'
neo4j_adaptor = Neo4j::Core::CypherSession::Adaptors::Embedded.new('path/to/db', options)

neo4j_session = Neo4j::Core::CypherSession.new(neo4j_adaptor)

With your session object, you can make queries in a number of different ways:

# Basic query
neo4j_session.query('MATCH (n) RETURN n LIMIT 10')

# Query with parameters
neo4j_session.query('MATCH (n) RETURN n LIMIT {limit}', limit: 10)

Or via the Neo4j::Core::Query class

query_obj = Neo4j::Core::Query.new.match(:n).return(:n).limit(10)


Making multiple queries with one request is supported with the HTTP Adaptor:

results = neo4j_session.queries do
  append 'MATCH (n:Foo) RETURN n LIMIT 10'
  append 'MATCH (n:Bar) RETURN n LIMIT 5'

results[0] # results of first query
results[1] # results of second query

When doing batched queries, there is also a shortcut for getting a new Neo4j::Core::Query:

results = neo4j_session.queries do
  append query.match(:n).return(:n).limit(10)

results[0] # result

With your session object, you can wrap multiple queries inside a transaction like so:

neo4j_session.transaction do |tx|
  # do stuff

The neo4j gem


In 7.0 of the neo4j-core gem, the new API doesn’t have the concept of a “current” session in the way that the old API did. If you are using neo4j-core, you must keep track of whatever sessions that you open yourself. In version 8.0 of the neo4j gem, however, there is a concept of a current session for your models. Previously you might have used:


If you are using version 8.0 of the neo4j gem, that will be accessible, but neo4j is no longer using that old API to have a session with Neo4j. Instead you might use:



Because of the changes to the current session API in the neo4j gem, the transactions API has also changed. Previously you might have created a transaction like so:

Neo4j::Transaction.run do |tx|
  # do stuff

Now, you now interact with transactions through Neo4j::ActiveBase like so:

Neo4j::ActiveBase.run_transaction do |tx|
  # do stuff

See also

Check out the ActiveBase source code to learn about some other neat helper methods ActiveBase has


In previous version of the neo4j gem to connect to Neo4j via HTTP you would define the value server_db in the neo4j.yml file, the NEO4J_TYPE environment variable, or a Rails configuration (config.neo4j.session.type). This should now be replaced and either bolt or http should be used depending on which connection type you need.

Also, instead of using session_type, session_url, session_path, and session_options, you should use session.type, session.url, session.path, and session.options respectively.

Some examples:

# config/neo4j.yml
# Before
  type: server_db
  url: http://localhost:7474

# After
  type: http # or bolt
  url: http://localhost:7474
# Rails config/application.rb, config/environments/development.rb, etc...

# Before
config.neo4j.session_type = :server_db
config.neo4j.session_url = 'http://localhost:7474'

# After
config.neo4j.session.type = :http # or :bolt
config.neo4j.session.url = 'http://localhost:7474'

Also, there was a slight change in the way that you configure the internal faraday adaptor of the neo4j-core gem:

# Before 8.0.x of `neo4j` gem
config.neo4j.session_options = {initialize: { ssl: { verify: true }}}

# After 8.0.x of `neo4j` gem
config.neo4j.session.options = {faraday_options: { ssl: { verify: true }}}

Outside of Rails

The neo4j gem will automatically set up a number of things with it’s railtie. If you aren’t using Rails you may need to set some things up yourself and some of the details have changed with version 8.0 of the neo4j gem.

Previously a connection with be established with Neo4j::Session.open and the default session from neo4j-core would be used. In version 7.0 of the neo4j-core gem, no such default session exists for the new API so you will need to establish a session to use the ActiveNode and ActiveRel modules like so:

adaptor = Neo4j::Core::CypherSession::Adaptors::HTTP.new('http://username:password@localhost:7474', wrap_level: :proc)

session = Neo4j::Core::CypherSession.new(adaptor)

Neo4j::ActiveBase.current_session = session

# Or skip setting up the session yourself:

Neo4j::ActiveBase.current_adaptor = adaptor

If you are using multiple threads, you should use the on_establish_session method to define how to setup your session. The current_session is stored on a per-thread basis and if you spawn a new thread, this block will be used to establish the session for that thread:

Neo4j::ActiveBase.on_establish_session do
  adaptor = Neo4j::Core::CypherSession::Adaptors::HTTP.new('http://username:password@localhost:7474', wrap_level: :proc)



If you would like to use the migrations provided by the neo4j outside of Rails you can include this in your Rakefile:

load 'neo4j/tasks/migration.rake'

Indexes and Constraints

In previous versions of the neo4j gem, ActiveNode models would allow you to define indexes and constraints as part of the model. While this was a convenient feature, it would often cause problems because Neo4j does not allow schema changes to happen in the same transaction as data changes. This would often happen when using ActiveNode because constraints and indexes would be automatically created when your model was first loaded, which may very well be in the middle of a transaction.

In version 8.0 of the neo4j gem, you must now create indexes and constraints separately. You can do this yourself, but version 8.0 provides fully featured migration functionality to make this easy (see the Migrations section).

If you still have indexes or constraints defined, the gem will check to see if those indexes or constraints exist. If they don’t, an exception will be raised with command that you can run to generate the appropriate migrations. If they do exist, a warning will be given to remove the index / constraint definitions.

Also note that all ActiveNode models must have an id_property defined (which is the uuid property by default). These constraints will also be checked and an exception will be raised if they do not exist.


Version 8.0 of the neo4j gem now includes a fully featured migration system similar to the one provided by ActiveRecord. See the documentation for details.

neo_id id_properties

In version 8.0 of the neo4j gem support was added to allow for definining the internal Neo4j ID as the id_property for a model like so:

id_property :neo_id


Use of neo_id as a perminent identifier should be done with caution. Neo4j can recycle IDs from deleted nodes meaning that URLs or other external references using that ID will reference the wrong item. Neo4j may be updated in the future to support internal IDs which aren’t recycled, but for now use at your own risk


With the new API comes some new exceptions which are raised. With the new adaptor API errors are more dependable across different ways of connecting to Neo4j.

Old Exception New Exception
Neo4j::Server::Resource::ServerException Neo4j::Core::CypherSession::ConnectionFailedError
Neo4j::Server::CypherResponse::ConstraintViolationError Neo4j::Core::CypherSession::SchemaErrors::ConstraintValidationFailedError
Neo4j::Session::CypherError Neo4j::Core::CypherSession::CypherError
? ConstraintAlreadyExistsError
? IndexAlreadyExistsError