Active Record – Object-relational mapping in Rails¶ ↑
Active Record connects classes to relational database tables to establish an almost zero-configuration persistence layer for applications. The library provides a base class that, when subclassed, sets up a mapping between the new class and an existing table in the database. In the context of an application, these classes are commonly referred to as models. Models can also be connected to other models; this is done by defining associations.
Active Record relies heavily on naming in that it uses class and association names to establish mappings between respective database tables and foreign key columns. Although these mappings can be defined explicitly, it’s recommended to follow naming conventions, especially when getting started with the library.
You can read more about Active Record in the Active Record Basics guide.
A short rundown of some of the major features:
-
Automated mapping between classes and tables, attributes and columns.
class Product < ActiveRecord::Base end
The Product class is automatically mapped to the table named “products”, which might look like this:
CREATE TABLE products ( id bigint NOT NULL auto_increment, name varchar(255), PRIMARY KEY (id) );
This would also define the following accessors:
Product#nameandProduct#name=(new_name). -
Associationsbetween objects defined by simple class methods.class Firm < ActiveRecord::Base has_many :clients has_one :account belongs_to :conglomerate end
-
Aggregationsof value objects.class Account < ActiveRecord::Base composed_of :balance, class_name: 'Money', mapping: %w(balance amount) composed_of :address, mapping: [%w(address_street street), %w(address_city city)] end
-
Validation rules that can differ for new or existing objects.
class Account < ActiveRecord::Base validates :subdomain, :name, :email_address, :password, presence: true validates :subdomain, uniqueness: true validates :terms_of_service, acceptance: true, on: :create validates :password, :email_address, confirmation: true, on: :create end
-
Callbacksavailable for the entire life cycle (instantiation, saving, destroying, validating, etc.).class Person < ActiveRecord::Base before_destroy :invalidate_payment_plan # the `invalidate_payment_plan` method gets called just before Person#destroy end
-
Inheritancehierarchies.class Company < ActiveRecord::Base; end class Firm < Company; end class Client < Company; end class PriorityClient < Client; end
-
# Database transaction Account.transaction do david.withdrawal(100) mary.deposit(100) end
-
Reflections on columns, associations, and aggregations.
reflection = Firm.reflect_on_association(:clients) reflection.klass # => Client (class) Firm.columns # Returns an array of column descriptors for the firms table
-
Database abstraction through simple adapters.
# connect to SQLite3 ActiveRecord::Base.establish_connection(adapter: 'sqlite3', database: 'dbfile.sqlite3') # connect to MySQL with authentication ActiveRecord::Base.establish_connection( adapter: 'mysql2', host: 'localhost', username: 'me', password: 'secret', database: 'activerecord' )
Learn more and read about the built-in support for MySQL, PostgreSQL, and SQLite3.
-
Logging support for Log4r and Logger.
ActiveRecord::Base.logger = ActiveSupport::Logger.new(STDOUT) ActiveRecord::Base.logger = Log4r::Logger.new('Application Log')
-
Database agnostic schema management with Migrations.
class AddSystemSettings < ActiveRecord::Migration[8.1] def up create_table :system_settings do |t| t.string :name t.string :label t.text :value t.string :type t.integer :position end SystemSetting.create name: 'notice', label: 'Use notice?', value: 1 end def down drop_table :system_settings end end
Philosophy¶ ↑
Active Record is an implementation of the object-relational mapping (ORM) pattern by the same name described by Martin Fowler:
“An object that wraps a row in a database table or view, encapsulates the database access, and adds domain logic on that data.”
Active Record attempts to provide a coherent wrapper as a solution for the inconvenience that is object-relational mapping. The prime directive for this mapping has been to minimize the amount of code needed to build a real-world domain model. This is made possible by relying on a number of conventions that make it easy for Active Record to infer complex relations and structures from a minimal amount of explicit direction.
Convention over Configuration:
-
No XML files!
-
Lots of reflection and run-time extension
-
Magic is not inherently a bad word
Admit the Database:
-
Lets you drop down to SQL for odd cases and performance
-
Doesn’t attempt to duplicate or replace data definitions
Download and installation¶ ↑
The latest version of Active Record can be installed with RubyGems:
$ gem install activerecord
Source code can be downloaded as part of the Rails project on GitHub:
License¶ ↑
Active Record is released under the MIT license:
Support¶ ↑
API documentation is at:
Bug reports for the Ruby on Rails project can be filed here:
Feature requests should be discussed on the rubyonrails-core forum here:
Validation error class to wrap association records’ errors, with index_errors support.
- MODULE ActiveRecord::Aggregations
- MODULE ActiveRecord::Assertions
- MODULE ActiveRecord::Associations
- MODULE ActiveRecord::AttributeAssignment
- MODULE ActiveRecord::AttributeMethods
- MODULE ActiveRecord::Attributes
- MODULE ActiveRecord::AutosaveAssociation
- MODULE ActiveRecord::Batches
- MODULE ActiveRecord::Calculations
- MODULE ActiveRecord::Callbacks
- MODULE ActiveRecord::Coders
- MODULE ActiveRecord::ConnectionAdapters
- MODULE ActiveRecord::ConnectionHandling
- MODULE ActiveRecord::Core
- MODULE ActiveRecord::CounterCache
- MODULE ActiveRecord::DelegatedType
- MODULE ActiveRecord::DynamicMatchers
- MODULE ActiveRecord::Encryption
- MODULE ActiveRecord::Enum
- MODULE ActiveRecord::Explain
- MODULE ActiveRecord::FinderMethods
- MODULE ActiveRecord::Inheritance
- MODULE ActiveRecord::Integration
- MODULE ActiveRecord::Locking
- MODULE ActiveRecord::Marshalling
- MODULE ActiveRecord::MessagePack
- MODULE ActiveRecord::Middleware
- MODULE ActiveRecord::ModelSchema
- MODULE ActiveRecord::NestedAttributes
- MODULE ActiveRecord::NoTouching
- MODULE ActiveRecord::Persistence
- MODULE ActiveRecord::QueryLogs
- MODULE ActiveRecord::QueryMethods
- MODULE ActiveRecord::Querying
- MODULE ActiveRecord::ReadonlyAttributes
- MODULE ActiveRecord::Reflection
- MODULE ActiveRecord::RuntimeRegistry
- MODULE ActiveRecord::Sanitization
- MODULE ActiveRecord::Scoping
- MODULE ActiveRecord::SecurePassword
- MODULE ActiveRecord::SecureToken
- MODULE ActiveRecord::Serialization
- MODULE ActiveRecord::SignedId
- MODULE ActiveRecord::SpawnMethods
- MODULE ActiveRecord::Store
- MODULE ActiveRecord::Suppressor
- MODULE ActiveRecord::Tasks
- MODULE ActiveRecord::TestFixtures
- MODULE ActiveRecord::Timestamp
- MODULE ActiveRecord::TokenFor
- MODULE ActiveRecord::Transactions
- MODULE ActiveRecord::Translation
- MODULE ActiveRecord::Type
- MODULE ActiveRecord::VERSION
- MODULE ActiveRecord::Validations
- CLASS ActiveRecord::ActiveRecordError
- CLASS ActiveRecord::AdapterError
- CLASS ActiveRecord::AdapterNotFound
- CLASS ActiveRecord::AdapterNotSpecified
- CLASS ActiveRecord::AdapterTimeout
- CLASS ActiveRecord::AssociationTypeMismatch
- CLASS ActiveRecord::AsynchronousQueryInsideTransactionError
- CLASS ActiveRecord::AttributeAssignmentError
- CLASS ActiveRecord::Base
- CLASS ActiveRecord::CheckViolation
- CLASS ActiveRecord::ConfigurationError
- CLASS ActiveRecord::ConnectionFailed
- CLASS ActiveRecord::ConnectionNotDefined
- CLASS ActiveRecord::ConnectionNotEstablished
- CLASS ActiveRecord::ConnectionTimeoutError
- CLASS ActiveRecord::DangerousAttributeError
- CLASS ActiveRecord::DatabaseAlreadyExists
- CLASS ActiveRecord::DatabaseConfigurations
- CLASS ActiveRecord::DatabaseConnectionError
- CLASS ActiveRecord::DatabaseVersionError
- CLASS ActiveRecord::Deadlocked
- CLASS ActiveRecord::DeprecatedAssociationError
- CLASS ActiveRecord::DestroyAssociationAsyncError
- CLASS ActiveRecord::DestroyAssociationAsyncJob
- CLASS ActiveRecord::EagerLoadPolymorphicError
- CLASS ActiveRecord::EnvironmentMismatchError
- CLASS ActiveRecord::ExclusionViolation
- CLASS ActiveRecord::ExclusiveConnectionTimeoutError
- CLASS ActiveRecord::ExplainRegistry
- CLASS ActiveRecord::FixtureSet
- CLASS ActiveRecord::FutureResult
- CLASS ActiveRecord::InvalidForeignKey
- CLASS ActiveRecord::IrreversibleMigration
- CLASS ActiveRecord::IrreversibleOrderError
- CLASS ActiveRecord::LockWaitTimeout
- CLASS ActiveRecord::Migration
- CLASS ActiveRecord::MigrationContext
- CLASS ActiveRecord::MismatchedForeignKey
- CLASS ActiveRecord::MissingRequiredOrderError
- CLASS ActiveRecord::MultiparameterAssignmentErrors
- CLASS ActiveRecord::NoDatabaseError
- CLASS ActiveRecord::NotNullViolation
- CLASS ActiveRecord::PreparedStatementCacheExpired
- CLASS ActiveRecord::PreparedStatementInvalid
- CLASS ActiveRecord::Promise
- CLASS ActiveRecord::QueryAborted
- CLASS ActiveRecord::QueryCache
- CLASS ActiveRecord::QueryCanceled
- CLASS ActiveRecord::RangeError
- CLASS ActiveRecord::ReadOnlyError
- CLASS ActiveRecord::ReadOnlyRecord
- CLASS ActiveRecord::ReadonlyAttributeError
- CLASS ActiveRecord::RecordInvalid
- CLASS ActiveRecord::RecordNotDestroyed
- CLASS ActiveRecord::RecordNotFound
- CLASS ActiveRecord::RecordNotSaved
- CLASS ActiveRecord::RecordNotUnique
- CLASS ActiveRecord::Relation
- CLASS ActiveRecord::Result
- CLASS ActiveRecord::Rollback
- CLASS ActiveRecord::SQLWarning
- CLASS ActiveRecord::Schema
- CLASS ActiveRecord::SerializationFailure
- CLASS ActiveRecord::SerializationTypeMismatch
- CLASS ActiveRecord::SoleRecordExceeded
- CLASS ActiveRecord::StaleObjectError
- CLASS ActiveRecord::StatementCache
- CLASS ActiveRecord::StatementInvalid
- CLASS ActiveRecord::StatementTimeout
- CLASS ActiveRecord::StrictLoadingViolationError
- CLASS ActiveRecord::SubclassNotFound
- CLASS ActiveRecord::TableNotSpecified
- CLASS ActiveRecord::Transaction
- CLASS ActiveRecord::TransactionIsolationError
- CLASS ActiveRecord::TransactionRollbackError
- CLASS ActiveRecord::UnknownAttributeError
- CLASS ActiveRecord::UnknownAttributeReference
- CLASS ActiveRecord::UnknownPrimaryKey
- CLASS ActiveRecord::UnmodifiableRelation
- CLASS ActiveRecord::ValueTooLong
- CLASS ActiveRecord::WrappedDatabaseException
- A
- D
- E
- G
- L
- M
- P
- Q
- R
- S
- T
- U
- V
- W
- Y
Constants
| MigrationProxy | = | Struct.new(:name, :version, :filename, :scope) do def initialize(name, version, filename, scope) super @migration = nil end def basename File.basename(filename) end delegate :migrate, :announce, :write, :disable_ddl_transaction, to: :migration private def migration @migration ||= load_migration end def load_migration Object.send(:remove_const, name) rescue nil load(File.expand_path(filename)) name.constantize.new(name, version) end end |
| ||
| Point | = | Struct.new(:x, :y) |
| UnknownAttributeError | = | ActiveModel::UnknownAttributeError |
Active Model UnknownAttributeError¶ ↑Raised when unknown attributes are supplied via mass assignment. class Person include ActiveModel::AttributeAssignment include ActiveModel::Validations end person = Person.new person.assign_attributes(name: 'Gorby') # => ActiveModel::UnknownAttributeError: unknown attribute 'name' for Person. | ||
Attributes
| [RW] | application_record_class | |
| [RW] | before_committed_on_all_records | |
| [RW] | belongs_to_required_validates_foreign_key | |
| [RW] | database_cli | |
| [R] | default_timezone | |
| [RW] | disable_prepared_statements | |
| [RW] | index_nested_attribute_errors | |
| [RW] | maintain_test_schema | |
| [R] | permanent_connection_checkout | |
| [RW] | query_transformers | |
| [RW] | raise_on_assign_to_attr_readonly | |
| [RW] | raise_on_missing_required_finder_order_columns | |
| [RW] | reading_role | |
| [RW] | run_after_transaction_callbacks_in_order_defined | |
| [RW] | writing_role |
Class Public methods
action_on_strict_loading_violation Link
Set the application to log or raise when an association violates strict loading. Defaults to :raise.
after_all_transactions_commit(&block) Link
Registers a block to be called after all the current transactions have been committed.
If there is no currently open transaction, the block is called immediately.
If there are multiple nested transactions, the block is called after the outermost one has been committed,
If any of the currently open transactions is rolled back, the block is never called.
If multiple transactions are open across multiple databases, the block will be invoked if and once all of them have been committed. But note that nesting transactions across two distinct databases is a sharding anti-pattern that comes with a world of hurts.
# File activerecord/lib/active_record.rb, line 573 def self.after_all_transactions_commit(&block) open_transactions = all_open_transactions if open_transactions.empty? yield elsif open_transactions.size == 1 open_transactions.first.after_commit(&block) else count = open_transactions.size callback = -> do count -= 1 block.call if count.zero? end open_transactions.each do |t| t.after_commit(&callback) end open_transactions = nil # rubocop:disable Lint/UselessAssignment avoid holding it in the closure end end
async_query_executor Link
Sets the async_query_executor for an application. By default the thread pool executor set to nil which will not run queries in the background. Applications must configure a thread pool executor to use this feature. Options are:
* nil - Does not initialize a thread pool executor. Any async calls will be run in the foreground. * :global_thread_pool - Initializes a single +Concurrent::ThreadPoolExecutor+ that uses the +async_query_concurrency+ for the +max_threads+ value. * :multi_thread_pool - Initializes a +Concurrent::ThreadPoolExecutor+ for each database connection. The initializer values are defined in the configuration hash.
db_warnings_action Link
The action to take when database query produces warning. Must be one of :ignore, :log, :raise, :report, or a custom proc. The default is :ignore.
db_warnings_action=(action) Link
# File activerecord/lib/active_record.rb, line 237 def self.db_warnings_action=(action) @db_warnings_action = case action when :ignore nil when :log ->(warning) do warning_message = "[#{warning.class}] #{warning.message}" warning_message += " (#{warning.code})" if warning.code ActiveRecord::Base.logger.warn(warning_message) end when :raise ->(warning) { raise warning } when :report ->(warning) { Rails.error.report(warning, handled: true) } when Proc action else raise ArgumentError, "db_warnings_action must be one of :ignore, :log, :raise, :report, or a custom proc." end end
db_warnings_ignore Link
Specify allowlist of database warnings. Can be a string, regular expression, or an error code from the database.
ActiveRecord::Base.db_warnings_ignore = [/`SHOW WARNINGS` did not return the warnings/, "01000"]
default_timezone=(default_timezone) Link
Determines whether to use Time.utc (using :utc) or Time.local (using :local) when pulling dates and times from the database. This is set to :utc by default.
deprecated_associations_options() Link
deprecated_associations_options=(options) Link
# File activerecord/lib/active_record.rb, line 479 def self.deprecated_associations_options=(options) raise ArgumentError, "deprecated_associations_options must be a hash" unless options.is_a?(Hash) valid_keys = [:mode, :backtrace] invalid_keys = options.keys - valid_keys unless invalid_keys.empty? inflected_key = invalid_keys.size == 1 ? "key" : "keys" raise ArgumentError, "invalid deprecated_associations_options #{inflected_key} #{invalid_keys.map(&:inspect).to_sentence} (valid keys are #{valid_keys.map(&:inspect).to_sentence})" end options.each do |key, value| ActiveRecord::Associations::Deprecation.send("#{key}=", value) end end
disconnect_all!() Link
Explicitly closes all database connections in all pools.
dump_schema_after_migration Link
Specify whether schema dump should happen at the end of the bin/rails db:migrate command. This is true by default, which is useful for the development environment. This should ideally be false in the production environment where dumping schema is rarely needed.
dump_schemas Link
Specifies which database schemas to dump when calling db:schema:dump. If the value is :schema_search_path (the default), any schemas listed in schema_search_path are dumped. Use :all to dump all schemas regardless of schema_search_path, or a string of comma separated schemas for a custom list.
eager_load!() Link
# File activerecord/lib/active_record.rb, line 545 def self.eager_load! super ActiveRecord::Locking.eager_load! ActiveRecord::Scoping.eager_load! ActiveRecord::Associations.eager_load! ActiveRecord::AttributeMethods.eager_load! ActiveRecord::ConnectionAdapters.eager_load! ActiveRecord::Encryption.eager_load! end
error_on_ignored_order Link
Specifies if an error should be raised if the query has an order being ignored when doing batch queries. Useful in applications where the scope being ignored is error-worthy, rather than a warning.
gem_version() Link
Returns the currently loaded version of Active Record as a Gem::Version.
generate_secure_token_on Link
Controls when to generate a value for has_secure_token declarations. Defaults to :create.
global_executor_concurrency=(global_executor_concurrency) Link
Set the global_executor_concurrency. This configuration value can only be used with the global thread pool async query executor.
# File activerecord/lib/active_record.rb, line 304 def self.global_executor_concurrency=(global_executor_concurrency) if self.async_query_executor.nil? || self.async_query_executor == :multi_thread_pool raise ArgumentError, "`global_executor_concurrency` cannot be set when the executor is nil or set to `:multi_thread_pool`. For multiple thread pools, please set the concurrency in your database configuration." end @global_executor_concurrency = global_executor_concurrency end
lazily_load_schema_cache Link
Lazily load the schema cache. This option will load the schema cache when a connection is established rather than on boot.
marshalling_format_version() Link
marshalling_format_version=(value) Link
message_verifiers Link
ActiveSupport::MessageVerifiers instance for Active Record. If you are using Rails, this will be set to Rails.application.message_verifiers.
migration_strategy Link
Specify strategy to use for executing migrations.
permanent_connection_checkout=(value) Link
Defines whether ActiveRecord::Base.connection is allowed, deprecated, or entirely disallowed.
# File activerecord/lib/active_record.rb, line 320 def self.permanent_connection_checkout=(value) unless [true, :deprecated, :disallowed].include?(value) raise ArgumentError, "permanent_connection_checkout must be one of: `true`, `:deprecated` or `:disallowed`" end @permanent_connection_checkout = value end
protocol_adapters Link
Provides a mapping between database protocols/DBMSs and the underlying database adapter to be used. This is used only by the DATABASE_URL environment variable.
Example¶ ↑
DATABASE_URL="mysql://myuser:mypass@localhost/somedatabase"
The above URL specifies that MySQL is the desired protocol/DBMS, and the application configuration can then decide which adapter to use. For this example the default mapping is from mysql to mysql2, but :trilogy is also supported.
ActiveRecord.protocol_adapters.mysql = "mysql2"
The protocols names are arbitrary, and external database adapters can be registered and set here.
queues Link
Specifies the names of the queues used by background jobs.
raise_int_wider_than_64bit Link
Application configurable boolean that denotes whether or not to raise an exception when the PostgreSQLAdapter is provided with an integer that is wider than signed 64bit representation
schema_cache_ignored_table?(table_name) Link
Checks to see if the table_name is ignored by checking against the schema_cache_ignored_tables option.
ActiveRecord.schema_cache_ignored_table?(:developers)
schema_cache_ignored_tables Link
A list of tables or regex’s to match tables to ignore when dumping the schema cache. For example if this is set to +[/^_/]+ the schema cache will not dump tables named with an underscore.
schema_format Link
Specifies the format to use when dumping the database schema with Rails’ Rakefile. If :sql, the schema is dumped as (potentially database- specific) SQL statements. If :ruby, the schema is dumped as an ActiveRecord::Schema file which can be loaded into any database that supports migrations. Use :ruby if you want to have different database adapters for, e.g., your development and test environments. This can be overridden per-database in the database configuration.
schema_versions_formatter Link
Specify the formatter used by schema dumper to format versions information.
timestamped_migrations Link
Specify whether or not to use timestamps for migration versions
use_yaml_unsafe_load Link
Application configurable boolean that instructs the YAML Coder to use an unsafe load if set to true.
validate_migration_timestamps Link
Specify whether or not to validate migration timestamps. When set, an error will be raised if a timestamp is more than a day ahead of the timestamp associated with the current time. timestamped_migrations must be set to true.
verbose_query_logs Link
Specifies if the methods calling database queries should be logged below their relevant queries. Defaults to false.
verify_foreign_keys_for_fixtures Link
If true, Rails will verify all foreign keys in the database after loading fixtures. An error will be raised if there are any foreign key violations, indicating incorrectly written fixtures. Supported by PostgreSQL and SQLite.
version() Link
Returns the currently loaded version of Active Record as a Gem::Version.
with_transaction_isolation_level(isolation_level, &block) Link
Sets a transaction isolation level for all connection pools within the block.
# File activerecord/lib/active_record.rb, line 616 def self.with_transaction_isolation_level(isolation_level, &block) original_level = self.default_transaction_isolation_level self.default_transaction_isolation_level = isolation_level yield ensure self.default_transaction_isolation_level = original_level end