Connecting Meteor to a Neo4j database and deploying with GrapheneDB

Neo4j is a graph database that is extremely efficient when mapping relationships. As recommendation engines and long tail economics become an increasingly important piece of software, graph databases will become indispensable.

This only takes about 10 minutes to set up and gives you access to Neo4j either locally or through the GrapheneDB and Neo4j’s REST API.

I decided to use the package ccorcos:neo4j because it’s lightweight and doesn’t rely on Mongo — Chet Corcos, the package’s author, also happens to be my brother. It’s also relatively painless to implement and deploy with GrapheneDB.

The other available packages write the result of every Neo4j query to Mongo, which is fine if you have one query that is regularly updated, and has the advantage of making the data reactive, but will cause scaling problems if you have many different queries. Eventually, Neo4j will probably include change feeds, which will make the data reactive in a less-hacky way.

Step 1

First, you need Neo4j. If you have brew, run the following commands:

brew install neo4j
npm install -g neo4j

Step 2

If you want to run Neo4j locally, you have to start it. We will go over setting up both the local database and a cloud-hosted database with GrapheneDB, though you really only need to choose one of them.

Run the following commands to start Neo4j, install the ccorcos:neo4j package, and then start Meteor:

neo4j start
meteor add ccorcos:neo4j
meteor

Step 3

You now have access to the Neo4j database! Neo4j provides you with a nifty browser GUI at http://localhost:7474/ which I highly recommend playing around with to get used to Neo4j’s querying language, Cypher.

Step 4

Now, it’s time to instantiate a connection to Neo4j. You can do this with the following line of code in your server, likely in your server.js file:

Neo4j = new Neo4jDB()

This will create a Neo4j object that you can use to make queries. Below, I have included a few example queries. For more information on the query language Cypher, check out Neoj4's docs.

Adds a person named Bob to the database:

Neo4j.query("MERGE (n:Person {name:'Bob'})")

Finds everything in your database:

Neo4j.query("MATCH (n) OPTIONAL MATCH (n)-[r]-() MATCH n,r")

Deletes everything in your database:

Neo4j.query("MATCH (n) OPTIONAL MATCH (n)-[r]-() DELETE n,r")

You now have a functional Neo4j database that runs locally. Hurray! Next step, running on GrapheneDB. Doing so will make it possible to use Neo4j in production.

Step 5

The next step involves GrapheneDB. You need to go to their website (graphenedb.com) and register. Then create a database and take note of the url, username, and password they provide you for that database. You will use that information in the next step.

Step 6

When you instantiate the Neo4j object in line in Step 4 above, you actually have a few options. Looking at this line of code from the package (written in coffeescript) will help clarify the situation:

@url = url or process.env.NEO4J_URL or process.env.GRAPHENEDB_URL or ‘http://localhost:7474'

So, you can pass in a url, an environment variable called NEO4J_URL or GRAPHENEDB_URL, or, if you pass nothing, it will default to localhost:7474. It’s important to note the order in which these are processed in case you run into conflicts later on.

If you want to pass in a url, all you have to do is pass a string when you instantiate the Neo4j object. This string needs to include the username and password immediately after “http://” in the format, username:password. For example:

Neo4j = new Neo4jDb("http://<USERNAME>:<PASSWORD>@projectname.sb05.stations.graphenedb.com:24789")

NOTE: The database that GrapheneDB gives you by default includes /db/data/. Do not include this when you instantiate the Neo4j object.

The username, password, and url are all provided by GrapheneDB. You should probably store you username and password in settings.json and refrain from committing that information to your git repo, but that’s just a best-practice and not a rule.

Your other option is to set up environment variables, such as GRAPHENEDB_URL and not pass in a string. You can do this with the following code (in coffeescript):

Meteor.startup ->
  process.env.GRAPHENEDB_URL = "http://<USERNAME>:<PASSWORD>@projectname.sb05.stations.graphenedb.com:24789"

You now have a functioning Neo4j database working with Meteor and hosted on GrapheneDB! You should see the following output in your terminal if the connection was successful:

$ Meteor is successfully connected to Neo4j on http://projectname.sb05.stations.graphenedb.com:24789

Additional notes

If you are running Neo4j locally, be sure to stop Neo4j when you are finished using it. Otherwise, it will continue to run in the background. Run the following command to stop Neo4j:

neo4j stop

There are a few edge cases where the database might not stop running. If you run into one of those, look at the docs for ccorcos:neo4j.

Sam Corcos is the lead developer and co-founder of Sightline Maps, the most intuitive platform for 3D printing topographical maps, as well as LearnPhoenix.io, an advanced tutorial site for building scaleable production apps with Phoenix and React.