GrapheneDB

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

Neo4j Graph Database as a Service

GrapheneDB

Last Updated: 20 April 2014

The GrapheneDB add-on is currently in beta.

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
Adding graphenedb on heroku-neo4j-example... done, v9 (free)
Your Neo4j database is ready to use!
Use `heroku addons:docs graphenedb` to view documentation.```

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
http://<user>:<pass>@resourceId.station-name.stations.graphenedb.com:7474/db/data

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 apt, puppet or chef
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 Neo4j with Ruby

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'

neo = Neography::Rest.new(ENV["GRAPHENEDB_URL"])

Test that the connection works properly by querying the database:

neo.execute_query("start n=node(*) return n limit 1")

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

Using Neo4j with Rails 3.x

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 = uri.host
  conf.port = uri.port
  conf.authentication = 'basic'
  conf.username = uri.user
  conf.password = uri.password
end

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 = Neography::Rest.new
1.9.3p385 :001 > neo.execute_query("start n=node(*) return n limit 1")

Using with Python and Py2Neo

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

$ pip install py2neo
import os
from py2neo import neo4j
from py2neo.packages.httpstream import URI

def connect_neo4j():
  uri = URI(os.environ.get("GRAPHENEDB_URL", "http://localhost:7474/db/data/"))
  db_uri = URI(uri.scheme + "://" + uri.host_port + uri.path.string)
  if uri.user_info:
    db_user, db_pass = uri.user_info.split(":")
    neo4j.authenticate(uri.host_port, db_user, db_pass)
  return neo4j.GraphDatabaseService(db_uri)

graph_db = connect_neo4j()

Test the connection by querying the server version:

print(graph_db.neo4j_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("start n=node(*) return n limit 1")
>>> for result in results: print result

Using with PHP and neo4jphp

You can install neo4jphp via Composer by adding the following requirement to the composer.json file

{
  "require": {
    "everyman/neo4jphp": "dev-master"
  }
}

Require the composer autoloader at the top of the script:

require_once('vendor/autoload.php')

Setup the connection within your PHP script:

require_once('vendor/autoload.php');

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

$client = new Everyman\Neo4j\Client($grapheneUrl['host'], $grapheneUrl['port']);
$client->getTransport()->setAuth($grapheneUrl['user'], $grapheneUrl['pass']);

You can test the connection by retrieving the server info:

print_r($client->getServerInfo());

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'] ||
    'http://localhost:7474'
);

You can test the connection by creating a dummy node:

var node = db.createNode({hello: 'world'});     // instantaneous, but...
node.save(function (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:', node.id);
    }
});

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

GrapheneDB dashboard

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

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
Adding graphenedb on heroku-neo4j-example... done, v9 (free)
Your Neo4j database is ready to use!
Use `heroku addons:docs graphenedb` to view documentation.

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

$ heroku addons:add graphenedb --version v195
Adding graphenedb on heroku-neo4j-example... done, v11 (free)
Your Neo4j database is ready to use!
Use `heroku addons:docs graphenedb` to view documentation.

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
Opening graphenedb:test for heroku-neo4j-example... done

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.

Troubleshooting

  • If restoring a database does not work, make sure that you are uploading a ZIP file of the graph.db directory. The zip command is:
$ cd neo4j/data/graph.db
$ zip -r ../backup.zip .

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
-----> Removing graphenedb from sharp-mountain-4005... done, v20 (free)

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.

Support

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 support@graphenedb.com.