Module: ActiveRecord::ConnectionHandling
- Included in:
- Base
- Defined in:
- lib/active_record/connection_adapters/mysql2_adapter.rb,
lib/active_record/connection_handling.rb,
lib/active_record/connection_adapters/sqlite3_adapter.rb,
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(database: nil, role: nil, shard: nil, prevent_writes: false, &blk) ⇒ Object
Connects to a role (ex 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_config ⇒ Object
Returns the configuration of the associated connection as a hash:.
-
#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:.
- #remove_connection(name = nil) ⇒ Object
- #retrieve_connection ⇒ Object
- #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.
289 290 291 292 293 294 |
# File 'lib/active_record/connection_handling.rb', line 289 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:
347 348 349 |
# File 'lib/active_record/connection_handling.rb', line 347 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.
269 270 271 272 273 274 275 276 277 |
# File 'lib/active_record/connection_handling.rb', line 269 def clear_query_caches_for_current_thread if ActiveRecord::Base.legacy_connection_handling ActiveRecord::Base.connection_handlers.each_value do |handler| clear_on_handler(handler) end else clear_on_handler(ActiveRecord::Base.connection_handler) end end |
#connected? ⇒ Boolean
Returns true
if Active Record is connected.
331 332 333 |
# File 'lib/active_record/connection_handling.rb', line 331 def connected? connection_handler.connected?(connection_specification_name, role: current_role, shard: current_shard) end |
#connected_to(database: nil, role: nil, shard: nil, prevent_writes: false, &blk) ⇒ Object
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
The database kwarg is deprecated and will be removed in 6.2.0 without replacement.
139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 |
# File 'lib/active_record/connection_handling.rb', line 139 def connected_to(database: nil, role: nil, shard: nil, prevent_writes: false, &blk) if 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 if database && (role || shard) raise ArgumentError, "`connected_to` cannot accept a `database` argument with any other arguments." elsif database ActiveSupport::Deprecation.warn("The database key in `connected_to` is deprecated. It will be removed in Rails 6.2.0 without replacement.") if database.is_a?(Hash) role, database = database.first role = role.to_sym end db_config, owner_name = resolve_config_for_connection(database) handler = lookup_connection_handler(role) handler.establish_connection(db_config, owner_name: owner_name, role: role) with_handler(role, &blk) elsif role || shard unless role raise ArgumentError, "`connected_to` cannot accept a `shard` argument without a `role`." end with_role_and_shard(role, shard, prevent_writes, &blk) else raise ArgumentError, "must provide a `shard` and/or `role`." end 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
255 256 257 |
# File 'lib/active_record/connection_handling.rb', line 255 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
194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 |
# File 'lib/active_record/connection_handling.rb', line 194 def connected_to_many(*classes, role:, shard: nil, prevent_writes: false) classes = classes.flatten if legacy_connection_handling raise NotImplementedError, "connected_to_many is not available with legacy connection handling" end if self != Base || classes.include?(Base) raise NotImplementedError, "connected_to_many can only be called on ActiveRecord::Base." end prevent_writes = true if role == reading_role 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
.
220 221 222 223 224 225 226 227 228 |
# File 'lib/active_record/connection_handling.rb', line 220 def connecting_to(role: default_role, shard: default_shard, prevent_writes: false) if legacy_connection_handling raise NotImplementedError, "`connecting_to` is not available with `legacy_connection_handling`." end prevent_writes = true if role == reading_role self.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.
282 283 284 |
# File 'lib/active_record/connection_handling.rb', line 282 def connection retrieve_connection end |
#connection_config ⇒ Object
Returns the configuration of the associated connection as a hash:
ActiveRecord::Base.connection_config
# => {pool: 5, timeout: 5000, database: "db/development.sqlite3", adapter: "sqlite3"}
Please use only for reading.
306 307 308 |
# File 'lib/active_record/connection_handling.rb', line 306 def connection_config connection_pool.db_config.configuration_hash 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.
318 319 320 |
# File 'lib/active_record/connection_handling.rb', line 318 def connection_db_config connection_pool.db_config end |
#connection_pool ⇒ Object
322 323 324 |
# File 'lib/active_record/connection_handling.rb', line 322 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 '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:mypass@localhost/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 '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:
259 260 261 262 263 264 265 266 |
# File 'lib/active_record/connection_handling.rb', line 259 def lookup_connection_handler(handler_key) # :nodoc: if ActiveRecord::Base.legacy_connection_handling handler_key ||= ActiveRecord::Base.writing_role connection_handlers[handler_key] ||= ActiveRecord::ConnectionAdapters::ConnectionHandler.new else ActiveRecord::Base.connection_handler end 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 '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 '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:
296 297 298 |
# File 'lib/active_record/connection_handling.rb', line 296 def primary_class? # :nodoc: self == Base || defined?(ApplicationRecord) && self == ApplicationRecord end |
#remove_connection(name = nil) ⇒ Object
335 336 337 338 339 340 341 342 343 344 345 |
# File 'lib/active_record/connection_handling.rb', line 335 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
326 327 328 |
# File 'lib/active_record/connection_handling.rb', line 326 def retrieve_connection connection_handler.retrieve_connection(connection_specification_name, role: current_role, shard: current_shard) 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 '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.
241 242 243 244 245 246 247 |
# File 'lib/active_record/connection_handling.rb', line 241 def while_preventing_writes(enabled = true, &block) if legacy_connection_handling connection_handler.while_preventing_writes(enabled, &block) else connected_to(role: current_role, prevent_writes: enabled, &block) end end |