Migrating to a Neo4j Graph Database with Ruby on Rails

This tutorial applies to existing and new Rails Projects. Listed below are the versions of the technologies used. (Using the correct versions is vital to making this work)

Neo4j 4.0.11
Rails 6.1.3.2
gem "activegraph", "~> 10.1.0"
gem "neo4j-ruby-driver", "~> 1.7"

Prerequisites

1. Install Neo4j Desktop
2. Install Seabolt

brew install michael-simons/homebrew-seabolt/seabolt

Concepts to understand.

1. A Neo4j database instance is a completely separate entity from the rails project. Similar to how front-end code is completely agnostic from its API.
2. Neo4j transfers data over the BOLT protocol (Think about how data is transferred via HTTP, same concept).

Neo4j Database (Development) Setup

Neo4j Database (Development)

1. Create a project in Neo4j Desktop.

2. Create a new Local DBMS, create a password and configure it to use Version 4.0.11.

The reason for the specific versions is that the Neo4j ActiveGraph gem is only compatible in certain configurations when using specific versions of Neo4j and the ActiveGraph gem. See versions support here.

3. Start the Neo4j Database instance.

4. After opening, login to the Neo4j instance in the Neo4j Browser.

Rails Neo4j Integration (Development) Setup

1. Add the following gems to your gemfile.

gem "activegraph", "~> 10.1.0"
gem "neo4j-ruby-driver", "~> 1.7"

2. Create a neo4j.yml file in the config folder.

touch config/neo4j.yml

In the neo4j.yml file add your configuration for accessing the Neo4j database instance that you just created. This includes the URL for accessing the database entry point, the login credentials, and encryption configurations.

development:
url: neo4j://localhost:7687
    username: neo4j
    password: Neo5j
    encryption: false

The url can be found once you start the Neo4j instance from Neo4j Desktop and the username and password is what you have set. By default the username is neo4j.

3. In config/application.rb require ActiveGraph after require “rails/all”.

require "active_graph/railtie"

4. In config/application.rb, add configuration for the rails generators to use ActiveNode when generating models etc. (which needs to be included in your models in order to use the DSL for creating new nodes in your database in a similar way to ActiveRecord).

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

config/application.rb

Final set up

Generate your models or re-configure them by removing the ApplicationRecord inheritance and replacing it instead with Active Node.

class User
    include ActiveGraph::Node
end

You can define properties and has_many relationships etc. in your model in a similar way to active record. See examples here.

Important!

You will be prompted in the console when testing out creating and retrieving nodes to add constraints to the database such as making all the id’s unique. These will be in the form of rake tasks. If there are brackets in the rake task command, you must enclose the task in quotes.

rake ‘neo4j:generate_schema_migration[constraint,User,uuid]’

After adding these constraints you must run migrations. The order in which this is done is important. Constraints need to be added first before running the migrate command below.

rails neo4j:migrate

You can now start rails console and try it out like so.

User.create

Start the server as usual with rails and you are all set!

rails s

Resources

• Neo4j Ruby Docs — https://neo4jrb.readthedocs.io/en/v10.0.1/index.html
• Neo4j Ruby Gitter Chat Room — https://gitter.im/neo4jrb/neo4j

Shoutouts

Special thanks to Brian Underwood and Heinrich Klobuczek, and the entire Neo4j community.