Module: ActiveRecord::ConnectionHandling
- Included in:
- Base
- Defined in:
- activerecord/lib/active_record/connection_adapters/mysql2_adapter.rb,
activerecord/lib/active_record/connection_handling.rb,
activerecord/lib/active_record/connection_adapters/sqlite3_adapter.rb,
activerecord/lib/active_record/connection_adapters/postgresql_adapter.rb
Overview
:nodoc:
Constant Summary collapse
- RAILS_ENV =
-> { (Rails.env if defined?(Rails.env)) || ENV["RAILS_ENV"].presence || ENV["RACK_ENV"].presence }
- DEFAULT_ENV =
-> { RAILS_ENV.call || "default_env" }
Instance Attribute Summary collapse
-
#connection_specification_name ⇒ Object
Return the connection specification name from the current class or its parent.
Instance Method Summary collapse
-
#clear_cache! ⇒ Object
:nodoc:.
-
#clear_query_caches_for_current_thread ⇒ Object
Clears the query cache for all connections associated with the current thread.
-
#connected? ⇒ Boolean
Returns
true
if Active Record is connected. -
#connected_to(role: nil, shard: nil, prevent_writes: false, &blk) ⇒ Object
Connects to a role (e.g. writing, reading, or a custom role) and/or shard for the duration of the block.
-
#connected_to?(role:, shard: ActiveRecord::Base.default_shard) ⇒ Boolean
Returns true if role is the current connected role.
-
#connected_to_many(*classes, role:, shard: nil, prevent_writes: false) ⇒ Object
Connects a role and/or shard to the provided connection names.
-
#connecting_to(role: default_role, shard: default_shard, prevent_writes: false) ⇒ Object
Use a specified connection.
-
#connection ⇒ Object
Returns the connection currently associated with the class.
-
#connection_db_config ⇒ Object
Returns the db_config object from the associated connection:.
- #connection_pool ⇒ Object
-
#connects_to(database: {}, shards: {}) ⇒ Object
Connects a model to the databases specified.
-
#establish_connection(config_or_env = nil) ⇒ Object
Establishes the connection to the database.
-
#lookup_connection_handler(handler_key) ⇒ Object
:nodoc:.
-
#mysql2_connection(config) ⇒ Object
Establishes a connection to the database that's used by all Active Record objects.
-
#postgresql_connection(config) ⇒ Object
Establishes a connection to the database that's used by all Active Record objects.
-
#primary_class? ⇒ Boolean
:nodoc:.
-
#prohibit_shard_swapping(enabled = true) ⇒ Object
Prohibit swapping shards while inside of the passed block.
- #remove_connection(name = nil) ⇒ Object
- #retrieve_connection ⇒ Object
-
#shard_swapping_prohibited? ⇒ Boolean
Determine whether or not shard swapping is currently prohibited.
- #sqlite3_connection(config) ⇒ Object
-
#while_preventing_writes(enabled = true, &block) ⇒ Object
Prevent writing to the database regardless of role.
Instance Attribute Details
#connection_specification_name ⇒ Object
Return the connection specification name from the current class or its parent.
257 258 259 260 261 262 |
# File 'activerecord/lib/active_record/connection_handling.rb', line 257 def connection_specification_name if !defined?(@connection_specification_name) || @connection_specification_name.nil? return self == Base ? Base.name : superclass.connection_specification_name end @connection_specification_name end |
Instance Method Details
#clear_cache! ⇒ Object
:nodoc:
304 305 306 |
# File 'activerecord/lib/active_record/connection_handling.rb', line 304 def clear_cache! # :nodoc: connection.schema_cache.clear! end |
#clear_query_caches_for_current_thread ⇒ Object
Clears the query cache for all connections associated with the current thread.
243 244 245 |
# File 'activerecord/lib/active_record/connection_handling.rb', line 243 def clear_query_caches_for_current_thread clear_on_handler(ActiveRecord::Base.connection_handler) end |
#connected? ⇒ Boolean
Returns true
if Active Record is connected.
288 289 290 |
# File 'activerecord/lib/active_record/connection_handling.rb', line 288 def connected? connection_handler.connected?(connection_specification_name, role: current_role, shard: current_shard) end |
#connected_to(role: nil, shard: nil, prevent_writes: false, &blk) ⇒ Object
Connects to a role (e.g. 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
137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 |
# File 'activerecord/lib/active_record/connection_handling.rb', line 137 def connected_to(role: nil, shard: nil, prevent_writes: false, &blk) if self != Base && !abstract_class raise NotImplementedError, "calling `connected_to` is only allowed on ActiveRecord::Base or abstract classes." end if !connection_class? && !primary_class? raise NotImplementedError, "calling `connected_to` is only allowed on the abstract class that established the connection." 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?(role:, shard: ActiveRecord::Base.default_shard) ⇒ Boolean
Returns true if role is the current connected role.
ActiveRecord::Base.connected_to(role: :writing) do
ActiveRecord::Base.connected_to?(role: :writing) #=> true
ActiveRecord::Base.connected_to?(role: :reading) #=> false
end
234 235 236 |
# File 'activerecord/lib/active_record/connection_handling.rb', line 234 def connected_to?(role:, shard: ActiveRecord::Base.default_shard) current_role == role.to_sym && current_shard == shard.to_sym end |
#connected_to_many(*classes, role:, shard: nil, prevent_writes: false) ⇒ Object
Connects a role and/or shard to the provided connection names. Optionally prevent_writes
can be passed to block writes on a connection. reading
will automatically set prevent_writes
to true.
connected_to_many
is an alternative to deeply nested connected_to
blocks.
Usage:
ActiveRecord::Base.connected_to_many(AnimalsRecord, MealsRecord, role: :reading) do
Dog.first # Read from animals replica
Dinner.first # Read from meals replica
Person.first # Read from primary writer
end
166 167 168 169 170 171 172 173 174 175 176 177 178 179 |
# File 'activerecord/lib/active_record/connection_handling.rb', line 166 def connected_to_many(*classes, role:, shard: nil, prevent_writes: false) classes = classes.flatten if self != Base || classes.include?(Base) raise NotImplementedError, "connected_to_many can only be called on ActiveRecord::Base." end prevent_writes = true if role == ActiveRecord.reading_role append_to_connected_to_stack(role: role, shard: shard, prevent_writes: prevent_writes, klasses: classes) yield ensure connected_to_stack.pop end |
#connecting_to(role: default_role, shard: default_shard, prevent_writes: false) ⇒ Object
Use a specified connection.
This method is useful for ensuring that a specific connection is being used. For example, when booting a console in readonly mode.
It is not recommended to use this method in a request since it does not yield to a block like connected_to
.
188 189 190 191 192 |
# File 'activerecord/lib/active_record/connection_handling.rb', line 188 def connecting_to(role: default_role, shard: default_shard, prevent_writes: false) prevent_writes = true if role == ActiveRecord.reading_role append_to_connected_to_stack(role: role, shard: shard, prevent_writes: prevent_writes, klasses: [self]) end |
#connection ⇒ Object
Returns the connection currently associated with the class. This can also be used to “borrow” the connection to do database work unrelated to any of the specific Active Records.
250 251 252 |
# File 'activerecord/lib/active_record/connection_handling.rb', line 250 def connection retrieve_connection end |
#connection_db_config ⇒ Object
Returns the db_config object from the associated connection:
ActiveRecord::Base.connection_db_config
#<ActiveRecord::DatabaseConfigurations::HashConfig:0x00007fd1acbded10 @env_name="development",
@name="primary", @config={pool: 5, timeout: 5000, database: "db/development.sqlite3", adapter: "sqlite3"}>
Use only for reading.
275 276 277 |
# File 'activerecord/lib/active_record/connection_handling.rb', line 275 def connection_db_config connection_pool.db_config end |
#connection_pool ⇒ Object
279 280 281 |
# File 'activerecord/lib/active_record/connection_handling.rb', line 279 def connection_pool connection_handler.retrieve_connection_pool(connection_specification_name, role: current_role, shard: current_shard) || raise(ConnectionNotEstablished) end |
#connects_to(database: {}, shards: {}) ⇒ Object
Connects a model to the databases specified. The database
keyword takes a hash consisting of a role
and a database_key
.
This will create a connection handler for switching between connections, look up the config hash using the database_key
and finally establishes a connection to that config.
class AnimalsModel < ApplicationRecord
self.abstract_class = true
connects_to database: { writing: :primary, reading: :primary_replica }
end
connects_to
also supports horizontal sharding. The horizontal sharding API also supports read replicas. Connect a model to a list of shards like this:
class AnimalsModel < ApplicationRecord
self.abstract_class = true
connects_to shards: {
default: { writing: :primary, reading: :primary_replica },
shard_two: { writing: :primary_shard_two, reading: :primary_shard_replica_two }
}
end
Returns an array of database connections.
81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 |
# File 'activerecord/lib/active_record/connection_handling.rb', line 81 def connects_to(database: {}, shards: {}) raise NotImplementedError, "`connects_to` can only be called on ActiveRecord::Base or abstract classes" unless self == Base || abstract_class? if database.present? && shards.present? raise ArgumentError, "`connects_to` can only accept a `database` or `shards` argument, but not both arguments." end connections = [] database.each do |role, database_key| db_config, owner_name = resolve_config_for_connection(database_key) handler = lookup_connection_handler(role.to_sym) self.connection_class = true connections << handler.establish_connection(db_config, owner_name: owner_name, role: role) end shards.each do |shard, database_keys| database_keys.each do |role, database_key| db_config, owner_name = resolve_config_for_connection(database_key) handler = lookup_connection_handler(role.to_sym) self.connection_class = true connections << handler.establish_connection(db_config, owner_name: owner_name, role: role, shard: shard.to_sym) end end connections end |
#establish_connection(config_or_env = nil) ⇒ Object
Establishes the connection to the database. Accepts a hash as input where the :adapter
key must be specified with the name of a database adapter (in lower-case) example for regular databases (MySQL, PostgreSQL, etc):
ActiveRecord::Base.establish_connection(
adapter: "mysql2",
host: "localhost",
username: "myuser",
password: "mypass",
database: "somedatabase"
)
Example for SQLite database:
ActiveRecord::Base.establish_connection(
adapter: "sqlite3",
database: "path/to/dbfile"
)
Also accepts keys as strings (for parsing from YAML for example):
ActiveRecord::Base.establish_connection(
"adapter" => "sqlite3",
"database" => "path/to/dbfile"
)
Or a URL:
ActiveRecord::Base.establish_connection(
"postgres://myuser:[email protected]/somedatabase"
)
In case ActiveRecord::Base.configurations is set (Rails automatically loads the contents of config/database.yml into it), a symbol can also be given as argument, representing a key in the configuration hash:
ActiveRecord::Base.establish_connection(:production)
The exceptions AdapterNotSpecified, AdapterNotFound, and ArgumentError
may be returned on an error.
49 50 51 52 53 |
# File 'activerecord/lib/active_record/connection_handling.rb', line 49 def establish_connection(config_or_env = nil) config_or_env ||= DEFAULT_ENV.call.to_sym db_config, owner_name = resolve_config_for_connection(config_or_env) connection_handler.establish_connection(db_config, owner_name: owner_name, role: current_role, shard: current_shard) end |
#lookup_connection_handler(handler_key) ⇒ Object
:nodoc:
238 239 240 |
# File 'activerecord/lib/active_record/connection_handling.rb', line 238 def lookup_connection_handler(handler_key) # :nodoc: ActiveRecord::Base.connection_handler end |
#mysql2_connection(config) ⇒ Object
Establishes a connection to the database that's used by all Active Record objects.
12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 |
# File 'activerecord/lib/active_record/connection_adapters/mysql2_adapter.rb', line 12 def mysql2_connection(config) config = config.symbolize_keys config[:flags] ||= 0 if config[:flags].kind_of? Array config[:flags].push "FOUND_ROWS" else config[:flags] |= Mysql2::Client::FOUND_ROWS end ConnectionAdapters::Mysql2Adapter.new( ConnectionAdapters::Mysql2Adapter.new_client(config), logger, nil, config, ) end |
#postgresql_connection(config) ⇒ Object
Establishes a connection to the database that's used by all Active Record objects
25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 |
# File 'activerecord/lib/active_record/connection_adapters/postgresql_adapter.rb', line 25 def postgresql_connection(config) conn_params = config.symbolize_keys.compact # Map ActiveRecords param names to PGs. conn_params[:user] = conn_params.delete(:username) if conn_params[:username] conn_params[:dbname] = conn_params.delete(:database) if conn_params[:database] # Forward only valid config params to PG::Connection.connect. valid_conn_param_keys = PG::Connection.conndefaults_hash.keys + [:requiressl] conn_params.slice!(*valid_conn_param_keys) ConnectionAdapters::PostgreSQLAdapter.new( ConnectionAdapters::PostgreSQLAdapter.new_client(conn_params), logger, conn_params, config, ) end |
#primary_class? ⇒ Boolean
:nodoc:
264 265 266 |
# File 'activerecord/lib/active_record/connection_handling.rb', line 264 def primary_class? # :nodoc: self == Base || application_record_class? end |
#prohibit_shard_swapping(enabled = true) ⇒ Object
Prohibit swapping shards while inside of the passed block.
In some cases you may want to be able to swap shards but not allow a nested call to connected_to or connected_to_many to swap again. This is useful in cases you're using sharding to provide per-request database isolation.
200 201 202 203 204 205 206 |
# File 'activerecord/lib/active_record/connection_handling.rb', line 200 def prohibit_shard_swapping(enabled = true) prev_value = ActiveSupport::IsolatedExecutionState[:active_record_prohibit_shard_swapping] ActiveSupport::IsolatedExecutionState[:active_record_prohibit_shard_swapping] = enabled yield ensure ActiveSupport::IsolatedExecutionState[:active_record_prohibit_shard_swapping] = prev_value end |
#remove_connection(name = nil) ⇒ Object
292 293 294 295 296 297 298 299 300 301 302 |
# File 'activerecord/lib/active_record/connection_handling.rb', line 292 def remove_connection(name = nil) name ||= @connection_specification_name if defined?(@connection_specification_name) # if removing a connection that has a pool, we reset the # connection_specification_name so it will use the parent # pool. if connection_handler.retrieve_connection_pool(name, role: current_role, shard: current_shard) self.connection_specification_name = nil end connection_handler.remove_connection_pool(name, role: current_role, shard: current_shard) end |
#retrieve_connection ⇒ Object
283 284 285 |
# File 'activerecord/lib/active_record/connection_handling.rb', line 283 def retrieve_connection connection_handler.retrieve_connection(connection_specification_name, role: current_role, shard: current_shard) end |
#shard_swapping_prohibited? ⇒ Boolean
Determine whether or not shard swapping is currently prohibited
209 210 211 |
# File 'activerecord/lib/active_record/connection_handling.rb', line 209 def shard_swapping_prohibited? ActiveSupport::IsolatedExecutionState[:active_record_prohibit_shard_swapping] end |
#sqlite3_connection(config) ⇒ Object
18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 |
# File 'activerecord/lib/active_record/connection_adapters/sqlite3_adapter.rb', line 18 def sqlite3_connection(config) config = config.symbolize_keys # Require database. unless config[:database] raise ArgumentError, "No database file specified. Missing argument: database" end # Allow database path relative to Rails.root, but only if the database # path is not the special path that tells sqlite to build a database only # in memory. if ":memory:" != config[:database] && !config[:database].to_s.start_with?("file:") config[:database] = File.(config[:database], Rails.root) if defined?(Rails.root) dirname = File.dirname(config[:database]) Dir.mkdir(dirname) unless File.directory?(dirname) end db = SQLite3::Database.new( config[:database].to_s, config.merge(results_as_hash: true) ) ConnectionAdapters::SQLite3Adapter.new(db, logger, nil, config) rescue Errno::ENOENT => error if error..include?("No such file or directory") raise ActiveRecord::NoDatabaseError else raise end end |
#while_preventing_writes(enabled = true, &block) ⇒ Object
Prevent writing to the database regardless of role.
In some cases you may want to prevent writes to the database even if you are on a database that can write. while_preventing_writes
will prevent writes to the database for the duration of the block.
This method does not provide the same protection as a readonly user and is meant to be a safeguard against accidental writes.
See READ_QUERY
for the queries that are blocked by this method.
224 225 226 |
# File 'activerecord/lib/active_record/connection_handling.rb', line 224 def while_preventing_writes(enabled = true, &block) connected_to(role: current_role, prevent_writes: enabled, &block) end |