{"id":15284751,"url":"https://github.com/specht/neo4j_bolt","last_synced_at":"2025-10-24T12:21:50.163Z","repository":{"id":62128439,"uuid":"558086723","full_name":"specht/neo4j_bolt","owner":"specht","description":"A Neo4j/Bolt driver written in pure Ruby.","archived":false,"fork":false,"pushed_at":"2024-03-28T08:52:56.000Z","size":65,"stargazers_count":5,"open_issues_count":2,"forks_count":0,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-04-12T23:43:59.352Z","etag":null,"topics":["bolt","neo4j","ruby"],"latest_commit_sha":null,"homepage":"","language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/specht.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null}},"created_at":"2022-10-26T21:47:36.000Z","updated_at":"2023-09-20T18:47:34.000Z","dependencies_parsed_at":"2024-02-09T17:47:57.560Z","dependency_job_id":"400734ca-e4e4-4b9e-bc40-f57a527cef64","html_url":"https://github.com/specht/neo4j_bolt","commit_stats":{"total_commits":30,"total_committers":1,"mean_commits":30.0,"dds":0.0,"last_synced_commit":"3509cc6408a812ae24e05fbfdd925298689b7822"},"previous_names":[],"tags_count":17,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/specht%2Fneo4j_bolt","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/specht%2Fneo4j_bolt/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/specht%2Fneo4j_bolt/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/specht%2Fneo4j_bolt/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/specht","download_url":"https://codeload.github.com/specht/neo4j_bolt/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248647256,"owners_count":21139081,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["bolt","neo4j","ruby"],"created_at":"2024-09-30T15:00:03.219Z","updated_at":"2025-10-24T12:21:50.080Z","avatar_url":"https://github.com/specht.png","language":"Ruby","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Neo4jBolt\n\nA Neo4j/Bolt driver written in pure Ruby. **Currently only supporting Neo4j 4.4 with Bolt 4.4.** Contains a CLI tool which can dump databases, load database dumps, and visualize database contents.\n\nCaution: This gem is not feature complete regarding Neo4j and Bolt. Nevertheless, it is used successfully in production – make sure it supports the features you need.\n\n- PackStream:\n  - data types:\n    - supported: Null, Boolean, Integer, Float, String, List, Dictionary, Structure\n    - not supported: Bytes\n  - structures:\n    - supported: Node, Relationship\n    - not supported: UnboundRelationship, Path, Date, Time, LocalTime, DateTime, DateTimeZoneId, LocalDateTime, Duration, Point2D, Point3D\n- Bolt Protocol:\n  - supported: transactions\n  - not supported:\n    - auto transactions (all transactions are explicit in Neo4jBolt)\n    - routing\n    - interrupt\n\n## Installation\n\nAdd this line to your application's Gemfile:\n\n```ruby\ngem 'neo4j_bolt'\n```\n\nAnd then execute:\n\n    $ bundle install\n\nOr install it yourself as:\n\n    $ gem install neo4j_bolt\n\nIn order to use this gem, you need a running Neo4j database. Chances are you already have a Neo4j database running if you're reading this. Otherwise, you can start one via Docker using the following command:\n\n```\ndocker run --rm --env NEO4J_AUTH=none --publish 7687:7687 neo4j:4.4-community\n```\n\nIf you want the Browser interface at http://localhost:7474/, additionaly specify `--publish 7474:7474`.\n\n## Connecting to a Neo4j database\n\nSpecify your Bolt host and port (if you omit this it will be localhost:7687 by default):\n\n```ruby\nNeo4jBolt.bolt_host = 'localhost'\nNeo4jBolt.bolt_port = 7687\n```\n\nUse `Neo4jBolt::cleanup_neo4j` to disconnect (this is important when running a web app – it might be a good idea to close a socket once we're done with it so we don't run out of available ports).\n\n## Running queries\n\nUse `neo4j_query` to run a query and receive all results:\n\n```ruby\nentries = neo4j_query(\"MATCH (n) RETURN n;\")\n```\nAlternatively, specify a block to make use of Neo4j's streaming capabilities and receive entries one by one:\n\n```ruby\nneo4j_query(\"MATCH (n) RETURN n;\") do |entry|\n    # handle entry here\nend\n```\n\nUsing streaming avoids memory hog since it prevents having to read all entries into memory before handling them. Nodes are returned as `Neo4jBolt::Node`, relationships as `Neo4jBolt::Relationship`. Both are subclasses of `Hash`, providing access to all properties plus a few extra details:\n\n- `Neo4jBolt::Node` attributes: `id`, `labels`\n- `Neo4jBolt::Relationship` attributes: `id`, `start_node_id`, `end_node_id`, `type`\n\n```ruby\nnode = neo4j_query_expect_one(\"CREATE (n:Node {a: 1, b: 2}) RETURN n;\")['n']\n# All nodes returned from Neo4j are a Neo4jBolt::Node\n# It's a subclass of Hash and it stores all the node's\n# properties plus two attributes called id and labels:\nputs node.id\nputs node.labels\nputs node.keys\nnode.each_pair { |k, v| puts \"#{k}: #{v}\" }\nputs node.to_json\nputs \"a: #{node[:a]}\"\n```\n\nWhile values returned by Neo4j can be accesses via string keys (`['n']` in the example above), property keys of nodes and relationships are converted to symbols (`node[:a]`).\n\nUse `neo4j_query_expect_one` if you want to make sure there's exactly one entry to be returned:\n\n```ruby\nnode = neo4j_query_expect_one(\"MATCH (n) RETURN n LIMIT 1;\")['n']\n```\n\nIf there's zero, two, or more results, this will raise a `ExpectedOneResultError`.\n\n## Using transactions\n\nAny Neo4j query will run in its own transaction by default. If you want to group multiple queries into a transaction to make sure they either succeed completely or fail completely, use `transaction` like this:\n\n```ruby\ntransaction do\n    neo4j_query(\"CREATE (n:Node {a: 1});\")\n    neo4j_query(\"CREATE (n:Node {b: 1});\")\nend\n```\n\nTransactions can be nested, with the inner transactions doing nothing and the outermost transaction being committed unless something goes wrong in which case the outermost transaction gets rolled back. No matter how often you nest transactions, there's only one transaction from the perspective of Neo4j.\n\n## Setting up constraints and indexes\n\nUse `setup_constraints_and_indexes` like this:\n\n```ruby\nCONSTRAINTS_LIST = ['User/email', 'Session/sid']\nINDEX_LIST = ['Session/expires']\nsetup_constraints_and_indexes(CONSTRAINTS_LIST, INDEX_LIST)\n```\n\nThis setup up two uniqueness constraints and one index:\n- the `email` property of all nodes with label `User` must be unique\n- the `sid` property of all nodes with label `Session` must be unique\n- the `expires` property of all nodes with label `Session` gets indexed for faster lookup\n\nNeo4jBolt prefixes all constraints and indexes declared this way with `neo4j_bolt_` and it will remove all such entries previously declared (as detected by the prefix) and not passed to `setup_constraints_and_indexes`. That way, constraints and indexes can be added and removed.\n\nNeo4jBolt does not currently support putting constraints on relationships or declaring indexes on relationships or combining several properties into one uniqueness constraint. You are, however, free to declare these constraints and indexes via Cypher yourself.\n\n## Housekeeping and inspection\n\nUse the `neo4j_bolt` command line tool to perform various tasks regarding your database:\n\n| Command | Description |\n| ------- | ----------- |\n| `neo4j_bolt console` | launch Pry console with Neo4jBolt |\n| `neo4j_bolt clear` | remove all nodes and relationships, needs `--srsly` argument |\n| `neo4j_bolt dump` | dump database contents |\n| `neo4j_bolt load` | load database dump |\n| `neo4j_bolt index ls` | list all database constraints and indexes |\n| `neo4j_bolt index rm` | remove all constraints and indexes, needs `-f` |\n| `neo4j_bolt visualize` | generates a visual representation of the current datbase contents |\n\nSpecify you Neo4j host and port using `--host` if your database is not running on localhost:7687.\n\n### Dump database contents\n\nWhen you dump a database, output will go to `/dev/stdout` by default, but it can be redirected to any file via `--out-file`. In the export, node IDs start at 0, regardless of the actual node IDs in the database, and start node / end node IDs in the relationship dumps are adjusted accodingly. Don't rely on actual node IDs within your database, as they may change during export and import. Relationship IDs are omitted in the export.\n\n### Load database dump\n\nA database dump can only be loaded if the database is empty. Otherwise, you'll have to specify `--force`.\n\n### List constraints and indexes\n\nUse the command `neo4j_bolt index ls` to see which constraints and indexes are currently active in the database.\n\n### Remove all constraints and indexes\n\nUse the command `neo4j_bolt index rm -f` to remove all constraints and indexes in the database but make sure you know what you're doing.\n\n### Visualize database contents\n\nUse the command `neo4j_bolt visualize` to obtain a GraphViz-formatted document suitable for piping into `dot`:\n\n```bash\n./bin/neo4j_bolt visualize | dot -Tsvg \u003e graph.svg\n```\n\nIf you don't have GraphViz installed, you can use a Docker image instead:\n\n```bash\n./bin/neo4j_bolt visualize | docker run --rm -i nshine/dot dot -Tsvg \u003e graph.svg\n```\n\nThe result looks like this for the movie graph example provided by Neo4j:\n\n\u003cimg src=\"movie_graph.svg\" /\u003e\n\nYou can see nodes and relationships with their current numbers, plus all properties with their respective data types and for each data type the percentage of entities with that data type and min / mean / max values (for ints and floats) or min / mean / max lengths (for strings and lists).\n\nUniqueness constraints and indexes (if available) are shown as well if they are defined on a single node or relationship with a single attribute.\n\nIf a property is an integer and has `ts` or `timestamp` in its name separated from other alphanumeric characters (like `ts_created` but not like `hits`), it gets treated as a UNIX timestamp (just for the visualization).\n\n## Development\n\nAfter checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.\n\nTo install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).\n\n## Contributing\n\nBug reports and pull requests are welcome on GitHub at https://github.com/specht/neo4j_bolt.\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fspecht%2Fneo4j_bolt","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fspecht%2Fneo4j_bolt","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fspecht%2Fneo4j_bolt/lists"}