actual_db_schema 0.5.0 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fc3d368f25e1d191f7a3e3b57215208ecc72cd6c7b40662e4898279b585d0d0e
-  data.tar.gz: a907caa6bad53ff65c4e257a85871350d3ab1aa6f8cce07710436d8a99f9b52c
+  metadata.gz: 116a62e0bbc1d2f43ad5e7654f732807bb6807520f26f33bfde84889601bb895
+  data.tar.gz: 63c36388ed0efa1d19b9daec936206b6580e22b1b04b25a0db3f058047c34b56
 SHA512:
-  metadata.gz: c5d79fe8513b58084f31a85274c130f4cd6983c271e64b042697ff7e38b5c3be0c4b3af71f5e7f47be09d167a12ca5c1844cdcde9f4e4063b2ac015bb84163cb
-  data.tar.gz: f9914a080827f0e906745cd7b1ff703d594a315e308059b3f614aeeea03d0aa571dc76a827186cdd0f073324bb9536c718891b06f4497f55ec5a48c7447f24de
+  metadata.gz: ef27b62051c6183b68a35018b0ed7f402f25f8de2f3d3da8f842b914c13516a49b00ab57687a513bca04b664fc682b40c93c75929e414dfea514c2e0065a68b9
+  data.tar.gz: 7a7f0ce3ef0ce09a5a0ecf90ff0aec292ae6f9ab58050ce946dd849123b36162398592a9249ea9ec4acecbe9cfe2031737cbe16c5c0b5ef89989ebb48237fee9

data/CHANGELOG.md

@@ -1,3 +1,8 @@
+## [0.6.0] - 2024-01-03
+
+- Added db:phantom_migrations task to display phantom migrations
+- Updated README
+
 ## [0.5.0] - 2023-11-06
 
 - Rails 7.1 support added

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    actual_db_schema (0.5.0)
+    actual_db_schema (0.6.0)
       activerecord (>= 6.0.0)
       activesupport (>= 6.0.0)
 

data/README.md

@@ -2,7 +2,37 @@
 
 # ActualDbSchema
 
-Keep Rails DB schema consistent while switching between branches with no additional actions.
+Does switching between branches in your Rails app mess up the DB schema?
+
+Keep the DB schema actual across branches in your Rails project. Just install `actual_db_schema` gem and run `db:migrate` in branches as usual. It automatically rolls back the *phantom migrations* (non-relevant to the current branch). No additional steps are needed.
+
+## Why ActualDbSchema
+
+Still not clear why it's needed? To grasp the purpose of this gem and the issue it addresses, review the problem definition outlined below.
+
+### The problem definition
+
+Imagine you're working on **branch A**. You add a not-null column to a database table with a migration. You run the migration. Then you switch to **branch B**. The code in **branch B** isn't aware of this newly added field. When it tries to write data to the table, it fails with an error `null value provided for non-null field`. Why? The existing code is writing a null value into the column with a not-null constraint.
+
+Here's an example of this error:
+
+    ActiveRecord::NotNullViolation:
+      PG::NotNullViolation: ERROR:  null value in column "log" of relation "check_results" violates not-null constraint
+      DETAIL:  Failing row contains (8, 46, success, 2022-10-16 21:47:21.07212, 2022-10-16 21:47:21.07212, null).
+
+Furthermore, the `db:migrate` task on **branch B** generates an irrelevant diff on the `schema.rb` file, reflecting the new column added in **branch A**.
+
+To fix this, you need to switch back to **branch A**, find the migration that added the problematic field, and roll it back. We'll call it a *phantom migration*. It's a pain, especially if you have a lot of branches in your project because you have to remember which branch the *phantom migration* is in and then manually roll it back.
+
+With `actual_db_schema` gem you don't need to care about that anymore. It saves you time by handling all this dirty work behind the scenes automatically.
+
+### How it solves the issue
+
+This gem stores all run migrations with their code in the `tmp/migrations` folder. Whenever you perform a schema dump, it rolls back the *phantom migrations*.
+
+The *phantom migrations* list is the difference between the migrations you've executed (in the `tmp/migrations` folder) and the current ones (in the `db/migrate` folder).
+
+Therefore, all you do is run rails `db:migrate` in your current branch. `actual_db_schema` will ensure the DB schema is up-to-date. You'll never have an inaccurate `schema.rb` file again.
 
 ## Installation
 
@@ -20,28 +50,14 @@ And then execute:
 
 ## Usage
 
-TLTR; Just run `rails db:migrate` inside the current branch.
-
-In **branch A** I add a mandatory (not null) field into DB via migration and run it.
-Then I switch to another **branch B**. This branch's code is not aware of that field.
-As the result, the code is failing with an error "null value provided for non-null field".
-Moreover, a DB rake task generates a diff on `schema.rb` that's not relevant to this branch.
-I can switch to **branch A** and roll back the migration, but I need to remember that branch or waste time on it.
-
-Some example of this error:
-
-     ActiveRecord::NotNullViolation:
-       PG::NotNullViolation: ERROR:  null value in column "log" of relation "check_results" violates not-null constraint
-       DETAIL:  Failing row contains (8, 46, success, 2022-10-16 21:47:21.07212, 2022-10-16 21:47:21.07212, null).
-
-This gem saves all run migrations inside `tmp/migrations` folder.
-Every run of schema dump (that's a dependency of `db:migrate` task as well) rolls back the "unknown" for the current branch migrations
-looking into the `tmp/migrations` folder.
+Just run `rails db:migrate` inside the current branch.
 
-You just need to run `rails db:migrate` in the current branch to actualize the DB schema. With its hand, you will never have wrongly generated `schema.rb`.
+> [!WARNING]
+> This solution implies that all migrations are reversible. The irreversible migrations should be solved manually. At the moment, the gem ignores them. You will see warnings in the terminal for each irreversible migrations.
 
-> **Warning**
-> This solution implies that all migrations are reversible. The cases with irreversible migrations should be solved manually. At the moment, these migrations are ignored by the gem and you will see a warning if some migrations can't roll back automatically.
+The gem offers the following rake tasks that can be manually run according to your preferences:
+- `rails db:rollback_branches` - run it to manually rolls back phantom migrations.
+- `rails db:phantom_migrations` - displays a list of phantom migrations.
 
 ## Development
 

data/lib/actual_db_schema/commands/base.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module ActualDbSchema
+  module Commands
+    # Base class for all commands
+    class Base
+      def call
+        unless ActualDbSchema.config.fetch(:enabled, true)
+          raise "ActualDbSchema is disabled. Set ActualDbSchema.config[:enabled] = true to enable it."
+        end
+
+        if ActiveRecord::Migration.current_version >= 6
+          ActiveRecord::Tasks::DatabaseTasks.raise_for_multi_db(command: "db:rollback_branches")
+        end
+
+        call_impl
+      end
+
+      private
+
+      def call_impl
+        raise NotImplementedError
+      end
+
+      def context
+        @context ||=
+          ActiveRecord::Base.connection.migration_context.tap do |c|
+            c.extend(ActualDbSchema::Patches::MigrationContext)
+          end
+      end
+    end
+  end
+end

data/lib/actual_db_schema/commands/list.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module ActualDbSchema
+  module Commands
+    # Shows the list of phantom migrations
+    class List < Base
+      private
+
+      def call_impl
+        preambule
+        table
+      end
+
+      def indexed_phantom_migrations
+        @indexed_phantom_migrations ||= context.migrations.index_by { |m| m.version.to_s }
+      end
+
+      def preambule
+        puts "\nPhantom migrations\n\n"
+        puts "Below is a list of irrelevant migrations executed in unmerged branches."
+        puts "To bring your database schema up to date, the migrations marked as \"up\" should be rolled back."
+        puts "\ndatabase: #{ActiveRecord::Base.connection_db_config.database}\n\n"
+        puts %(#{"Status".center(8)}  #{"Migration ID".ljust(14)}  Migration File)
+        puts "-" * 50
+      end
+
+      def table
+        context.migrations_status.each do |status, version|
+          migration = indexed_phantom_migrations[version]
+          next unless migration
+
+          puts %(#{status.center(8)}  #{version.to_s.ljust(14)}  #{migration.filename.gsub("#{Rails.root}/", "")})
+        end
+      end
+    end
+  end
+end

data/lib/actual_db_schema/commands/rollback.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module ActualDbSchema
+  module Commands
+    # Rolls back all phantom migrations
+    class Rollback < Base
+      private
+
+      def call_impl
+        context.rollback_branches
+
+        return if ActualDbSchema.failed.empty?
+
+        puts ""
+        puts "[ActualDbSchema] Irreversible migrations were found from other branches. Roll them back or fix manually:"
+        puts ""
+        puts ActualDbSchema.failed.map { |migration| "- #{migration.filename}" }.join("\n")
+        puts ""
+      end
+    end
+  end
+end

data/lib/actual_db_schema/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module ActualDbSchema
-  VERSION = "0.5.0"
+  VERSION = "0.6.0"
 end

data/lib/actual_db_schema.rb

@@ -6,6 +6,10 @@ require_relative "actual_db_schema/patches/migration_proxy"
 require_relative "actual_db_schema/patches/migrator"
 require_relative "actual_db_schema/patches/migration_context"
 
+require_relative "actual_db_schema/commands/base"
+require_relative "actual_db_schema/commands/rollback"
+require_relative "actual_db_schema/commands/list"
+
 # The main module definition
 module ActualDbSchema
   raise NotImplementedError, "ActualDbSchema is only supported in Rails" unless defined?(Rails)

data/lib/tasks/db.rake

@@ -3,24 +3,12 @@
 namespace :db do
   desc "Rollback migrations that were run inside not a merged branch."
   task rollback_branches: :load_config do
-    unless ActualDbSchema.config.fetch(:enabled, true)
-      raise "ActualDbSchema is disabled. Set ActualDbSchema.config[:enabled] = true to enable it."
-    end
-
-    if ActiveRecord::Migration.current_version >= 6
-      ActiveRecord::Tasks::DatabaseTasks.raise_for_multi_db(command: "db:rollback_branches")
-    end
+    ActualDbSchema::Commands::Rollback.new.call
+  end
 
-    context = ActiveRecord::Base.connection.migration_context
-    context.extend(ActualDbSchema::Patches::MigrationContext)
-    context.rollback_branches
-    if ActualDbSchema.failed.any?
-      puts ""
-      puts "[ActualDbSchema] Irreversible migrations were found from other branches. Roll them back or fix manually:"
-      puts ""
-      puts ActualDbSchema.failed.map { |migration| "- #{migration.filename}" }.join("\n")
-      puts ""
-    end
+  desc "List all phantom migrations - non-relevant migrations that were run inside not a merged branch."
+  task phantom_migrations: :load_config do
+    ActualDbSchema::Commands::List.new.call
   end
 
   task _dump: :rollback_branches

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: actual_db_schema
 version: !ruby/object:Gem::Version
-  version: 0.5.0
+  version: 0.6.0
 platform: ruby
 authors:
 - Andrei Kaleshka
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2023-11-06 00:00:00.000000000 Z
+date: 2024-01-03 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activerecord
@@ -119,6 +119,9 @@ files:
 - gemfiles/rails.7.0.gemfile
 - gemfiles/rails.7.1.gemfile
 - lib/actual_db_schema.rb
+- lib/actual_db_schema/commands/base.rb
+- lib/actual_db_schema/commands/list.rb
+- lib/actual_db_schema/commands/rollback.rb
 - lib/actual_db_schema/patches/migration_context.rb
 - lib/actual_db_schema/patches/migration_proxy.rb
 - lib/actual_db_schema/patches/migrator.rb