neo4j_bolt 0.4.3 → 0.4.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 38ed2e6727f1bc4baccc838b195d72a2392bbb82788598d704a1e81bd0f20de0
-  data.tar.gz: d781a67c3eee09dd9e32a9af60fe1fb65a61bb8afddb96307dd897cbcd99ddf1
+  metadata.gz: cc5ccd396277de9c75f73bd338f89a2af476475940d53e0399cfbbeaa9589dc6
+  data.tar.gz: 90a393bb3f4819245613ca34206d24932487de5af4959b27e26232137766e15f
 SHA512:
-  metadata.gz: e1d4c318c5adb68878da6368dc8d694a63c79cc953ab0e87ffe5aceaf77ce9d47d06b35a80cef8ea835ac90e6753974a59c2bb2bd9088f144fdf8761976b9b8a
-  data.tar.gz: d28fd8341cbbfe89391c7685331ed8fc666864edb7222f8ccb3530ddd3e93b2bad68d9fa6ebdf75049cad99c8d68926b356e3b55fadcb795e017dfc0be9d0f22
+  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.0` 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.0"
+gem "neo4j_bolt", "0.4.5"
 ```
 
 Then run `bundle install`. A running Neo4j database is required.
@@ -26,6 +26,27 @@ Neo4jBolt.bolt_port = 7687
 Neo4jBolt.bolt_verbosity = 0
 ```
 
+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. `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"
+```
+
+If both username and password are unset, Neo4jBolt keeps the existing unauthenticated connection behavior. If only one is set, the first query raises `Neo4jBolt::Error`. Leaving the database unset lets Neo4j choose the user's/server's default database.
+
 Applications can include the module as before:
 
 ```ruby
@@ -36,7 +57,7 @@ They can also extend another object or call the convenience methods directly on
 
 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.
+`cleanup_neo4j` safely retires the driver and its pool after active operations finish. A later query creates a new driver. Changing host, port, username, or password also retires the pool so later connections use the new settings. Database selection is a session setting and therefore applies to newly opened sessions without rebuilding the driver. Do not call cleanup from inside an active query or transaction on the same thread.
 
 ## Running queries
 
@@ -168,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`.
 
@@ -188,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` to select a server. `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
 
@@ -198,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.0`.
+No compatibility beyond this matrix is claimed for `0.4.5`.
 
 Run one modern LTS target:
 
@@ -212,15 +233,16 @@ Run the complete sequential matrix:
 bundle exec rake spec:matrix
 ```
 
-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.
+The harness creates uniquely named disposable containers with Basic authentication enabled, 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.
+To point RSpec itself at an already disposable database, set `NEO4J_BOLT_TEST_HOST` and `NEO4J_BOLT_TEST_PORT`. If it requires authentication or an explicit database, also set `NEO4J_USERNAME`, `NEO4J_PASSWORD`, and `NEO4J_DATABASE`. 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 |
+| `bolt_username`, `bolt_password`, `bolt_database` | Additive authentication/database configuration |
 | Included/extended/module-style use | Preserved |
 | `neo4j_query`, including incremental block form | Preserved via adapter |
 | `neo4j_query_expect_one` | Preserved via adapter |
@@ -235,12 +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.0 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.
-- TLS, routing, authentication, database selection, and other upstream-driver configuration are not newly exposed through the legacy three-setting API in this compatibility prerelease.
+- `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,13 +21,22 @@ 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?
+        Neo4jBolt.bolt_database = global_options[:database] unless global_options[:database].nil?
         true
     end
 

data/lib/neo4j_bolt/version.rb

@@ -1,3 +1,3 @@
 module Neo4jBolt
-    VERSION = "0.4.3"
+    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
@@ -335,10 +337,22 @@ module Neo4jBolt
         host = "[#{host}]" if host.include?(":") && !host.start_with?("[")
         Neo4j::Driver::GraphDatabase.driver(
           "bolt://#{host}:#{Neo4jBolt.bolt_port}",
-          Neo4j::Driver::AuthTokens.none
+          authentication_token
         )
       end
 
+      def authentication_token
+        username = Neo4jBolt.bolt_username
+        password = Neo4jBolt.bolt_password
+        return Neo4j::Driver::AuthTokens.none if username.nil? && password.nil?
+
+        if username.nil? || password.nil?
+          raise Error, "Neo4j username and password must either both be set or both be unset"
+        end
+
+        Neo4j::Driver::AuthTokens.basic(username, password)
+      end
+
       def leases
         @leases ||= 0
       end
@@ -354,8 +368,8 @@ module Neo4jBolt
   end
 
   class << self
-    attr_reader :bolt_host, :bolt_port
-    attr_accessor :bolt_verbosity
+    attr_reader :bolt_host, :bolt_port, :bolt_username, :bolt_password
+    attr_accessor :bolt_verbosity, :bolt_database
 
     def bolt_host=(host)
       reconfigure_driver if defined?(@bolt_host) && @bolt_host != host
@@ -367,6 +381,16 @@ module Neo4jBolt
       @bolt_port = port
     end
 
+    def bolt_username=(username)
+      reconfigure_driver if defined?(@bolt_username) && @bolt_username != username
+      @bolt_username = username
+    end
+
+    def bolt_password=(password)
+      reconfigure_driver if defined?(@bolt_password) && @bolt_password != password
+      @bolt_password = password
+    end
+
     private
 
     def reconfigure_driver
@@ -374,13 +398,47 @@ 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"]
+  self.bolt_database = ENV["NEO4J_DATABASE"]
 
   # Keep both `include Neo4jBolt` and direct module-style calls working.
   extend self
 
+  def with_session(driver)
+    database = Neo4jBolt.bolt_database
+    if database.nil?
+      driver.session { |session| yield session }
+    else
+      driver.session(database: database) { |session| yield session }
+    end
+  end
+  private :with_session
+
   def neo4j_query(query, data = {}, &block)
     validate_parameters!(data)
     log_query(query, data)
@@ -390,7 +448,7 @@ module Neo4jBolt
       run_and_convert(context.transaction, query, data, &block)
     else
       DriverRegistry.with_driver do |driver|
-        driver.session do |session|
+        with_session(driver) do |session|
           run_and_convert(session, query, data, &block)
         end
       end
@@ -430,7 +488,7 @@ module Neo4jBolt
     end
 
     DriverRegistry.with_driver do |driver|
-      driver.session do |session|
+      with_session(driver) do |session|
         upstream_transaction = session.begin_transaction
         context = TransactionContext.new(
           session: session, transaction: upstream_transaction, depth: 1, rollback_only: false
@@ -615,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.3
+  version: 0.4.5
 platform: ruby
 authors:
 - Michael Specht