модуль ActiveRecord

Включенные модули:: ActiveSupport::Deprecation::DeprecatedConstantAccessor

Active Record – Объектно-реляционное отображение в Rails

Active Record связывает классы с таблицами реляционной базы данных, чтобы создать практически безконфигурационный уровень сохранения для приложений. Библиотека предоставляет базовый класс, который, при наследовании, устанавливает отображение между новым классом и существующей таблицей в базе данных. В контексте приложения эти классы обычно называются моделями. Модели также могут быть связаны с другими моделями; это делается путем определения ассоциаций.

Active Record сильно зависит от именования, поскольку он использует имена классов и ассоциаций для установления сопоставлений между соответствующими таблицами базы данных и столбцами внешних ключей. Хотя эти сопоставления могут быть определены явно, рекомендуется следовать соглашениям об именовании, особенно при первом знакомстве с библиотекой.

Вы можете узнать больше об Active Record в руководстве Основные принципы Active Record.

Краткое описание некоторых основных функций:

Автоматическое отображение между классами и таблицами, атрибутами и столбцами.
```
class Product < ActiveRecord::Base
end
```
Класс Product автоматически отображается на таблицу с именем «products», которая может выглядеть так:
```
CREATE TABLE products (
  id bigint NOT NULL auto_increment,
  name varchar(255),
  PRIMARY KEY  (id)
);
```
Это также определит следующие аксессоры: Product#name и Product#name=(new_name).

Подробнее
Associations между объектами, определенными простыми методами класса.
```
class Firm < ActiveRecord::Base
  has_many   :clients
  has_one    :account
  belongs_to :conglomerate
end
```
Подробнее

Aggregations объектов-значений.

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

Подробнее

Правила валидации, которые могут отличаться для новых или существующих объектов.

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

Подробнее

Callbacks, доступные для всего жизненного цикла (создание, сохранение, удаление, валидация и т. д.).
```
class Person < ActiveRecord::Base
  before_destroy :invalidate_payment_plan
  # the `invalidate_payment_plan` method gets called just before Person#destroy
end
```
Подробнее

Inheritance иерархии.

class Company < ActiveRecord::Base; end
class Firm < Company; end
class Client < Company; end
class PriorityClient < Client; end

Подробнее

Transactions.

# Database transaction
Account.transaction do
  david.withdrawal(100)
  mary.deposit(100)
end

Подробнее

Рефлексия по столбцам, ассоциациям и агрегациям.

reflection = Firm.reflect_on_association(:clients)
reflection.klass # => Client (class)
Firm.columns # Returns an array of column descriptors for the firms table

Подробнее

Абстракция базы данных с помощью простых адаптеров.

# 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'
)

Подробнее, и ознакомьтесь с встроенной поддержкой MySQL, PostgreSQL и SQLite3.

Поддержка протоколирования для Log4r и Logger.

ActiveRecord::Base.logger = ActiveSupport::Logger.new(STDOUT)
ActiveRecord::Base.logger = Log4r::Logger.new('Application Log')

Управление схемой базы данных, независимой от базы данных, с помощью миграций.

class AddSystemSettings < ActiveRecord::Migration[7.2]
  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

Подробнее

Философия

Active Record — это реализация одноимённого шаблона объектно-реляционного отображения (ORM), описанного Мартином Фаулером:

«Объект, который оборачивает строку в таблице или представлении базы данных, инкапсулирует доступ к базе данных и добавляет логику предметной области к этим данным»

Active Record пытается предоставить связный оболочку как решение неудобств, связанных с объектно-реляционным отображением. Основная директива для этого отображения заключается в минимизации кода, необходимого для построения реальной модели предметной области. Это достигается за счёт использования ряда соглашений, которые позволяют Active Record легко выводить сложные отношения и структуры из минимального объёма явных указаний.

Конвенции вместо конфигурации:

Нет файлов XML!
Много рефлексии и расширения во время выполнения
Магия — не обязательно плохой термин

Признание базы данных:

Позволяет перейти к SQL для необычных случаев и производительности
Не пытается дублировать или заменять определения данных

Загрузка и установка

Последнюю версию Active Record можно установить с помощью RubyGems:

$ gem install activerecord

Исходный код можно загрузить как часть проекта Rails на GitHub:

github.com/rails/rails/tree/main/activerecord

Лицензия

Active Record распространяется под лицензией MIT:

opensource.org/licenses/MIT

Поддержка

Документация API находится по адресу:

api.rubyonrails.org

Отчёты об ошибках для проекта Ruby on Rails можно подать здесь:

github.com/rails/rails/issues

Запросы новых функций следует обсудить на почтовом списке rails-core здесь:

discuss.rubyonrails.org/c/rubyonrails-core

Класс ошибок валидации для обертывания ошибок записей ассоциаций, с поддержкой index_errors.

Константы

MigrationProxy

MigrationProxy используется для отложенной загрузки фактических классов миграций до тех пор, пока они не понадобятся

Point

UnknownAttributeError

Active Model UnknownAttributeError

Вызывается, когда неизвестные атрибуты предоставляются через массовое назначение.

class Person
  include ActiveModel::AttributeAssignment
  include ActiveModel::Validations
end

person = Person.new
person.assign_attributes(name: 'Gorby')
# => ActiveModel::UnknownAttributeError: unknown attribute 'name' for Person.

Атрибуты

application_record_class[RW]

before_committed_on_all_records[RW]

belongs_to_required_validates_foreign_key[RW]

default_timezone[R]

disable_prepared_statements[RW]

index_nested_attribute_errors[RW]

maintain_test_schema[RW]

permanent_connection_checkout[R]

query_transformers[RW]

raise_on_assign_to_attr_readonly[RW]

reading_role[RW]

run_after_transaction_callbacks_in_order_defined[RW]

writing_role[RW]

END_OF_DOCUMENT_MARKER

Публичные методы класса

action_on_strict_loading_violation() Показать исходный код

# File activerecord/lib/active_record.rb, line 377
singleton_class.attr_accessor :action_on_strict_loading_violation

Устанавливает для приложения режим логирования или генерации исключения при нарушении строгой загрузки ассоциаций. По умолчанию: :raise.

after_all_transactions_commit() { || ... } Показать исходный код

# File activerecord/lib/active_record.rb, line 557
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

Регистрирует блок кода, который будет выполнен после подтверждения всех текущих транзакций.

Если открытых транзакций нет, блок выполняется немедленно.

Если есть несколько вложенных транзакций, блок вызывается после подтверждения самой внешней из них.

Если какая-либо из открытых транзакций отменена, блок никогда не вызывается.

Если открыто несколько транзакций в нескольких базах данных, блок будет вызван, если и когда все они будут подтверждены. Но обратите внимание, что вложенные транзакции в двух разных базах данных — это антипаттерн шардинга, который чреват множеством проблем.

allow_deprecated_singular_associations_name() Показать исходный код

# File activerecord/lib/active_record.rb, line 447
  def self.allow_deprecated_singular_associations_name
    ActiveRecord.deprecator.warn <<-WARNING.squish
      `Rails.application.config.active_record.allow_deprecated_singular_associations_name`
      is deprecated and will be removed in Rails 8.0.
    WARNING
  end

allow_deprecated_singular_associations_name=(value) Показать исходный код

# File activerecord/lib/active_record.rb, line 454
  def self.allow_deprecated_singular_associations_name=(value)
    ActiveRecord.deprecator.warn <<-WARNING.squish
      `Rails.application.config.active_record.allow_deprecated_singular_associations_name`
      is deprecated and will be removed in Rails 8.0.
    WARNING
  end

async_query_executor() Показать исходный код

# File activerecord/lib/active_record.rb, line 276
singleton_class.attr_accessor :async_query_executor

Устанавливает async_query_executor для приложения. По умолчанию используется пул потоков, установленный на nil, который не будет выполнять запросы в фоновом режиме. Для использования этой функции приложения должны настроить пул потоков. Варианты:

* 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.

commit_transaction_on_non_local_return() Показать исходный код

# File activerecord/lib/active_record.rb, line 347
  def self.commit_transaction_on_non_local_return
    ActiveRecord.deprecator.warn <<-WARNING.squish
      `Rails.application.config.active_record.commit_transaction_on_non_local_return`
      is deprecated and will be removed in Rails 8.0.
    WARNING
  end

commit_transaction_on_non_local_return=(value) Показать исходный код

# File activerecord/lib/active_record.rb, line 354
  def self.commit_transaction_on_non_local_return=(value)
    ActiveRecord.deprecator.warn <<-WARNING.squish
      `Rails.application.config.active_record.commit_transaction_on_non_local_return`
      is deprecated and will be removed in Rails 8.0.
    WARNING
  end

db_warnings_action() Показать исходный код

# File activerecord/lib/active_record.rb, line 218
singleton_class.attr_reader :db_warnings_action

Действие, которое необходимо предпринять, когда запрос к базе данных выдает предупреждение. Должно быть одним из :ignore, :log, :raise, :report или пользовательской процедурой. По умолчанию: :ignore.

db_warnings_action=(action) Показать исходный код

# File activerecord/lib/active_record.rb, line 220
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() Показать исходный код

# File activerecord/lib/active_record.rb, line 247
singleton_class.attr_accessor :db_warnings_ignore

Указывает белый список предупреждений базы данных.

default_timezone=(default_timezone) Показать исходный код

# File activerecord/lib/active_record.rb, line 203
def self.default_timezone=(default_timezone)
  unless %i(local utc).include?(default_timezone)
    raise ArgumentError, "default_timezone must be either :utc (default) or :local."
  end

  @default_timezone = default_timezone
end

Определяет, использовать ли Time.utc (используя :utc) или Time.local (используя :local) при извлечении дат и времени из базы данных. По умолчанию установлено значение :utc.

disconnect_all!() Показать исходный код

# File activerecord/lib/active_record.rb, line 540
def self.disconnect_all!
  ConnectionAdapters::PoolConfig.disconnect_all!
end

Явно закрывает все соединения с базой данных во всех пулах.

dump_schema_after_migration() Показать исходный код

# File activerecord/lib/active_record.rb, line 425
singleton_class.attr_accessor :dump_schema_after_migration

Указывает, следует ли выполнять дамп схемы в конце команды bin/rails db:migrate. По умолчанию это значение true, что полезно для среды разработки. В рабочей среде это значение должно быть false, так как дамп схемы редко требуется.

dump_schemas() Показать исходный код

# File activerecord/lib/active_record.rb, line 435
singleton_class.attr_accessor :dump_schemas

Указывает, какие схемы базы данных следует дампать при вызове db:schema:dump. Если значение равно :schema_search_path (по умолчанию), дампятся все схемы, указанные в schema_search_path. Используйте :all, чтобы дампать все схемы независимо от schema_search_path, или строку, разделенную запятыми, для пользовательского списка.

eager_load!() Показать исходный код

# File activerecord/lib/active_record.rb, line 529
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() Показать исходный код

# File activerecord/lib/active_record.rb, line 396
singleton_class.attr_accessor :error_on_ignored_order

Указывает, следует ли генерировать ошибку, если запрос имеет порядок, игнорируемый при выполнении пакетных запросов. Полезно в приложениях, где игнорируемая область является ошибкой, а не предупреждением.

gem_version() Показать исходный код

# File activerecord/lib/active_record/gem_version.rb, line 5
def self.gem_version
  Gem::Version.new VERSION::STRING
end

Возвращает текущую загруженную версию Active Record в виде Gem::Version.

generate_secure_token_on() Показать исходный код

# File activerecord/lib/active_record.rb, line 490
singleton_class.attr_accessor :generate_secure_token_on

Управляет моментом генерации значения для деклараций has_secure_token. Значение по умолчанию — :create.

global_executor_concurrency=(global_executor_concurrency) Показать исходный код

# File activerecord/lib/active_record.rb, line 291
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

Устанавливает global_executor_concurrency. Это значение конфигурации может использоваться только с глобальным пулом потоков асинхронного выполнения запросов.

lazily_load_schema_cache() Показать исходный код

# File activerecord/lib/active_record.rb, line 188
singleton_class.attr_accessor :lazily_load_schema_cache

Ленивая загрузка кеша схемы. Этот параметр загрузит кеш схемы при установке соединения, а не при загрузке.

legacy_connection_handling=(_) Показать исходный код

# File activerecord/lib/active_record.rb, line 256
  def self.legacy_connection_handling=(_)
    raise ArgumentError, <<~MSG.squish
      The `legacy_connection_handling` setter was deprecated in 7.0 and removed in 7.1,
      but is still defined in your configuration. Please remove this call as it no longer
      has any effect."
    MSG
  end

marshalling_format_version() Показать исходный код

# File activerecord/lib/active_record.rb, line 493
def self.marshalling_format_version
  Marshalling.format_version
end

marshalling_format_version=(value) Показать исходный код

# File activerecord/lib/active_record.rb, line 497
def self.marshalling_format_version=(value)
  Marshalling.format_version = value
end

migration_strategy() Показать исходный код

# File activerecord/lib/active_record.rb, line 416
singleton_class.attr_accessor :migration_strategy

Указывает стратегию, используемую для выполнения миграций.

permanent_connection_checkout=(value) Показать исходный код

# File activerecord/lib/active_record.rb, line 307
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

Определяет, разрешено ли ActiveRecord::Base.connection, устарело или полностью запрещено.

protocol_adapters() Показать исходный код

# File activerecord/lib/active_record.rb, line 520
singleton_class.attr_accessor :protocol_adapters

Обеспечивает сопоставление протоколов баз данных/СУБД и базового адаптера базы данных для использования. Это используется только переменной среды DATABASE_URL.

Пример

DATABASE_URL="mysql://myuser:mypass@localhost/somedatabase"

Вышеупомянутый URL указывает, что MySQL является желаемым протоколом/СУБД, и приложение может затем определить, какой адаптер использовать. Для этого примера сопоставление по умолчанию – от mysql до mysql2, но также поддерживается :trilogy.

ActiveRecord.protocol_adapters.mysql = "mysql2"

Имена протоколов произвольны, и внешние адаптеры баз данных могут быть зарегистрированы и заданы здесь.

queues() Показать исходный код

# File activerecord/lib/active_record.rb, line 329
singleton_class.attr_accessor :queues

Указывает имена очередей, используемых фоновыми задачами.

raise_int_wider_than_64bit() Показать исходный код

# File activerecord/lib/active_record.rb, line 476
singleton_class.attr_accessor :raise_int_wider_than_64bit

Конфигурируемый приложением булево значение, указывающее, следует ли генерировать исключение, если PostgreSQLAdapter получает целое число, которое шире, чем представленное в формате со знаком 64 бит.

schema_cache_ignored_tables() Показать исходный код

# File activerecord/lib/active_record.rb, line 196
singleton_class.attr_accessor :schema_cache_ignored_tables

Список таблиц или регулярных выражений для соответствия таблицам, которые нужно игнорировать при экспорте кэша схемы. Например, если это установлено как +[/^_/]+, кэш схемы не будет экспортировать таблицы с именем, содержащим символ подчеркивания.

schema_format() Показать исходный код

# File activerecord/lib/active_record.rb, line 388
singleton_class.attr_accessor :schema_format

Указывает формат, который необходимо использовать при экспорте схемы базы данных с помощью файла Rakefile Rails. Если :sql, схема экспортируется в виде (возможно, специфичных для базы данных) операторов SQL. Если :ruby, схема экспортируется как файл ActiveRecord::Schema, который может быть загружен в любую базу данных, поддерживающую миграции. Используйте :ruby, если вы хотите использовать различные адаптеры баз данных для, например, ваших сред разработки и тестирования.

timestamped_migrations() Показать исходный код

# File activerecord/lib/active_record.rb, line 402
singleton_class.attr_accessor :timestamped_migrations

Указывает, использовать ли отметки времени для версий миграций.

use_yaml_unsafe_load() Показать исходный код

# File activerecord/lib/active_record.rb, line 468
singleton_class.attr_accessor :use_yaml_unsafe_load

Конфигурируемый приложением булево значение, которое инструктирует YAML Coder использовать небезопасную загрузку, если значение установлено в true.

validate_migration_timestamps() Показать исходный код

# File activerecord/lib/active_record.rb, line 410
singleton_class.attr_accessor :validate_migration_timestamps

Указывает, проверять ли отметки времени миграций. При установке, если отметка времени более чем на один день опережает отметку времени, связанную с текущим временем, будет выброшено исключение. timestamped_migrations должно быть установлено в значение true.

verbose_query_logs() Показать исходный код

# File activerecord/lib/active_record.rb, line 322
singleton_class.attr_accessor :verbose_query_logs

Указывает, должны ли методы, вызывающие запросы к базе данных, регистрироваться ниже соответствующих запросов. По умолчанию false.

verify_foreign_keys_for_fixtures() Показать исходный код

# File activerecord/lib/active_record.rb, line 444
singleton_class.attr_accessor :verify_foreign_keys_for_fixtures

Если true, Rails проверит все внешние ключи в базе данных после загрузки фикстур. Если есть нарушения внешних ключей, будет выброшено исключение, что укажет на неправильно написанные фикстуры. Поддерживается PostgreSQL и SQLite.

version() Показать исходный код

# File activerecord/lib/active_record/version.rb, line 7
def self.version
  gem_version
end

Возвращает текущую загруженную версию Active Record в виде Gem::Version.

warn_on_records_fetched_greater_than() Показать исходный код

# File activerecord/lib/active_record.rb, line 367
singleton_class.attr_accessor :warn_on_records_fetched_greater_than

Указывает порог размера наборов результатов запросов. Если количество записей в наборе превышает порог, выводится предупреждение. Это можно использовать для выявления запросов, которые загружают тысячи записей и, возможно, приводят к переполнению памяти.

yaml_column_permitted_classes() Показать исходный код

# File activerecord/lib/active_record.rb, line 483
singleton_class.attr_accessor :yaml_column_permitted_classes

Конфигурируемый приложением массив, предоставляющий дополнительные разрешенные классы для Psych safe_load в YAML Coder.