The neo4j.rb gems (neo4j and neo4j-core) support both Ruby and JRuby and can be used with many different frameworks and services. If you’re just looking to get started you’ll probably want to use the neo4j gem which includes neo4j-core as a dependency.

Below are some instructions on how to get started:

Ruby on Rails

The following contains instructions on how to setup Neo4j with Rails. If you prefer a video to follow along you can use this YouTube video

There are two ways to add neo4j to your Rails project. You can generate a new project with Neo4j as the default model mapper or you can add it manually.

Generating a new app

To create a new Rails app with Neo4j as the default model mapper use -m to run a script from the Neo4j project and -O to exclude ActiveRecord like so:

rails new myapp -m -O


Due to network issues sometimes you may need to run this command two or three times for the file to download correctly

An example series of setup commands:

rails new myapp -m -O
cd myapp
rake neo4j:install[community-latest]
rake neo4j:start

rails generate scaffold User name:string email:string
rails s
open http://localhost:3000/users

See also

There is also a screencast available demonstrating how to set up a new Rails app:

Adding the gem to an existing project

Include in your Gemfile:

# for rubygems
gem 'neo4j', '~> 7.0.0'

In application.rb:

require 'neo4j/railtie'


Neo4j does not interfere with ActiveRecord and both can be used in the same application

If you want the rails generate command to generate Neo4j models by default you can modify application.rb like so:

class Application < Rails::Application
  # ...

  config.generators { |g| g.orm :neo4j }

Rails configuration

For both new apps and existing apps the following configuration applies:

An example config/neo4j.yml file:

  type: http
  url: http://localhost:7474

  type: http
  url: http://localhost:7575

  type: http
  url: http://neo4j:password@localhost:7000

The railtie provided by the neo4j gem will automatically look for and load this file.

You can also use your Rails configuration. The following example can be put into config/application.rb or any of your environment configurations (config/environments/(development|test|production).rb) file:

config.neo4j.session.type = :http
config.neo4j.session.url = 'http://localhost:7474'

# Or, for embedded in jRuby

config.neo4j.session.type = :embedded
config.neo4j.session.path = '/path/to/graph.db'

Neo4j requires authentication by default but if you install using the built-in rake tasks) authentication is disabled. If you are using authentication you can configure it like this:

config.neo4j.session.url = 'http://neo4j:password@localhost:7474'

Of course it’s often the case that you don’t want to expose your username / password / URL in your repository. In these cases you can use the NEO4J_TYPE (either http or embedded) and NEO4J_URL/NEO4J_PATH environment variables.

Configuring Faraday

Faraday is used under the covers to connect to Neo4j. You can use the initialize option to initialize the Faraday session. Example:

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

# After 8.0.x of `neo4j` gem
# Switched to allowing a "configurator" since everything can be done there
config.neo4j.session.options = {
  faraday_configurator: proc do |faraday|
    # The default configurator uses typhoeus (it was `Faraday::Adapter::NetHttpPersistent` for `neo4j-core` < 7.1.0), so if you override the configurator you must specify this
    faraday.adapter :typhoeus
    # Optionally you can instead specify another adaptor
    # faraday.use Faraday::Adapter::NetHttpPersistent

    # If you need to set options which would normally be the second argument of ``, you can do the following:
    faraday.options[:open_timeout] = 5
    faraday.options[:timeout] = 65
    faraday.options[:ssl] = { verify: true }

If you are just using the neo4j-core gem, the configurator can also be set via the Neo4j HTTP adaptor. For example:

require 'neo4j/core/cypher_session/adaptors/http'
faraday_configurator = proc do |faraday|
  faraday.adapter :typhoeus
http_adaptor ='http://neo4j:pass@localhost:7474', faraday_configurator: faraday_configurator)

Any Ruby Project

Include either neo4j or neo4j-core in your Gemfile (neo4j includes neo4j-core as a dependency):

gem 'neo4j', '~> 7.0.0'
# OR
gem 'neo4j-core', '~> 7.0.0'

If using only neo4j-core you can optionally include the rake tasks (documentation) manually in your Rakefile:

# Both are optional

# To provide tasks to install/start/stop/configure Neo4j
require 'neo4j/rake_tasks'
# Comes from the `neo4j-rake_tasks` gem

# It was formerly requried that you load migrations via a rake task like this:
# load 'neo4j/tasks/migration.rake'
# This is NO LONGER required.  Migrations are included automatically when requiring the `neo4j` gem.

If you don’t already have a server you can install one with the rake tasks from neo4j_server.rake. See the (rake tasks documentation) for details on how to install, configure, and start/stop a Neo4j server in your project directory.


To open a session to the neo4j server database:

In Ruby

# In JRuby or MRI, using Neo4j Server mode. When the railtie is included, this happens automatically.

Embedded mode in JRuby

In jRuby you can access the data in server mode as above. If you want to run the database in “embedded” mode, however you can configure it like this:

neo4j_adaptor ='/file/path/to/graph.db')
neo4j_session =

Embedded mode means that Neo4j is running inside your jRuby process. This allows for direct access to the Neo4j Java APIs for faster and more direct querying.

Using the neo4j gem (ActiveNode and ActiveRel) without Rails

To define your own session for the neo4j gem you create a Neo4j::Core::CypherSession object and establish it as the current session for the neo4j gem with the ActiveBase module (this is done automatically in Rails):

require 'neo4j/core/cypher_session/adaptors/http'
neo4j_adaptor ='http://user:pass@host:7474')
Neo4j::ActiveBase.on_establish_session { }

You could instead use the following, but on_establish_session will establish a new session for each thread for thread-safety and thus the above is recommended in general unless you know what you are doing:

Neo4j::ActiveBase.current_session =


Add a Neo4j db to your application:

# To use GrapheneDB:
heroku addons:create graphenedb

# To use Graph Story:
heroku addons:create graphstory