actual_db_schema 0.9.1 → 0.10.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a1fd777a52ad2881a451c80498693f36267944c4fe1c1b6796582900ce968224
-  data.tar.gz: d051372a40ec8002d72ce969f30cb93f02f09c4cd60b3c151922caa501d21687
+  metadata.gz: f52b65d1b46f79d260c1e2d8c6fa768e03d991220954a88d7ff9f3c9f9e31a7b
+  data.tar.gz: c50d05e0800fd85c35cc84f570342e67af2c5212c1629cb93facfcde2dd6b749
 SHA512:
-  metadata.gz: b6b16965816aff4dbc9b5cdaa5422a6cb89a609f577d6f5dfc4b93df541067d3d111c1d66decc489a312d4e602460b86e32036ce1c3653fdb477a5075b2fa85c
-  data.tar.gz: 6c133a90fd82909e1beaac3db9735e98b5d790315a115e190880a428a5cba37b76921549884e947cc67667be5678dd8bc4c9e9bee9fded042be466331651dc2e
+  metadata.gz: 3d4af8729461e9c106215a72d78d22628217e1c1138307a39056fcd02e567f656ca6452b5eee20a82e886b141c11c35ce8eff51785758661cc3daa59d8fef259
+  data.tar.gz: 5ca66e12fdb0969b1a8296b945231286908069e789d6b7329fd84f3459a4d2c2d502621676cf220fade2bc628f1c5cf8c35cae8a8a101d5e99b2f711a63a0764

data/CHANGELOG.md

@@ -1,3 +1,14 @@
+## [0.10.0] - 2026-10-11
+
+- Remove the `parser` dependency and use `prism` directly.
+- Update the README and gem description to explain database synchronization, migration management, and schema diff troubleshooting.
+- Add an animated demo to the README; exclude demo media from the gem package.
+
+## [0.9.2] - 2026-06-14
+
+- Skip pending migrations in the UI
+- Restore original connection after iterating through connections
+
 ## [0.9.1] - 2026-02-25
 
 - Support schema diffs for `structure.sql`

data/Gemfile.lock

@@ -1,12 +1,10 @@
 PATH
   remote: .
   specs:
-    actual_db_schema (0.9.1)
+    actual_db_schema (0.10.0)
       activerecord
       activesupport
-      ast
       csv
-      parser
       prism
 
 GEM
@@ -96,7 +94,7 @@ GEM
     concurrent-ruby (1.2.2)
     connection_pool (2.4.1)
     crass (1.0.6)
-    csv (3.3.5)
+    csv (3.3.6)
     date (3.3.3)
     debug (1.8.0)
       irb (>= 1.5.0)

data/README.md

@@ -1,46 +1,91 @@
 [![Gem Version](https://badge.fury.io/rb/actual_db_schema.svg)](https://badge.fury.io/rb/actual_db_schema)
 
-# ActualDbSchema
+# ActualDbSchema: Keep Rails Databases in Sync with Git Branches
 
-**Stop database headaches when switching Git branches in Rails**
+**Manage stale migrations, fix database drift, and understand schema changes in Rails.**
 
-Keep your database schema perfectly synchronized across Git branches, eliminate broken tests and schema conflicts, and save wasted hours on phantom migrations.
+`actual_db_schema` keeps your database aligned with the migrations on your current Git branch. It tracks executed migration source code and rolls back **phantom migrations** left behind by other branches. It also provides a web dashboard, annotated schema diffs, migration history, and manual cleanup tools for development, staging, and sandbox environments.
 
-## 🚀 What You Get
+## Problems ActualDbSchema Solves
 
-- **Zero Manual Work**: Switch branches freely - phantom migrations roll back automatically
-- **No More Schema Conflicts**: Clean `schema.rb`/`structure.sql` diffs every time, no irrelevant changes
-- **Error Prevention**: Eliminates `ActiveRecord::NotNullViolation` and similar errors when switching branches
-- **Time Savings**: Stop hunting down which branch has the problematic migration
-- **Team Productivity**: Everyone stays focused on coding, not database maintenance
-- **Staging/Sandbox Sync**: Keep staging and sandbox databases aligned with your current branch code
-- **Visual Management**: Web UI to view and manage migrations across all databases
+### Database errors and failing tests after switching branches
 
-<img width="3024" height="1886" alt="Visual management of Rails DB migrations with ActualDbSchema" src="https://github.com/user-attachments/assets/87cfb7b4-6380-4dad-ab18-6a0633f561b5" />
+Switching Git branches changes your code and migration files, but does not undo migrations already applied to your database. A column, table, index, or constraint from another branch can break the application or its tests. For example, an extra `NOT NULL` column can cause `ActiveRecord::NotNullViolation` when the current branch inserts a record.
 
-And you get all of that with **zero** changes to your workflow!
+ActualDbSchema rolls back tracked migrations missing from the current branch, removing their database changes when their reversals succeed.
 
-## 🎯 The Problem This Solves
+### Manual rollback work when moving between feature branches
 
-**Before ActualDbSchema:**
-1. Work on Branch A → Add migration → Run migration
-2. Switch to Branch B → Code breaks with database errors
-3. Manually find and rollback the "phantom" migration
-4. Deal with irrelevant `schema.rb` diffs
-5. Repeat this tedious process constantly
+Without a stored copy of a migration, you may need to find the branch that introduced it, check it out, roll it back, and return to your work. These stale migrations are called **phantom migrations**: they have been applied to the database, but their files are absent from the current branch.
 
-**After ActualDbSchema:**
-1. Work on any branch → Add migrations as usual
-2. Switch branches freely → Everything just works
-3. Focus on building features, not fixing database issues
+The gem saves migration source code and branch metadata so it can identify and roll back phantom migrations without checking out their original branch. Cleanup runs as part of the schema dump triggered by `rails db:migrate`. An optional [post-checkout Git hook](#automatic-phantom-migration-rollback-on-branch-switch) runs cleanup when you switch branches. You can also inspect and roll back migrations manually through rake tasks or the web UI.
+
+### Unwanted schema.rb diffs and schema conflicts in Git
+
+**Why does `schema.rb` keep changing after `db:migrate`, even when you have not changed a migration?** Rails dumps your database's actual structure, including leftover tables, columns, and indexes from other branches. Those changes pollute `db/schema.rb` or `db/structure.sql` and can lead to unrelated pull request changes and Git merge conflicts.
+
+ActualDbSchema rolls back tracked phantom migrations before the schema dump, preventing their leftover changes from appearing in the generated file. Legitimate schema changes from the current branch still appear in the diff. Both schema formats are supported.
+
+### Rebuilding the entire database to clean up stale migrations
+
+Resetting a development database and replaying migrations can take time and discard local data. ActualDbSchema targets tracked phantom migrations instead of requiring a full database reset. Each rollback still executes the migration's reversal and can remove data in affected tables or columns.
+
+### Difficulty tracing a schema change to its migration
+
+When a schema diff contains unexpected changes, it can be hard to tell which migration introduced them. The [annotated schema diff](#schema-diff-with-migration-annotations) associates changes with migration source files, available through a rake task or the web UI. This helps you investigate a diff before deciding how to resolve it.
+
+### Missing visibility into migration history and database state
+
+The [web dashboard](#-web-interface) lets you inspect migration status, source code, branch metadata, and phantom migrations across configured databases. It supports individual migration actions and remains accessible when pending migrations would otherwise block Rails requests.
+
+### Orphaned migration versions with missing source files
+
+Your database can contain migration version records whose source files are no longer available. The [broken migration cleanup tools](#delete-broken-migrations) identify and delete these orphaned records through the UI or a rake task. Deleting a version record does **not** reverse its database changes; use phantom migration rollback when stored source code is available.
+
+### Database drift across multiple databases, tenants, and shared environments
+
+Branch-specific migrations can leave several databases or tenant schemas out of sync, not just the primary development database. ActualDbSchema processes configured databases, supports a configurable list of [tenant schemas](#multi-tenancy-support), and lets you [exclude infrastructure databases](#excluding-databases-from-processing).
+
+For staging or sandbox environments, optional [database-backed migration storage](#3-store-migrations-in-the-database) retains executed migration sources in the database rather than relying on one machine's local files. Features can be enabled per environment.
+
+### Friction when experimenting with schema changes in the Rails console
+
+The optional [console migrations](#console-migrations) feature exposes migration methods such as `add_column`, `add_index`, and `create_table` directly in the Rails console. This helps with local schema experiments and manual repairs; it does not create a migration file for you.
+
+## Example: Switch Branches Without Leaving Phantom Migrations Behind
+
+Suppose a feature branch adds a required `users.nickname` column. After switching to `main`, which has no such migration, inserts may fail because the application does not populate that column. The next schema dump can also add the unrelated column to `schema.rb`.
+
+With `actual_db_schema` installed ([Quick Start](#-quick-start)), keep using your normal workflow:
+
+```sh
+git switch main
+bundle exec rails db:migrate
+```
+
+The gem uses its stored migration source to roll back the phantom migration before Rails dumps the schema. When the rollback succeeds, the extra column is removed, fixing both the stale constraint and its unwanted schema diff.
+
+## Scope and Rollback Requirements
+
+The gem needs a stored copy of a migration to roll it back, so install it before running migrations you want it to track. Irreversible migrations and rollbacks that depend on unavailable branch code require manual intervention; failed rollbacks are reported. Phantom migrations are rolled back in reverse migration order.
+
+ActualDbSchema does not detect edits to an already-applied migration that remains on the current branch. Its schema cleanup targets phantom migrations; it does not sort schema columns or resolve every Git merge conflict.
+
+## Animated Demo
+
+[![ActualDbSchema animated demo](docs/actual_db_schema_demo.gif)](docs/actual_db_schema_h264.mp4)
+
+[Watch the full-resolution video](docs/actual_db_schema_h264.mp4)
+
+<img width="3024" height="1886" alt="ActualDbSchema Rails migration dashboard showing migration history and database management" src="https://github.com/user-attachments/assets/87cfb7b4-6380-4dad-ab18-6a0633f561b5" />
 
 ## 🌟 Complete Feature Set
 
 ### Core Migration Management
 - **Phantom Migration Detection**: Automatically identifies migrations from other branches
-- **Smart Rollback**: Rolls back phantom migrations in correct dependency order
-- **Irreversible Migration Handling**: Safely handles and reports irreversible migrations
-- **Multi-Database Support**: Works seamlessly with multiple database configurations
+- **Smart Rollback**: Rolls back phantom migrations in reverse migration order
+- **Rollback Failure Reporting**: Reports irreversible migrations and other rollback failures for manual resolution
+- **Multi-Database Support**: Processes multiple database configurations with configurable exclusions
 - **Schema Format Agnostic**: Supports both `schema.rb` and `structure.sql`
 
 ### Automation & Git Integration
@@ -65,8 +110,8 @@ And you get all of that with **zero** changes to your workflow!
 ### Team & Environment Support
 - **Multi-Tenant Compatible**: Works with apartment gem and similar multi-tenant setups
 - **Environment Flexibility**: Enable/disable features per environment
-- **Team Synchronization**: Keeps all team members' databases in sync
-- **CI/CD Friendly**: No interference with deployment pipelines
+- **Shared Migration Storage**: Optional database storage retains migration sources across environments
+- **Rollback Instrumentation**: Emits notifications for successful rollbacks and provides optional persisted statistics
 
 ### Manual Control Options
 - **Manual Rollback Mode**: Disable automatic rollback for full manual control
@@ -95,11 +140,11 @@ That's it! Now just run `rails db:migrate` as usual - phantom migrations roll ba
 
 ## 🔧 How It Works
 
-This gem stores all run migrations with their code in the `tmp/migrated` folder. Whenever you perform a schema dump, it rolls back the *phantom migrations*.
+This gem stores migrations executed while it is installed, including their source code, in the `tmp/migrated` folder by default. [Database storage](#3-store-migrations-in-the-database) is also available. Before the Rails `db:schema:dump` task runs, it attempts to roll back the *phantom migrations*.
 
 The *phantom migrations* list is the difference between the migrations you've executed (in the `tmp/migrated` 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.
+Run `rails db:migrate` in your current branch as usual. With automatic rollback enabled (the default), `actual_db_schema` rolls back tracked phantom migrations in reverse migration order before the schema dump, removing their leftover schema changes when the rollbacks succeed.
 
 ## Installation
 

data/actual_db_schema.gemspec

@@ -8,11 +8,10 @@ Gem::Specification.new do |spec|
   spec.authors = ["Andrei Kaleshka"]
   spec.email = ["ka8725@gmail.com"]
 
-  spec.summary = "Keep DB schema in sync across branches effortlessly."
+  spec.summary = "Keep Rails databases in sync across Git branches."
   spec.description = <<~DESC
-    Keep your DB schema in sync across all branches effortlessly.
-    Install once, then use `rails db:migrate` normally — the gem handles phantom migration rollback automatically, eliminating schema conflicts and inconsistent database states.
-    Stop wasting hours on DB maintenance locally, CI, staging/sandbox, or even production.
+    Keep Rails databases in sync across Git branches. Automatically roll back stale migrations,
+    prevent database errors and unwanted schema diffs, and inspect migration history with a web dashboard.
   DESC
   spec.homepage = "https://blog.widefix.com/actual-db-schema/"
   spec.license = "MIT"
@@ -28,7 +27,8 @@ Gem::Specification.new do |spec|
   # The `git ls-files -z` loads the files in the RubyGem that have been added into git.
   spec.files = Dir.chdir(File.expand_path(__dir__)) do
     `git ls-files -z`.split("\x0").reject do |f|
-      (f == __FILE__) || f.match(%r{\A(?:(?:bin|test|spec|features)/|\.(?:git|travis|circleci)|appveyor)})
+      (f == __FILE__) || %w[docs/actual_db_schema_h264.mp4 docs/actual_db_schema_demo.gif].include?(f) ||
+        f.match(%r{\A(?:(?:bin|test|spec|features)/|\.(?:git|travis|circleci)|appveyor)})
     end
   end
   spec.bindir = "exe"
@@ -38,9 +38,7 @@ Gem::Specification.new do |spec|
   # Uncomment to register a new dependency of your gem
   spec.add_runtime_dependency "activerecord"
   spec.add_runtime_dependency "activesupport"
-  spec.add_runtime_dependency "ast"
   spec.add_runtime_dependency "csv"
-  spec.add_runtime_dependency "parser"
   spec.add_runtime_dependency "prism"
 
   spec.add_development_dependency "appraisal"

data/lib/actual_db_schema/engine.rb

@@ -10,6 +10,13 @@ module ActualDbSchema
         app.routes.append do
           mount ActualDbSchema::Engine => "/rails"
         end
+
+        ActiveRecord::Migration::CheckPending.prepend(ActualDbSchema::Patches::CheckPending)
+
+        app.middleware.insert_before(
+          ActiveRecord::Migration::CheckPending,
+          ActualDbSchema::Middlewares::SkipPendingMigrationCheck
+        )
       end
     end
 

data/lib/actual_db_schema/middlewares/skip_pending_migration_check.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module ActualDbSchema
+  module Middlewares
+    # Middleware that skips the pending migration check for ActualDbSchema UI routes.
+    # This allows accessing /rails/ paths even when there are pending migrations.
+    class SkipPendingMigrationCheck
+      def initialize(app)
+        @app = app
+      end
+
+      def call(env)
+        if actual_db_schema_path?(env["PATH_INFO"], env["REQUEST_METHOD"])
+          env["actual_db_schema.skip_pending_check"] = true
+        end
+        @app.call(env)
+      end
+
+      private
+
+      def actual_db_schema_path?(path, method)
+        return false unless path.start_with?(engine_mount_path)
+
+        ActualDbSchema::Engine.routes.recognize_path(
+          path.sub(engine_mount_path, "") || "/",
+          method: method
+        )
+
+        true
+      rescue ActionController::RoutingError
+        false
+      end
+
+      def engine_mount_path
+        @engine_mount_path ||= ActualDbSchema::Engine.routes.find_script_name({})
+      end
+    end
+  end
+end

data/lib/actual_db_schema/migration_context.rb

@@ -6,10 +6,13 @@ module ActualDbSchema
     include Singleton
 
     def each
+      original_config = current_config
       configs.each do |db_config|
         establish_connection(db_config)
         yield context
       end
+    ensure
+      establish_connection(original_config) if original_config
     end
 
     private
@@ -19,6 +22,14 @@ module ActualDbSchema
       ActiveRecord::Base.establish_connection(config)
     end
 
+    def current_config
+      if ActiveRecord::Base.respond_to?(:connection_db_config)
+        ActiveRecord::Base.connection_db_config
+      else
+        ActiveRecord::Base.connection_config
+      end
+    end
+
     def configs
       all_configs = if ActiveRecord::Base.configurations.is_a?(Hash)
                       # Rails < 6.0 has a Hash in configurations

data/lib/actual_db_schema/migration_parser.rb

@@ -1,6 +1,5 @@
 # frozen_string_literal: true
 
-require "ast"
 require "prism"
 
 module ActualDbSchema
@@ -8,18 +7,6 @@ module ActualDbSchema
   module MigrationParser
     extend self
 
-    PARSER_MAPPING = {
-      add_column: ->(args) { parse_add_column(args) },
-      change_column: ->(args) { parse_change_column(args) },
-      remove_column: ->(args) { parse_remove_column(args) },
-      rename_column: ->(args) { parse_rename_column(args) },
-      add_index: ->(args) { parse_add_index(args) },
-      remove_index: ->(args) { parse_remove_index(args) },
-      rename_index: ->(args) { parse_rename_index(args) },
-      create_table: ->(args) { parse_create_table(args) },
-      drop_table: ->(args) { parse_drop_table(args) }
-    }.freeze
-
     def parse_all_migrations(dirs)
       changes_by_path = {}
       handled_files = Set.new
@@ -41,221 +28,233 @@ module ActualDbSchema
     private
 
     def parse_file(file_path)
-      Prism::Translation::Parser.parse_file(file_path)
+      parse_result = Prism.parse_file(file_path)
+      raise SyntaxError, "Migration #{file_path} is syntax invalid" unless parse_result.success?
+
+      parse_result.value
     end
 
     def find_migration_changes(node)
-      return [] unless node.is_a?(Parser::AST::Node)
-
-      changes = []
-      if node.type == :block
-        return process_block_node(node)
-      elsif node.type == :send
-        changes.concat(process_send_node(node))
-      end
-
-      node.children.each { |child| changes.concat(find_migration_changes(child)) if child.is_a?(Parser::AST::Node) }
-
-      changes
+      visitor = MigrationVisitor.new
+      visitor.visit(node)
+      visitor.changes
     end
 
-    def process_block_node(node)
-      changes = []
-      send_node = node.children.first
-      return changes unless send_node.type == :send
+    # Internal class used to process the AST and collect migration information.
+    class MigrationVisitor < Prism::Visitor
+      MAPPING = {
+        add_column: ->(visitor, args) { visitor.parse_add_column(args) },
+        change_column: ->(visitor, args) { visitor.parse_change_column(args) },
+        remove_column: ->(visitor, args) { visitor.parse_remove_column(args) },
+        rename_column: ->(visitor, args) { visitor.parse_rename_column(args) },
+        add_index: ->(visitor, args) { visitor.parse_add_index(args) },
+        remove_index: ->(visitor, args) { visitor.parse_remove_index(args) },
+        rename_index: ->(visitor, args) { visitor.parse_rename_index(args) },
+        create_table: ->(visitor, args) { visitor.parse_create_table(args) },
+        drop_table: ->(visitor, args) { visitor.parse_drop_table(args) }
+      }.freeze
+
+      attr_reader :changes
+
+      def initialize
+        super
+        @changes = []
+      end
 
-      method_name = send_node.children[1]
-      return changes unless method_name == :create_table
+      def visit_call_node(node)
+        arguments = node.arguments&.arguments
+        if node.block
+          return unless node.name == :create_table
 
-      change = parse_create_table_with_block(send_node, node)
-      changes << change if change
-      changes
-    end
+          change = parse_create_table_with_block(arguments, node.block)
+          @changes << change if change
+        elsif arguments && (parser = MAPPING[node.name])
+          change = parser.call(self, arguments)
+          @changes << change if change
 
-    def process_send_node(node)
-      changes = []
-      _receiver, method_name, *args = node.children
-      if (parser = PARSER_MAPPING[method_name])
-        change = parser.call(args)
-        changes << change if change
+          return
+        end
+        super
       end
 
-      changes
-    end
+      def parse_add_column(args)
+        return unless args.size >= 3
 
-    def parse_add_column(args)
-      return unless args.size >= 3
+        {
+          action: :add_column,
+          table: sym_value(args[0]),
+          column: sym_value(args[1]),
+          type: sym_value(args[2]),
+          options: parse_hash(args[3])
+        }
+      end
 
-      {
-        action: :add_column,
-        table: sym_value(args[0]),
-        column: sym_value(args[1]),
-        type: sym_value(args[2]),
-        options: parse_hash(args[3])
-      }
-    end
+      def parse_change_column(args)
+        return unless args.size >= 3
 
-    def parse_change_column(args)
-      return unless args.size >= 3
+        {
+          action: :change_column,
+          table: sym_value(args[0]),
+          column: sym_value(args[1]),
+          type: sym_value(args[2]),
+          options: parse_hash(args[3])
+        }
+      end
 
-      {
-        action: :change_column,
-        table: sym_value(args[0]),
-        column: sym_value(args[1]),
-        type: sym_value(args[2]),
-        options: parse_hash(args[3])
-      }
-    end
+      def parse_remove_column(args)
+        return unless args.size >= 2
 
-    def parse_remove_column(args)
-      return unless args.size >= 2
+        {
+          action: :remove_column,
+          table: sym_value(args[0]),
+          column: sym_value(args[1]),
+          options: parse_hash(args[2])
+        }
+      end
 
-      {
-        action: :remove_column,
-        table: sym_value(args[0]),
-        column: sym_value(args[1]),
-        options: parse_hash(args[2])
-      }
-    end
+      def parse_rename_column(args)
+        return unless args.size >= 3
 
-    def parse_rename_column(args)
-      return unless args.size >= 3
+        {
+          action: :rename_column,
+          table: sym_value(args[0]),
+          old_column: sym_value(args[1]),
+          new_column: sym_value(args[2])
+        }
+      end
 
-      {
-        action: :rename_column,
-        table: sym_value(args[0]),
-        old_column: sym_value(args[1]),
-        new_column: sym_value(args[2])
-      }
-    end
+      def parse_add_index(args)
+        return unless args.size >= 2
 
-    def parse_add_index(args)
-      return unless args.size >= 2
+        {
+          action: :add_index,
+          table: sym_value(args[0]),
+          columns: array_or_single_value(args[1]),
+          options: parse_hash(args[2])
+        }
+      end
 
-      {
-        action: :add_index,
-        table: sym_value(args[0]),
-        columns: array_or_single_value(args[1]),
-        options: parse_hash(args[2])
-      }
-    end
+      def parse_remove_index(args)
+        return unless args.size >= 1
 
-    def parse_remove_index(args)
-      return unless args.size >= 1
+        {
+          action: :remove_index,
+          table: sym_value(args[0]),
+          options: parse_hash(args[1])
+        }
+      end
 
-      {
-        action: :remove_index,
-        table: sym_value(args[0]),
-        options: parse_hash(args[1])
-      }
-    end
+      def parse_rename_index(args)
+        return unless args.size >= 3
 
-    def parse_rename_index(args)
-      return unless args.size >= 3
+        {
+          action: :rename_index,
+          table: sym_value(args[0]),
+          old_name: node_value(args[1]),
+          new_name: node_value(args[2])
+        }
+      end
 
-      {
-        action: :rename_index,
-        table: sym_value(args[0]),
-        old_name: node_value(args[1]),
-        new_name: node_value(args[2])
-      }
-    end
+      def parse_create_table(args)
+        return unless args.size >= 1
 
-    def parse_create_table(args)
-      return unless args.size >= 1
+        {
+          action: :create_table,
+          table: sym_value(args[0]),
+          options: parse_hash(args[1])
+        }
+      end
 
-      {
-        action: :create_table,
-        table: sym_value(args[0]),
-        options: parse_hash(args[1])
-      }
-    end
+      def parse_drop_table(args)
+        return unless args.size >= 1
 
-    def parse_drop_table(args)
-      return unless args.size >= 1
+        {
+          action: :drop_table,
+          table: sym_value(args[0]),
+          options: parse_hash(args[1])
+        }
+      end
 
-      {
-        action: :drop_table,
-        table: sym_value(args[0]),
-        options: parse_hash(args[1])
-      }
-    end
+      def parse_create_table_with_block(args, block_node)
+        columns = parse_create_table_columns(block_node.body)
+        {
+          action: :create_table,
+          table: sym_value(args[0]),
+          options: parse_hash(args[1]),
+          columns: columns
+        }
+      end
 
-    def parse_create_table_with_block(send_node, block_node)
-      args = send_node.children[2..]
-      columns = parse_create_table_columns(block_node.children[2])
-      {
-        action: :create_table,
-        table: sym_value(args[0]),
-        options: parse_hash(args[1]),
-        columns: columns
-      }
-    end
+      def parse_create_table_columns(statements_node)
+        return [] unless statements_node
 
-    def parse_create_table_columns(body_node)
-      return [] unless body_node
+        statements_node.body.map { |node| parse_column_node(node) }.compact
+      end
 
-      nodes = body_node.type == :begin ? body_node.children : [body_node]
-      nodes.map { |node| parse_column_node(node) }.compact
-    end
+      def parse_column_node(node)
+        return unless node.is_a?(Prism::CallNode)
 
-    def parse_column_node(node)
-      return unless node.is_a?(Parser::AST::Node) && node.type == :send
+        method = node.name
+        return parse_timestamps if method == :timestamps
 
-      method = node.children[1]
-      return parse_timestamps if method == :timestamps
+        arguments = node.arguments&.arguments
+        return unless arguments
 
-      {
-        column: sym_value(node.children[2]),
-        type: method,
-        options: parse_hash(node.children[3])
-      }
-    end
+        {
+          column: sym_value(arguments[0]),
+          type: method,
+          options: parse_hash(arguments[1])
+        }
+      end
 
-    def parse_timestamps
-      [
-        { column: :created_at, type: :datetime, options: { null: false } },
-        { column: :updated_at, type: :datetime, options: { null: false } }
-      ]
-    end
+      def parse_timestamps
+        [
+          { column: :created_at, type: :datetime, options: { null: false } },
+          { column: :updated_at, type: :datetime, options: { null: false } }
+        ]
+      end
 
-    def sym_value(node)
-      return nil unless node && node.type == :sym
+      def sym_value(node)
+        return nil unless node.is_a?(Prism::SymbolNode)
 
-      node.children.first
-    end
+        node.value.to_sym
+      end
 
-    def array_or_single_value(node)
-      return [] unless node
+      def array_or_single_value(node)
+        return [] unless node
 
-      if node.type == :array
-        node.children.map { |child| node_value(child) }
-      else
-        node_value(node)
+        if node.is_a?(Prism::ArrayNode)
+          node.elements.map { |child| node_value(child) }
+        else
+          node_value(node)
+        end
       end
-    end
 
-    def parse_hash(node)
-      return {} unless node && node.type == :hash
+      def parse_hash(node)
+        return {} unless node.is_a?(Prism::KeywordHashNode)
 
-      node.children.each_with_object({}) do |pair_node, result|
-        key_node, value_node = pair_node.children
-        key = sym_value(key_node) || node_value(key_node)
-        value = node_value(value_node)
-        result[key] = value
+        node.elements.each_with_object({}) do |assoc_node, result|
+          key_node = assoc_node.key
+          value_node = assoc_node.value
+          key = sym_value(key_node) || node_value(key_node)
+          value = node_value(value_node)
+          result[key] = value
+        end
       end
-    end
 
-    def node_value(node)
-      return nil unless node
-
-      case node.type
-      when :str, :sym, :int then node.children.first
-      when true then true
-      when false then false
-      when nil then nil
-      else
-        node.children.first
+      def node_value(node)
+        return nil unless node
+
+        case node
+        when Prism::StringNode then node.content
+        when Prism::SymbolNode then node.value.to_sym
+        when Prism::IntegerNode then node.value
+        when Prism::TrueNode then true
+        when Prism::FalseNode then false
+        when Prism::NilNode then nil
+        else
+          node
+        end
       end
     end
   end

data/lib/actual_db_schema/patches/check_pending.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module ActualDbSchema
+  module Patches
+    # Patches Rails' CheckPending middleware to skip the pending
+    # migration check for ActualDbSchema UI routes (/rails/).
+    module CheckPending
+      def call(env)
+        return @app.call(env) if env["actual_db_schema.skip_pending_check"]
+
+        super
+      end
+    end
+  end
+end

data/lib/actual_db_schema/schema_parser.rb

@@ -1,6 +1,5 @@
 # frozen_string_literal: true
 
-require "parser/ast/processor"
 require "prism"
 
 module ActualDbSchema
@@ -9,141 +8,121 @@ module ActualDbSchema
     module_function
 
     def parse_string(schema_content)
-      ast = Prism::Translation::Parser.parse(schema_content)
+      parse_result = Prism.parse(schema_content)
+      raise SyntaxError, "Schema is syntax invalid" unless parse_result.success?
 
-      collector = SchemaCollector.new
-      collector.process(ast)
-      collector.schema
+      visitor = SchemaVisitor.new
+      visitor.visit(parse_result.value)
+      visitor.schema
     end
 
-    # Internal class used to process the AST and collect schema information.
-    class SchemaCollector < Parser::AST::Processor
-      attr_reader :schema
+    # Internal class used to visit a create_table block
+    class CreateTableVisitor < Prism::Visitor
+      attr_reader :columns
 
-      def initialize
+      def initialize(block_arg)
         super()
-        @schema = {}
+        @block_arg = block_arg
+        @columns = {}
       end
 
-      def on_block(node)
-        send_node, _args_node, body = *node
+      def visit_call_node(node)
+        return unless node.receiver.is_a?(Prism::LocalVariableReadNode) && node.receiver.name == @block_arg
 
-        if create_table_call?(send_node)
-          table_name = extract_table_name(send_node)
-          columns    = extract_columns(body)
-          @schema[table_name] = columns if table_name
+        if node.name == :timestamps
+          name = "timestamps"
+          options = {}
+        else
+          name_arg, *, keyword_args = node.arguments&.arguments
+          name = extract_column_name(name_arg)
+          options = extract_column_options(keyword_args)
         end
+        return unless name
 
-        super
+        @columns[name] = { type: node.message.to_sym, options: options }
       end
 
-      def on_send(node)
-        _receiver, method_name, *args = *node
-        if method_name == :create_table && args.any?
-          table_name = extract_table_name(node)
-          @schema[table_name] ||= {}
+      def extract_column_name(node)
+        case node
+        when Prism::StringNode
+          node.content
+        when Prism::SymbolNode
+          node.value
         end
-
-        super
       end
 
-      private
-
-      def create_table_call?(node)
-        return false unless node.is_a?(Parser::AST::Node)
-
-        _receiver, method_name, *_args = node.children
-        method_name == :create_table
-      end
+      def extract_column_options(node)
+        return {} unless node.is_a?(Prism::KeywordHashNode)
 
-      def extract_table_name(send_node)
-        _receiver, _method_name, table_arg, *_rest = send_node.children
-        return unless table_arg
+        options = {}
+        node.elements.each do |assoc_node|
+          next unless assoc_node.is_a?(Prism::AssocNode)
+          next unless (key = extract_key(assoc_node.key))
 
-        case table_arg.type
-        when :str then table_arg.children.first
-        when :sym then table_arg.children.first.to_s
+          options[key] = extract_literal(assoc_node.value)
         end
+        options
       end
 
-      def extract_columns(body_node)
-        return {} unless body_node
-
-        children = body_node.type == :begin ? body_node.children : [body_node]
-
-        columns = {}
-        children.each do |expr|
-          col = process_column_node(expr)
-          columns[col[:name]] = { type: col[:type], options: col[:options] } if col && col[:name]
+      def extract_key(node)
+        case node
+        when Prism::SymbolNode then node.value.to_sym
+        when Prism::StringNode then node.content.to_sym
         end
-        columns
-      end
-
-      def process_column_node(node)
-        return unless node.is_a?(Parser::AST::Node)
-        return unless node.type == :send
-
-        receiver, method_name, column_node, *args = node.children
-
-        return unless receiver && receiver.type == :lvar
-
-        return { name: "timestamps", type: :timestamps, options: {} } if method_name == :timestamps
-
-        col_name = extract_column_name(column_node)
-        options  = extract_column_options(args)
-
-        { name: col_name, type: method_name, options: options }
       end
 
-      def extract_column_name(node)
-        return nil unless node.is_a?(Parser::AST::Node)
-
-        case node.type
-        when :str then node.children.first
-        when :sym then node.children.first.to_s
+      def extract_literal(node)
+        case node
+        when Prism::TrueNode then true
+        when Prism::FalseNode then false
+        when Prism::IntegerNode then node.value
+        when Prism::SymbolNode then node.value.to_sym
+        when Prism::StringNode then node.content
         end
       end
+    end
 
-      def extract_column_options(args)
-        opts = {}
-        args.each do |arg|
-          next unless arg && arg.type == :hash
+    # Internal class used to process the AST and collect schema information.
+    class SchemaVisitor < Prism::Visitor
+      attr_reader :schema
 
-          opts.merge!(parse_hash(arg))
-        end
-        opts
+      def initialize
+        super
+        @schema = {}
       end
 
-      def parse_hash(node)
-        hash = {}
-        return hash unless node && node.type == :hash
+      def visit_call_node(node)
+        if node.name == :create_table
+          return unless node.block
+
+          table_name = extract_table_name(node)
+          return unless table_name
 
-        node.children.each do |pair|
-          key_node, value_node = pair.children
-          key = extract_key(key_node)
-          value = extract_literal(value_node)
-          hash[key] = value
+          columns = extract_columns(node.block)
+          @schema[table_name] = columns
+          return
         end
-        hash
+        super
       end
 
-      def extract_key(node)
-        return unless node.is_a?(Parser::AST::Node)
+      private
 
-        case node.type
-        when :sym then node.children.first
-        when :str then node.children.first.to_sym
+      def extract_table_name(call_node)
+        first_arg = call_node.arguments&.arguments&.first
+        case first_arg
+        when Prism::StringNode
+          first_arg.content
+        when Prism::SymbolNode
+          first_arg.value
         end
       end
 
-      def extract_literal(node)
-        return unless node.is_a?(Parser::AST::Node)
+      def extract_columns(block_node)
+        return unless (block_arg = block_node.locals&.first)
 
-        case node.type
-        when :int, :str, :sym then node.children.first
-        when true then true
-        when false then false
-        end
+        v = CreateTableVisitor.new(block_arg)
+        v.visit(block_node)
+        v.columns
       end
     end
   end

data/lib/actual_db_schema/version.rb

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

data/lib/actual_db_schema.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require_relative "actual_db_schema/middlewares/skip_pending_migration_check"
 require "actual_db_schema/engine"
 require "active_record/migration"
 require "csv"
@@ -14,6 +15,7 @@ require_relative "actual_db_schema/failed_migration"
 require_relative "actual_db_schema/migration_context"
 require_relative "actual_db_schema/migration_parser"
 require_relative "actual_db_schema/output_formatter"
+require_relative "actual_db_schema/patches/check_pending"
 require_relative "actual_db_schema/patches/migration_proxy"
 require_relative "actual_db_schema/patches/migrator"
 require_relative "actual_db_schema/patches/migration_context"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: actual_db_schema
 version: !ruby/object:Gem::Version
-  version: 0.9.1
+  version: 0.10.0
 platform: ruby
 authors:
 - Andrei Kaleshka
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-02-25 00:00:00.000000000 Z
+date: 2026-10-11 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activerecord
@@ -38,20 +38,6 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
-- !ruby/object:Gem::Dependency
-  name: ast
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
-  type: :runtime
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
 - !ruby/object:Gem::Dependency
   name: csv
   requirement: !ruby/object:Gem::Requirement
@@ -66,20 +52,6 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
-- !ruby/object:Gem::Dependency
-  name: parser
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
-  type: :runtime
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
 - !ruby/object:Gem::Dependency
   name: prism
   requirement: !ruby/object:Gem::Requirement
@@ -151,9 +123,8 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '0'
 description: |
-  Keep your DB schema in sync across all branches effortlessly.
-  Install once, then use `rails db:migrate` normally — the gem handles phantom migration rollback automatically, eliminating schema conflicts and inconsistent database states.
-  Stop wasting hours on DB maintenance locally, CI, staging/sandbox, or even production.
+  Keep Rails databases in sync across Git branches. Automatically roll back stale migrations,
+  prevent database errors and unwanted schema diffs, and inspect migration history with a web dashboard.
 email:
 - ka8725@gmail.com
 executables: []
@@ -202,11 +173,13 @@ files:
 - lib/actual_db_schema/git.rb
 - lib/actual_db_schema/git_hooks.rb
 - lib/actual_db_schema/instrumentation.rb
+- lib/actual_db_schema/middlewares/skip_pending_migration_check.rb
 - lib/actual_db_schema/migration.rb
 - lib/actual_db_schema/migration_context.rb
 - lib/actual_db_schema/migration_parser.rb
 - lib/actual_db_schema/multi_tenant.rb
 - lib/actual_db_schema/output_formatter.rb
+- lib/actual_db_schema/patches/check_pending.rb
 - lib/actual_db_schema/patches/migration_context.rb
 - lib/actual_db_schema/patches/migration_proxy.rb
 - lib/actual_db_schema/patches/migrator.rb
@@ -257,6 +230,6 @@ requirements: []
 rubygems_version: 3.3.26
 signing_key:
 specification_version: 4
-summary: Keep DB schema in sync across branches effortlessly.
+summary: Keep Rails databases in sync across Git branches.
 test_files: []
 ...