PgHaMigrations is a gem that applies learned best practices to ActiveRecord Migrations.
Add this line to your application's Gemfile:
And then execute:
Or install it yourself as:
$ gem install pg_ha_migrations
In general, existing migrations are prefixed with
unsafe_ and safer alternatives are provided prefixed with
Migrations prefixed with
unsafe_ will warn when invoked. The API is designed to be explicit yet remain flexible. There may be situations where invoking the unsafe migration is preferred.
Migrations prefixed with
safe_ prefer concurrent operations where available, set low lock timeouts where appropriate, and decompose operations into multiple safe steps.
The following functionality is currently unsupported:
Safely creates a new table.
safe_create_table :table do |t| t.type :column end
Safely create a new enum without values.
Or, safely create the enum with values.
safe_create_enum_type :enum, ["value1", "value2"]
Safely add a new enum value.
safe_add_enum_value :enum, "value"
Safely add a column.
safe_add_column :table, :column, :type
Unsafely add a column, but do so with a lock that is safely acquired.
unsafe_add_column :table, :column, :type
Safely change the default value for a column.
safe_change_column_default :table, :column, "value"
Safely make the column nullable.
safe_make_column_nullable :table, :column
Unsafely make a column not nullable.
unsafe_make_column_not_nullable :table, :column
Add an index concurrently. Migrations that contain this statement must also include
safe_add_concurrent_index :table, :column
Add a composite btree index.
safe_add_concurrent_index :table, [:column1, :column2], name: "index_name", using: :btree
Safely remove an index. Migrations that contain this statement must also include
safe_remove_concurrent_index :table, :name => :index_name
Safely acquire a lock for a table.
safely_acquire_lock_for_table(:table) do ... end
Adjust lock timeout.
adjust_lock_timeout(seconds) do ... end
Adjust statement timeout.
adjust_statement_timeout(seconds) do ... end
Set maintenance work mem.
Use this to check for blocking transactions before migrating.
$ bundle exec rake pg_ha_migrations:check_blocking_database_transactions
This rake task expects that you already have a connection open to your database. We suggest that you add another rake task to open the connection and then add that as a prerequisite for
namespace :db do desc "Establish a database connection" task :establish_connection do ActiveRecord::Base.establish_connection end end Rake::Task["pg_ha_migrations:check_blocking_database_transactions"].enhance ["db:establish_connection"]
After checking out the repo, run
bin/setup to install dependencies and start a postgres docker container. Then, run
rake spec to run the tests. You can also run
bin/console for an interactive prompt that will allow you to experiment.
To install this gem onto your local machine, run
bundle exec rake install. To release a new version, update the version number in
version.rb, and then run
bundle exec rake release, which will create a git tag for the version, push git commits and tags, and push the
.gem file to rubygems.org.
Bug reports and pull requests are welcome on GitHub at https://github.com/braintreeps/pg_ha_migrations. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the Contributor Covenant code of conduct.
The gem is available as open source under the terms of the MIT License.
Code of Conduct
Everyone interacting in the PgHaMigrations project’s codebases, issue trackers, chat rooms and mailing lists is expected to follow the code of conduct.