class OnlineMigrations::Config

Class representing configuration options for the gem.

Attributes

background_migrations[R]

Configuration object to configure background migrations

@return [BackgroundMigrationsConfig] @see BackgroundMigrationsConfig

check_down[RW]

Whether to perform checks when migrating down

Disabled by default @return [Boolean]

checks[R]

Returns a list of custom checks

Use ‘add_check` to add custom checks

@return [Array<Array<Hash>, Proc>]

column_renames[RW]

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" }
enabled_checks[R]

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[RW]

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[R]

Lock retrier in use (see LockRetrier)

No retries are performed by default. @return [OnlineMigrations::LockRetrier]

lock_timeout_limit[RW]

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]

small_tables[R]

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>]

table_renames[RW]

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"
verbose_sql_logs[RW]

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

new() click to toggle source
# 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

add_check(start_after: nil, &block) click to toggle source

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
check_enabled?(name, version: nil) click to toggle source

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
disable_check(name) click to toggle source

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
enable_check(name, start_after: nil) click to toggle source

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
lock_retrier=(value) click to toggle source
# File lib/online_migrations/config.rb, line 191
def lock_retrier=(value)
  @lock_retrier = value || NullLockRetrier.new
end
small_tables=(table_names) click to toggle source
# File lib/online_migrations/config.rb, line 195
def small_tables=(table_names)
  @small_tables = table_names.map(&:to_s)
end
start_after() click to toggle source

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
start_after=(value) click to toggle source

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
target_version() click to toggle source

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
target_version=(value) click to toggle source

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

db_config_name() click to toggle source
# 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
ensure_supports_multiple_dbs() click to toggle source
# 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