neo4jrb/activegraph: Ruby Graph Modeling for Neo4j

ActiveGraph's Ruby model boundary

ActiveGraph solves the impedance problem that appears when a Ruby application stores connected records in Neo4j. A graph database represents information as nodes connected by relationships, with properties attached to either side. ActiveGraph places an Active Model compliant layer around that model, so Ruby developers can work with application objects and relationships instead of treating every database operation as a hand-written driver call. The intended users are Ruby and JRuby applications that need graph traversal while remaining within familiar Ruby object and model conventions.

The project is not a general-purpose replacement for every relational database interface. Its value is tied to graph data, especially paths across connected entities. The README example starts from a `person` association, follows friends and favorite beers, then groups by country of origin. That shape is difficult to express cleanly when the same domain is modeled primarily as fixed tables and foreign keys. ActiveGraph makes the connection path visible in the Ruby query itself.

The repository is not archived, and the last push was on 2026-08-18. The release history includes `v12.0.0` dated 2026-08-17, followed by older releases listed as `v5.0.1` and `v5.0.0` from 2015. That release gap is worth noticing because compatibility documentation is split across versions and database releases. The current repository state should be checked against the application before selecting a dependency version.

Driver-backed association traversal

According to the README, ActiveGraph uses the `neo4j-ruby-driver` and `active_attr` gems. The driver is the database-facing component, while `active_attr` supplies the Active Model style attributes that make model declarations more conventional for Ruby applications. This means the wrapper does not present Neo4j as a collection of relational tables. It exposes graph-oriented associations and traversal behavior on top of Neo4j's node and relationship model.

The query builder is a high-level interface rather than a plain string-only Cypher layer. The documented example chains `person.friends.favorite_beers.country_of_origin(:country)`, applies `order('count(country) DESC')`, and then uses `pluck` with a count expression. The resulting operation is a traversal across several associations followed by aggregation. This keeps the starting entity and the graph path close together in application code, although it also means that relationship semantics and Cypher naming are part of the abstraction developers must understand.

The README identifies transactions as supported. It also distinguishes transport and feature support by Neo4j release. Bolt Protocol is listed as unavailable for the `v2.x` and `v3.x` entries, available for `>= v8.x`, and available for `activegraph 10`. Remote Cypher is available in the earlier entries but marked unavailable for `activegraph 10`. These are not interchangeable deployment choices. The wrapper may be usable with several server generations, but the usable path depends on the ActiveGraph and Neo4j versions together.

Installing the gem and defining a first traversal

The README gives a minimal Bundler installation step. Add the gem declaration to the application's `Gemfile`; it does not document a separate installer command or a complete connection configuration in the README.

gem 'neo4j'

After adding that declaration, the application must be configured for a Neo4j server before a model can perform a real traversal. The README does not provide a connection URL, environment variable, authentication example, or model definition, so those details should come from the linked documentation and the application's Neo4j deployment. The first documented query pattern starts from an existing `person` association and follows related records:

person.friends.favorite_beers.country_of_origin(:country).
  order('count(country) DESC').
  pluck(:country, count: 'count(country)')

This example is useful because it shows the expected shape of use rather than a low-level Cypher statement. The caller supplies a model or association named `person`, ActiveGraph traverses friends, their favorite beers, and the country association, then orders by the country count and returns selected values. A real application must ensure that those associations and stored properties exist. The README does not document how to create the initial nodes or handle missing connections.

Version support and transport constraints

Compatibility is the main adoption constraint. The support table covers Neo4j versions from `1.9.x` through `5.x` and ActiveGraph releases including `activegraph 10` and `activegraph 11.1`. The table marks older ActiveGraph lines as incompatible with many newer Neo4j releases. For example, `activegraph 11.1` supports Neo4j `3.5`, `4.0` through `4.4`, and `5.x`, while `activegraph 10` has a different support boundary and marks Neo4j `3.0`, `3.1`, and `3.3` as unsupported.

The table also includes a note that Neo4j.rb version 4.x and later do not support Neo4j versions before `2.1.5`. Applications targeting Neo4j `2.1.x` therefore need to verify the exact server patch version. The feature table adds another decision point: Bolt Protocol and authentication are not available across every listed version combination. Remote Cypher is listed as unavailable for `activegraph 10`, so moving to that line changes more than the wrapper version.

This matrix is useful, but it is not a substitute for an application-level test. It does not say how a deployment should be migrated, how existing Neo4j data is transformed, or what rollback procedure to follow. The README explicitly points readers to newer documentation on ReadTheDocs while warning that some wiki pages are outdated. Documentation freshness should therefore be checked by topic, not assumed from the existence of a documentation link.

JRuby, deployment, and documentation boundaries

The repository includes a Dockerfile based on `jruby:latest`. It installs build tools, `libjson-c-dev`, Bundler, and the project dependencies before copying the rest of the application. The file also sets the locale environment variables `LANG`, `LANGUAGE`, and `LC_ALL`. This gives the project a documented container-oriented development path, but the README does not explain whether that image is intended for production, which Neo4j server configuration it expects, or how a containerized application connects to an external database.

The project supports Ruby and JRuby according to the introduction, and the embedded JVM support row says `via bolt only` for `activegraph 10`. That distinction matters to teams choosing between driver-based and embedded operation. The README does not provide a sample Dockerfile command, port mapping, database startup command, or health check. It also does not document production deployment guidance, so the repository Dockerfile should not be treated as a complete deployment recipe.

Documentation itself has a mixed state. New documentation is said to be moving to ReadTheDocs, while old wiki pages remain and are described as outdated. The README contains legacy documentation for versions `2.x` and notes that some `3.X` documentation remains valid for version `4`. A team evaluating a new model should prefer version-specific documentation corresponding to the selected release and compare it with the compatibility table before copying examples from an older guide.

When ActiveGraph is the wrong abstraction

ActiveGraph is the wrong choice when the data model does not need graph traversal. A conventional Ruby model layer backed by a relational database may be a better fit for fixed records, simple reporting, and schemas whose relationships are mostly one-to-one or one-to-many. The README positions ActiveGraph around connected data and does not claim that its association API is a general replacement for every relational workflow.

It can also be the wrong choice when the deployment is constrained to an unsupported Neo4j release or needs embedded JVM behavior across versions. The compatibility matrix explicitly marks several Neo4j versions as unsupported for particular ActiveGraph lines. Likewise, applications that require Remote Cypher should not assume that every current ActiveGraph configuration supports it, because the feature table marks it unavailable for `activegraph 10`.

The wrapper is not a migration tool. The README does not describe converting relational data into nodes and relationships, validating property schemas, handling old relationship representations, or rolling back a data migration. Those tasks require separate planning. ActiveGraph can provide the Ruby model after the graph representation and server compatibility have been settled, but it does not remove the hard part of deciding how connected records should be stored.

Maintenance, licensing, and operational cost

The repository is not archived, and its last push was on 2026-08-18. The listed `v12.0.0` release was published on 2026-08-17. Those facts indicate recent repository activity around the current release, but the README does not provide a support policy, upgrade cadence, or migration guide for moving between the listed ActiveGraph versions. The older `v5.0.1` and `v5.0.0` entries also show that version selection needs deliberate checking rather than relying on the package name alone.

The project license is MIT, as stated in the README. Neo4j itself uses a dual free software and commercial license according to the same section. The README also distinguishes the `neo4j-community`, `neo4j-advanced`, and `neo4j-enterprise` jar gems, saying that `neo4j-community` is required by default. Those statements identify licensing boundaries, but they are not legal advice. An organization should review the exact license files and its chosen Neo4j distribution separately.

Operational cost comes from version alignment, JRuby or Ruby runtime management, database transport, and documentation migration. The repository's `Dockerfile`, `Gemfile`, `activegraph.gemspec`, and test directories show a conventional Ruby project layout, but the README does not give a release cadence or production support window. The practical upgrade question is whether the selected ActiveGraph line supports the exact Neo4j server and features already used by the application.

Editorial conclusion

ActiveGraph fits Ruby teams that want an Active Model-style interface over Neo4j and can align the application with a supported database and transport combination. It is a poor fit for projects that require documented support for older Neo4j releases, embedded JVM operation in every deployment, or a fully current standalone documentation set. Before adoption, verify the required ActiveGraph version, Neo4j server version, Ruby or JRuby runtime, connection configuration, and whether Bolt is acceptable for the application.

Frequently asked questions

Official sources

1. License: MIT
2. neo4jrb/activegraph on GitHub
3. Project website
4. README
5. Releases