actual_db_schema 0.7.9 → 0.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5a0d117f27b4bd908cbc04b0d3ca0faf0297a5feed5fd4f869c5672a50fc3cd9
-  data.tar.gz: cf0f37bc743eb44c8c5f6350454cc7f84f1781c8a8bc06ef25eb878830d7b973
+  metadata.gz: 43a6d3a4c89ea984fe7b4cbc6160a9f459951bac207d2592b609ae0a7606fd76
+  data.tar.gz: ac2dcb733bb87bdf8dcf5daa250eb386e0ac15f99297d0feb53815e308fb3915
 SHA512:
-  metadata.gz: 50f4a4cd52039cd29d308676028a51fd7f44e25b89084e03c2ca570361c3c556f13bc924989415d04164967b63aadf0d88709c0f58289947fd2cf6a164f7f6dc
-  data.tar.gz: bd471eb79d28d9cf124452fe6e5608eb2a092800b4c49f1299348adf7a7c2a9d6a9bcd85da3f0cc6272753f743862e84b9777bab0cf095def8b9d1180a910e49
+  metadata.gz: 1bd9b3d3ed5145aacc2d0a481742dc3a45e707257dc3290de245ca4e6ce8db26aaad75619bb0212273aedc6dc30c833e0e604d84c5a1711ea0d1bf8d0cef0dc2
+  data.tar.gz: bbc183547eeb23566c326405519120af7e4e1aea2525ade5c7f8711985d90b6d3d142322bcc19b955a1605f58074420c28657646a16be8c667d47aeae2531ebc

data/CHANGELOG.md

@@ -1,3 +1,9 @@
+## [0.8.0] - 2024-12-30
+- Enhanced Console Visibility: Automatically rolled-back phantom migrations now provide clearer and more visible logs in the console
+- Git Hooks for Branch Management: Introduced hooks that automatically rollback phantom migrations after checking out a branch. Additionally, the schema migration rake task can now be executed automatically upon branch checkout
+- Temporary Folder Cleanup: Rolled-back phantom migrations are now automatically deleted from the temporary folder after rollback
+- Acronym Support in Phantom Migration Names: Resolved an issue where phantom migrations with acronyms in their names, defined in other branches, couldn't be rolled back automatically. These are now handled seamlessly
+
 ## [0.7.9] - 2024-09-07
 - Don't stop if a phantom migration rollback fails
 - Improve failed rollback of phantom migrations report

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    actual_db_schema (0.7.9)
+    actual_db_schema (0.8.0)
       activerecord
       activesupport
       csv
@@ -93,7 +93,7 @@ GEM
     concurrent-ruby (1.2.2)
     connection_pool (2.4.1)
     crass (1.0.6)
-    csv (3.3.0)
+    csv (3.3.2)
     date (3.3.3)
     debug (1.8.0)
       irb (>= 1.5.0)

data/README.md

@@ -110,6 +110,40 @@ Add the following line to your initializer file (`config/initializers/actual_db_
 ActualDbSchema.config[:auto_rollback_disabled] = true
 ```
 
+## Automatic Phantom Migration Rollback On Branch Switch
+
+By default, the automatic rollback of migrations on branch switch is disabled. If you prefer to automatically rollback phantom migrations whenever you switch branches with `git checkout`, you can enable it in two ways:
+
+### 1. Using Environment Variable
+
+Set the environment variable `ACTUAL_DB_SCHEMA_GIT_HOOKS_ENABLED` to `true`:
+
+```sh
+export ACTUAL_DB_SCHEMA_GIT_HOOKS_ENABLED=true
+```
+
+### 2. Using Initializer
+Add the following line to your initializer file (`config/initializers/actual_db_schema.rb`):
+
+```ruby
+ActualDbSchema.config[:git_hooks_enabled] = true
+```
+
+### Installing the Post-Checkout Hook
+After enabling Git hooks in your configuration, run the rake task to install the post-checkout hook:
+
+```sh
+rake actual_db_schema:install_git_hooks
+```
+
+This task will prompt you to choose one of the three options:
+
+1. Rollback phantom migrations with `db:rollback_branches`
+2. Migrate up to the latest schema with `db:migrate`
+3. Skip installing git hook
+
+Based on your selection, a post-checkout hook will be installed or updated in your `.git/hooks` folder.
+
 ## Development
 
 After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake test` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.

data/actual_db_schema.gemspec

@@ -44,6 +44,18 @@ Gem::Specification.new do |spec|
   spec.add_development_dependency "rails"
   spec.add_development_dependency "sqlite3"
 
+  spec.post_install_message = <<~MSG
+    Thank you for installing ActualDbSchema!
+
+    To enable automatic rollback of phantom migrations when switching branches, follow these steps:
+    1. Set `export ACTUAL_DB_SCHEMA_GIT_HOOKS_ENABLED=true` in your environment, OR
+       add `ActualDbSchema.config[:git_hooks_enabled] = true` to your initializer.
+    2. Run `rake actual_db_schema:install_git_hooks` to install the post-checkout Git hook.
+
+    For more information, see the README.
+
+  MSG
+
   # For more information and examples about making a new gem, check out our
   # guide at: https://bundler.io/guides/creating_gem.html
 end

data/lib/actual_db_schema/commands/rollback.rb

@@ -4,11 +4,8 @@ module ActualDbSchema
   module Commands
     # Rolls back all phantom migrations
     class Rollback < Base
-      UNICODE_COLORS = {
-        red: 31,
-        green: 32,
-        yellow: 33
-      }.freeze
+      include ActualDbSchema::OutputFormatter
+      include ActionView::Helpers::TextHelper
 
       def initialize(context, manual_mode: false)
         @manual_mode = manual_mode || manual_mode_default?
@@ -18,50 +15,63 @@ module ActualDbSchema
       private
 
       def call_impl
-        context.rollback_branches(manual_mode: @manual_mode)
+        rolled_back = context.rollback_branches(manual_mode: @manual_mode)
 
-        return if ActualDbSchema.failed.empty?
+        return unless rolled_back
 
-        puts_preamble
-        puts_into
-        puts ""
-        puts failed_migrations_list
-        puts_preamble
+        ActualDbSchema.failed.empty? ? print_success : print_error
+      end
+
+      def print_success
+        puts colorize("[ActualDbSchema] All phantom migrations rolled back successfully! 🎉", :green)
+      end
+
+      def print_error
+        header_message = <<~HEADER
+          #{ActualDbSchema.failed.count} phantom migration(s) could not be rolled back automatically.
+
+          Try these steps to fix and move forward:
+            1. Ensure the migrations are reversible (define #up and #down methods or use #reversible).
+            2. If the migration references code or tables from another branch, restore or remove them.
+            3. Once fixed, run `rails db:migrate` again.
+
+          Below are the details of the problematic migrations:
+        HEADER
+
+        print_error_summary("#{header_message}\n#{failed_migrations_list}")
       end
 
       def failed_migrations_list
         ActualDbSchema.failed.map.with_index(1) do |failed, index|
-          filename = failed.short_filename
-          exception = failed.exception
-          <<~MSG
-            \t#{colorize("[Migration##{index}]", :yellow)}
-            \t- #{filename}
-
-            \t\t#{exception.inspect.gsub("\n", "\n\t  ")}
-          MSG
-        end
+          <<~MIGRATION
+            #{colorize("Migration ##{index}:", :yellow)}
+              File: #{failed.short_filename}
+              Branch: #{failed.branch}
+          MIGRATION
+        end.join("\n")
       end
 
-      def puts_preamble
-        puts ""
-        puts %(\u2757\u2757\u2757 #{colorize("[ActualDbSchema]", :red)})
-        puts ""
+      def print_error_summary(content)
+        width = 100
+        indent = 4
+        gem_name = "ActualDbSchema"
+
+        puts colorize("╔═ [#{gem_name}] #{"═" * (width - gem_name.length - 5)}╗", :red)
+        print_wrapped_content(content, width, indent)
+        puts colorize("╚#{"═" * width}╝", :red)
       end
 
-      def puts_into
-        msg = "#{ActualDbSchema.failed.count} phantom migration(s) could not be rolled back automatically."
-        msg += " Roll them back or fix manually:"
-        puts colorize(msg, :red)
+      def print_wrapped_content(content, width, indent)
+        usable_width = width - indent - 4
+        wrapped_content = word_wrap(content, line_width: usable_width)
+        wrapped_content.each_line do |line|
+          puts "#{" " * indent}#{line.chomp}"
+        end
       end
 
       def manual_mode_default?
         ActualDbSchema.config[:auto_rollback_disabled]
       end
-
-      def colorize(text, color)
-        code = UNICODE_COLORS.fetch(color, 37)
-        "\e[#{code}m#{text}\e[0m"
-      end
     end
   end
 end

data/lib/actual_db_schema/failed_migration.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module ActualDbSchema
-  FailedMigration = Struct.new(:migration, :exception, keyword_init: true) do
+  FailedMigration = Struct.new(:migration, :exception, :branch, keyword_init: true) do
     def filename
       migration.filename
     end

data/lib/actual_db_schema/git_hooks.rb

@@ -0,0 +1,184 @@
+# frozen_string_literal: true
+
+require "fileutils"
+
+module ActualDbSchema
+  # Handles the installation of a git post-checkout hook that rolls back phantom migrations when switching branches
+  class GitHooks # rubocop:disable Metrics/ClassLength
+    include ActualDbSchema::OutputFormatter
+
+    POST_CHECKOUT_MARKER_START = "# >>> BEGIN ACTUAL_DB_SCHEMA"
+    POST_CHECKOUT_MARKER_END   = "# <<< END ACTUAL_DB_SCHEMA"
+
+    POST_CHECKOUT_HOOK_ROLLBACK = <<~BASH
+      #{POST_CHECKOUT_MARKER_START}
+      # ActualDbSchema post-checkout hook (ROLLBACK)
+      # Runs db:rollback_branches on branch checkout.
+
+      if [ -f ./bin/rails ]; then
+        if [ -n "$ACTUAL_DB_SCHEMA_GIT_HOOKS_ENABLED" ]; then
+          GIT_HOOKS_ENABLED="$ACTUAL_DB_SCHEMA_GIT_HOOKS_ENABLED"
+        else
+          GIT_HOOKS_ENABLED=$(./bin/rails runner "puts ActualDbSchema.config[:git_hooks_enabled]" 2>/dev/null)
+        fi
+
+        if [ "$GIT_HOOKS_ENABLED" == "true" ]; then
+          ./bin/rails db:rollback_branches
+        fi
+      fi
+      #{POST_CHECKOUT_MARKER_END}
+    BASH
+
+    POST_CHECKOUT_HOOK_MIGRATE = <<~BASH
+      #{POST_CHECKOUT_MARKER_START}
+      # ActualDbSchema post-checkout hook (MIGRATE)
+      # Runs db:migrate on branch checkout.
+
+      if [ -f ./bin/rails ]; then
+        if [ -n "$ACTUAL_DB_SCHEMA_GIT_HOOKS_ENABLED" ]; then
+          GIT_HOOKS_ENABLED="$ACTUAL_DB_SCHEMA_GIT_HOOKS_ENABLED"
+        else
+          GIT_HOOKS_ENABLED=$(./bin/rails runner "puts ActualDbSchema.config[:git_hooks_enabled]" 2>/dev/null)
+        fi
+
+        if [ "$GIT_HOOKS_ENABLED" == "true" ]; then
+          ./bin/rails db:migrate
+        fi
+      fi
+      #{POST_CHECKOUT_MARKER_END}
+    BASH
+
+    def initialize(strategy: :rollback)
+      @strategy = strategy
+    end
+
+    def install_post_checkout_hook
+      return unless git_hooks_enabled?
+      return unless hooks_directory_present?
+
+      if File.exist?(hook_path)
+        handle_existing_hook
+      else
+        create_new_hook
+      end
+    end
+
+    private
+
+    def hook_code
+      @strategy == :migrate ? POST_CHECKOUT_HOOK_MIGRATE : POST_CHECKOUT_HOOK_ROLLBACK
+    end
+
+    def hooks_dir
+      @hooks_dir ||= Rails.root.join(".git", "hooks")
+    end
+
+    def hook_path
+      @hook_path ||= hooks_dir.join("post-checkout")
+    end
+
+    def git_hooks_enabled?
+      return true if ActualDbSchema.config[:git_hooks_enabled]
+
+      puts colorize("[ActualDbSchema] Git hooks are disabled in configuration. Skipping installation.", :gray)
+    end
+
+    def hooks_directory_present?
+      return true if Dir.exist?(hooks_dir)
+
+      puts colorize("[ActualDbSchema] .git/hooks directory not found. Please ensure this is a Git repository.", :gray)
+    end
+
+    def handle_existing_hook
+      return update_hook if markers_exist?
+      return install_hook if safe_install?
+
+      show_manual_install_instructions
+    end
+
+    def create_new_hook
+      contents = <<~BASH
+        #!/usr/bin/env bash
+
+        #{hook_code}
+      BASH
+
+      write_hook_file(contents)
+      print_success
+    end
+
+    def markers_exist?
+      contents = File.read(hook_path)
+      contents.include?(POST_CHECKOUT_MARKER_START) && contents.include?(POST_CHECKOUT_MARKER_END)
+    end
+
+    def update_hook
+      contents = File.read(hook_path)
+      new_contents = replace_marker_contents(contents)
+
+      if new_contents == contents
+        message = "[ActualDbSchema] post-checkout git hook already contains the necessary code. Nothing to update."
+        puts colorize(message, :gray)
+      else
+        write_hook_file(new_contents)
+        puts colorize("[ActualDbSchema] post-checkout git hook updated successfully at #{hook_path}", :green)
+      end
+    end
+
+    def replace_marker_contents(contents)
+      contents.gsub(
+        /#{Regexp.quote(POST_CHECKOUT_MARKER_START)}.*#{Regexp.quote(POST_CHECKOUT_MARKER_END)}/m,
+        hook_code.strip
+      )
+    end
+
+    def safe_install?
+      puts colorize("[ActualDbSchema] A post-checkout hook already exists at #{hook_path}.", :gray)
+      puts "Overwrite the existing hook at #{hook_path}? [y,n] "
+
+      answer = $stdin.gets.chomp.downcase
+      answer.start_with?("y")
+    end
+
+    def install_hook
+      contents = File.read(hook_path)
+      new_contents = <<~BASH
+        #{contents.rstrip}
+
+        #{hook_code}
+      BASH
+
+      write_hook_file(new_contents)
+      print_success
+    end
+
+    def show_manual_install_instructions
+      puts colorize("[ActualDbSchema] You can follow these steps to manually install the hook:", :yellow)
+      puts <<~MSG
+
+        1. Open the existing post-checkout hook at:
+           #{hook_path}
+
+        2. Insert the following lines into that file (preferably at the end or in a relevant section).
+           Make sure you include the #{POST_CHECKOUT_MARKER_START} and #{POST_CHECKOUT_MARKER_END} lines:
+
+        #{hook_code}
+
+        3. Ensure the post-checkout file is executable:
+           chmod +x #{hook_path}
+
+        4. Done! Now when you switch branches, phantom migrations will be rolled back automatically (if enabled).
+
+      MSG
+    end
+
+    def write_hook_file(contents)
+      File.open(hook_path, "w") { |file| file.write(contents) }
+      FileUtils.chmod("+x", hook_path)
+    end
+
+    def print_success
+      puts colorize("[ActualDbSchema] post-checkout git hook installed successfully at #{hook_path}", :green)
+    end
+  end
+end

data/lib/actual_db_schema/output_formatter.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module ActualDbSchema
+  # Provides functionality for formatting terminal output with colors
+  module OutputFormatter
+    UNICODE_COLORS = {
+      red: 31,
+      green: 32,
+      yellow: 33,
+      gray: 90
+    }.freeze
+
+    def colorize(text, color)
+      code = UNICODE_COLORS.fetch(color, 37)
+      "\e[#{code}m#{text}\e[0m"
+    end
+  end
+end

data/lib/actual_db_schema/patches/migration_context.rb

@@ -4,15 +4,22 @@ module ActualDbSchema
   module Patches
     # Add new command to roll back the phantom migrations
     module MigrationContext
+      include ActualDbSchema::OutputFormatter
+
       def rollback_branches(manual_mode: false)
+        rolled_back = false
+
         phantom_migrations.reverse_each do |migration|
           next unless status_up?(migration)
 
+          rolled_back = true
           show_info_for(migration) if manual_mode
           migrate(migration) if !manual_mode || user_wants_rollback?
         rescue StandardError => e
-          ActualDbSchema.failed << FailedMigration.new(migration: migration, exception: e)
+          handle_rollback_error(migration, e)
         end
+
+        rolled_back
       end
 
       def phantom_migrations
@@ -63,7 +70,7 @@ module ActualDbSchema
       end
 
       def show_info_for(migration)
-        puts "\n[ActualDbSchema] A phantom migration was found and is about to be rolled back."
+        puts colorize("\n[ActualDbSchema] A phantom migration was found and is about to be rolled back.", :gray)
         puts "Please make a decision from the options below to proceed.\n\n"
         puts "Branch: #{branch_for(migration.version.to_s)}"
         puts "Database: #{ActualDbSchema.db_config[:database]}"
@@ -72,9 +79,21 @@ module ActualDbSchema
       end
 
       def migrate(migration)
+        migration.name = extract_class_name(migration.filename)
+
+        message = "[ActualDbSchema] Rolling back phantom migration #{migration.version} #{migration.name} " \
+            "(from branch: #{branch_for(migration.version.to_s)})"
+        puts colorize(message, :gray)
+
         migrator = down_migrator_for(migration)
         migrator.extend(ActualDbSchema::Patches::Migrator)
         migrator.migrate
+        File.delete(migration.filename)
+      end
+
+      def extract_class_name(filename)
+        content = File.read(filename)
+        content.match(/^class\s+([A-Za-z0-9_]+)\s+</)[1]
       end
 
       def branch_for(version)
@@ -84,6 +103,21 @@ module ActualDbSchema
       def metadata
         @metadata ||= ActualDbSchema::Store.instance.read
       end
+
+      def handle_rollback_error(migration, exception)
+        error_message = <<~ERROR
+          Error encountered during rollback:
+
+          #{exception.message.gsub(/^An error has occurred, all later migrations canceled:\s*/, "").strip}
+        ERROR
+
+        puts colorize(error_message, :red)
+        ActualDbSchema.failed << FailedMigration.new(
+          migration: migration,
+          exception: exception,
+          branch: branch_for(migration.version.to_s)
+        )
+      end
     end
   end
 end

data/lib/actual_db_schema/version.rb

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

data/lib/actual_db_schema.rb

@@ -9,9 +9,11 @@ require_relative "actual_db_schema/version"
 require_relative "actual_db_schema/migration"
 require_relative "actual_db_schema/failed_migration"
 require_relative "actual_db_schema/migration_context"
+require_relative "actual_db_schema/output_formatter"
 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/git_hooks"
 
 require_relative "actual_db_schema/commands/base"
 require_relative "actual_db_schema/commands/rollback"
@@ -29,7 +31,8 @@ module ActualDbSchema
   self.config = {
     enabled: Rails.env.development?,
     auto_rollback_disabled: ENV["ACTUAL_DB_SCHEMA_AUTO_ROLLBACK_DISABLED"].present?,
-    ui_enabled: Rails.env.development? || ENV["ACTUAL_DB_SCHEMA_UI_ENABLED"].present?
+    ui_enabled: Rails.env.development? || ENV["ACTUAL_DB_SCHEMA_UI_ENABLED"].present?,
+    git_hooks_enabled: ENV["ACTUAL_DB_SCHEMA_GIT_HOOKS_ENABLED"].present?
   }
 
   def self.migrated_folder

data/lib/tasks/actual_db_schema.rake

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+namespace :actual_db_schema do
+  desc "Install ActualDbSchema post-checkout git hook that rolls back phantom migrations when switching branches."
+  task :install_git_hooks do
+    extend ActualDbSchema::OutputFormatter
+
+    puts "Which Git hook strategy would you like to install? [1, 2, 3]"
+    puts "  1) Rollback phantom migrations (db:rollback_branches)"
+    puts "  2) Migrate up to latest (db:migrate)"
+    puts "  3) No hook installation (skip)"
+    answer = $stdin.gets.chomp
+
+    strategy =
+      case answer
+      when "1" then :rollback
+      when "2" then :migrate
+      else
+        :none
+      end
+
+    if strategy == :none
+      puts colorize("[ActualDbSchema] Skipping git hook installation.", :gray)
+    else
+      ActualDbSchema::GitHooks.new(strategy: strategy).install_post_checkout_hook
+    end
+  end
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: actual_db_schema
 version: !ruby/object:Gem::Version
-  version: 0.7.9
+  version: 0.8.0
 platform: ruby
 authors:
 - Andrei Kaleshka
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2024-09-06 00:00:00.000000000 Z
+date: 2024-12-30 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activerecord
@@ -148,13 +148,16 @@ files:
 - lib/actual_db_schema/engine.rb
 - lib/actual_db_schema/failed_migration.rb
 - lib/actual_db_schema/git.rb
+- lib/actual_db_schema/git_hooks.rb
 - lib/actual_db_schema/migration.rb
 - lib/actual_db_schema/migration_context.rb
+- lib/actual_db_schema/output_formatter.rb
 - lib/actual_db_schema/patches/migration_context.rb
 - lib/actual_db_schema/patches/migration_proxy.rb
 - lib/actual_db_schema/patches/migrator.rb
 - lib/actual_db_schema/store.rb
 - lib/actual_db_schema/version.rb
+- lib/tasks/actual_db_schema.rake
 - lib/tasks/db.rake
 - sig/actual_db_schema.rbs
 homepage: https://blog.widefix.com/actual-db-schema/
@@ -164,7 +167,16 @@ metadata:
   homepage_uri: https://blog.widefix.com/actual-db-schema/
   source_code_uri: https://github.com/widefix/actual_db_schema
   changelog_uri: https://blog.widefix.com/actual-db-schema//blob/main/CHANGELOG.md
-post_install_message:
+post_install_message: |+
+  Thank you for installing ActualDbSchema!
+
+  To enable automatic rollback of phantom migrations when switching branches, follow these steps:
+  1. Set `export ACTUAL_DB_SCHEMA_GIT_HOOKS_ENABLED=true` in your environment, OR
+     add `ActualDbSchema.config[:git_hooks_enabled] = true` to your initializer.
+  2. Run `rake actual_db_schema:install_git_hooks` to install the post-checkout Git hook.
+
+  For more information, see the README.
+
 rdoc_options: []
 require_paths:
 - lib
@@ -184,3 +196,4 @@ signing_key:
 specification_version: 4
 summary: Keep your DB and schema.rb consistent in dev branches.
 test_files: []
+...