This add-on is operated by Aentos Consulting S.L.

Neo4j Graph Database as a Service


Last Updated: 14 May 2015

Table of Contents

GrapheneDB is an add-on providing Neo4j as a service. GrapheneDB operates hosted, production-ready Neo4j graph databases.

Neo4j is an open-source, high-performance, enterprise-grade and fully ACID NoSQL graph database.

All official Neo4j language drivers work with GrapheneDB and there are libraries for almost every platform, including Ruby, Node.js, Java, Python and Clojure.

Provisioning the database

GrapheneDB Neo4j instances are attached to a Heroku application via the CLI:

$ heroku addons:add graphenedb:chalk

This command adds a Neo4j sandbox instance to your app and updates your Heroku configuration with an environment variable GRAPHENEDB_URL. This variable is assigned the canonical URL as well as an automatically-generated user/pass authentication pair used to access the newly provisioned database instance.

This is confirmed using the heroku config:get command.

$ heroku config:get GRAPHENEDB_URL

You can use the GRAPHENEDB_URL variable now in your code to configure your driver according to the programming language used in your app. There are examples in this documentation.

Within the GrapheneDB dashboard you will also find code snippets for the most popular drivers and languages ready to be copied and pasted in to the source code of your app.

A list of all plans available can be found here.

Provisioning a specific version of Neo4j

When provisioning a new instance through this add-on, the latest stable version will be used by default. You can deploy a specific version of Neo4j by passing --version param to the Heroku CLI with the corresponding version string.

Example for Neo4j v 1.9.5:

$ heroku addons:add graphenedb --version v195

An up-to-date list of the Neo4j versions available on GrapheneDB and the corresponding parameter values can be found in this specific FAQ section of the GrapheneDB docs.

Installing Neo4j on your local machine

We strongly recommend that you use the official Neo4j packages, available for download on the neo4j website.

If you have… Install with…
Mac OS X Download the Linux/Mac tarball, unpack and follow the instructions in README.txt or brew install neo4j
Linux Download the Linux/Mac tarball, unpack and follow the instructions in README.txt or install via .deb package
Windows Download the zip file for Windows, unpack and follow the instructions in README.txt

To install Neo4j as a service, please follow the instructions in the official documentation.

Using with Ruby

The most popular gems for working with Neo4j from Ruby are Neo4j-core, Neo4j.rb, and Neography.

  • Neo4j-Core provides classes and methods related to nodes, relationships, and Cypher.
  • Neo4j.rb acts as an ActiveRecord replacement for Rails. It uses neo4j-core for communication with the database.
  • Neography is a thin Ruby wrapper for the REST API.

Using Neo4j-core with Ruby

The Neo4j-core gem provides nodes and relationship classes and a Cypher DSL.

Install the ‘neo4j-core’ gem:

gem install 'neo4j-core'

Require the gem in your Ruby code or irb and open a connection using the GRAPHENEDB_URL environment variable:

require 'rubygems'
require 'neo4j-core'

session =, ENV["GRAPHENEDB_URL"])

Create a node with the property “name” and the label “Person” from the console:

kyle = Neo4j::Node.create({name: 'Kyle'}, :Person)
stan = Neo4j::Node.create({name: 'Stan'}, :Person)
kyle.create_rel(:friend, stan, since: 1997)

Using Neo4j.rb with Rails

If you want to use Neo4j instead of or in additional to SQL in Ruby on Rails, the neo4j.rb gem is the best option. It provides an especially comfortable experience for anyone familiar with ActiveRecord.

Add the ‘neo4j’ gem to your Gemfile:

gem 'neo4j'

Configure your session using the GRAPHENEDB_URL environment variable in application.rb or environments/production.rb:

config.neo4j.session_type = :server_db
config.neo4j.session_path = ENV["GRAPHENEDB_URL"] || 'http://localhost:7474'

Confirm a session is established from the rails console:

=> Neo4j::Server::CypherSession url: 'http:/' version: '2.1.4'

See the neo4j.rb documentation for help building your Rails app.

Using Neography with Ruby

If you want a thin REST wrapper, the neography gem is the easiest way to work with Neo4j and GrapheneDB from Ruby.

Install the neography gem:

$ gem install neography

Require the gem in your Ruby code or irb and open a connection using the GRAPHENEDB_URL environment variable:

require 'rubygems'
require 'neography'


Test that the connection works properly by querying the database:

neo.execute_query("MATCH(n) RETURN n LIMIT 1")

Please refer to the documentation on the project page for more information on using the neography gem.

Neography with Rails

Add the neography gem to your Gemfile.

gem 'neography'

Update application dependencies with bundler.

$ bundle install

Open the connection within an initializer, ie config/initializers/neography.rb:

neo4j_url = ENV["GRAPHENEDB_URL"] || "http://localhost:7474" # default to local server

uri = URI.parse(neo4j_url)

require 'neography'

Neography.configure do |conf|
  conf.server =
  conf.port = uri.port
  conf.protocol = uri.scheme + "://"
  conf.authentication = 'basic'
  conf.username = uri.user
  conf.password = uri.password

To test the configuration, query the database from the rails console:

$ rails console
Loading development environment (Rails 3.2.13)
1.9.3p385 :001 > neo =
1.9.3p385 :001 > neo.execute_query("MATCH(n) RETURN n LIMIT 1")

Using with Python and Py2Neo

The easiest way to install Py2Neo is via Python Package Index (PyPI):

$ pip install py2neo

The latest version of Py2neo can be configured by passing a URL with protocol, authentication credentials, hostname and port number. Please note that a trailing slash is required in the URL, which needs to be appended to the GRAPHENEDB_URL environment variable.

The following code configures the connection to the GrapheneDB instance and falls back to localhost if the environment variable is not present, i.e. on your local development environment:

import os
from py2neo import ServiceRoot

graphenedb_url = os.environ.get("GRAPHENEDB_URL", "http://localhost:7474/")
graph = ServiceRoot(graphenedb_url).graph

Test the connection by querying the server version:


Using with Python and Neo4j Rest Client

You can install Neo4j Rest Client with Python Package Index (PyPI):

$ pip install neo4jrestclient

Setting up the connection:

from neo4jrestclient.client import GraphDatabase

from urlparse import urlparse, urlunparse
url = urlparse(GRAPHENEDB_URL)
url_without_auth = urlunparse((url.scheme, "{0}:{1}".format(url.hostname, url.port), url.path, None, None, None))

gdb = GraphDatabase(url_without_auth, username = url.username, password = url.password)

Test the connection by querying the database:

>>> results = gdb.query("MATCH (n) RETURN n LIMIT 1")
>>> for result in results: print result

Using with PHP and NeoClient

Require the NeoClient dependency in your composer.json :

  "require": {
    "neoxygen/neoclient": "~1.5"

Require the autoloader in your application :

require_once 'vendor/autoload.php';

Setup the connection in your script, for e.g. giving the alias ‘default’ for the default connection :

use Neoxygen\NeoClient\Client;

$url = parse_url(getenv('GRAPHENEDB_URL'));

// Assuming default is your connection alias
$client = new Client();
$client->addConnection('default', $url['scheme'], $url['host'], $url['port'], true, $url['user'], $url['pass'])

Use it :

$query = 'MATCH (n) RETURN count(n)';
$response = $client->sendCypherQuery($query);

More info in the repository’s README.

Using with Node.js and node-neo4j

You can install node-neo4j via npm:

$ npm install neo4j

Connect to the Neo4j instance using the GRAPHENEDB_URL environment variable:

var neo4j = require('neo4j');
var db = new neo4j.GraphDatabase(
    process.env['GRAPHENEDB_URL'] ||

You can test the connection by creating a dummy node:

var node = db.createNode({hello: 'world'});     // instantaneous, but... (err, node) {    // ...this is what actually persists.
    if (err) {
        console.error('Error saving new node to database:', err);
    } else {
        console.log('Node saved to database with id:',;

There is also a template application that will work on Heroku and the GrapheneDB add-on without any modification.

Using with Node.js and Seraph

You can install seraph via npm:

$ npm install seraph

Connect to the Neo4j instance using the GRAPHENEDB_URL environment variable:

url = require('url').parse(process.env.GRAPHENEDB_URL)

var db = require("seraph")({
  server: url.protocol + '//' +,
  user: url.auth.split(':')[0],
  pass: url.auth.split(':')[1]

You can test the connection by creating and deleting a dummy node:{ name: "Test-Man", age: 40 }, function(err, node) {
  if (err) throw err;
  console.log("Test-Man inserted.");

  db.delete(node, function(err) {
    if (err) throw err;
    console.log("Test-Man away!");

Using with Go and Neoism

Install neoism via the go executable:

go get -v

Import the os library and neoism:

import (

Connect to the Neo4j instance using the GRAPHENEDB_URL environment variable:

db, err := neoism.Connect(os.Getenv("GRAPHENEDB_URL"))

You can test the connection by creating a dummy node:

n, err := db.CreateNode(neoism.Props{"hello": "world"})

GrapheneDB dashboard

For more information on the features available within the GrapheneDB dashboard please see the docs at

The GrapheneDB dashboard can be accessed via the CLI:

$ heroku addons:open graphenedb
Opening graphenedb for sharp-mountain-4005...

or by visiting the Heroku apps web interface and selecting the application in question. Select GrapheneDB from the Add-ons menu.

GrapheneDB dashboard

Migrating your database from the Neo4j add-on

Backing up current data on the Neo4j add-on

The Neo4j add-on UI can be opened from the Heroku CLI:

$ heroku addons:open neo4j
Opening neo4j:try for heroku-neo4j-example... done

The Backup database button is used to take a snapshot of the current data in the database.

Backing up your database in the Neo4j add-on

You will see a message displayed at the top to indicate a successful backup process. Instead of downloading the backup, copy the download URL to the clipboard. That is all that’s necessary to import the data into the GrapheneDB add-on.

Copying the backup download URL

Note: The process described here uses the backup download URL for a faster restore process. You can also import the data into the GrapheneDB add-on by uploading the downloaded backup file.

Provisioning a new Neo4j database with the GrapheneDB add-on

The Heroku CLI can be used to provision a new database on the free tier. The latest available stable version is provisioned by default.

$ heroku addons:add graphenedb:chalk

To provision a specific version of Neo4j an optional --version param can be used:

$ heroku addons:add graphenedb:chalk --version v204

Please note that Neo Technology suggests upgrading databases only from a minor version to the next. For instance, the recommended method to upgrade from 1.8 to 2.0 is to upgrade to 1.9 first, and then to 2.0. Read more in the official upgrade documentation.

An up-to-date list of the Neo4j versions available on GrapheneDB and the corresponding parameter values can be found in this specific FAQ section of the GrapheneDB docs.

Loading the data into the new instance

The GrapheneDB add-on UI can be opened using the Heroku CLI:

$ heroku addons:open graphenedb

The restore process can be started from the Admin tab.

Restoring into your GrapheneDB instance

To continue the restore process, select the option “Load file from URL” and paste the download URL into the corresponding field.

You will see a notification message when the process is successfully completed. The storage indicator will reflect the storage size used up by the data loaded from the backup.

Storage usage after successful restore

The restore process will destroy all data within your instance and cannot be undone!

Verifying data migration and connecting your app

Optional: To verify that data has been properly restored into the new instance, the WebAdmin/Browser can be launched from the Overview tab.

The GrapheneDB add-on will update the Heroku configuration of the app with an environment variable GRAPHENEDB_URL.

There is one final step. Update the application code to connect to Neo4j using the GRAPHENEDB_URL environment variable.


Restore process does not work

To ensure a database restore process is executed successfully follow these steps:

  • the origin instance need to be stopped cleanly before creating the tarball/zip file with the store
  • to avoid issues, a restore should be done into the same version (2.0 store into 2.0 instance) or one higher (2.0 store into 2.1 instance)

Make sure that you are uploading a ZIP file of the graph.db directory. The correct zip command is:

$ cd neo4j/data/graph.db
$ zip -r ../ .

Upgrading/downgrading the database

The GrapheneDB database plan can be changed using the Heroku CLI:

$ heroku addons:upgrade graphenedb:quartz

When downgrading attention must be payed to the limits of the new plan (nodes, relationships and storage capacity). If the database size exceeds the maximum storage size of the new plan, the downgrade operation will be aborted. If the node or relationship counts exceed the maximum counts allowed in the new plan, the downgrade operation will be completed, but the database will be switched to read-only mode.

Enabling the Spatial plugin

Developer plans and higher include support for the neo4j-spatial plugin. The plugin can be enabled from the Plugins tab in the GrapheneDB user interface.

Removing the add-on

GrapheneDB can be removed via the CLI.

This will destroy all associated data and cannot be undone!

$ heroku addons:remove graphenedb

Before removing GrapheneDB, export your data using the Export Database feature in the GrapheneDB dashboard. This will generate a zip file with your database file structure, which you can download.


All GrapheneDB support and runtime issues should be submitted via one of the Heroku Support channels. Any non-support related issues or product feedback is welcome via email to