class OnlineMigrations::Config
Class representing configuration options for the gem.
Attributes
Configuration object to configure background migrations
@return [BackgroundMigrationsConfig] @see BackgroundMigrationsConfig
Whether to perform checks when migrating down
Disabled by default @return [Boolean]
Returns a list of custom checks
Use ‘add_check` to add custom checks
@return [Array<Array<Hash>, Proc>]
Columns that are in the process of being renamed
@return [Hash] Keys are table names, values - hashes with old column names as keys
and new column names as values
@example To add a column
OnlineMigrations.config.column_renames["users] = { "name" => "first_name" }
Returns a list of enabled checks
All checks are enabled by default. To disable/enable a check use ‘disable_check`/`enable_check`. For the list of available checks look at `lib/error_messages` folder.
@return [Array]
Error
messages
@return [Hash] Keys are error names, values are error messages @example To change a message
OnlineMigrations.config.error_messages[:remove_column] = "Your custom instructions"
Lock retrier in use (see LockRetrier
)
No retries are performed by default. @return [OnlineMigrations::LockRetrier]
Maximum allowed lock timeout value (in seconds)
If set lock timeout is greater than this value, the migration will fail. The default value is 10 seconds.
@return [Numeric]
List of tables with permanently small number of records
These are usually tables like “settings”, “prices”, “plans” etc. It is considered safe to perform most of the dangerous operations on them,
like adding indexes, columns etc.
@return [Array<String, Symbol>]
Tables that are in the process of being renamed
@return [Hash] Keys are old table names, values - new table names @example To add a table
OnlineMigrations.config.table_renames["users"] = "clients"
Whether to log every SQL query happening in a migration
This is useful to demystify online_migrations inner workings, and to better investigate migration failure in production. This is also useful in development to get a better grasp of what is going on for high-level statements like add_column_with_default.
This feature is enabled by default in a production Rails environment. @return [Boolean]
@note: It can be overriden by ‘ONLINE_MIGRATIONS_VERBOSE_SQL_LOGS` environment variable.
Public Class Methods
# File lib/online_migrations/config.rb, line 167 def initialize @table_renames = {} @column_renames = {} @error_messages = ERROR_MESSAGES @lock_timeout_limit = 10.seconds @lock_retrier = ExponentialLockRetrier.new( attempts: 30, base_delay: 0.01.seconds, max_delay: 1.minute, lock_timeout: 0.05.seconds ) @background_migrations = BackgroundMigrations::Config.new @checks = [] @start_after = 0 @target_version = nil @small_tables = [] @check_down = false @enabled_checks = @error_messages.keys.map { |k| [k, {}] }.to_h @verbose_sql_logs = defined?(Rails) && Rails.env.production? end
Public Instance Methods
Adds custom check
@param start_after
[Integer] migration version from which this check will be performed
@yield [method, args] a block to be called with custom check @yieldparam method [Symbol] method name @yieldparam args [Array] method arguments
@return [void]
Use ‘stop!` method to stop the migration
@example
OnlineMigrations.config.add_check do |method, args| if method == :add_column && args[0].to_s == "users" stop!("No more columns on the users table") end end
# File lib/online_migrations/config.rb, line 258 def add_check(start_after: nil, &block) @checks << [{ start_after: start_after }, block] end
Test whether specific check is enabled
For the list of available checks look at ‘lib/error_messages` module.
@param name [Symbol] check name @param version [Integer] migration version @return [void]
# File lib/online_migrations/config.rb, line 230 def check_enabled?(name, version: nil) if enabled_checks[name] start_after = enabled_checks[name][:start_after] || OnlineMigrations.config.start_after !version || version > start_after else false end end
Disables specific check
For the list of available checks look at ‘lib/error_messages` module.
@param name [Symbol] check name @return [void]
# File lib/online_migrations/config.rb, line 218 def disable_check(name) enabled_checks.delete(name) end
Enables specific check
For the list of available checks look at ‘lib/error_messages` module.
@param name [Symbol] check name @param start_after
[Integer] migration version from which this check will be performed @return [void]
# File lib/online_migrations/config.rb, line 207 def enable_check(name, start_after: nil) enabled_checks[name] = { start_after: start_after } end
# File lib/online_migrations/config.rb, line 191 def lock_retrier=(value) @lock_retrier = value || NullLockRetrier.new end
# File lib/online_migrations/config.rb, line 195 def small_tables=(table_names) @small_tables = table_names.map(&:to_s) end
The migration version starting after which checks are performed @return [Integer]
# File lib/online_migrations/config.rb, line 29 def start_after if @start_after.is_a?(Hash) @start_after.fetch(db_config_name) do raise "OnlineMigrations.config.start_after is not configured for :#{db_config_name}" end else @start_after end end
Set the migration version starting after which checks are performed @example
OnlineMigrations.config.start_after = 20220101000000
@example Multiple databases
OnlineMigrations.config.start_after = { primary: 20211112000000, animals: 20220101000000 }
@note Use the version from your latest migration.
# File lib/online_migrations/config.rb, line 17 def start_after=(value) if value.is_a?(Hash) ensure_supports_multiple_dbs @start_after = value.stringify_keys else @start_after = value end end
The database version against which the checks will be performed @return [Numeric, String, nil]
# File lib/online_migrations/config.rb, line 62 def target_version if @target_version.is_a?(Hash) @target_version.fetch(db_config_name) do raise "OnlineMigrations.config.target_version is not configured for :#{db_config_name}" end else @target_version end end
Set the database version against which the checks will be performed
If your development database version is different from production, you can specify the production version so the right checks run in development.
@example
OnlineMigrations.config.target_version = 10
@example Multiple databases
OnlineMigrations.config.target_version = { primary: 10, animals: 14.1 }
# File lib/online_migrations/config.rb, line 50 def target_version=(value) if value.is_a?(Hash) ensure_supports_multiple_dbs @target_version = value.stringify_keys else @target_version = value end end
Private Instance Methods
# File lib/online_migrations/config.rb, line 269 def db_config_name connection = OnlineMigrations.current_migration.connection if Utils.ar_version < 6.1 connection.pool.spec.name else connection.pool.db_config.name end end
# File lib/online_migrations/config.rb, line 263 def ensure_supports_multiple_dbs unless Utils.supports_multiple_dbs? raise "Multiple databases are not supported by this ActiveRecord version" end end