Class: OnlineMigrations::Config

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

Overview

Class representing configuration options for the gem.

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize ⇒ Config

Returns a new instance of Config.



191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
 
# File 'lib/online_migrations/config.rb', line 191

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

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


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

def background_migrations
  @background_migrations
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

#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



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

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



257
258
259
260
261
262
263
264
 
# File 'lib/online_migrations/config.rb', line 257

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



245
246
247
 
# File 'lib/online_migrations/config.rb', line 245

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



234
235
236
 
# File 'lib/online_migrations/config.rb', line 234

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