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 



220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
 
# File 'lib/online_migrations/config.rb', line 220

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_data_migrations = BackgroundDataMigrations::Config.new
  @background_schema_migrations = BackgroundSchemaMigrations::Config.new

  @checks = []
  @start_after = 0
  @target_version = nil
  @small_tables = []
  @require_safety_assured_reason = false
  @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



106
107
108
 
# File 'lib/online_migrations/config.rb', line 106

def alphabetize_schema
  @alphabetize_schema
end

#auto_analyze ⇒ Boolean

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



101
102
103
 
# File 'lib/online_migrations/config.rb', line 101

def auto_analyze
  @auto_analyze
end

#background_data_migrations ⇒ BackgroundDataMigrations::Config (readonly)

Configuration object to configure background migrations

See Also:



216
217
218
 
# File 'lib/online_migrations/config.rb', line 216

def background_data_migrations
  @background_data_migrations
end

#background_schema_migrations ⇒ Object (readonly)

Returns the value of attribute background_schema_migrations.



218
219
220
 
# File 'lib/online_migrations/config.rb', line 218

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.



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

def backtrace_cleaner
  @backtrace_cleaner
end

#check_down ⇒ Boolean

Whether to perform checks when migrating down

Disabled by default



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

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



157
158
159
 
# File 'lib/online_migrations/config.rb', line 157

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" }



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

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.



166
167
168
 
# File 'lib/online_migrations/config.rb', line 166

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"



96
97
98
 
# File 'lib/online_migrations/config.rb', line 96

def error_messages
  @error_messages
end

#lock_retrier ⇒ OnlineMigrations::LockRetrier

Lock retrier in use (see LockRetrier)

No retries are performed by default.



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

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.



115
116
117
 
# File 'lib/online_migrations/config.rb', line 115

def lock_timeout_limit
  @lock_timeout_limit
end

#require_safety_assured_reason ⇒ Boolean

Whether to require safety reason explanation when calling #safery_assured

Disabled by default



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

def require_safety_assured_reason
  @require_safety_assured_reason
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? }



189
190
191
 
# File 'lib/online_migrations/config.rb', line 189

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.



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

def small_tables
  @small_tables
end

#statement_timeout ⇒ Numeric

Statement timeout used for migrations (in seconds)



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"



133
134
135
 
# File 'lib/online_migrations/config.rb', line 133

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? }



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

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.



179
180
181
 
# File 'lib/online_migrations/config.rb', line 179

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

Yields:

  • (method, args) —

    a block to be called with custom check

Yield Parameters:

  • method (Symbol) —

    method name

  • args (Array) —

    method arguments



325
326
327
 
# File 'lib/online_migrations/config.rb', line 325

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.



297
298
299
300
301
302
303
304
 
# File 'lib/online_migrations/config.rb', line 297

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.



285
286
287
 
# File 'lib/online_migrations/config.rb', line 285

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.



274
275
276
 
# File 'lib/online_migrations/config.rb', line 274

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



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



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