method

connected_to

v7.0.0 - Show latest stable - 0 notes - Class: ConnectionHandling

1.0.0
1.1.6
1.2.6
2.0.3
2.1.0
2.2.1
2.3.8
3.0.0
3.0.9
3.1.0
3.2.1
3.2.8
3.2.13
4.0.2
4.1.8
4.2.1
4.2.7
4.2.9
5.0.0.1
5.1.7
5.2.3
6.0.0 (0)
6.1.3.1 (-38)
6.1.7.7 (1)
7.0.0 (-10)
7.1.3.2 (0)
7.1.3.4 (0)
What's this?

connected_to(role: nil, shard: nil, prevent_writes: false, &blk) public

Connects to a role (ex writing, reading or a custom role) and/or shard for the duration of the block. At the end of the block the connection will be returned to the original role / shard.

If only a role is passed, Active Record will look up the connection based on the requested role. If a non-established role is requested an +ActiveRecord::ConnectionNotEstablished+ error will be raised:

ActiveRecord::Base.connected_to(role: :writing) do
  Dog.create! # creates dog using dog writing connection
end

ActiveRecord::Base.connected_to(role: :reading) do
  Dog.create! # throws exception because we're on a replica
end

When swapping to a shard, the role must be passed as well. If a non-existent shard is passed, an +ActiveRecord::ConnectionNotEstablished+ error will be raised.

When a shard and role is passed, Active Record will first lookup the role, and then look up the connection by shard key.

ActiveRecord::Base.connected_to(role: :reading, shard: :shard_one_replica) do
  Dog.first # finds first Dog record stored on the shard one replica
end

Show source

# File activerecord/lib/active_record/connection_handling.rb, line 137
    def connected_to(role: nil, shard: nil, prevent_writes: false, &blk)
      if ActiveRecord.legacy_connection_handling
        if self != Base
          raise NotImplementedError, "`connected_to` can only be called on ActiveRecord::Base with legacy connection handling."
        end
      else
        if self != Base && !abstract_class
          raise NotImplementedError, "calling `connected_to` is only allowed on ActiveRecord::Base or abstract classes."
        end

        if name != connection_specification_name && !primary_class?
          raise NotImplementedError, "calling `connected_to` is only allowed on the abstract class that established the connection."
        end
      end

      unless role || shard
        raise ArgumentError, "must provide a `shard` and/or `role`."
      end

      with_role_and_shard(role, shard, prevent_writes, &blk)
    end

connected_to

Related methods