neo4j_bolt 0.3.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 316d22f20084bb29755e8693c25860bd4d3afa5e5aadce5b89e415bf53157b82
-  data.tar.gz: 405c68b29be5578f7859cdc973b956ccb9898a4b7d105cc19b0e31e81c5615b3
+  metadata.gz: a0582f714d9d1c8793edb70481db6a2ff5548200b14ad55c1f44b0859270b7d9
+  data.tar.gz: 73e300f77c941909738411fdbd9ce6b72ea6ef73a72a10184395e2228ce6a52c
 SHA512:
-  metadata.gz: 94766bfe86f3487582229ed0d11fa4c2bc813adac23fe1065c5dc026c692e3b82c859978b08d5dfb78915382d224425b7e7f81eb06f620eebb23014d8e4934b9
-  data.tar.gz: e144730f9cb75b44450c0dfb3b56d76698c9839e1f54a375c4e7608cb6eb7d6cf70d1544a7065a78d08c4d813387da66ec758bc1749d24037899233c80feb3d7
+  metadata.gz: 8e5debab26d8b655b1fa3fc1e4c877308e8221345aec76844d2b423ef4fe3061bc535241566f9af63ba889274b944c81efbad9daeadf1cc9b0ed166c82a18417
+  data.tar.gz: 65ed32647603bdeaf9bbca19335a0ca6fdccf5b17f3aaa11e19ef48868b242731a34b3cba74ff9475dbd5db94e6bf15f44f60110dca5adb8fe83d9709ef45a3d

data/README.md

@@ -1,196 +1,235 @@
 # Neo4jBolt
 
-A 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.
-
-Caution: 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.
-
-- PackStream:
-  - data types:
-    - supported: Null, Boolean, Integer, Float, String, List, Dictionary, Structure
-    - not supported: Bytes
-  - structures:
-    - supported: Node, Relationship
-    - not supported: UnboundRelationship, Path, Date, Time, LocalTime, DateTime, DateTimeZoneId, LocalDateTime, Duration, Point2D, Point3D
-- Bolt Protocol:
-  - supported: transactions
-  - not supported:
-    - auto transactions (all transactions are explicit in Neo4jBolt)
-    - routing
-    - interrupt
+Neo4jBolt 0.4 is a small compatibility and convenience layer for Ruby applications, backed by [neo4j-ruby-driver](https://github.com/neo4jrb/neo4j-ruby-driver). It preserves the straightforward `Neo4jBolt` application API while delegating connections, pooling, Bolt negotiation, protocol state, PackStream, reconnects, and modern Neo4j value support to the upstream driver.
+
+Neo4jBolt no longer implements the Bolt wire protocol itself.
+
+`0.4.0.pre1` requires Ruby 3.4 or newer and pins `neo4j-ruby-driver` to `6.2.1.beta.4`. Applications on older Rubies can remain on the Neo4jBolt 0.3.x line; this prerelease is intentionally not an automatic upgrade for them.
 
 ## Installation
 
-Add this line to your application's Gemfile:
+For this prerelease, specify the version explicitly:
 
 ```ruby
-gem 'neo4j_bolt'
+gem "neo4j_bolt", "0.4.0.pre1"
 ```
 
-And then execute:
-
-    $ bundle install
+Then run `bundle install`. A running Neo4j database is required.
 
-Or install it yourself as:
+## Connecting
 
-    $ gem install neo4j_bolt
+The existing host, port, and verbosity settings remain available:
 
-In 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:
-
-```
-docker run --rm --env NEO4J_AUTH=none --publish 7687:7687 neo4j:4.4-community
+```ruby
+Neo4jBolt.bolt_host = "localhost"
+Neo4jBolt.bolt_port = 7687
+Neo4jBolt.bolt_verbosity = 0
 ```
 
-If you want the Browser interface at http://localhost:7474/, additionaly specify `--publish 7474:7474`.
-
-## Connecting to a Neo4j database
-
-Specify your Bolt host and port (if you omit this it will be localhost:7687 by default):
+Applications can include the module as before:
 
 ```ruby
-Neo4jBolt.bolt_host = 'localhost'
-Neo4jBolt.bolt_port = 7687
+include Neo4jBolt
 ```
 
-Use `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).
+They can also extend another object or call the convenience methods directly on `Neo4jBolt`.
+
+One lazily initialized upstream driver owns a thread-safe connection pool. Each standalone query uses a short-lived session and returns its connection to that pool after its result has been consumed. Queries from several Puma threads are not globally serialized.
+
+`cleanup_neo4j` safely retires the driver and its pool after active operations finish. A later query creates a new driver. Do not call cleanup from inside an active query or transaction on the same thread.
 
 ## Running queries
 
-Use `neo4j_query` to run a query and receive all results:
+Materialize all result rows:
 
 ```ruby
-entries = neo4j_query("MATCH (n) RETURN n;")
+rows = neo4j_query("MATCH (person:Person) RETURN person.name AS name")
+puts rows.first["name"]
 ```
-Alternatively, specify a block to make use of Neo4j's streaming capabilities and receive entries one by one:
+
+Or process records incrementally without first materializing the complete result:
 
 ```ruby
-neo4j_query("MATCH (n) RETURN n;") do |entry|
-    # handle entry here
+neo4j_query("MATCH (person:Person) RETURN person") do |row|
+  puts row["person"][:name]
 end
 ```
 
-Using 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:
+The block form returns `nil`. Its upstream session, result, and pooled connection remain alive for the duration of iteration.
 
-- `Neo4jBolt::Node` attributes: `id`, `labels`
-- `Neo4jBolt::Relationship` attributes: `id`, `start_node_id`, `end_node_id`, `type`
+Parameters stay separate from Cypher:
 
 ```ruby
-node = neo4j_query_expect_one("CREATE (n:Node {a: 1, b: 2}) RETURN n;")['n']
-# All nodes returned from Neo4j are a Neo4jBolt::Node
-# It's a subclass of Hash and it stores all the node's
-# properties plus two attributes called id and labels:
-puts node.id
-puts node.labels
-puts node.keys
-node.each_pair { |k, v| puts "#{k}: #{v}" }
-puts node.to_json
-puts "a: #{node[:a]}"
+row = neo4j_query_expect_one(
+  "MATCH (person:Person {email: $email}) RETURN person",
+  email: "ada@example.test"
+)
 ```
 
-While 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]`).
+`neo4j_query_expect_one` raises `Neo4jBolt::ExpectedOneResultError` unless the query produces exactly one row.
+
+### Result compatibility
+
+Result-row keys are strings:
 
-Use `neo4j_query_expect_one` if you want to make sure there's exactly one entry to be returned:
+```ruby
+row["person"]
+```
+
+Nodes and relationships remain Hash subclasses whose property keys are symbols:
 
 ```ruby
-node = neo4j_query_expect_one("MATCH (n) RETURN n LIMIT 1;")['n']
+node = row["person"]
+node[:name]
+node.id
+node.labels
+node.element_id
 ```
 
-If there's zero, two, or more results, this will raise a `ExpectedOneResultError`.
+`Neo4jBolt::Node` preserves `id` and `labels` and additively exposes `element_id`.
+
+`Neo4jBolt::Relationship` preserves `id`, `start_node_id`, `end_node_id`, and `type`, and additively exposes `element_id`, `start_node_element_id`, and `end_node_element_id`.
+
+Arrays and maps are adapted recursively. Map/property keys inside values are symbols, matching Neo4jBolt 0.3 behavior. Modern upstream values that 0.3 could not represent—such as temporal, spatial, path, byte, duration, and UUID values—pass through as upstream value objects. This is additive support.
 
-## Using transactions
+Signed 64-bit integer limits are checked before transport. Out-of-range integers raise `Neo4jBolt::IntegerOutOfRangeError`.
 
-Any 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:
+## Transactions
+
+The convenient compatibility API is unchanged:
 
 ```ruby
 transaction do
-    neo4j_query("CREATE (n:Node {a: 1});")
-    neo4j_query("CREATE (n:Node {b: 1});")
+  neo4j_query("CREATE (:Person {name: 'Ada'})")
+  neo4j_query("CREATE (:Person {name: 'Grace'})")
 end
 ```
 
-Transactions 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.
+Nested `transaction` blocks reuse one actual upstream session and transaction. Applications do not receive or pass an upstream transaction object.
 
-## Setting up constraints and indexes
+Transaction context is isolated by calling thread and by the object using `Neo4jBolt`. Two threads using the same object receive independent upstream transactions and pooled connections.
 
-Use `setup_constraints_and_indexes` like this:
+Transactions are rollback-only after any nested operation raises, even if application code rescues the exception later. This includes database failures and `ExpectedOneResultError`:
 
 ```ruby
-CONSTRAINTS_LIST = ['User/email', 'Session/sid']
-INDEX_LIST = ['Session/expires']
-setup_constraints_and_indexes(CONSTRAINTS_LIST, INDEX_LIST)
+transaction do
+  neo4j_query("CREATE (:Marker)")
+
+  begin
+    neo4j_query("invalid cypher")
+  rescue Neo4jBolt::SyntaxError
+  end
+end
+# Nothing is committed.
 ```
 
-This setup up two uniqueness constraints and one index:
-- the `email` property of all nodes with label `User` must be unique
-- the `sid` property of all nodes with label `Session` must be unique
-- the `expires` property of all nodes with label `Session` gets indexed for faster lookup
+Calling `rollback` inside a transaction marks that outer transaction rollback-only and returns `nil`. Calling it outside a transaction raises `Neo4jBolt::Error`; the old 0.3 implementation exposed the method but accidentally delegated to a nonexistent private implementation.
 
-Neo4jBolt 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.
+Upstream server/driver failures are translated to `Neo4jBolt::Error`. Syntax and uniqueness-constraint failures are translated narrowly to `Neo4jBolt::SyntaxError` and `Neo4jBolt::ConstraintValidationFailedError`. The upstream exception remains available as `error.cause`.
 
-Neo4jBolt 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.
+## Constraints and indexes
 
-## Housekeeping and inspection
+The existing setup format remains supported:
 
-Use the `neo4j_bolt` command line tool to perform various tasks regarding your database:
+```ruby
+setup_constraints_and_indexes(
+  ["User/email", "Session/sid"],
+  ["Session/expires"]
+)
+```
 
-| Command | Description |
-| ------- | ----------- |
-| `neo4j_bolt console` | launch Pry console with Neo4jBolt |
-| `neo4j_bolt clear` | remove all nodes and relationships, needs `--srsly` argument |
-| `neo4j_bolt dump` | dump database contents |
-| `neo4j_bolt load` | load database dump |
-| `neo4j_bolt index ls` | list all database constraints and indexes |
-| `neo4j_bolt index rm` | remove all constraints and indexes, needs `-f` |
-| `neo4j_bolt visualize` | generates a visual representation of the current datbase contents |
+Managed entries retain the `neo4j_bolt_` prefix. Setup removes obsolete entries with that prefix only; it does not remove arbitrary application-defined indexes or constraints.
 
-Specify you Neo4j host and port using `--host` if your database is not running on localhost:7687.
+## Dump and load
 
-### Dump database contents
+The textual format is unchanged:
 
-When 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.
+```text
+n {"id":0,"labels":["Person"],"properties":{"name":"Ada"}}
+n {"id":1,"labels":["Person"],"properties":{"name":"Grace"}}
+r {"from":0,"to":1,"type":"KNOWS","properties":{"since":2024}}
+```
 
-### Load database dump
+```ruby
+File.open("database.dump", "w") { |io| dump_database(io) }
+File.open("database.dump", "r") { |io| load_database_dump(io) }
+```
 
-A database dump can only be loaded if the database is empty. Otherwise, you'll have to specify `--force`.
+The `0, 1, 2, ...` IDs are synthetic dump-local IDs. Database-internal IDs and element IDs are never written to the persistent format. The adapter uses driver-provided entity identity while dumping and a random temporary property (removed in `ensure`) while loading, so relationship reconstruction does not depend on deprecated persistent integer IDs. To keep dump numbering deterministic, ordering uses `elementId()` on modern Neo4j and an internal `id()` fallback only on Neo4j 4.4, where `elementId()` does not exist. Old Neo4jBolt dumps remain loadable.
 
-### List constraints and indexes
+Loading requires an empty database unless `force_append: true` is passed.
 
-Use the command `neo4j_bolt index ls` to see which constraints and indexes are currently active in the database.
+## CLI
 
-### Remove all constraints and indexes
+The `neo4j_bolt` executable retains these commands:
 
-Use 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.
+| Command | Purpose |
+| --- | --- |
+| `neo4j_bolt console` | Open an IRB console with Neo4jBolt loaded |
+| `neo4j_bolt clear --srsly` | Delete all nodes and relationships |
+| `neo4j_bolt dump` | Write the textual database dump |
+| `neo4j_bolt load [--force] PATH` | Load a textual dump |
+| `neo4j_bolt index ls` | List constraints and indexes |
+| `neo4j_bolt index rm --force` | Remove all constraints and indexes |
+| `neo4j_bolt visualize` | Generate a GraphViz document |
 
-### Visualize database contents
+Use `--host HOST:PORT` to select a server. `gli` remains a runtime dependency for the CLI, and `pry` remains for the separate `bin/console` executable.
 
-Use the command `neo4j_bolt visualize` to obtain a GraphViz-formatted document suitable for piping into `dot`:
+## Tested Neo4j versions
 
-```bash
-./bin/neo4j_bolt visualize | dot -Tsvg > graph.svg
-```
+The same complete integration suite is run against these exact Community images:
 
-If you don't have GraphViz installed, you can use a Docker image instead:
+- `neo4j:4.4.48-community`
+- `neo4j:5.26.28-community`
+- `neo4j:2026.06.0-community`
 
-```bash
-./bin/neo4j_bolt visualize | docker run --rm -i nshine/dot dot -Tsvg > graph.svg
-```
+No compatibility beyond this matrix is claimed for `0.4.0.pre1`.
 
-The result looks like this for the movie graph example provided by Neo4j:
+Run one modern LTS target:
 
-<img src="movie_graph.svg" />
+```bash
+bundle exec rake spec
+```
 
-You 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).
+Run the complete sequential matrix:
 
-Uniqueness constraints and indexes (if available) are shown as well if they are defined on a single node or relationship with a single attribute.
+```bash
+bundle exec rake spec:matrix
+```
 
-If 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).
+The harness creates uniquely named disposable containers with `NEO4J_AUTH=none`, dynamically publishes Bolt ports, waits by establishing a real driver/query connection, and cleans every container through shell traps. A developer does not need to start Neo4j manually.
+
+To point RSpec itself at an already disposable database, set `NEO4J_BOLT_TEST_HOST` and `NEO4J_BOLT_TEST_PORT`. The explicit port requirement protects real databases from the destructive integration suite.
+
+## Compatibility inventory for 0.4
+
+| API | Status |
+| --- | --- |
+| `bolt_host`, `bolt_port`, `bolt_verbosity` | Preserved |
+| Included/extended/module-style use | Preserved |
+| `neo4j_query`, including incremental block form | Preserved via adapter |
+| `neo4j_query_expect_one` | Preserved via adapter |
+| `transaction`, nesting, rollback-only behavior | Preserved via thread-local adapter |
+| `rollback` | Preserved and repaired as rollback-only |
+| `cleanup_neo4j`, `wait_for_neo4j` | Preserved via pooled driver lifecycle |
+| `setup_constraints_and_indexes` | Preserved with current Cypher |
+| `dump_database`, `load_database_dump` | Preserved; relationship reconstruction modernized |
+| Named error classes | Preserved with narrow upstream translation |
+| `Node` and `Relationship` Hash behavior | Preserved via recursive value adapter |
+| Element identity and modern values | Additive behavior |
+| CLI commands | Preserved |
+| `BoltSocket`, `BoltBuffer`, protocol markers/state/parser/packer | Intentionally removed private implementation details |
+
+## 0.4.0.pre1 migration notes
+
+- Ruby 3.4 or newer is required; Ruby 2.x/3.0–3.3 applications should stay on 0.3.x until upgraded.
+- The exact prerelease upstream dependency is pinned while no stable `neo4j-ruby-driver` 6.2.x exists.
+- Connections are pooled and safe for concurrent use instead of one mutable socket per including object.
+- TLS, routing, authentication, database selection, and other upstream-driver configuration are not newly exposed through the legacy three-setting API in this compatibility prerelease.
+- `BoltSocket`, `BoltBuffer`, `ServerState`, `BoltMarker`, `UnexpectedServerResponse`, `State`, and `CypherError` were undocumented wire internals and are removed.
 
 ## Development
 
-After 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.
-
-To 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).
-
-## Contributing
-
-Bug reports and pull requests are welcome on GitHub at https://github.com/specht/neo4j_bolt.
+Run `bin/setup`, then `bundle exec rake spec` or `bundle exec rake spec:matrix`. Build without publishing with `bundle exec rake build`.
 
+Bug reports and pull requests are welcome at <https://github.com/specht/neo4j_bolt>.

data/bin/neo4j_bolt

@@ -92,10 +92,10 @@ class App
     command :index do |c|
         c.command :ls do |c2|
             c2.action do |global_options, options, args|
-                neo4j_query("SHOW ALL CONSTRAINTS") do |row|
+                neo4j_query("SHOW CONSTRAINTS") do |row|
                     puts "#{row['type']} #{row['name']} #{(row['labelsOrTypes'] || []).join('/')}/#{(row['properties'] || []).join('/')}"
                 end
-                neo4j_query("SHOW ALL INDEXES") do |row|
+                neo4j_query("SHOW INDEXES") do |row|
                     puts "#{row['uniqueness']} #{row['entityType']} #{row['state']} #{row['populationPercent']}% #{row['name']} #{(row['labelsOrTypes'] || []).join('/')}/#{(row['properties'] || []).join('/')}"
                 end
             end
@@ -106,10 +106,10 @@ class App
                 if options[:force]
                     all_constraints = []
                     all_indexes = []
-                    neo4j_query("SHOW ALL CONSTRAINTS") do |row|
+                    neo4j_query("SHOW CONSTRAINTS") do |row|
                         all_constraints << row['name']
                     end
-                    neo4j_query("SHOW ALL INDEXES") do |row|
+                    neo4j_query("SHOW INDEXES") do |row|
                         all_indexes << row['name']
                     end
                     transaction do
@@ -242,7 +242,7 @@ class App
                     'BTREE' => 'indexed',
                 }
 
-                ['SHOW ALL CONSTRAINTS', 'SHOW ALL INDEXES'].each do |query|
+                ['SHOW CONSTRAINTS', 'SHOW INDEXES'].each do |query|
                     neo4j_query(query) do |row|
                         # STDERR.puts row.to_json
                         labels_or_types = row['labelsOrTypes'] || []

data/lib/neo4j_bolt/version.rb

@@ -1,3 +1,3 @@
 module Neo4jBolt
-    VERSION = "0.3.0"
+    VERSION = "0.4.0"
 end