online_migrations 0.25.0 → 0.27.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f6b7685527d71319ba50e3a5c29744d9ef28103c1cacfdc650cba12c276782d8
-  data.tar.gz: e10e0d1dfb1c807b05927189f682633a7ab17c53f37974c5df5a2b452d78ab92
+  metadata.gz: 7125a034a085c11fff526219d8f2483dfea610b100486766145b7caf85e07700
+  data.tar.gz: 609636661c23e939a1766a14097fca30bc01b21666cfcb5e207bc20dfde4923c
 SHA512:
-  metadata.gz: d7c62d15765a2837cf0dcba5e9a0c63c89ecc73f33fbd5500284184a78027f80a4ad12d980b5ac5de8235550384bd123708a075adab0243a06202154348268a3
-  data.tar.gz: 24449c58e1bec9b3a31e925a27df17c56c7cd923f2cdd33a5d6781f1f253204776901e92fd4024d3340e4eeb533b043a71a1afeaacb046bcc6ea62d5e5444668
+  metadata.gz: 22866111b2a0ba3392d930c60548234f72c1f9dd27309a5b0c5ebff0b06232e5a59d2a6353db51d4c760abdafd90091a8ddf873808fb6cb53bbb755ebc7daf80
+  data.tar.gz: 16643b7af80d9d20e482a5be141e0ecd4733503ff9a80effcd03516af60270227c1c7d604b4b342c70a553e6fe729b83b9b8eb609f87cf9f5c6bde7e3177eb36

data/CHANGELOG.md

@@ -1,5 +1,36 @@
 ## master (unreleased)
 
+## 0.27.0 (2025-05-01)
+
+- **WARNING**: This release has breaking changes! See `docs/0.27-upgrade.md` for release notes
+
+- Add ability to run background data migrations in parallel
+
+    ```ruby
+    # Run 2 data migrations in parallel.
+    OnlineMigrations.run_background_data_migrations(concurrency: 2)
+    ```
+
+- Retry deadlocks by lock retrier
+- Fix copying check constraints on columns with similar names when changing column type
+
+## 0.26.0 (2025-04-28)
+
+- Drop support for Ruby < 3.1 and Rails < 7.1
+- Add check for `change_column` for columns with check constraints
+
+- Allow to require safety reason explanation when calling `safery_assured`
+
+  ```ruby
+  # config/initializers/online_migrations.rb
+  config.require_safety_assured_reason = true
+
+  # in migration
+  safety_assured("Table is small") do
+    add_index :users, :email, unique: true
+  end
+  ```
+
 ## 0.25.0 (2025-02-03)
 
 - Track start/finish time of background data migrations

data/README.md

@@ -16,8 +16,8 @@ See [comparison to `strong_migrations`](#comparison-to-strong_migrations)
 
 ## Requirements
 
-- Ruby 3.0+
-- Rails 7.0+
+- Ruby 3.1+
+- Rails 7.1+
 - PostgreSQL 12+
 
 For older Ruby and Rails versions you can use older versions of this gem.
@@ -64,76 +64,32 @@ An operation is classified as dangerous if it either:
 
 ## Example
 
-Consider the following migration:
-
-```ruby
-class AddAdminToUsers < ActiveRecord::Migration[8.0]
-  def change
-    add_column :users, :admin, :boolean, default: false, null: false
-  end
-end
-```
-
-If the `users` table is large, running this migration on a live PostgreSQL < 11 database will likely cause downtime.
-
-A safer approach would be to run something like the following:
-
-```ruby
-class AddAdminToUsers < ActiveRecord::Migration[8.0]
-  # Do not wrap the migration in a transaction so that locks are held for a shorter time.
-  disable_ddl_transaction!
-
-  def up
-    # Lower PostgreSQL's lock timeout to avoid statement queueing.
-    execute "SET lock_timeout TO '5s'" # The lock_timeout duration is customizable.
-
-    # Add the column without the default value and the not-null constraint.
-    add_column :users, :admin, :boolean
-
-    # Set the column's default value.
-    change_column_default :users, :admin, false
-
-    # Backfill the column in batches.
-    User.in_batches.update_all(admin: false)
-
-    # Add the not-null constraint. Beforehand, set a short statement timeout so that
-    # Postgres does not spend too much time performing the full table scan to verify
-    # the column contains no nulls.
-    execute "SET statement_timeout TO '5s'"
-    change_column_null :users, :admin, false
-  end
-
-  def down
-    remove_column :users, :admin
-  end
-end
-```
-
-When you actually run the original migration, you will get an error message:
+When you run a migration that's potentially dangerous, you'll see an error message like:
 
 ```txt
 ⚠️  [online_migrations] Dangerous operation detected ⚠️
 
-Adding a column with a non-null default blocks reads and writes while the entire table is rewritten.
-
+Active Record caches database columns at runtime, so if you drop a column, it can cause exceptions until your app reboots.
 A safer approach is to:
-1. add the column without a default value
-2. change the column default
-3. backfill existing rows with the new value
-4. add the NOT NULL constraint
 
-add_column_with_default takes care of all this steps:
+1. Ignore the column:
 
-class AddAdminToUsers < ActiveRecord::Migration[8.0]
-  disable_ddl_transaction!
+  class User < ApplicationRecord
+    self.ignored_columns += ["name"]
+  end
 
-  def change
-    add_column_with_default :users, :admin, :boolean, default: false, null: false
+2. Deploy
+3. Wrap column removing in a safety_assured { ... } block
+
+  class RemoveColumn < ActiveRecord::Migration[8.0]
+    def change
+      safety_assured { remove_column :users, :name }
+    end
   end
-end
-```
 
-It suggests how to safely implement a migration, which essentially runs the steps similar to described in the previous example.
+4. Remove column ignoring from step 1
+5. Deploy
+```
 
 ## Checks
 
@@ -1278,17 +1234,6 @@ Interesting reads:
 - [Stop worrying about PostgreSQL locks in your Rails migrations](https://medium.com/doctolib/stop-worrying-about-postgresql-locks-in-your-rails-migrations-3426027e9cc9)
 - [Avoiding integer overflows with zero downtime](https://buildkite.com/blog/avoiding-integer-overflows-with-zero-downtime)
 
-## Maybe TODO
-
-- support MySQL
-- support other ORMs
-
-Background migrations:
-
-- extract as a separate gem
-- add UI
-- support batching over non-integer and multiple columns
-
 ## Comparison to `strong_migrations`
 
 This gem was heavily inspired by the `strong_migrations` and GitLab's approaches to database migrations. This gem is a superset of `strong_migrations`, feature-wise, and has the same APIs.

data/docs/0.27-upgrade.md

@@ -0,0 +1,24 @@
+# Upgrading to online_migrations 0.27.0
+
+In this version, background data migrations internals were significantly refactored and rewritten, that allowed to make the gem much simpler and its API more flexible and not attached to a single use case (whole table data migrations). It relies on [Sidekiq's Iteration feature](https://github.com/sidekiq/sidekiq/wiki/Iteration), so having Sidekiq 7.3.3+ is a hard requirement for background data migrations feature to work now.
+
+This is one of the preceding releases before v1.0.
+
+To upgrade:
+
+* Upgrade gem to v0.27: `gem 'online_migrations', '~> 0.27.0'`
+* Upgrade the gem's initializer in `config/online_migrations.rb` by referring to the [newest contents](https://github.com/fatkodima/online_migrations/blob/master/lib/generators/online_migrations/templates/initializer.rb.tt)
+
+If you don't use any of the [background data migrations](docs/background_data_migrations.md) or [background schema migrations](docs/background_schema_migrations.md), then this is probably all you need.
+
+If you use background data migrations:
+
+* Make sure all existing background data migrations completed before upgrading
+
+* Get the latest schema changes
+  ```sh
+  $ bin/rails generate online_migrations:upgrade
+  $ bin/rails db:migrate
+  ```
+
+Look at [background data migrations guide](docs/background_data_migrations.md) to find the API changes and new features.