neo4j-ruby-driver 5.7.0.alpha.4 → 6.0.0.alpha.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6e0343454cd9cf98cab65814233386d198abbd6644152af5b0e514f2e2d152ea
-  data.tar.gz: fe48e618ebbcacd6148f31055367b5e6feb328a24dca43a6769f0261c9de7a68
+  metadata.gz: 2cb3ba5c3c1dda74bf82e77866ac67ad834c3cc0fbe34c60c6f94d15040f56f2
+  data.tar.gz: 50a8a7f3c771de94889c3edfc28e2c0d3f26fc80c39bae330d81b5d34aedf4ae
 SHA512:
-  metadata.gz: 3d8c347a0cee9ae197dfca6afd2deaed9f144a72df354a18f3298c052c75c6a627eae062993f638b67cace9b4195938845e6fb1917f9c9f034b5a349e2c0b4dd
-  data.tar.gz: 0c87b4ba135c8ad6626ac0d0fc8678ccc7e255860a163f4d0a862a62b2b6795d9cffab01fdd5c803df93d0ca69007cfb0e27eb77455477789e617e6dcf59a514
+  metadata.gz: f2011130ffcc499091ded7d02ff85484ec8f170a4d7adca828bf7d125eaa9d4b3b1ec0d1c93b53b0d1379ac8b378bb5c77ef7f869e0d1ffe4a2fca4442672a1b
+  data.tar.gz: bae2f8340186a2f0ad94da8e24c193dfdea98bee1a814ea78df481b35e9f4e4ea93c1827b662a46a9a742eaf94d82b8e09b9721754aad2a26dfb77196429ce5d

data/README.md

@@ -1,12 +1,50 @@
-# Neo4j::Driver
+# Neo4j Ruby Driver
 
-home  :: https://github.com/neo4jrb/neo4j-ruby-driver
+This repository contains 2 implementation of a Neo4j driver for Ruby:
 
-This repository contains 2 implementation of a neo4j driver for ruby:
-- based on official java implementation. It provides a thin wrapper over the java driver (only on jruby).
-- pure ruby implmementation. Available on all ruby versions >= 3.1.
+- based on official Java implementation. It provides a thin wrapper over the Java driver (only on jruby).
+- pure Ruby implementation. Available on all Ruby versions >= 3.1.
 
-## Installation
+Network communication is handled using [Bolt Protocol](https://7687.org/).
+
+<details>
+<summary>Table of Contents</summary>
+
+* [Getting started](#getting-started)
+    * [Installation](#installation)
+    * [Getting a Neo4j instance](#getting-a-neo4j-instance)
+    * [Quick start example](#quick-start-example)
+* [Server Compatibility](#server-compatibility)
+* [Usage](#usage)
+    * [Connecting to a database](#connecting-to-a-database)
+        * [URI schemes](#uri-schemes)
+        * [Authentication](#authentication)
+        * [Configuration](#configuration)
+        * [Connectivity check](#connectivity-check)
+    * [Sessions & transactions](#sessions--transactions)
+        * [Session](#session)
+        * [Auto-commit transactions](#auto-commit-transactions)
+        * [Explicit transactions](#explicit-transactions)
+        * [Read transactions](#read-transactions)
+        * [Write transactions](#write-transactions)
+    * [Working with results](#working-with-results)
+        * [Accessing Node and Relationship data](#accessing-node-and-relationship-data)
+        * [Working with Paths](#working-with-paths)
+        * [Working with temporal types](#working-with-temporal-types)
+    * [Type mapping](#type-mapping)
+    * [Advanced](#advanced)
+        * [Connection pooling](#connection-pooling)
+        * [Logging](#logging)
+* [For Driver Engineers](#for-driver-engineers)
+    * [Testing](#testing)
+* [Contributing](#contributing)
+* [License](#license)
+
+</details>
+
+## Getting started
+
+### Installation
 
 Add this line to your application's Gemfile:
 
@@ -16,68 +54,430 @@ gem 'neo4j-ruby-driver'
 
 And then execute:
 
-    $ bundle
+```bash
+bundle install
+```
 
 Or install it yourself as:
 
-    $ gem install neo4j-ruby-driver
+```bash
+gem install neo4j-ruby-driver
+```
+
+### Getting a Neo4j instance
+
+You need a running Neo4j database in order to use the driver with it. The easiest way to spin up a **local instance** is
+through a Docker container.
+
+The command below runs the latest Neo4j version in Docker, setting the admin username and password to `neo4j` and
+`password` respectively:
+
+```bash
+docker run \
+        -p7474:7474 \
+        -p7687:7687 \
+        -d \
+        -e NEO4J_AUTH=neo4j/password \
+        neo4j:latest
+```
+
+### Quick start example
+
+```ruby
+require 'neo4j/driver'
+
+Neo4j::Driver::GraphDatabase.driver(
+  'bolt://localhost:7687',
+  Neo4j::Driver::AuthTokens.basic('neo4j', 'password')
+) do |driver|
+  driver.session(database: 'neo4j') do |session|
+    query_result = session.run('RETURN 2+2 AS value')
+    puts "2+2 equals #{query_result.single['value']}"
+
+    # consume gives the execution summary
+    create_result = session.run('CREATE (n)').consume
+    puts "Nodes created: #{create_result.counters.nodes_created}"
+  end
+end
+```
 
 ## Server Compatibility
 
-The compatibility with Neo4j Server versions is documented in the [Neo4j Knowledge Base](https://neo4j.com/developer/kb/neo4j-supported-versions/).
+The compatibility with Neo4j Server versions is documented in
+the [Neo4j Knowledge Base](https://neo4j.com/developer/kb/neo4j-supported-versions/).
 
 ## Usage
 
-The API is to highest possible degree consistent with the official java driver. 
-At this moment [The Neo4j Drivers Manual v4.4](https://neo4j.com/docs/java-manual/current/) along with the ruby version of the [code fragments](https://github.com/neo4jrb/neo4j-ruby-driver/blob/master/docs/dev_manual_examples.rb) and the ruby specs provide the only documentation. 
+The API is to highest possible degree consistent with the official Java driver. Please refer to
+the [Neo4j Java Driver Manual](https://neo4j.com/docs/java-manual/current/), [examples in Ruby](https://github.com/neo4jrb/neo4j-ruby-driver/blob/master/docs/dev_manual_examples.rb),
+and code snippets below to understand how to use it.
+[Neo4j Java Driver API Docs](https://neo4j.com/docs/api/java-driver/current/) can be helpful as well.
+
+### Connecting to a database
+
+#### URI schemes
+
+The driver supports the following URI schemes:
+
+| URI Scheme     | Description                                                                     |
+|----------------|---------------------------------------------------------------------------------|
+| `neo4j://`     | Connect using routing to a cluster/causal cluster.                              |
+| `neo4j+s://`   | Same as `neo4j://` but with full TLS encryption.                                |
+| `neo4j+ssc://` | Same as `neo4j://` but with full TLS encryption, without hostname verification. |
+| `bolt://`      | Connect directly to a server using the Bolt protocol.                           |
+| `bolt+s://`    | Same as `bolt://` but with full TLS encryption.                                 |
+| `bolt+ssc://`  | Same as `bolt://` but with full TLS encryption, without hostname verification.  |
+
+Example:
+
+```ruby
+# Connect to a single instance
+driver = Neo4j::Driver::GraphDatabase.driver(
+  'bolt://localhost:7687',
+  Neo4j::Driver::AuthTokens.basic('neo4j', 'password')
+)
+
+# Connect to a cluster
+driver = Neo4j::Driver::GraphDatabase.driver(
+  'neo4j://graph.example.com:7687',
+  Neo4j::Driver::AuthTokens.basic('neo4j', 'password')
+)
+```
+
+#### Authentication
+
+The driver provides multiple authentication methods:
+
+```ruby
+# Basic authentication
+auth = Neo4j::Driver::AuthTokens.basic('neo4j', 'password')
+
+# With realm specification
+auth = Neo4j::Driver::AuthTokens.basic('neo4j', 'password', 'realm')
+
+# Kerberos authentication
+auth = Neo4j::Driver::AuthTokens.kerberos('ticket')
+
+# Bearer authentication
+auth = Neo4j::Driver::AuthTokens.bearer('token')
+
+# Custom authentication
+auth = Neo4j::Driver::AuthTokens.custom('principal', 'credentials', 'realm', 'scheme')
+
+# No authentication
+auth = Neo4j::Driver::AuthTokens.none
+```
+
+#### Configuration
+
+You can configure the driver with additional options:
+
+```ruby
+config = {
+  connection_timeout: 15.seconds,
+  connection_acquisition_timeout: 1.minute,
+  max_transaction_retry_time: 30.seconds,
+  encryption: true,
+  trust_strategy: :trust_all_certificates
+}
+
+driver = Neo4j::Driver::GraphDatabase.driver(
+  'neo4j://localhost:7687',
+  Neo4j::Driver::AuthTokens.basic('neo4j', 'password'),
+  **config
+)
+```
+
+#### Connectivity check
+
+```ruby
+if driver.verify_connectivity
+  puts "Driver is connected to the database"
+else
+  puts "Driver cannot connect to the database"
+end
+```
+
+### Sessions & transactions
+
+The driver provides sessions to interact with the database and to execute queries.
+
+#### Session
+
+Sessions are lightweight and disposable database connections. Always close your sessions when done:
+
+```ruby
+session = driver.session(database: 'neo4j')
+begin
+  session.run('MATCH (n) RETURN n LIMIT 10')
+ensure
+  session.close
+end
+```
+
+Or use a block that automatically closes the session:
+
+```ruby
+driver.session(database: 'neo4j') do |session|
+  session.run('MATCH (n) RETURN n LIMIT 10')
+end
+```
+
+Session options:
+
+```ruby
+# Default database
+session = driver.session
+
+# Specific database
+session = driver.session(database: 'neo4j')
+
+# With access mode
+session = driver.session(database: 'neo4j', default_access_mode: Neo4j::Driver::AccessMode::READ)
+
+# With bookmarks for causal consistency
+session = driver.session(
+  database: 'neo4j',
+  bookmarks: [Neo4j::Driver::Bookmark.from('bookmark-1')]
+)
+```
+
+#### Auto-commit transactions
+
+For simple, one-off queries, use auto-commit transactions:
+
+```ruby
+session.run('CREATE (n:Person {name: $name})', name: 'Alice')
+```
+
+#### Explicit transactions
+
+For multiple queries that need to be executed as a unit, use explicit transactions:
+
+```ruby
+tx = session.begin_transaction
+begin
+  tx.run('CREATE (n:Person {name: $name})', name: 'Alice')
+  tx.run('CREATE (n:Person {name: $name})', name: 'Bob')
+  tx.commit
+rescue
+  tx.rollback
+  raise
+end
+```
+
+#### Read transactions
+
+Specifically for read operations:
+
+```ruby
+result = session.read_transaction do |tx|
+  tx.run('MATCH (n:Person) RETURN n.name').map { |record| record['n.name'] }
+end
+puts result
+```
+
+#### Write transactions
+
+Specifically for write operations:
+
+```ruby
+session.write_transaction do |tx|
+  tx.run('CREATE (n:Person {name: $name})', name: 'Charlie')
+end
+```
+
+### Working with results
+
+```ruby
+result = session.run('MATCH (n:Person) RETURN n.name AS name, n.age AS age')
+
+# Process results
+result.each do |record|
+  puts "#{record['name']} is #{record['age']} years old"
+end
+
+# Check if there are more results
+puts "Has more results: #{result.has_next?}"
+
+# Get a single record
+single = result.single
+puts single['name'] if single
+
+# Get keys available in the result
+puts "Keys: #{result.keys}"
+
+# Access by field index
+result.each do |record|
+  puts "First field: #{record[0]}"
+end
+
+# Convert to array
+records = result.to_a
+```
+
+#### Accessing Node and Relationship data
+
+Working with graph entities:
+
+```ruby
+result = session.run('MATCH (p:Person)-[r:KNOWS]->(friend) RETURN p, r, friend')
+
+result.each do |record|
+  # Working with nodes
+  person = record['p']
+  puts "Node ID: #{person.id}"
+  puts "Labels: #{person.labels.join(', ')}"
+  puts "Properties: #{person.properties}"
+  puts "Name property: #{person.properties['name']}"
+
+  # Working with relationships
+  relationship = record['r']
+  puts "Relationship ID: #{relationship.id}"
+  puts "Type: #{relationship.type}"
+  puts "Properties: #{relationship.properties}"
+
+  # Start and end nodes of the relationship
+  puts "Relationship: #{relationship.start_node_id} -> #{relationship.end_node_id}"
+end
+```
+
+#### Working with Paths
+
+Processing paths returned from Cypher:
+
+```ruby
+result = session.run('MATCH p = (:Person)-[:KNOWS*]->(:Person) RETURN p')
+
+result.each do |record|
+  path = record['p']
+
+  # Get all nodes in the path
+  nodes = path.nodes
+  puts "Nodes in path: #{nodes.map { |n| n.properties['name'] }.join(' -> ')}"
+
+  # Get all relationships in the path
+  relationships = path.relationships
+  puts "Relationship types: #{relationships.map(&:type).join(', ')}"
+
+  # Iterate through the path segments
+  path.each do |segment|
+    puts "#{segment.start_node.properties['name']} -[#{segment.relationship.type}]-> #{segment.end_node.properties['name']}"
+  end
+end
+```
+
+#### Working with temporal types
+
+Creating a node with properties of temporal types:
+
+```ruby
+session.run(
+  'CREATE (e:Event {datetime: $datetime, duration: $duration})',
+  datetime: DateTime.new(2025, 5, 5, 5, 55, 55), duration: 1.hour
+)
+```
+
+Querying temporal values:
+
+```ruby
+session.run('MATCH (e:Event) LIMIT 1 RETURN e.datetime, e.duration').single.to_h
+# => {"e.datetime": 2025-05-05 05:55:55 +0000, "e.duration": 3600 seconds}
+```
+
+### Type mapping
 
-[Neo4j Java Driver 4.3 API](https://neo4j.com/docs/api/java-driver/current/) can be helpful as well..
+The Neo4j Ruby Driver maps Cypher types to Ruby types:
 
-## Development
+| Cypher Type    | Ruby Type                                     |
+|----------------|-----------------------------------------------|
+| null           | nil                                           |
+| List           | Enumerable                                    |
+| Map            | Hash (symbolized keys)                        |
+| Boolean        | TrueClass/FalseClass                          |
+| Integer        | Integer/String[^1]                            |
+| Float          | Float                                         |
+| String         | String/Symbol[^2] (encoding: UTF-8)           |
+| ByteArray      | String (encoding: BINARY)                     |
+| Date           | Date                                          |
+| Zoned Time     | Neo4j::Driver::Types::OffsetTime              |
+| Local Time     | Neo4j::Driver::Types::LocalTime               |
+| Zoned DateTime | Time/ActiveSupport::TimeWithZone/DateTime[^3] |
+| Local DateTime | Neo4j::Driver::Types::LocalDateTime           |
+| Duration       | ActiveSupport::Duration                       |
+| Point          | Neo4j::Driver::Types::Point                   |
+| Node           | Neo4j::Driver::Types::Node                    |
+| Relationship   | Neo4j::Driver::Types::Relationship            |
+| Path           | Neo4j::Driver::Types::Path                    |
 
-This gem includes 2 different implementations: java driver wrapper and pure ruby driver
+[^1]: An Integer smaller than -2 ** 63 or larger than 2 ** 63 will always be implicitly converted to String
+[^2]: A Symbol passed as a parameter will always be implicitly converted to String. All Strings other than BINARY
+encoded are converted to UTF-8 when stored in Neo4j
+[^3]: A Ruby DateTime passed as a parameter will always be implicitly converted to Time
 
-    $ bin/setup 
-     
-## Testing
+### Advanced
 
-To run the tests the following tools need to be installed:
+#### Connection pooling
 
-    $ brew install python
-    $ pip3 install --user git+https://github.com/klobuczek/boltkit@1.3#egg=boltkit
-    $ neoctrl-install -e 4.4.5 servers
-    $ neoctrl-configure servers/neo4j-enterprise-4.4.5 dbms.directories.import= dbms.default_listen_address=::
-    $ neoctrl-set-initial-password pass servers/neo4j-enterprise-4.4.5
-    $ neoctrl-start servers/neo4j-enterprise-4.4.5
+The driver handles connection pooling automatically. Configure the connection pool:
+
+```ruby
+config = {
+  max_connection_pool_size: 100,
+  max_connection_lifetime: 1.hour
+}
 
-To run the tests:
-```console
-$ bin/setup
-$ rspec spec
+driver = Neo4j::Driver::GraphDatabase.driver('neo4j://localhost:7687', auth, **config)
 ```
 
-Known errors:
+#### Logging
 
-1. In case of heap space memory error (`org.neo4j.driver.exceptions.DatabaseException: Java heap space`), you should limit the dbms memory, for example:
+Configure logging for the driver:
 
-```console
-$ neoctrl-configure servers/neo4j-enterprise-4.4.5 dbms.memory.pagecache.size=600m dbms.memory.heap.max_size=600m dbms.memory.heap.initial_size=600m dbms.directories.import= dbms.connectors.default_listen_address=::
+```ruby
+config = {
+  logger: Logger.new(STDOUT).tap { |log| log.level = Logger::DEBUG }
+}
+
+driver = Neo4j::Driver::GraphDatabase.driver('neo4j://localhost:7687', auth, **config)
 ```
 
-2. When using command `pip3 install --user git+https://github.com/klobuczek/boltkit@1.3#egg=boltkit`, if you have m1 mac chip, you may get error when pip3 tries to install `cryptography`. Steps to take in that case (reference https://stackoverflow.com/a/70074869/2559490)
+## For Driver Engineers
 
-```console
-$ pip uninstall cffi
-$ python -m pip install --upgrade pip
-$ pip install cffi
-$ pip install cryptography
+This gem includes 2 different implementations: a Java driver wrapper and a pure Ruby driver, so you will have to run
+this command every time you switch the Ruby engine:
+
+```bash
+bin/setup
 ```
 
+### Testing
+
+There are two sets of tests for the driver. To run the specs placed in this repository, use a normal rspec command:
+
+```bash
+rspec spec
+```
+
+To run the [Testkit](https://github.com/neo4j-drivers/testkit) that is used to test all Neo4j driver implementations,
+use the following:
+
+```bash
+git clone git@github.com:neo4j-drivers/testkit.git
+cd testkit
+export TEST_DRIVER_NAME=ruby
+export TEST_DRIVER_REPO=`realpath ../neo4j-ruby-driver`
+export TEST_NEO4J_PASS=password
+python3 main.py --tests UNIT_TESTS --configs 4.3-enterprise
+```
+
+Please refer to the [Testkit](https://github.com/neo4j-drivers/testkit) documentation to learn more about its features.
+
 ## Contributing
 
-Suggestions, improvements, bug reports and pull requests are welcome on GitHub at https://github.com/neo4jrb/neo4j-ruby-driver.
+Suggestions, improvements, bug reports and pull requests are welcome on GitHub
+at https://github.com/neo4jrb/neo4j-ruby-driver.
 
 ## License
 
 The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
-

data/lib/neo4j/driver/{auto_closable.rb → auto_closeable.rb}

@@ -2,8 +2,8 @@
 
 module Neo4j
   module Driver
-    module AutoClosable
-      def auto_closable(*methods)
+    module AutoCloseable
+      def auto_closeable(*methods)
         prepend with_block_definer(methods)
       end
 
@@ -13,15 +13,15 @@ module Neo4j
         Module.new do
           methods.each do |method|
             define_method(method) do |*args, **kwargs, &block|
-              closable = super(*args, **kwargs)
+              closeable = super(*args, **kwargs)
               if block
                 begin
-                  block.arity.zero? ? closable.instance_eval(&block) : block.call(closable)
+                  block.arity.zero? ? closeable.instance_eval(&block) : block.call(closeable)
                 ensure
-                  closable&.close
+                  closeable&.close
                 end
               else
-                closable
+                closeable
               end
             end
           end

data/lib/neo4j/driver/internal/deprecator.rb

@@ -0,0 +1,15 @@
+module Neo4j
+  module Driver
+    module Internal
+      module Deprecator
+        def self.deprecator
+          @deprecator ||= ActiveSupport::Deprecation.new('6.0', 'neo4j-ruby-driver')
+        end
+
+        def self.log_warning(old_method, new_method, version)
+          deprecator.deprecation_warning(old_method, new_method)
+        end
+      end
+    end
+  end
+end

data/ruby/neo4j/driver/bookmark.rb

@@ -13,8 +13,8 @@ module Neo4j
       # Reconstruct bookmark from \bookmarks string values.
       # @param values values obtained from a previous bookmark.
       # @return A bookmark.
-      def self.from(*values)
-        Internal::InternalBookmark.parse(*values)
+      def self.from(value)
+        Internal::InternalBookmark.new(value)
       end
     end
   end

data/ruby/neo4j/driver/graph_database.rb

@@ -3,8 +3,8 @@
 module Neo4j::Driver
   class GraphDatabase
     class << self
-      extend AutoClosable
-      auto_closable :driver, :routing_driver
+      extend AutoCloseable
+      auto_closeable :driver, :routing_driver
 
       def driver(uri, auth_token = nil, **config)
         internal_driver(uri, auth_token, config)

data/ruby/neo4j/driver/internal/async/immutable_connection_context.rb

@@ -2,16 +2,16 @@ module Neo4j::Driver
   module Internal
     module Async
       class ImmutableConnectionContext
-        attr :database_name, :mode, :rediscovery_bookmark, :impersonated_user
+        attr :database_name, :mode, :rediscovery_bookmarks, :impersonated_user
 
-        def initialize(database_name, bookmark, mode)
+        def initialize(database_name, bookmarks, mode)
           @database_name = database_name
-          @rediscovery_bookmark = bookmark
+          @rediscovery_bookmarks = bookmarks
           @mode = mode
         end
 
-        SINGLE_DB_CONTEXT = new(DatabaseNameUtil::DEFAULT_DATABASE, InternalBookmark::EMPTY, AccessMode::READ)
-        MULTI_DB_CONTEXT = new(DatabaseNameUtil::SYSTEM_DATABASE, InternalBookmark::EMPTY, AccessMode::READ)
+        SINGLE_DB_CONTEXT = new(DatabaseNameUtil::DEFAULT_DATABASE, [], AccessMode::READ)
+        MULTI_DB_CONTEXT = new(DatabaseNameUtil::SYSTEM_DATABASE, [], AccessMode::READ)
 
         # A simple context is used to test connectivity with a remote server/cluster. As long as there is a read only service, the connection shall be established
         # successfully. Depending on whether multidb is supported or not, this method returns different context for routing table discovery.

data/ruby/neo4j/driver/internal/async/internal_async_session.rb

@@ -6,7 +6,7 @@ module Neo4j::Driver
           @session = session
         end
 
-        delegate :last_bookmark, :close_async, to: :@session
+        delegate :last_bookmarks, :close_async, to: :@session
 
         def run_async(query, parameters = {}, config = {})
           @session.run_async(org.neo4j.driver.Query.new(query, **parameters), **config)

data/ruby/neo4j/driver/internal/async/network_session.rb

@@ -11,7 +11,7 @@ module Neo4j::Driver
           @log = Logging::PrefixedLogger.new("[#{hash}]", logger)
           @bookmark_holder = bookmark_holder
           # @database_name = database_name.database_name
-          @connection_context = NetworkSessionConnectionContext.new(database_name, @bookmark_holder.bookmark, impersonated_user)
+          @connection_context = NetworkSessionConnectionContext.new(database_name, @bookmark_holder.bookmarks, impersonated_user)
           @fetch_size = fetch_size
           @open = Concurrent::AtomicBoolean.new(true)
         end
@@ -28,7 +28,7 @@ module Neo4j::Driver
           acquire_connection(mode).then do |connection|
             ImpersonationUtil.ensure_impersonation_support(connection, connection.impersonated_user)
             tx = UnmanagedTransaction.new(connection, @bookmark_holder, @fetch_size)
-            tx.begin_async(@bookmark_holder.bookmark, config)
+            tx.begin_async(@bookmark_holder.bookmarks, config)
           end&.tap { |new_transaction| @transaction = new_transaction }
         end
 
@@ -42,8 +42,8 @@ module Neo4j::Driver
           end
         end
 
-        def last_bookmark
-          @bookmark_holder.bookmark
+        def last_bookmarks
+          @bookmark_holder.bookmarks
         end
 
         def release_connection_async
@@ -131,11 +131,11 @@ module Neo4j::Driver
           # It has to be the initial bookmark given at the creation of the session.
           # As only that bookmark could carry extra system bookmarks
           attr_accessor :database_name
-          attr :mode, :rediscovery_bookmark, :impersonated_user
+          attr :mode, :rediscovery_bookmarks, :impersonated_user
 
-          def initialize(database_name, bookmark, impersonated_user)
+          def initialize(database_name, bookmarks, impersonated_user)
             @database_name = database_name
-            @rediscovery_bookmark = bookmark
+            @rediscovery_bookmarks = bookmarks
             @impersonated_user = impersonated_user
           end
 

data/ruby/neo4j/driver/internal/async/unmanaged_transaction.rb

@@ -35,8 +35,8 @@ module Neo4j::Driver
           @state = State::ACTIVE
         end
 
-        def begin_async(initial_bookmark, config)
-          @protocol.begin_transaction(@connection, initial_bookmark, config)
+        def begin_async(initial_bookmarks, config)
+          @protocol.begin_transaction(@connection, initial_bookmarks, config)
           self
         rescue Neo4j::Driver::Exceptions::AuthorizationExpiredException
           @connection.terminate_and_release(Neo4j::Driver::Exceptions::AuthorizationExpiredException::DESCRIPTION)
@@ -175,7 +175,7 @@ module Neo4j::Driver
           if exception
             Util::ResultHolder.failed(exception)
           else
-            @protocol.commit_transaction(@connection).then(&@bookmark_holder.method(:bookmark=))
+            @protocol.commit_transaction(@connection).then { @bookmark_holder.bookmarks = Set[it] }
           end
         end
 

data/ruby/neo4j/driver/internal/cluster/routing_table_handler_impl.rb

@@ -33,7 +33,7 @@ module Neo4j::Driver
               @log.debug("Routing table for database '#{@database_name.description}' is stale. #{@routing_table}")
 
               fresh_cluster_composition_fetched(
-                @rediscovery.lookup_cluster_composition(@routing_table, @connection_pool, context.rediscovery_bookmark,
+                @rediscovery.lookup_cluster_composition(@routing_table, @connection_pool, context.rediscovery_bookmarks,
                                                         nil))
             else
               # existing routing table is fresh, use it

data/ruby/neo4j/driver/internal/default_bookmark_holder.rb

@@ -1,8 +1,8 @@
 module Neo4j::Driver
   module Internal
     class DefaultBookmarkHolder < ReadOnlyBookmarkHolder
-      def bookmark=(bookmark)
-        @bookmark = bookmark if bookmark.present?
+      def bookmarks=(bookmarks)
+        @bookmarks = bookmarks
       end
     end
   end

data/ruby/neo4j/driver/internal/delegating_transaction.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Neo4j::Driver
+  module Internal
+    class DelegatingTransaction
+      delegate :run, to: :@tx
+
+      def initialize(tx)
+        @tx = tx
+      end
+    end
+  end
+end

data/ruby/neo4j/driver/internal/eager_result_value.rb

@@ -0,0 +1,5 @@
+module Neo4j::Driver
+  module Internal
+    EagerResultValue = Struct.new(:keys, :records, :summary)
+  end
+end

data/ruby/neo4j/driver/internal/handlers/commit_tx_response_handler.rb

@@ -8,9 +8,7 @@ module Neo4j::Driver
           @result_holder = result_holder
         end
 
-        def on_success(metadata)
-          @result_holder.succeed(metadata[:bookmark]&.then(&InternalBookmark.method(:parse)))
-        end
+        def on_success(metadata) = @result_holder.succeed(Util::MetadataExtractor.extract_bookmark(metadata))
 
         def on_failure(error)
           @result_holder.fail(error)

data/ruby/neo4j/driver/internal/handlers/pulln/auto_pull_response_handler.rb

@@ -3,7 +3,7 @@ module Neo4j::Driver
     module Handlers
       module Pulln
         class AutoPullResponseHandler < BasicPullResponseHandler
-          delegate :signal, to: :@records
+          delegate :signal, to: :@queue_notification
           LONG_MAX_VALUE = 2 ** 63 - 1
 
           def initialize(query, run_response_handler, connection, metadata_extractor, completion_listener, fetch_size)
@@ -19,7 +19,8 @@ module Neo4j::Driver
               @low_record_watermark = fetch_size * 0.3
             end
 
-            @records = ::Async::Queue.new
+            @queue_notification = ::Async::Notification.new
+            @records = ::Async::Queue.new(available: @queue_notification)
             @auto_pull_enabled = true
 
             install_record_and_summary_consumers

data/ruby/neo4j/driver/internal/handlers/session_pull_response_completion_listener.rb

@@ -9,7 +9,7 @@ module Neo4j::Driver
 
         def after_success(metadata)
           release_connection
-          @bookmark_holder.bookmark = Util::MetadataExtractor.extract_bookmarks(metadata)
+          @bookmark_holder.bookmarks = Array(Util::MetadataExtractor.extract_bookmark(metadata)).to_set
         end
 
         def after_failure(error)

data/ruby/neo4j/driver/internal/internal_bookmark.rb

@@ -1,36 +1,9 @@
 module Neo4j::Driver
   module Internal
-    class InternalBookmark
+    class InternalBookmark < String
       include Bookmark
-      attr :values
-      delegate :hash, :empty?, to: :values
 
-      private def initialize(*values)
-        @values = values.to_set
-      end
-      EMPTY = new.freeze
-
-      def ==(other)
-        equal?(other) || self.class == other.class && values == other.values
-      end
-
-      alias eql? ==
-
-      def to_s
-        "Bookmark{values=#{values}}"
-      end
-
-      class << self
-        def empty
-          EMPTY
-        end
-
-        def from(*bookmarks)
-          new(*bookmarks.reduce(Set.new) { |set, bookmark| set + bookmark.values })
-        end
-
-        alias parse new
-      end
+      def to_s = "Bookmark{value=#{super}}"
     end
   end
 end

data/ruby/neo4j/driver/internal/internal_driver.rb

@@ -1,12 +1,12 @@
 module Neo4j::Driver
   module Internal
     class InternalDriver
-      extend AutoClosable
+      extend AutoCloseable
       extend Synchronizable
       attr_reader :session_factory, :metrics_provider
       # delegate :verify_connectivity, to: :session_factory
       delegate :metrics, :metrics_enabled?, to: :metrics_provider
-      auto_closable :session
+      auto_closeable :session
       sync :close, :supports_multi_db?, :verify_connectivity, :session
 
       def initialize(security_plan, session_factory, metrics_provider, logger)
@@ -25,6 +25,15 @@ module Neo4j::Driver
         InternalAsyncSession.new(new_session(**session_config))
       end
 
+      def execute_query(query, auth_token = nil, config = {}, **parameters)
+        # TODO: auth_token not implemented yet
+        session(**config.slice(:bookmarks, :database, :impersonated_user, :default_access_mode, :fetch_size)) do |session|
+          session.run(query, parameters, config.slice(:timeout, :metadata)).then do
+            EagerResultValue.new(it.keys, it.to_a, it.consume)
+          end
+        end
+      end
+
       def encrypted?
         assert_open!
         @security_plan.requires_encryption?

data/ruby/neo4j/driver/internal/internal_session.rb

@@ -1,11 +1,11 @@
 module Neo4j::Driver
   module Internal
     class InternalSession
-      extend AutoClosable
+      extend AutoCloseable
       extend Synchronizable
       # include Ext::RunOverride
-      delegate :open?, :last_bookmark, to: :@session
-      auto_closable :begin_transaction
+      delegate :open?, :last_bookmarks, to: :@session
+      auto_closeable :begin_transaction
       sync :close, :begin_transaction, :run, :transaction
 
       def initialize(session)
@@ -38,15 +38,29 @@ module Neo4j::Driver
       end
 
       def read_transaction(**config, &block)
+        Deprecator.log_warning(:read_transaction, :execute_read, '6.0')
         transaction(AccessMode::READ, **config, &block)
       end
 
       def write_transaction(**config, &block)
+        Deprecator.log_warning(:write_transaction, :execute_write, '6.0')
         transaction(AccessMode::WRITE, **config, &block)
       end
 
+      def execute_read(**config, &block)
+        delegating_transaction(AccessMode::READ, **config, &block)
+      end
+
+      def execute_write(**config, &block)
+        delegating_transaction(AccessMode::WRITE, **config, &block)
+      end
+
       private
 
+      def delegating_transaction(mode, **config, &block)
+        transaction(mode, **config) { |tx| block.call(DelegatingTransaction.new(tx)) }
+      end
+
       def transaction(mode, **config)
         # use different code path compared to async so that work is executed in the caller thread
         # caller thread will also be the one who sleeps between retries;

data/ruby/neo4j/driver/internal/messaging/encode/route_message_encoder.rb

@@ -8,7 +8,7 @@ module Neo4j::Driver
             Util::Preconditions.check_argument(message, Request::RouteMessage)
             packer.pack_struct_header(3, message.signature)
             packer.pack(message.routing_context)
-            packer.pack(message.bookmark&.values || [])
+            packer.pack(message.bookmark || [])
             packer.pack(option(message))
           end
 

data/ruby/neo4j/driver/internal/messaging/request/begin_message.rb

@@ -5,10 +5,10 @@ module Neo4j::Driver
         class BeginMessage < MessageWithMetadata
           SIGNATURE = 0x11
 
-          def initialize(bookmark, config, database_name, mode, impersonated_user)
+          def initialize(bookmarks, config, database_name, mode, impersonated_user)
             super(Request::TransactionMetadataBuilder.build_metadata(
               timeout: config[:timeout], tx_metadata: config[:metadata], database_name: database_name, mode: mode,
-              bookmark: bookmark, impersonated_user: impersonated_user))
+              bookmarks: bookmarks, impersonated_user: impersonated_user))
           end
 
           def signature

data/ruby/neo4j/driver/internal/messaging/request/run_with_metadata_message.rb

@@ -7,10 +7,10 @@ module Neo4j::Driver
           attr_reader :query, :parameters
 
           class << self
-            def auto_commit_tx_run_message(query, config, database_name, mode, bookmark, impersonated_user)
+            def auto_commit_tx_run_message(query, config, database_name, mode, bookmarks, impersonated_user)
               metadata = Request::TransactionMetadataBuilder.build_metadata(
                 timeout: config[:timeout], tx_metadata: config[:metadata], database_name: database_name, mode: mode,
-                bookmark: bookmark, impersonated_user: impersonated_user)
+                bookmarks: bookmarks, impersonated_user: impersonated_user)
               new(query.text, query.parameters, metadata)
             end
 

data/ruby/neo4j/driver/internal/messaging/request/transaction_metadata_builder.rb

@@ -6,9 +6,9 @@ module Neo4j::Driver
           MODE_READ_VALUE = 'r'
 
           class << self
-            def build_metadata(timeout:, tx_metadata:, mode:, bookmark:, impersonated_user:,
+            def build_metadata(timeout:, tx_metadata:, mode:, bookmarks:, impersonated_user:,
                                database_name: DatabaseNameUtil.default_database)
-              { bookmarks: bookmark.presence,
+              { bookmarks: bookmarks.presence,
                 tx_timeout: timeout&.then(&DurationNormalizer.method(:milliseconds)),
                 tx_metadata: tx_metadata.presence,
                 mode: (MODE_READ_VALUE if mode == AccessMode::READ),

data/ruby/neo4j/driver/internal/messaging/v3/bolt_protocol_v3.rb

@@ -30,9 +30,9 @@ module Neo4j::Driver
             message_dispatcher.prepare_to_close_channel
           end
 
-          def begin_transaction(connection, bookmark, config)
+          def begin_transaction(connection, bookmarks, config)
             verify_database_name_before_transaction(connection.database_name)
-            begin_message = Request::BeginMessage.new(bookmark, config, connection.database_name, connection.mode, connection.impersonated_user)
+            begin_message = Request::BeginMessage.new(bookmarks, config, connection.database_name, connection.mode, connection.impersonated_user)
             connection.write_and_flush(begin_message, Handlers::BeginTxResponseHandler.new)
           end
 
@@ -51,7 +51,7 @@ module Neo4j::Driver
           def run_in_auto_commit_transaction(connection, query, bookmark_holder, config, fetch_size)
             verify_database_name_before_transaction(connection.database_name)
 
-            run_message = Request::RunWithMetadataMessage.auto_commit_tx_run_message(query, config, connection.database_name, connection.mode, bookmark_holder.bookmark, connection.impersonated_user)
+            run_message = Request::RunWithMetadataMessage.auto_commit_tx_run_message(query, config, connection.database_name, connection.mode, bookmark_holder.bookmarks, connection.impersonated_user)
 
             build_result_cursor_factory(connection, query, bookmark_holder, nil, run_message, fetch_size)
           end

data/ruby/neo4j/driver/internal/packstream/pack_stream.rb

@@ -114,8 +114,6 @@ module Neo4j::Driver
               value = value.to_a
               pack_list_header(value.size)
               value.each(&method(:pack))
-            when Bookmark
-              pack(value.values)
             else
               unpackable(value)
             end

data/ruby/neo4j/driver/internal/read_only_bookmark_holder.rb

@@ -1,13 +1,13 @@
 module Neo4j::Driver
   module Internal
     class ReadOnlyBookmarkHolder
-      attr_reader :bookmark
+      attr_reader :bookmarks
 
-      def initialize(bookmark = InternalBookmark.empty)
-        @bookmark = bookmark
+      def initialize(bookmarks = Set[])
+        @bookmarks = bookmarks
       end
 
-      def bookmark=(_value) end
+      def bookmarks=(_value) end
     end
   end
 end

data/ruby/neo4j/driver/internal/session_factory_impl.rb

@@ -13,7 +13,7 @@ module Neo4j::Driver
       end
 
       def new_instance(fetch_size: @default_fetch_size, default_access_mode: AccessMode::WRITE, **config)
-        bookmark_holder = DefaultBookmarkHolder.new(InternalBookmark.from(*config[:bookmarks]))
+        bookmark_holder = DefaultBookmarkHolder.new(Array(config[:bookmarks]).to_set)
         create_session(parse_database_name(config), default_access_mode, bookmark_holder, fetch_size, config[:impersonated_user])
       end
 

data/ruby/neo4j/driver/internal/summary/internal_notification.rb

@@ -1,10 +1,10 @@
 # frozen_string_literal: true
 
 module Neo4j::Driver::Internal::Summary
-  class InternalNotification < Struct.new(:code, :title, :description, :severity, :position)
+  class InternalNotification < Struct.new(:code, :title, :description, :severity_level, :position)
 
     VALUE_TO_NOTIFICATION = lambda do |value|
-      severity = value[:severity] || 'N/A'
+      severity = value[:severity]
 
       position = value[:position]&.then do |pos_value|
         InternalInputPosition.new(*pos_value.values_at(:offset, :line, :column).map(&:to_i))

data/ruby/neo4j/driver/internal/util/metadata_extractor.rb

@@ -35,13 +35,7 @@ module Neo4j::Driver
               Summary::InternalDatabaseInfo::DEFAULT_DATABASE_INFO
           end
 
-          def extract_bookmarks(metadata)
-            bookmark_value = metadata[:bookmark]
-
-            return InternalBookmark.parse(bookmark_value) if bookmark_value&.is_a? String
-
-            InternalBookmark.empty
-          end
+          def extract_bookmark(metadata) = metadata[:bookmark]&.then(&InternalBookmark.method(:new))
 
           def extract_neo4j_server_version(metadata)
             server_value = extract_server(metadata)

data/ruby/neo4j/driver/version.rb

@@ -2,6 +2,6 @@
 
 module Neo4j
   module Driver
-    VERSION = '5.7.0.alpha.4'
+    VERSION = '6.0.0.alpha.0'
   end
 end

data/ruby/neo4j/driver.rb

@@ -2,6 +2,7 @@
 
 require 'active_support/core_ext/array/grouping'
 require 'active_support/core_ext/hash/keys'
+require 'active_support/core_ext/object/blank'
 require 'active_support/logger'
 require 'async/io'
 require 'async/io/stream'
@@ -14,6 +15,7 @@ module Neo4j
   module Driver
     Loader.load
 
+    EagerResult = Neo4j::Driver::Internal::EagerResultValue
     Record = Neo4j::Driver::Internal::InternalRecord
     Result = Neo4j::Driver::Internal::InternalResult
     Transaction = Neo4j::Driver::Internal::InternalTransaction

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: neo4j-ruby-driver
 version: !ruby/object:Gem::Version
-  version: 5.7.0.alpha.4
+  version: 6.0.0.alpha.0
 platform: ruby
 authors:
 - Heinrich Klobuczek
 bindir: bin
 cert_chain: []
-date: 2025-01-14 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -24,49 +24,55 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '7.1'
 - !ruby/object:Gem::Dependency
-  name: zeitwerk
+  name: csv
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 2.1.10
+        version: '3.0'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 2.1.10
+        version: '3.0'
 - !ruby/object:Gem::Dependency
-  name: async
+  name: zeitwerk
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "<"
+    - - ">="
       - !ruby/object:Gem::Version
-        version: '2.13'
+        version: 2.1.10
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "<"
+    - - ">="
       - !ruby/object:Gem::Version
-        version: '2.13'
+        version: 2.1.10
 - !ruby/object:Gem::Dependency
-  name: async-io
+  name: async
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '0'
+        version: '2.13'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '2.24'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '0'
+        version: '2.13'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '2.24'
 - !ruby/object:Gem::Dependency
-  name: connection_pool
+  name: async-io
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
@@ -80,7 +86,7 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '0'
 - !ruby/object:Gem::Dependency
-  name: csv
+  name: connection_pool
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
@@ -224,7 +230,7 @@ files:
 - README.md
 - lib/neo4j-ruby-driver.rb
 - lib/neo4j-ruby-driver_loader.rb
-- lib/neo4j/driver/auto_closable.rb
+- lib/neo4j/driver/auto_closeable.rb
 - lib/neo4j/driver/exceptions/authentication_exception.rb
 - lib/neo4j/driver/exceptions/authorization_expired_exception.rb
 - lib/neo4j/driver/exceptions/certificate_exception.rb
@@ -252,6 +258,7 @@ files:
 - lib/neo4j/driver/exceptions/value/unsizable.rb
 - lib/neo4j/driver/exceptions/value/value_exception.rb
 - lib/neo4j/driver/internal/bolt_server_address.rb
+- lib/neo4j/driver/internal/deprecator.rb
 - lib/neo4j/driver/internal/duration_normalizer.rb
 - lib/neo4j/driver/internal/validator.rb
 - lib/neo4j/driver/summary/query_type.rb
@@ -339,8 +346,10 @@ files:
 - ruby/neo4j/driver/internal/database_name_util.rb
 - ruby/neo4j/driver/internal/default_bookmark_holder.rb
 - ruby/neo4j/driver/internal/default_domain_name_resolver.rb
+- ruby/neo4j/driver/internal/delegating_transaction.rb
 - ruby/neo4j/driver/internal/direct_connection_provider.rb
 - ruby/neo4j/driver/internal/driver_factory.rb
+- ruby/neo4j/driver/internal/eager_result_value.rb
 - ruby/neo4j/driver/internal/handlers/begin_tx_response_handler.rb
 - ruby/neo4j/driver/internal/handlers/channel_releasing_reset_response_handler.rb
 - ruby/neo4j/driver/internal/handlers/commit_tx_response_handler.rb
@@ -524,7 +533,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.2
+rubygems_version: 3.6.9
 specification_version: 4
 summary: ''
 test_files: []