Class: OnlineMigrations::Config

Inherits:
Object
  • Object
show all
Includes:
ErrorMessages
Defined in:
lib/online_migrations/config.rb

Overview

Class representing configuration options for the gem.

Constant Summary

Constants included from ErrorMessages

ErrorMessages::ERROR_MESSAGES

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize ⇒ Config

Returns a new instance of Config.



213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
 
# File 'lib/online_migrations/config.rb', line 213

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.2.seconds
  )

  @background_migrations = BackgroundMigrations::Config.new
  @background_schema_migrations = BackgroundSchemaMigrations::Config.new

  @checks = []
  @start_after = 0
  @target_version = nil
  @small_tables = []
  @check_down = false
  @auto_analyze = false
  @alphabetize_schema = false
  @enabled_checks = @error_messages.keys.index_with({})
  @verbose_sql_logs = defined?(Rails.env) && (Rails.env.production? || Rails.env.staging?)
  @run_background_migrations_inline = -> { Utils.developer_env? }
  @throttler = -> { false }
end

Instance Attribute Details

#alphabetize_schema ⇒ Boolean

Whether to alphabetize schema

Returns:

  • (Boolean) 


99
100
101
 
# File 'lib/online_migrations/config.rb', line 99

def alphabetize_schema
  @alphabetize_schema
end

#auto_analyze ⇒ Boolean

Whether to automatically run ANALYZE on the table after the index was added

Returns:

  • (Boolean) 


94
95
96
 
# File 'lib/online_migrations/config.rb', line 94

def auto_analyze
  @auto_analyze
end

#background_migrations ⇒ BackgroundMigrationsConfig (readonly)

Configuration object to configure background migrations

Returns:

  • (BackgroundMigrationsConfig)

See Also:

  • BackgroundMigrationsConfig


209
210
211
 
# File 'lib/online_migrations/config.rb', line 209

def background_migrations
  @background_migrations
end

#background_schema_migrations ⇒ Object (readonly)

Returns the value of attribute background_schema_migrations.



211
212
213
 
# File 'lib/online_migrations/config.rb', line 211

def background_schema_migrations
  @background_schema_migrations
end

#backtrace_cleaner ⇒ ActiveSupport::BacktraceCleaner?

The Active Support backtrace cleaner that will be used to clean the backtrace of a background data or schema migration that errors.

Returns:

  • (ActiveSupport::BacktraceCleaner, nil) —

    the backtrace cleaner to use when cleaning a background migrations’s backtrace. Defaults to ‘Rails.backtrace_cleaner`



202
203
204
 
# File 'lib/online_migrations/config.rb', line 202

def backtrace_cleaner
  @backtrace_cleaner
end

#check_down ⇒ Boolean

Whether to perform checks when migrating down

Disabled by default

Returns:

  • (Boolean) 


81
82
83
 
# File 'lib/online_migrations/config.rb', line 81

def check_down
  @check_down
end

#checks ⇒ Array<Array<Hash>, Proc> (readonly)

Returns a list of custom checks

Use ‘add_check` to add custom checks

Returns:

  • (Array<Array<Hash>, Proc>) 


150
151
152
 
# File 'lib/online_migrations/config.rb', line 150

def checks
  @checks
end

#column_renames ⇒ Hash

Columns that are in the process of being renamed

Examples:

To add a column

OnlineMigrations.config.column_renames["users] = { "name" => "first_name" }

Returns:

  • (Hash) —

    Keys are table names, values - hashes with old column names as keys and new column names as values



135
136
137
 
# File 'lib/online_migrations/config.rb', line 135

def column_renames
  @column_renames
end

#enabled_checks ⇒ Array (readonly)

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 the `error_messages.rb` file.

Returns:

  • (Array) 


159
160
161
 
# File 'lib/online_migrations/config.rb', line 159

def enabled_checks
  @enabled_checks
end

#error_messages ⇒ Hash

Error messages

Examples:

To change a message

OnlineMigrations.config.error_messages[:remove_column] = "Your custom instructions"

Returns:

  • (Hash) —

    Keys are error names, values are error messages



89
90
91
 
# File 'lib/online_migrations/config.rb', line 89

def error_messages
  @error_messages
end

#lock_retrier ⇒ OnlineMigrations::LockRetrier

Lock retrier in use (see LockRetrier)

No retries are performed by default.

Returns:



142
143
144
 
# File 'lib/online_migrations/config.rb', line 142

def lock_retrier
  @lock_retrier
end

#lock_timeout_limit ⇒ Numeric

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.

Returns:

  • (Numeric) 


108
109
110
 
# File 'lib/online_migrations/config.rb', line 108

def lock_timeout_limit
  @lock_timeout_limit
end

#run_background_migrations_inline ⇒ Proc

The proc which decides whether background migrations should be run inline. For convenience defaults to true for development and test environments.

Examples:

OnlineMigrations.config.run_background_migrations_inline = -> { Rails.env.local? }

Returns:

  • (Proc) 


182
183
184
 
# File 'lib/online_migrations/config.rb', line 182

def run_background_migrations_inline
  @run_background_migrations_inline
end

#small_tables ⇒ Array<String, Symbol>

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.

Returns:

  • (Array<String, Symbol>) 


118
119
120
 
# File 'lib/online_migrations/config.rb', line 118

def small_tables
  @small_tables
end

#statement_timeout ⇒ Numeric

Statement timeout used for migrations (in seconds)

Returns:

  • (Numeric) 


42
43
44
 
# File 'lib/online_migrations/config.rb', line 42

def statement_timeout
  @statement_timeout
end

#table_renames ⇒ Hash

Tables that are in the process of being renamed

Examples:

To add a table

OnlineMigrations.config.table_renames["users"] = "clients"

Returns:

  • (Hash) —

    Keys are old table names, values - new table names



126
127
128
 
# File 'lib/online_migrations/config.rb', line 126

def table_renames
  @table_renames
end

#throttler ⇒ Proc

Allows to throttle background data or schema migrations based on external signal (e.g. database health)

It will be called before each run. If throttled, the current run will be retried next time.

Examples:

OnlineMigrations.config.throttler = -> { DatabaseStatus.unhealthy? }

Returns:

  • (Proc) 


194
195
196
 
# File 'lib/online_migrations/config.rb', line 194

def throttler
  @throttler
end

#verbose_sql_logs ⇒ Boolean

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 staging and production Rails environments. @note: It can be overridden by ‘ONLINE_MIGRATIONS_VERBOSE_SQL_LOGS` environment variable.

Returns:

  • (Boolean) 


172
173
174
 
# File 'lib/online_migrations/config.rb', line 172

def verbose_sql_logs
  @verbose_sql_logs
end

Instance Method Details

#add_check(start_after: nil) {|method, args| ... } ⇒ void

This method returns an undefined value.

Adds custom check

Use ‘stop!` method to stop the migration

Examples:

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

Parameters:

  • start_after (Integer) (defaults to: nil) —

    migration version from which this check will be performed

Yields:

  • (method, args) —

    a block to be called with custom check

Yield Parameters:

  • method (Symbol) —

    method name

  • args (Array) —

    method arguments



317
318
319
 
# File 'lib/online_migrations/config.rb', line 317

def add_check(start_after: nil, &block)
  @checks << [{ start_after: start_after }, block]
end

#check_enabled?(name, version: nil) ⇒ void

This method returns an undefined value.

Test whether specific check is enabled

For the list of available checks look at the ‘error_messages.rb` file.

Parameters:

  • name (Symbol) —

    check name

  • version (Integer) (defaults to: nil) —

    migration version



289
290
291
292
293
294
295
296
 
# File 'lib/online_migrations/config.rb', line 289

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) ⇒ void

This method returns an undefined value.

Disables specific check

For the list of available checks look at the ‘error_messages.rb` file.

Parameters:

  • name (Symbol) —

    check name



277
278
279
 
# File 'lib/online_migrations/config.rb', line 277

def disable_check(name)
  enabled_checks.delete(name)
end

#enable_check(name, start_after: nil) ⇒ void

This method returns an undefined value.

Enables specific check

For the list of available checks look at the ‘error_messages.rb` file.

Parameters:

  • name (Symbol) —

    check name

  • start_after (Integer) (defaults to: nil) —

    migration version from which this check will be performed



266
267
268
 
# File 'lib/online_migrations/config.rb', line 266

def enable_check(name, start_after: nil)
  enabled_checks[name] = { start_after: start_after }
end

#start_after ⇒ Integer

The migration version starting after which checks are performed

Returns:

  • (Integer) 


28
29
30
31
32
33
34
35
36
 
# File 'lib/online_migrations/config.rb', line 28

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) ⇒ Object

Note:

Use the version from your latest migration.

Set the migration version starting after which checks are performed

Examples:

OnlineMigrations.config.start_after = 20220101000000

Multiple databases

OnlineMigrations.config.start_after = { primary: 20211112000000, animals: 20220101000000 }


17
18
19
20
21
22
23
 
# File 'lib/online_migrations/config.rb', line 17

def start_after=(value)
  if value.is_a?(Hash)
    @start_after = value.stringify_keys
  else
    @start_after = value
  end
end

#target_version ⇒ Numeric, ...

The database version against which the checks will be performed

Returns:

  • (Numeric, String, nil) 


66
67
68
69
70
71
72
73
74
 
# File 'lib/online_migrations/config.rb', line 66

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) ⇒ Object

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.

Examples:

OnlineMigrations.config.target_version = 10

Multiple databases

OnlineMigrations.config.target_version = { primary: 10, animals: 14.1 }


55
56
57
58
59
60
61
 
# File 'lib/online_migrations/config.rb', line 55

def target_version=(value)
  if value.is_a?(Hash)
    @target_version = value.stringify_keys
  else
    @target_version = value
  end
end