Neo4j v3 Migrations

Migrations

Migrations are an easy way to make database-wide changes. Unlike ActiveRecord, Neo4j.rb does not (yet?) keep track of migrations to run during a new deployment; rather, it offers a process for performing one-time or scheduled tasks as needed.

Usage is simple.

To run, rake neo4j:migrate[task_name,subtask]

Gem-provided migrations are found in neo4j/migration.rb but if you have a custom task, put it in /db/neo4j-migrate/ and name it to match your task name. The contents of your file should be the classified version of the task name: task add_id_property would have file add_id_property.rb and contain class AddIdProperty.

Your migration class has a few simple requirements.

• Inherit from Neo4j::Migration
• initialize needs to accept one argument, the path from which the rake task was called
• Contain a migrate instance method, to be executed when no subtask is provided at the command line.

As an example rake neo4j:migrate[add_id_property] is essentially equivalent to Neo4j::Migration::AddIdProperty.new.migrate.

If you have other tasks that may be helpful, such as setup, define those as instance methods in your class and call from command line as rake neo4j:migrate[your_task,extra_method].

Gem-Provided Tasks

add_id_property

Purpose Per Neo Tech's guidelines, Neo4j.rb generates unique IDs for all nodes. By default, these are generated using SecureRandom::uuid and stored in a property called uuid, which has the id method aliased to it. If you want to use Neo4j data that was not created by this gem, you need unique IDs.

Usage Run rake neo4j:migrate[add_id_property,setup] and modify add_id_property.yml, created in your Rails app's db/neo4j-migrate/ folder. It contains one line, models = []. Add the names of models that need IDs generated to that array.

models = [Student,Lesson,Exam]

rake neo4j:migrate[add_id_property] to execute. It will load the model, find its given ID property and generation method, and populate that property on all nodes of that class where an ID is not already assigned. It does this in batches of up to 900 at a time by default, but this can be changed with the MAX_PER_BATCH environment variable (batch time taken standardized per node will be shown to help you tune batch size for your DB configuration)

add_classnames

Purpose To prevent n+1 queries to load a single node, a _classname property is added to every node or relationship created by an ActiveNode or ActiveRel model. The value of this property matches the name of the model that created it. If you change a model's name, decide to start using ActiveRel on an existing relationship, or want to use Neo4j.rb with a database that it did not create, you need to add _classname properties.

Usage

Run rake neo4j:migrate[add_classnames,setup] to generate add_classnames.yml in your /db/neo4j-migrate directory. It is a simple file that is used as a map for the migration. Use the example below as a guide.

nodes:
  # action:   [Label/ModelName]
  add:        [Lesson, Student, Exam]
  overwrite:  [Teacher]
relationships:
  # action:
  #   Model:       { from: 'FromLabel', to: 'ToLabel', type: 'relationship_type' }
  add:
    StudentLesson: { from: 'Student', to: 'Lesson', type: 'enrolled_in' }
  overwrite:
    ExamLesson:    { type: 'has_this_thing' }

Use add keys when importing data that does not a _classname set, use overwrite when you want to change all matching relationship _classnames. type is required, from and to are not but are encouraged. Your database will thank you!

To perform a dry run, use rake neo4j:migrate[add_classnames,test] and it will show you the Cypher that would be used to add make the changes based on your migration file. When you're ready, rake neo4j:migrate[add_classnames] to perform the migration.