neo4j_bolt 0.4.4 → 0.4.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e6322e3f763f052647f81029aaa96e45d6cb6f41a8e8d625c198d025b1408a81
-  data.tar.gz: ddf55ab34e93f5b65b36273a2c148037f4455e18252aba692296e52598668902
+  metadata.gz: cc5ccd396277de9c75f73bd338f89a2af476475940d53e0399cfbbeaa9589dc6
+  data.tar.gz: 90a393bb3f4819245613ca34206d24932487de5af4959b27e26232137766e15f
 SHA512:
-  metadata.gz: bff514f49ee709624ac1b178e2216edd001ad168845c397aff2f9d28a3d3752a4c3fcbf0d7f9ea4bc6c0a1f68ffd6feef8fae560127774c0aa0277a4d6cf6ffd
-  data.tar.gz: d5ef2dbebc19f6f1538ee461993ec20a9184b734ba4b490ca6a941f4de7b2cb526f22ad59daa9f8578afee00f0be25728c16eed29f6ddfab1a581901b8eabb42
+  metadata.gz: e4f8c0aa87b72f4081d19476dbb684ced5fed6851b729f7db4bb7d8b06f7e41f1607581498b1195043edc63433fe91b8ca7aadf0c58c3d8c7f14bf79dcae1395
+  data.tar.gz: '028fc3fc677e0a8d83f6f5554d851ff29b1ab7bf6b0c059ea646f18062f646e4c43554f612bb6c69055658af56e4f08bda30c5756b57899475b98178b91d6e87'

data/README.md

@@ -4,14 +4,14 @@ Neo4jBolt 0.4 is a small compatibility and convenience layer for Ruby applicatio
 
 Neo4jBolt no longer implements the Bolt wire protocol itself.
 
-`0.4.4` 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.
+`0.4.5` 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
 
 For this prerelease, specify the version explicitly:
 
 ```ruby
-gem "neo4j_bolt", "0.4.4"
+gem "neo4j_bolt", "0.4.5"
 ```
 
 Then run `bundle install`. A running Neo4j database is required.
@@ -26,17 +26,20 @@ Neo4jBolt.bolt_port = 7687
 Neo4jBolt.bolt_verbosity = 0
 ```
 
-Authentication and database selection can use the standard Neo4j client environment variables:
+The connection endpoint, authentication, and database selection can use the standard Neo4j client environment variables:
 
 ```bash
+export NEO4J_URI=neo4j://localhost:7687
 export NEO4J_USERNAME=neo4j
 export NEO4J_PASSWORD=secret
 export NEO4J_DATABASE=neo4j
 ```
 
-They are read when `neo4j_bolt` is loaded. Explicit Ruby configuration overrides those defaults:
+They are read when `neo4j_bolt` is loaded. `NEO4J_URI` accepts `neo4j://HOST[:PORT]` and `bolt://HOST[:PORT]` endpoint notation; Neo4jBolt uses the host and port while retaining its existing direct Bolt connection behavior. The default port is 7687. Explicit Ruby configuration overrides those defaults:
 
 ```ruby
+Neo4jBolt.bolt_host = "localhost"
+Neo4jBolt.bolt_port = 7687
 Neo4jBolt.bolt_username = "neo4j"
 Neo4jBolt.bolt_password = "secret"
 Neo4jBolt.bolt_database = "movies"
@@ -186,7 +189,7 @@ neo4j_bolt load --color bright-blue database.dump
 
 The `0, 1, 2, ...` IDs are synthetic dump-local IDs. Database-internal IDs and element IDs are never written to the persistent format. Dumping keeps the count, node, and relationship reads in one transaction, so the driver-provided entity identity used to connect the two streamed result sets stays within Neo4j's transaction-scoped identity guarantee. 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.
 
-For relational loads, the adapter assigns a random temporary label and dump-ID property to imported nodes. After the nodes are committed it builds a temporary `neo4j_bolt_` index on that property, uses indexed lookups while creating relationships, drops the index, and removes the temporary metadata in batches. No database-internal identity is carried from one load transaction to another. Loading a relational dump therefore requires permission to create and drop an index.
+For relational loads, the adapter assigns a random temporary label and the fixed reserved property `__neo4j_bolt_load_id` to imported nodes. After the nodes are committed it builds a temporary `neo4j_bolt_` index on that property, uses indexed lookups while creating relationships, drops the index, and removes the temporary metadata in batches. The fixed property key is reused by every load instead of registering a new random property-key token each time. Neo4j can keep the property key registered after all values have been removed, so it may remain visible in Browser's property-key list; no imported node retains the property after successful cleanup. Relational loads refuse to run if the dump itself, or existing data during `force_append`, currently uses the reserved property. No database-internal identity is carried from one load transaction to another. Loading a relational dump therefore requires permission to create and drop an index.
 
 Loads start with batches of 5,000 records by default. This is an initial ceiling rather than a claimed optimum: if Neo4j returns a transaction-memory/resource error whose server semantics guarantee rollback, the loader halves the failed batch and retries it, then keeps the smaller size for the rest of that phase. Node and relationship phases adapt independently. Other errors are not retried, because a generic connection failure cannot safely prove that a `CREATE` transaction did not commit. Callers can change the initial ceiling with `initial_batch_size:`; the CLI exposes the same setting as `--batch-size`.
 
@@ -206,7 +209,7 @@ The `neo4j_bolt` executable retains these commands:
 | `neo4j_bolt index rm --force` | Remove all constraints and indexes |
 | `neo4j_bolt visualize` | Generate a GraphViz document |
 
-Use `--host HOST:PORT`, `--username USER`, `--password PASSWORD`, and `--database DATABASE` to override connection settings. Username, password, and database otherwise inherit `NEO4J_USERNAME`, `NEO4J_PASSWORD`, and `NEO4J_DATABASE`. Prefer the password environment variable for routine use because command-line arguments may be visible in shell history or process listings. `gli` remains a runtime dependency for the CLI, and `pry` remains for the separate `bin/console` executable.
+Use `--host HOST:PORT`, `--username USER`, `--password PASSWORD`, and `--database DATABASE` to override connection settings. Host and port otherwise inherit `NEO4J_URI` when present, falling back to `localhost:7687`; username, password, and database inherit `NEO4J_USERNAME`, `NEO4J_PASSWORD`, and `NEO4J_DATABASE`. Prefer the password environment variable for routine use because command-line arguments may be visible in shell history or process listings. `gli` remains a runtime dependency for the CLI, and `pry` remains for the separate `bin/console` executable.
 
 ## Tested Neo4j versions
 
@@ -216,7 +219,7 @@ The same complete integration suite is run against these exact Community images:
 - `neo4j:5.26.28-community`
 - `neo4j:2026.06.0-community`
 
-No compatibility beyond this matrix is claimed for `0.4.4`.
+No compatibility beyond this matrix is claimed for `0.4.5`.
 
 Run one modern LTS target:
 
@@ -254,13 +257,15 @@ To point RSpec itself at an already disposable database, set `NEO4J_BOLT_TEST_HO
 | CLI commands | Preserved |
 | `BoltSocket`, `BoltBuffer`, protocol markers/state/parser/packer | Intentionally removed private implementation details |
 
-## 0.4.4 migration notes
+## 0.4.5 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.
-- Basic authentication and database selection are now exposed through `bolt_username`, `bolt_password`, and `bolt_database`, with `NEO4J_USERNAME`, `NEO4J_PASSWORD`, and `NEO4J_DATABASE` as environment defaults.
-- TLS, routing, URI schemes, and other upstream-driver configuration are still not exposed through the compatibility API.
+- `NEO4J_URI` now supplies the default host and port for `bolt://` and `neo4j://` endpoint notation; an explicit CLI `--host` or Ruby `bolt_host`/`bolt_port` setting overrides it.
+- Basic authentication and database selection are exposed through `bolt_username`, `bolt_password`, and `bolt_database`, with `NEO4J_USERNAME`, `NEO4J_PASSWORD`, and `NEO4J_DATABASE` as environment defaults.
+- TLS, routing behavior, URI query parameters, and other upstream-driver configuration are still not exposed through the compatibility API.
+- Relational loads reuse one reserved `__neo4j_bolt_load_id` property key while retaining the existing indexed lookup algorithm, preventing a new property-key token from being registered on every load.
 - `BoltSocket`, `BoltBuffer`, `ServerState`, `BoltMarker`, `UnexpectedServerResponse`, `State`, and `CypherError` were undocumented wire internals and are removed.
 
 ## Development

data/bin/neo4j_bolt

@@ -21,15 +21,18 @@ class App
     version Neo4jBolt::VERSION
 
     flag [:v, :verbosity], :default_value => 0
-    flag [:h, :host], :default_value => 'localhost:7687'
+    flag [:h, :host], :default_value => nil,
+         :desc => 'Neo4j host:port (default: NEO4J_URI or localhost:7687)'
     flag [:u, :username], :default_value => nil, :desc => 'Neo4j username (default: NEO4J_USERNAME)'
     flag [:p, :password], :default_value => nil, :desc => 'Neo4j password (default: NEO4J_PASSWORD)'
     flag [:d, :database], :default_value => nil, :desc => 'Neo4j database (default: NEO4J_DATABASE)'
 
     pre do |global_options, command, options, args|
         host = global_options[:host]
-        Neo4jBolt.bolt_host = host.split(':').first
-        Neo4jBolt.bolt_port = host.split(':').last.to_i
+        unless host.nil?
+            Neo4jBolt.bolt_host = host.split(':').first
+            Neo4jBolt.bolt_port = host.split(':').last.to_i
+        end
         Neo4jBolt.bolt_verbosity = global_options[:verbosity].to_i
         Neo4jBolt.bolt_username = global_options[:username] unless global_options[:username].nil?
         Neo4jBolt.bolt_password = global_options[:password] unless global_options[:password].nil?

data/lib/neo4j_bolt/version.rb

@@ -1,3 +1,3 @@
 module Neo4jBolt
-    VERSION = "0.4.4"
+    VERSION = "0.4.5"
 end

data/lib/neo4j_bolt.rb

@@ -4,6 +4,7 @@ require "json"
 require "securerandom"
 require "set"
 require "thread"
+require "uri"
 require "neo4j/driver"
 require "neo4j_bolt/version"
 
@@ -18,8 +19,9 @@ module Neo4jBolt
   LOAD_MEMORY_GQL_STATUSES = %w[51N72 51N73].freeze
   LOAD_PROGRESS_STEP = 5_000
   DUMP_PROGRESS_STEP = 1_000
+  LOAD_ID_PROPERTY = "__neo4j_bolt_load_id"
   private_constant :LOAD_MEMORY_ERROR_CODES, :LOAD_MEMORY_GQL_STATUSES,
-                   :LOAD_PROGRESS_STEP, :DUMP_PROGRESS_STEP
+                   :LOAD_PROGRESS_STEP, :DUMP_PROGRESS_STEP, :LOAD_ID_PROPERTY
 
   class ProgressReporter
     UPDATE_INTERVAL = 0.5
@@ -396,8 +398,29 @@ module Neo4jBolt
     end
   end
 
-  self.bolt_host = "localhost"
-  self.bolt_port = 7687
+  neo4j_uri = ENV["NEO4J_URI"]
+  if neo4j_uri.nil? || neo4j_uri.empty?
+    self.bolt_host = "localhost"
+    self.bolt_port = 7687
+  else
+    begin
+      parsed_neo4j_uri = URI.parse(neo4j_uri)
+    rescue URI::InvalidURIError => error
+      raise Error, "Invalid NEO4J_URI: #{error.message}"
+    end
+
+    unless %w[bolt neo4j].include?(parsed_neo4j_uri.scheme) && parsed_neo4j_uri.host
+      raise Error, "NEO4J_URI must be a bolt:// or neo4j:// URI with a host"
+    end
+    unless parsed_neo4j_uri.userinfo.nil? &&
+           ["", "/"].include?(parsed_neo4j_uri.path.to_s) &&
+           parsed_neo4j_uri.query.nil? && parsed_neo4j_uri.fragment.nil?
+      raise Error, "NEO4J_URI may only contain scheme, host, and port"
+    end
+
+    self.bolt_host = parsed_neo4j_uri.host
+    self.bolt_port = parsed_neo4j_uri.port || 7687
+  end
   self.bolt_verbosity = 0
   self.bolt_username = ENV["NEO4J_USERNAME"]
   self.bolt_password = ENV["NEO4J_PASSWORD"]
@@ -650,12 +673,32 @@ module Neo4jBolt
 
     temporary_token = SecureRandom.hex(12)
     temporary_label = "__neo4j_bolt_load_#{temporary_token}"
-    temporary_id_property = "__neo4j_bolt_load_id_#{temporary_token}"
+    temporary_id_property = LOAD_ID_PROPERTY
     temporary_index = "neo4j_bolt_load_#{temporary_token}"
     quoted_temporary_label = quote_identifier(temporary_label)
     quoted_temporary_id = quote_identifier(temporary_id_property)
     quoted_temporary_index = quote_identifier(temporary_index)
     needs_relationship_lookup = total_relationships.positive?
+
+    if needs_relationship_lookup
+      dump_uses_reserved_property = node_batches.each_value.any? do |nodes|
+        nodes.any? { |node| node.fetch("properties", {}).key?(LOAD_ID_PROPERTY) }
+      end
+      if dump_uses_reserved_property
+        raise Error, "Dump contains reserved Neo4jBolt load property #{LOAD_ID_PROPERTY.inspect}."
+      end
+
+      if force_append
+        reserved_property_in_use = neo4j_query(
+          "MATCH (n) WHERE n.#{quoted_temporary_id} IS NOT NULL RETURN 1 AS present LIMIT 1"
+        ).any?
+        if reserved_property_in_use
+          raise Error,
+                "Database contains reserved Neo4jBolt load property #{LOAD_ID_PROPERTY.inspect}."
+        end
+      end
+    end
+
     loaded_nodes = 0
     loaded_relationships = 0
     index_created = false

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: neo4j_bolt
 version: !ruby/object:Gem::Version
-  version: 0.4.4
+  version: 0.4.5
 platform: ruby
 authors:
 - Michael Specht