activecypher 0.11.2 → 0.12.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: dd727afea785772beaeb00a2d67953177535dfb60b6d64690e238b1df8d809ce
-  data.tar.gz: '08838575c512ef8d3bafd2b7118f3c274bc8a4ba0d071e790d879294d4b05f5c'
+  metadata.gz: 29fa2252b85c3c67d4f8a8e72acc69ad1021088561ce02c8e1d205bef28b4069
+  data.tar.gz: 0665ef0b5e7a68264f50b846ba78036dc5d3c805e874bc475abb12a3bb699069
 SHA512:
-  metadata.gz: 3789c6b35b8704ae06a7b497fa0a45db948fd69dc76326805a56cc16b396fa6c753a5ff78a5d96a28357fe6d1eb900ed26787e844e83a43a56f77bb5a20df6b5
-  data.tar.gz: f059e3273a82ea69d12a6c16a6892a53840c0b2179f05c572c4aa6530861950273d9f03152943340e88c90361eb6a602e162c8295021f1f1b7177d5846193bd4
+  metadata.gz: 13b575ead30e4ea3b3476e97993c33e8eebc2dfb788d10e7ad9aa8e02014f389581d3e619f50629611340ea33af2bae967b026cd07110de57586887919ff89f3
+  data.tar.gz: a9dd762af2674169b558739ca5652e21cfcb60adb8a491c5d0bdf22b64a19b45c1087858db972a71f26af9113ee146e67ef57188e6f273adef959ca369a407d3

data/lib/active_cypher/base.rb

@@ -44,11 +44,15 @@ module ActiveCypher
         # Determine the current role (e.g., :writing, :reading)
         # ActiveCypher::RuntimeRegistry.current_role defaults to :writing
         # Only use db_key for pool lookup
-        if respond_to?(:connects_to_mappings) && connects_to_mappings.is_a?(Hash)
-          db_key = connects_to_mappings[:writing] # or whichever role is appropriate
-          if db_key && (pool = connection_handler.pool(db_key))
-            return pool.connection
-          end
+        mapping = connects_to_mappings if respond_to?(:connects_to_mappings)
+        role = ActiveCypher::RuntimeRegistry.current_role || :writing
+        # Debug guardrails removed in release code; rely on role/shard registry.
+
+        db_key = ActiveCypher::Model::ConnectionOwner.db_key_for(mapping, role)
+        db_key = db_key.to_sym if db_key.respond_to?(:to_sym)
+
+        if db_key && (pool = connection_handler.pool(db_key))
+          return pool.connection
         end
 
         return @connection if defined?(@connection) && @connection&.active?

data/lib/active_cypher/bolt/connection.rb

@@ -15,7 +15,8 @@ module ActiveCypher
       include VersionEncoding
 
       attr_reader :host, :port, :timeout_seconds, :socket,
-                  :protocol_version, :server_agent, :connection_id, :adapter
+                  :protocol_version, :server_agent, :connection_id, :adapter,
+                  :count
 
       # Override inspect to redact sensitive information
       def inspect
@@ -68,6 +69,7 @@ module ActiveCypher
         @connection_id      = nil
         @reconnect_attempts = 0
         @max_reconnect_attempts = 3
+        @count = 0
       end
 
       # ───────────────────────── connection lifecycle ────────────── #
@@ -84,7 +86,7 @@ module ActiveCypher
         error = nil
 
         begin
-          Async do |task|
+          Sync do |task|
             task.with_timeout(@timeout_seconds) do
               @socket = open_socket
               perform_handshake
@@ -102,7 +104,7 @@ module ActiveCypher
             close
             # Store the error instead of raising
             error = ConnectionError.new("Error during connection: #{e.message}")
-          end.wait
+          end
         rescue Async::TimeoutError => e
           error = ConnectionError.new("Connection timed out to #{host}:#{port} - #{e.message}")
         rescue StandardError => e
@@ -223,6 +225,9 @@ module ActiveCypher
       # @return [Boolean]
       def reusable?   = connected?
 
+      # Increment the usage counter for compatibility with Async::Pool diagnostics.
+      def mark_used! = @count += 1
+
       # This method is required by Async::Pool to check if the connection is viable for reuse
       #
       # @return [Boolean]
@@ -480,15 +485,6 @@ module ActiveCypher
         session(database: db).write_transaction(db: db, timeout: timeout, metadata: metadata, &)
       end
 
-      # Asynchronously execute a read transaction.
-      def async_read_transaction(db: nil, timeout: nil, metadata: nil, &)
-        session(database: db).async_read_transaction(db: db, timeout: timeout, metadata: metadata, &)
-      end
-
-      # Asynchronously execute a write transaction.
-      def async_write_transaction(db: nil, timeout: nil, metadata: nil, &)
-        session(database: db).async_write_transaction(db: db, timeout: timeout, metadata: metadata, &)
-      end
 
       # ────────────────────────────────────────────────────────────────────
       # HEALTH AND VERSION DETECTION METHODS
@@ -521,16 +517,16 @@ module ActiveCypher
         result = nil
 
         begin
-          Async do
-            result = case database_type
-                     when :neo4j
-                       perform_neo4j_health_check
-                     when :memgraph
-                       perform_memgraph_health_check
-                     else
-                       perform_generic_health_check
-                     end
-          end.wait
+          result = Sync do
+            case database_type
+            when :neo4j
+              perform_neo4j_health_check
+            when :memgraph
+              perform_memgraph_health_check
+            else
+              perform_generic_health_check
+            end
+          end
 
           result
         rescue ConnectionError, ProtocolError => e

data/lib/active_cypher/bolt/driver.rb

@@ -40,33 +40,9 @@ module ActiveCypher
       #
       # @yieldparam session [Bolt::Session] The session to use
       # @return [Object] The result of the block
-      def with_session(**kw)
-        if Async::Task.current?
-          # We're already in an Async context, use the pool directly
-          @pool.acquire do |conn|
-            # Check if connection is viable before using it
-            unless conn.viable?
-              # Create a fresh connection, because hope springs eternal
-              conn.close
-              conn = build_connection
-            end
-
-            yield Bolt::Session.new(conn, **kw)
-          end
-        else
-          # We're not in an Async context, create one and wait
-          Async do
-            @pool.acquire do |conn|
-              # Check if connection is viable before using it
-              unless conn.viable?
-                # Create a fresh connection, because why not
-                conn.close
-                conn = build_connection
-              end
-
-              yield Bolt::Session.new(conn, **kw)
-            end
-          end.wait
+      def with_session(**kw, &block)
+        Sync do
+          _acquire_session(**kw, &block)
         end
       rescue Async::TimeoutError => e
         raise ActiveCypher::ConnectionError, "Connection pool timeout: #{e.message}"
@@ -74,6 +50,19 @@ module ActiveCypher
         raise ActiveCypher::ConnectionError, "Connection error: #{e.message}"
       end
 
+      # Asynchronously yields a Session. Each call acquires its own connection from the pool,
+      # making it safe for concurrent use across fibers.
+      #
+      # @yieldparam session [Bolt::Session] The session to use
+      # @return [Async::Task] A task that resolves to the block's result
+      def async_with_session(**kw, &block)
+        raise 'Cannot run async_with_session outside of an Async task' unless Async::Task.current?
+
+        Async do
+          _acquire_session(**kw, &block)
+        end
+      end
+
       # Checks if the database is alive, or just faking it for your benefit.
       #
       # @return [Boolean]
@@ -92,6 +81,25 @@ module ActiveCypher
 
       private
 
+      # Internal: acquires a connection and yields a session.
+      # @yieldparam session [Bolt::Session]
+      # @return [Object] The result of the block
+      def _acquire_session(**kw)
+        @pool.acquire do |conn|
+          conn.mark_used!
+          session = Bolt::Session.new(conn, **kw)
+
+          begin
+            yield session
+          ensure
+            # Make sure any open transaction is cleaned up before returning the
+            # connection to the pool, so the next borrower doesn't inherit
+            # IN_TRANSACTION state.
+            session&.close
+          end
+        end
+      end
+
       # Builds a new connection, because the old one just wasn't good enough.
       #
       # @return [Connection]

data/lib/active_cypher/bolt/session.rb

@@ -121,15 +121,8 @@ module ActiveCypher
       # @yield [tx] The transaction to use for queries.
       # @return The result of the block.
       def run_transaction(mode = :write, db: nil, timeout: nil, metadata: nil, &)
-        if Async::Task.current?
-          # Already in an async context, just run the block.
-          # The block will run asynchronously within the current task.
+        Sync do
           _execute_transaction_block(mode, db, timeout, metadata, &)
-        else
-          # Not in an async context, so we need to create one and wait for it to complete.
-          Async do
-            _execute_transaction_block(mode, db, timeout, metadata, &)
-          end.wait
         end
       end
 

data/lib/active_cypher/connection_adapters/abstract_bolt_adapter.rb

@@ -11,11 +11,12 @@ module ActiveCypher
     class AbstractBoltAdapter < AbstractAdapter
       include Instrumentation
 
-      attr_reader :connection
+      attr_reader :connection, :driver
 
       # Returns the raw Bolt connection object
       # This is useful for accessing low-level connection methods like
-      # read_transaction, write_transaction, async_read_transaction, etc.
+      # read_transaction, write_transaction, etc.
+      # NOTE: For concurrent async operations, use with_session or async_with_session instead.
       def raw_connection
         @connection
       end
@@ -54,6 +55,18 @@ module ActiveCypher
                          }
                        end
 
+          # Create the driver with connection pool for concurrent operations
+          @driver = Bolt::Driver.new(
+            uri: "bolt://#{host}:#{port}",
+            adapter: self,
+            auth_token: auth,
+            pool_size: config.fetch(:pool_size, 10),
+            secure: ssl_params[:secure],
+            verify_cert: ssl_params[:verify_cert]
+          )
+
+          # Also create a single connection for backwards compatibility
+          # This connection is used for simple synchronous operations
           @connection = Bolt::Connection.new(
             host, port, self,
             auth_token: auth,
@@ -72,12 +85,34 @@ module ActiveCypher
       # Clean disconnection. Resets the internal state.
       def disconnect
         instrument_connection(:disconnect) do
-          @connection.close if @connection
+          @driver&.close
+          @driver = nil
+          @connection&.close
           @connection = nil
           true
         end
       end
 
+      # Yields a Session from the connection pool. Safe for concurrent use.
+      # Each call acquires its own connection from the pool.
+      #
+      # @yieldparam session [Bolt::Session] The session to use
+      # @return [Object] The result of the block
+      def with_session(**kw, &block)
+        connect
+        @driver.with_session(**kw, &block)
+      end
+
+      # Asynchronously yields a Session from the connection pool.
+      # Each call acquires its own connection, making it safe for concurrent fibers.
+      #
+      # @yieldparam session [Bolt::Session] The session to use
+      # @return [Async::Task] A task that resolves to the block's result
+      def async_with_session(**kw, &block)
+        connect
+        @driver.async_with_session(**kw, &block)
+      end
+
       # Runs a Cypher query via Bolt session.
       # Automatically handles connect, logs query, cleans up session. Very adult.
       def run(cypher, params = {}, context: 'Query', db: nil, access_mode: :write)
@@ -98,6 +133,16 @@ module ActiveCypher
         mode.to_s # Default implementation
       end
 
+      # Ensure schema migration constraint exists for tracking migrations.
+      # Override in subclasses for database-specific syntax.
+      def ensure_schema_migration_constraint
+        execute_cypher(<<~CYPHER, {}, 'SchemaMigration')
+          CREATE CONSTRAINT graph_schema_migration IF NOT EXISTS
+          FOR (m:SchemaMigration)
+          REQUIRE m.version IS UNIQUE
+        CYPHER
+      end
+
       # Prepare transaction metadata with database-specific attributes
       def prepare_tx_metadata(metadata, _db, _access_mode)
         metadata # Default implementation
@@ -118,35 +163,37 @@ module ActiveCypher
         return false unless active?
 
         instrument_connection(:reset, config) do
-          # Wrap in async to handle the connection reset properly
+          # Use Sync for efficient synchronous execution within async context
           result = nil
           error = nil
 
-          Async do
-            begin
-              # Try to execute a simple query first
-              session = Bolt::Session.new(@connection)
-              session.run('RETURN 1 AS check', {})
-              session.close
-              result = true
-            rescue StandardError => e
-              # Query failed, need to reset the connection
-              logger.debug { "Connection needs reset: #{e.message}" }
-
-              # Send RESET message directly
+          begin
+            result = Sync do
               begin
-                @connection.write_message(Bolt::Messaging::Reset.new)
-                response = @connection.read_message
-                result = response.is_a?(Bolt::Messaging::Success)
-                logger.debug { "Reset response: #{response.class}" }
-              rescue StandardError => reset_error
-                logger.error { "Reset failed: #{reset_error.message}" }
-                result = false
+                # Try to execute a simple query first
+                session = Bolt::Session.new(@connection)
+                session.run('RETURN 1 AS check', {})
+                session.close
+                true
+              rescue StandardError => e
+                # Query failed, need to reset the connection
+                logger.debug { "Connection needs reset: #{e.message}" }
+
+                # Send RESET message directly
+                begin
+                  @connection.write_message(Bolt::Messaging::Reset.new)
+                  response = @connection.read_message
+                  logger.debug { "Reset response: #{response.class}" }
+                  response.is_a?(Bolt::Messaging::Success)
+                rescue StandardError => reset_error
+                  logger.error { "Reset failed: #{reset_error.message}" }
+                  false
+                end
               end
             end
           rescue StandardError => e
             error = e
-          end.wait
+          end
 
           raise error if error
 

data/lib/active_cypher/connection_adapters/memgraph_adapter.rb

@@ -63,6 +63,43 @@ module ActiveCypher
         self.class
       end
 
+      # Memgraph uses different constraint syntax than Neo4j
+      def ensure_schema_migration_constraint
+        execute_ddl(<<~CYPHER)
+          CREATE CONSTRAINT ON (m:SchemaMigration) ASSERT m.version IS UNIQUE
+        CYPHER
+      rescue ActiveCypher::QueryError => e
+        # Ignore if constraint already exists
+        raise unless e.message.include?('already exists')
+      end
+
+      # Execute DDL statements (constraints, indexes) without explicit transaction
+      # Memgraph requires auto-commit for schema manipulation
+      def execute_ddl(cypher, params = {})
+        connect
+        logger.debug { "[DDL] #{cypher}" }
+
+        Sync do
+          # Send RUN directly without BEGIN/COMMIT wrapper
+          connection.write_message(Bolt::Messaging::Run.new(cypher, params, {}))
+          connection.write_message(Bolt::Messaging::Pull.new({ n: -1 }))
+
+          # Read responses
+          run_response = connection.read_message
+          unless run_response.is_a?(Bolt::Messaging::Success)
+            # Read any remaining messages to clear connection state
+            connection.read_message rescue nil
+            # Send RESET to clear connection state
+            connection.write_message(Bolt::Messaging::Reset.new)
+            connection.read_message rescue nil
+            raise QueryError, "DDL failed for: #{cypher.inspect}\nError: #{run_response.fields.first}"
+          end
+
+          pull_response = connection.read_message
+          pull_response
+        end
+      end
+
       # Override run to execute queries without explicit transactions
       # Memgraph auto‑commits each query, so we send RUN + PULL directly
       def run(cypher, params = {}, context: 'Query', db: nil, access_mode: :write)

data/lib/active_cypher/migration.rb

@@ -29,34 +29,76 @@ module ActiveCypher
     # DSL ---------------------------------------------------------------
 
     def create_node_index(label, *props, unique: false, if_not_exists: true, name: nil)
-      props_clause = props.map { |p| "n.#{p}" }.join(', ')
-      cypher = +'CREATE '
-      cypher << 'UNIQUE ' if unique
-      cypher << 'INDEX'
-      cypher << " #{name}" if name
-      cypher << ' IF NOT EXISTS' if if_not_exists
-      cypher << " FOR (n:#{label}) ON (#{props_clause})"
-      operations << cypher
+      cypher = if connection.vendor == :memgraph
+                 # Memgraph syntax: CREATE INDEX ON :Label(prop)
+                 props.map { |p| "CREATE INDEX ON :#{label}(#{p})" }
+               else
+                 # Neo4j syntax
+                 props_clause = props.map { |p| "n.#{p}" }.join(', ')
+                 c = +'CREATE '
+                 c << 'UNIQUE ' if unique
+                 c << 'INDEX'
+                 c << " #{name}" if name
+                 c << ' IF NOT EXISTS' if if_not_exists
+                 c << " FOR (n:#{label}) ON (#{props_clause})"
+                 [c]
+               end
+      operations.concat(Array(cypher))
     end
 
     def create_rel_index(rel_type, *props, if_not_exists: true, name: nil)
-      props_clause = props.map { |p| "r.#{p}" }.join(', ')
-      cypher = +'CREATE INDEX'
-      cypher << " #{name}" if name
-      cypher << ' IF NOT EXISTS' if if_not_exists
-      cypher << " FOR ()-[r:#{rel_type}]-() ON (#{props_clause})"
-      operations << cypher
+      cypher = if connection.vendor == :memgraph
+                 # Memgraph syntax: CREATE EDGE INDEX ON :REL_TYPE(prop)
+                 props.map { |p| "CREATE EDGE INDEX ON :#{rel_type}(#{p})" }
+               else
+                 # Neo4j syntax
+                 props_clause = props.map { |p| "r.#{p}" }.join(', ')
+                 c = +'CREATE INDEX'
+                 c << " #{name}" if name
+                 c << ' IF NOT EXISTS' if if_not_exists
+                 c << " FOR ()-[r:#{rel_type}]-() ON (#{props_clause})"
+                 [c]
+               end
+      operations.concat(Array(cypher))
     end
 
     def create_uniqueness_constraint(label, *props, if_not_exists: true, name: nil)
-      props_clause = props.map { |p| "n.#{p}" }.join(', ')
-      cypher = +'CREATE CONSTRAINT'
-      cypher << " #{name}" if name
-      cypher << ' IF NOT EXISTS' if if_not_exists
-      cypher << " FOR (n:#{label}) REQUIRE (#{props_clause}) IS UNIQUE"
+      cypher = if connection.vendor == :memgraph
+                 # Memgraph syntax: CREATE CONSTRAINT ON (n:Label) ASSERT n.prop IS UNIQUE
+                 # Note: Memgraph doesn't support IF NOT EXISTS or named constraints
+                 props_clause = props.map { |p| "n.#{p}" }.join(', ')
+                 "CREATE CONSTRAINT ON (n:#{label}) ASSERT #{props_clause} IS UNIQUE"
+               else
+                 # Neo4j syntax
+                 props_clause = props.map { |p| "n.#{p}" }.join(', ')
+                 c = +'CREATE CONSTRAINT'
+                 c << " #{name}" if name
+                 c << ' IF NOT EXISTS' if if_not_exists
+                 c << " FOR (n:#{label}) REQUIRE (#{props_clause}) IS UNIQUE"
+                 c
+               end
       operations << cypher
     end
 
+    def create_fulltext_index(name, label, *props, if_not_exists: true)
+      cypher = if connection.vendor == :memgraph
+                 # Memgraph TEXT INDEX syntax (requires --experimental-enabled='text-search')
+                 # Memgraph only supports single property per text index, so create one per prop
+                 props.map.with_index do |p, i|
+                   index_name = props.size > 1 ? "#{name}_#{p}" : name.to_s
+                   "CREATE TEXT INDEX #{index_name} ON :#{label}(#{p})"
+                 end
+               else
+                 # Neo4j syntax
+                 props_clause = props.map { |p| "n.#{p}" }.join(', ')
+                 c = +"CREATE FULLTEXT INDEX #{name}"
+                 c << ' IF NOT EXISTS' if if_not_exists
+                 c << " FOR (n:#{label}) ON EACH [#{props_clause}]"
+                 [c]
+               end
+      operations.concat(Array(cypher))
+    end
+
     def execute(cypher_string)
       operations << cypher_string.strip
     end
@@ -64,17 +106,15 @@ module ActiveCypher
     private
 
     def execute_operations
-      tx = connection.begin_transaction if connection.respond_to?(:begin_transaction)
-      operations.each do |cypher|
-        if tx
-          tx.run(cypher)
-        else
-          connection.execute_cypher(cypher)
-        end
+      if connection.vendor == :memgraph
+        # Memgraph requires auto-commit for DDL operations
+        operations.each { |cypher| connection.execute_ddl(cypher) }
+      else
+        # Run each DDL individually (implicit auto-commit) to avoid session/async issues
+        operations.each { |cypher| connection.execute_cypher(cypher) }
       end
-      connection.commit_transaction(tx) if tx
     rescue StandardError
-      connection.rollback_transaction(tx) if tx
+      # Memgraph DDL is auto-committed, no rollback possible
       raise
     end
   end

data/lib/active_cypher/migrator.rb

@@ -56,9 +56,17 @@ module ActiveCypher
     end
 
     def migration_files
-      migration_dirs.flat_map do |dir|
-        Dir[File.expand_path(File.join(dir, '*.rb'), Dir.pwd)]
-      end.sort
+      roots = [Pathname.new(Dir.pwd)]
+      if defined?(Rails) && Rails.respond_to?(:root)
+        rails_root = Rails.root
+        roots << rails_root unless rails_root.to_s == Dir.pwd
+      end
+
+      files = migration_dirs.flat_map do |dir|
+        roots.flat_map { |r| Dir[r.join(dir, '*.rb')] }
+      end
+
+      files.sort_by { |path| File.basename(path)[0, 14] }
     end
 
     def existing_versions
@@ -67,11 +75,7 @@ module ActiveCypher
     end
 
     def ensure_schema_migration_constraint
-      @connection.execute_cypher(<<~CYPHER)
-        CREATE CONSTRAINT graph_schema_migration IF NOT EXISTS
-        FOR (m:SchemaMigration)
-        REQUIRE m.version IS UNIQUE
-      CYPHER
+      @connection.ensure_schema_migration_constraint
     end
   end
 end

data/lib/active_cypher/model/connection_handling.rb

@@ -26,35 +26,55 @@ module ActiveCypher
           # If you're lazy and don't specify :reading, it defaults to :writing. You're welcome.
           symbolized_mapping[:reading] ||= symbolized_mapping[:writing]
 
+          processed_specs = {}
+
           symbolized_mapping.each do |role, db_key|
-            # db_key can be a symbol (config name) or a nested hash. We’re not judging.
-            spec_name = db_key.is_a?(Hash) ? db_key.values.first : db_key
+            spec_names_for(db_key).each do |spec_name|
+              spec_key = spec_name.respond_to?(:to_sym) ? spec_name.to_sym : spec_name
 
-            spec = ActiveCypher::CypherConfig.for(spec_name) # Boom. Pulls your DB config.
-            config_for_adapter = spec.dup
+              next if processed_specs.key?(spec_key)
 
-            # If the spec has a URL, parse it and let it override the boring YAML values.
-            if spec[:url]
-              resolver = ActiveCypher::ConnectionUrlResolver.new(spec[:url])
-              url_config = resolver.to_hash
-              raise ArgumentError, "Invalid connection URL: #{spec[:url]}" unless url_config
+              processed_specs[spec_key] = true
 
-              config_for_adapter = url_config.merge(spec.except(*url_config.keys))
-            end
+              # Reuse existing pools rather than instantiating duplicates
+              next if connection_handler.pool(spec_key)
+
+              begin
+                spec = ActiveCypher::CypherConfig.for(spec_key) # Boom. Pulls your DB config.
+              rescue KeyError => e
+                raise ActiveCypher::UnknownConnectionError,
+                      "connects_to role `#{role}`: database configuration key `#{spec_name.inspect}` not found in cypher_databases.yml – #{e.message}"
+              end
+
+              config_for_adapter = spec.dup
+
+              # If the spec has a URL, parse it and let it override the boring YAML values.
+              if spec[:url]
+                resolver = ActiveCypher::ConnectionUrlResolver.new(spec[:url])
+                url_config = resolver.to_hash
+                raise ArgumentError, "Invalid connection URL: #{spec[:url]}" unless url_config
 
-            # Create a unique connection pool for this role/config combo.
-            pool = ActiveCypher::ConnectionPool.new(config_for_adapter)
+                config_for_adapter = url_config.merge(spec.except(*url_config.keys))
+              end
 
-            # Register the pool under this spec name.
-            connection_handler.set(spec_name, pool)
-          rescue KeyError => e
-            raise ActiveCypher::UnknownConnectionError,
-                  "connects_to role `#{role}`: database configuration key `#{spec_name.inspect}` not found in cypher_databases.yml – #{e.message}"
+              # Create a unique connection pool for this role/config combo.
+              pool = ActiveCypher::ConnectionPool.new(config_for_adapter)
+
+              # Register the pool under this spec name.
+              connection_handler.set(spec_key, pool)
+            end
           end
 
           # Save the mapping for later — introspection, debugging, blaming, etc.
           self.connects_to_mappings = symbolized_mapping
         end
+
+        private
+
+        def spec_names_for(db_key)
+          values = db_key.is_a?(Hash) ? db_key.values : db_key
+          Array(values).flatten.compact
+        end
       end
     end
   end

data/lib/active_cypher/model/connection_owner.rb

@@ -9,6 +9,42 @@ module ActiveCypher
       include ActiveCypher::Logging
       include ActiveCypher::Model::ConnectionHandling
 
+      def self.db_key_for(mapping, role)
+        return nil unless mapping.is_a?(Hash)
+
+        value = mapping[role]
+        value = mapping[:writing] if value.nil?
+
+        resolve_db_value(value, mapping[:writing])
+      end
+
+      def self.resolve_db_value(value, fallback, visited = nil)
+        visited ||= []
+        return nil if value.nil? && fallback.nil?
+
+        case value
+        when Hash
+          hash_id = value.object_id
+          return nil if visited.include?(hash_id)
+
+          visited += [hash_id]
+
+          shard = ActiveCypher::RuntimeRegistry.current_shard || :default
+          shard_value = value[shard] || value[:default] || value.values.first
+          resolve_db_value(shard_value, fallback, visited)
+        else
+          return value if value
+          return nil unless fallback
+
+          fallback_id = fallback.object_id
+          return nil if visited.include?(fallback_id)
+
+          visited += [fallback_id]
+          resolve_db_value(fallback, nil, visited)
+        end
+      end
+      private_class_method :resolve_db_value
+
       class_methods do
         # One handler for all subclasses that include this concern
         def connection_handler
@@ -30,12 +66,13 @@ module ActiveCypher
         # Always dynamically fetch the connection for the current db_key
         def connection
           handler = connection_handler
+          mapping = connects_to_mappings if respond_to?(:connects_to_mappings)
+          role = ActiveCypher::RuntimeRegistry.current_role || :writing
+          db_key = ConnectionOwner.db_key_for(mapping, role)
+          db_key = db_key.to_sym if db_key.respond_to?(:to_sym)
 
-          if respond_to?(:connects_to_mappings) && connects_to_mappings.is_a?(Hash)
-            db_key = connects_to_mappings[:writing] # Default to :writing mapping
-            if db_key && (pool = handler.pool(db_key))
-              return pool.connection
-            end
+          if db_key && (pool = handler.pool(db_key))
+            return pool.connection
           end
 
           return superclass.connection if superclass.respond_to?(:connection)
@@ -43,6 +80,29 @@ module ActiveCypher
           raise ActiveCypher::ConnectionNotEstablished,
                 "No connection pool found for #{name}, db_key=#{db_key.inspect}"
         end
+
+        # Switch the current role/shard for the duration of the block.
+        # Mirrors ActiveRecord::Base.connected_to semantics on a smaller scale.
+        def connected_to(role: nil, shard: nil)
+          raise ArgumentError, 'connected_to requires a block' unless block_given?
+
+          previous_role = ActiveCypher::RuntimeRegistry.current_role
+          previous_shard = ActiveCypher::RuntimeRegistry.current_shard
+
+          selected_role = role.nil? ? previous_role : role
+          selected_role ||= :writing
+
+          selected_shard = shard.nil? ? previous_shard : shard
+          selected_shard ||= :default
+
+          ActiveCypher::RuntimeRegistry.current_role = selected_role.to_sym
+          ActiveCypher::RuntimeRegistry.current_shard = selected_shard.to_sym
+
+          yield
+        ensure
+          ActiveCypher::RuntimeRegistry.current_role = previous_role
+          ActiveCypher::RuntimeRegistry.current_shard = previous_shard
+        end
       end
 
       # Instance method to access the adapter class

data/lib/active_cypher/relationship.rb

@@ -59,20 +59,30 @@ module ActiveCypher
     # --------------------------------------------------------------
     # Connection fallback
     # --------------------------------------------------------------
-    # Relationship classes usually share the same Bolt pool as the
-    # node they originate from; delegate there unless the relationship
-    # class was given its own pool explicitly.
-    #
-    #   WorksAtRelationship.connection  # -> PersonNode.connection
-    #
-    def self.connection
-      # If a node_base_class is set (directly or by convention), always delegate to its connection
+      # Relationship classes usually share the same Bolt pool as the
+      # node they originate from; delegate there unless the relationship
+      # class was given its own pool explicitly.
+      #
+      #   WorksAtRelationship.connection  # -> PersonNode.connection
+      #
+      def self.connection
+        # If this is a concrete relationship class with from_class defined,
+        # prefer delegating to that node's connection (so role/shard routing is respected).
+        if !abstract_class? && (fc = from_class_name)
+          klass = fc.constantize
+          role  = ActiveCypher::RuntimeRegistry.current_role
+          shard = ActiveCypher::RuntimeRegistry.current_shard
+
+          return klass.connected_to(role: role, shard: shard) do
+            klass.connection
+          end
+        end
+
+        # Otherwise, fall back to node_base_class if present (even if abstract)
       if (klass = node_base_class)
         return klass.connection
       end
 
-      return @connection if defined?(@connection) && @connection
-
       from_class.constantize.connection
     end
 

data/lib/active_cypher/runtime_registry.rb

@@ -1,8 +1,53 @@
 # frozen_string_literal: true
 
+# Fiber-aware storage for role/shard context.
+# Async schedules many fibers on a single thread, so classic
+# thread locals leak across concurrent tasks. We key values by
+# Fiber object id to isolate per-task state.
+require 'async/task'
 module ActiveCypher
   module RuntimeRegistry
-    thread_mattr_accessor :current_role, default: :writing
-    thread_mattr_accessor :current_shard, default: :default
+    ROLE_KEY  = :active_cypher_role
+    SHARD_KEY = :active_cypher_shard
+
+    module_function
+
+    def current_role
+      get(ROLE_KEY) || thread_store[ROLE_KEY] || :writing
+    end
+
+    def current_role=(value)
+      set(ROLE_KEY, value)
+      thread_store[ROLE_KEY] = value
+    end
+
+    def current_shard
+      get(SHARD_KEY) || thread_store[SHARD_KEY] || :default
+    end
+
+    def current_shard=(value)
+      set(SHARD_KEY, value)
+      thread_store[SHARD_KEY] = value
+    end
+
+    # ── storage helpers ────────────────────────────────────────────
+
+    def set(key, value)
+      store = fiber_store
+      store[key] = value
+    end
+
+    def get(key)
+      fiber_store[key]
+    end
+
+    def fiber_store
+      registry = thread_store[:active_cypher_fiber_store] ||= {}
+      registry[Fiber.current.object_id] ||= {}
+    end
+
+    def thread_store
+      Thread.current[:active_cypher_thread_store] ||= {}
+    end
   end
 end

data/lib/active_cypher/version.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module ActiveCypher
-  VERSION = '0.11.2'
+  VERSION = '0.12.2'
 
   def self.gem_version
     Gem::Version.new VERSION

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: activecypher
 version: !ruby/object:Gem::Version
-  version: 0.11.2
+  version: 0.12.2
 platform: ruby
 authors:
 - Abdelkader Boudih
@@ -27,30 +27,30 @@ dependencies:
   name: async
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
-        version: '2.21'
+        version: 2.34.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
-        version: '2.21'
+        version: 2.34.0
 - !ruby/object:Gem::Dependency
   name: async-pool
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '0'
+        version: 0.11.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '0'
+        version: 0.11.0
 - !ruby/object:Gem::Dependency
   name: io-endpoint
   requirement: !ruby/object:Gem::Requirement
@@ -93,6 +93,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '0.6'
+- !ruby/object:Gem::Dependency
+  name: async-safe
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 description: OpenCypher Adapter ala ActiveRecord
 email:
 - seuros@pre-history.com
@@ -241,7 +255,6 @@ files:
 - lib/cyrel/types/symbol_type.rb
 - lib/tasks/graphdb_migrate.rake
 - lib/tasks/graphdb_schema.rake
-- sig/activecypher.rbs
 homepage: https://github.com/seuros/activecypher
 licenses:
 - MIT

data/sig/activecypher.rbs

@@ -1,4 +0,0 @@
-module Activecypher
-  VERSION: String
-  # See the writing guide of rbs: https://github.com/ruby/rbs#guides
-end