neo4j_bolt 0.4.2 → 0.4.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 66da85ac04ffd0ef43fea4fba9a676ea2168770f85825573652a58dbc0a48f2b
-  data.tar.gz: 132911b813e88d5a3efb590fe5cd29da0c8adb6663b06b9931bb0a03f4fcae9c
+  metadata.gz: e6322e3f763f052647f81029aaa96e45d6cb6f41a8e8d625c198d025b1408a81
+  data.tar.gz: ddf55ab34e93f5b65b36273a2c148037f4455e18252aba692296e52598668902
 SHA512:
-  metadata.gz: 37e9205800f8661683bc246c6a962a15254c2d1e4a33d5b948f85d5e59d9ac38911e67c4a2e18bb318bc9f3ceeb3eedb7199004e98b0ce1694ae2e0f16f9ce8e
-  data.tar.gz: 3f7066485f251b5939b9a448b441290f16714311ebd7baa2b2baa27d785ae2463902c63b6c14b532df5adfe574242c8e415305967677110d92943a431e4360d3
+  metadata.gz: bff514f49ee709624ac1b178e2216edd001ad168845c397aff2f9d28a3d3752a4c3fcbf0d7f9ea4bc6c0a1f68ffd6feef8fae560127774c0aa0277a4d6cf6ffd
+  data.tar.gz: d5ef2dbebc19f6f1538ee461993ec20a9184b734ba4b490ca6a941f4de7b2cb526f22ad59daa9f8578afee00f0be25728c16eed29f6ddfab1a581901b8eabb42

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.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.
 
 ## Installation
 
 For this prerelease, specify the version explicitly:
 
 ```ruby
-gem "neo4j_bolt", "0.4.0"
+gem "neo4j_bolt", "0.4.4"
 ```
 
 Then run `bundle install`. A running Neo4j database is required.
@@ -26,6 +26,24 @@ Neo4jBolt.bolt_port = 7687
 Neo4jBolt.bolt_verbosity = 0
 ```
 
+Authentication and database selection can use the standard Neo4j client environment variables:
+
+```bash
+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:
+
+```ruby
+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 +54,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
 
@@ -159,6 +177,13 @@ end
 
 Passing `progress_io:` is optional for the Ruby API. The CLI always reports dump/load progress on stderr, so dump data written to stdout remains safe to redirect or pipe. In `auto` mode a terminal gets a colored, in-place progress bar while redirected stderr receives periodic plain-text progress lines. Set `NEO4J_BOLT_PROGRESS=pretty` to force the terminal display through a container or other wrapper that hides the TTY, or `NEO4J_BOLT_PROGRESS=plain` to force log-friendly output. `NO_COLOR` disables colors without disabling the in-place display.
 
+Both `dump` and `load` accept `--color COLOR` to choose the spinner and filled progress-bar accent. The default is `cyan`. The Ruby API exposes the same setting as `progress_color:`. Available colors are `red`, `green`, `yellow`, `blue`, `magenta`, `cyan`, `white`, `bright-red`, `bright-green`, `bright-yellow`, `bright-blue`, `bright-magenta`, `bright-cyan`, and `bright-white`.
+
+```bash
+neo4j_bolt dump --color magenta -o database.dump
+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.
@@ -175,13 +200,13 @@ The `neo4j_bolt` executable retains these commands:
 | --- | --- |
 | `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] [--batch-size N] PATH` | Load a textual dump |
+| `neo4j_bolt dump [--color COLOR]` | Write the textual database dump |
+| `neo4j_bolt load [--force] [--batch-size N] [--color COLOR] 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 |
 
-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. 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.
 
 ## Tested Neo4j versions
 
@@ -191,7 +216,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.4`.
 
 Run one modern LTS target:
 
@@ -205,15 +230,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 |
@@ -228,12 +254,13 @@ 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.4 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.
+- 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.
 - `BoltSocket`, `BoltBuffer`, `ServerState`, `BoltMarker`, `UnexpectedServerResponse`, `State`, and `CypherError` were undocumented wire internals and are removed.
 
 ## Development

data/bin/neo4j_bolt

@@ -22,12 +22,18 @@ class App
 
     flag [:v, :verbosity], :default_value => 0
     flag [:h, :host], :default_value => '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
         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
 
@@ -47,9 +53,10 @@ class App
     long_desc 'Dump all nodes and relationships.'
     command :dump do |c|
         c.flag [:o, 'out-file'.to_sym], :default_value => '/dev/stdout'
+        c.flag [:color], :default_value => 'cyan', :desc => 'progress accent color'
         c.action do |global_options, options|
             File.open(options['out-file'.to_sym], 'w') do |f|
-                dump_database(f, progress_io: $stderr)
+                dump_database(f, progress_io: $stderr, progress_color: options[:color])
             end
         end
     end
@@ -63,6 +70,7 @@ class App
         c.switch [:f, :force], :default_value => false, :desc => 'force appending nodes even if the database is not empty'
         c.flag [:b, 'batch-size'.to_sym], :default_value => Neo4jBolt::LOAD_INITIAL_BATCH_SIZE,
                :desc => 'initial batch size; automatically reduced on transaction-memory errors'
+        c.flag [:color], :default_value => 'cyan', :desc => 'progress accent color'
         c.action do |global_options, options, args|
             help_now!('input path is required') if args.empty?
             path = args.shift
@@ -71,6 +79,7 @@ class App
                     f,
                     force_append: options[:force],
                     progress_io: $stderr,
+                    progress_color: options[:color],
                     initial_batch_size: options['batch-size'.to_sym]
                 )
             end

data/lib/neo4j_bolt/version.rb

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

data/lib/neo4j_bolt.rb

@@ -29,13 +29,35 @@ module Neo4jBolt
       reset: "\e[0m",
       bold: "\e[1m",
       dim: "\e[2m",
-      cyan: "\e[36m",
+      red: "\e[31m",
       green: "\e[32m",
-      yellow: "\e[33m"
+      yellow: "\e[33m",
+      blue: "\e[34m",
+      magenta: "\e[35m",
+      cyan: "\e[36m",
+      white: "\e[37m",
+      bright_red: "\e[91m",
+      bright_green: "\e[92m",
+      bright_yellow: "\e[93m",
+      bright_blue: "\e[94m",
+      bright_magenta: "\e[95m",
+      bright_cyan: "\e[96m",
+      bright_white: "\e[97m"
+    }.freeze
+    ACCENT_STYLES = {
+      "red" => :red, "green" => :green, "yellow" => :yellow, "blue" => :blue,
+      "magenta" => :magenta, "cyan" => :cyan, "white" => :white,
+      "bright-red" => :bright_red, "bright-green" => :bright_green,
+      "bright-yellow" => :bright_yellow, "bright-blue" => :bright_blue,
+      "bright-magenta" => :bright_magenta, "bright-cyan" => :bright_cyan,
+      "bright-white" => :bright_white
     }.freeze
 
-    def initialize(io)
+    def initialize(io, color: "cyan")
       @io = io
+      @accent_style = ACCENT_STYLES.fetch(color.to_s) do
+        raise ArgumentError, "progress color must be one of: #{ACCENT_STYLES.keys.join(', ')}"
+      end
       mode = ENV.fetch("NEO4J_BOLT_PROGRESS", "auto")
       unless %w[auto pretty plain].include?(mode)
         raise ArgumentError, "NEO4J_BOLT_PROGRESS must be auto, pretty, or plain"
@@ -110,7 +132,7 @@ module Neo4jBolt
       spinner = SPINNER[@spinner_index % SPINNER.length]
       @spinner_index += 1
 
-      parts = [color(:cyan, spinner), color(:bold, label)]
+      parts = [color(@accent_style, spinner), color(:bold, label)]
       if percent
         percent = [[percent.to_i, 0].max, 100].min
         parts << progress_bar(percent)
@@ -123,7 +145,7 @@ module Neo4jBolt
     def progress_bar(percent)
       filled = (percent * BAR_WIDTH / 100.0).round
       empty = BAR_WIDTH - filled
-      "#{color(:cyan, '━' * filled)}#{color(:dim, '─' * empty)}"
+      "#{color(@accent_style, '━' * filled)}#{color(:dim, '─' * empty)}"
     end
 
     def terminal_parts(message, strip_percent: false)
@@ -313,10 +335,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
@@ -332,8 +366,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
@@ -345,6 +379,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
@@ -355,10 +399,23 @@ module Neo4jBolt
   self.bolt_host = "localhost"
   self.bolt_port = 7687
   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)
@@ -368,7 +425,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
@@ -408,7 +465,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
@@ -514,8 +571,8 @@ module Neo4jBolt
     nil
   end
 
-  def dump_database(io, progress_io: nil)
-    progress = ProgressReporter.new(progress_io)
+  def dump_database(io, progress_io: nil, progress_color: "cyan")
+    progress = ProgressReporter.new(progress_io, color: progress_color)
     dumped_nodes = 0
     dumped_relationships = 0
 
@@ -574,7 +631,7 @@ module Neo4jBolt
     progress&.close
   end
 
-  def load_database_dump(io, force_append: false, progress_io: nil,
+  def load_database_dump(io, force_append: false, progress_io: nil, progress_color: "cyan",
                          initial_batch_size: LOAD_INITIAL_BATCH_SIZE)
     raise Error, "load_database_dump cannot run inside a transaction" if transaction_context
 
@@ -586,7 +643,7 @@ module Neo4jBolt
       raise Error, "There are nodes in this database, exiting now." unless count.zero?
     end
 
-    progress = ProgressReporter.new(progress_io)
+    progress = ProgressReporter.new(progress_io, color: progress_color)
     node_batches = Hash.new { |hash, key| hash[key] = [] }
     relationship_batches = Hash.new { |hash, key| hash[key] = [] }
     total_nodes, total_relationships = parse_dump(io, node_batches, relationship_batches, progress)

metadata

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