actual_db_schema 0.8.6 → 0.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9b9b0ce8fc7b1dbf1e0af8af4d06cdb13c60a9b36499b2de11b3d2dd320833f2
-  data.tar.gz: bcb1f6e85b9fea8dcac89535fe4118edc9ced43f5ea57c3878d24d3b7b1786d2
+  metadata.gz: 3d7f7a42aa9ad38de5eeb7a64ca7a8a9117485a927d536f666aa2bf41be97b9f
+  data.tar.gz: 2236fd011c7aa72be7ffeef9d975da3bde1d6dd6844366cb458f51afa479395e
 SHA512:
-  metadata.gz: caa882430fcf07bcdd6c60a8653b0792587c627b99a93843599e9cb986bba53d644875650e825ddeb73b3c168d5831728cebb5e5ef276d077663da9f9c2bcdf9
-  data.tar.gz: f88c0acf54bba3ed626e380fa64a264573afc5ee2f1489ff6a3d3682ce2fd623d1b6b88917771811455a1e98e495b8252043cf6832044f86ccbb8da19d3d4f6e
+  metadata.gz: 3ed9ec959e789377596103e2be9214d5374551bbba0ab17a037cd47bc6481f035adf1b7a24bc2254702d8a64eead1fc503ee4d2317a55596258d7284500f5fd3
+  data.tar.gz: 48fc36d62e62e810d6d1fd4c8e3b578654587ac13f9ad8e0245e3e08c5cecf1a683ae3292715b366d0d5ce5b11cebcf953963aed8460664ddd7b0af9d7f1af7b

data/CHANGELOG.md

@@ -1,8 +1,11 @@
-## 0.8.6 - 2025-05-21
+## [0.9.0] - 2026-01-27
+- Store migration files in the DB to avoid reliance on the filesystem, enabling CI/CD usage on platforms with ephemeral storage (e.g., Heroku, Docker).
+
+## [0.8.6] - 2025-05-21
 - Fix gem installtion with git hooks
 - Update README
 
-## 0.8.5 - 2025-04-10
+## [0.8.5] - 2025-04-10
 
 - Fix the gem working on projects without git
 

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    actual_db_schema (0.8.6)
+    actual_db_schema (0.9.0)
       activerecord
       activesupport
       ast
@@ -96,7 +96,7 @@ GEM
     concurrent-ruby (1.2.2)
     connection_pool (2.4.1)
     crass (1.0.6)
-    csv (3.3.4)
+    csv (3.3.5)
     date (3.3.3)
     debug (1.8.0)
       irb (>= 1.5.0)
@@ -146,7 +146,7 @@ GEM
     parser (3.2.2.4)
       ast (~> 2.4.1)
       racc
-    prism (1.4.0)
+    prism (1.8.0)
     psych (5.1.1.1)
       stringio
     racc (1.7.3)

data/README.md

@@ -2,31 +2,98 @@
 
 # ActualDbSchema
 
-Does switching between branches in your Rails app mess up the DB schema?
+**Stop database headaches when switching Git branches in Rails**
+
+Keep your database schema perfectly synchronized across Git branches, eliminate broken tests and schema conflicts, and save wasted hours on phantom migrations.
+
+## 🚀 What You Get
+
+- **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
+
+<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" />
+
+And you get all of that with **zero** changes to your workflow!
+
+## 🎯 The Problem This Solves
+
+**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
+
+**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
+
+## 🌟 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
+- **Schema Format Agnostic**: Supports both `schema.rb` and `structure.sql`
+
+### Automation & Git Integration
+- **Automatic Rollback on Migration**: Phantom migrations roll back when running `db:migrate`
+- **Git Hook Integration**: Optional automatic rollback when switching branches
+- **Zero Configuration**: Works out of the box with sensible defaults
+- **Custom Migration Storage**: Configurable location for storing executed migrations
+
+### Web Interface & Management
+- **Migration Dashboard**: Visual overview of all migrations across databases
+- **Phantom Migration Browser**: Easy-to-use interface for viewing phantom migrations
+- **One-Click Rollback**: Rollback individual or all phantom migrations via web UI
+- **Broken Version Cleanup**: Identify and remove orphaned migration records
+- **Schema Diff Viewer**: Visual diff of schema changes with migration annotations
+
+### Developer Tools
+- **Console Migrations**: Run migration commands directly in Rails console
+- **Schema Diff Analysis**: Annotated diffs showing which migrations caused changes
+- **Migration Search & Filter**: Find specific migrations across all databases
+- **Detailed Migration Info**: View migration status, branch, and database information
+
+### 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
+
+### Manual Control Options
+- **Manual Rollback Mode**: Disable automatic rollback for full manual control
+- **Selective Rollback**: Choose which phantom migrations to rollback
+- **Interactive Mode**: Step-by-step confirmation for each rollback operation
+- **Rake Task Integration**: Full set of rake tasks for command-line management
+
+## ⚡ Quick Start
+
+Add to your Gemfile:
 
-Keep the DB schema current 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. It works with both `schema.rb` and `structure.sql`.
-
-## 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).
+```ruby
+group :development do
+  gem "actual_db_schema"
+end
+```
 
-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**.
+Install and configure:
 
-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.
+```sh
+bundle install
+rails actual_db_schema:install
+```
 
-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.
+That's it! Now just run `rails db:migrate` as usual - phantom migrations roll back automatically.
 
-### How it solves the issue
+## 🔧 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*.
 
@@ -53,10 +120,10 @@ If you cannot commit changes to the repo or Gemfile, consider the local Gemfile
 Next, generate your ActualDbSchema initializer file by running:
 
 ```sh
-rake actual_db_schema:install
+rails actual_db_schema:install
 ```
 
-This will create a `config/initializers/actual_db_schema.rb` file with all the available configuration options so you can adjust them as needed. It will also prompt you to install the post-checkout Git hook for automatic phantom migration rollback when switching branches.
+This will create a `config/initializers/actual_db_schema.rb` file that lists all available configuration options, allowing you to customize them as needed. The installation process will also prompt you to install the post-checkout Git hook, which automatically rolls back phantom migrations when switching branches. If enabled, this hook will run the schema actualization rake task every time you switch branches, which can slow down branch changes. Therefore, you might not always want this automatic actualization on every switch; in that case, running `rails db:migrate` manually provides a faster, more controlled alternative.
 
 For more details on the available configuration options, see the sections below.
 
@@ -72,7 +139,7 @@ The gem offers the following rake tasks that can be manually run according to yo
 - `rails db:rollback_branches:manual` - run it to manually rolls back phantom migrations one by one.
 - `rails db:phantom_migrations` - displays a list of phantom migrations.
 
-## Migrated Folder Configuration
+## 🎛️ Configuration Options
 
 By default, `actual_db_schema` stores all run migrations in the `tmp/migrated` folder. However, if you want to change this location, you can configure it in two ways:
 
@@ -91,13 +158,37 @@ Add the following line to your initializer file (`config/initializers/actual_db_
 config.migrated_folder = Rails.root.join("custom", "migrated")
 ```
 
-## Accessing the UI
+### 3. Store migrations in the database
 
-The UI for managing migrations is enabled automatically. To access the UI, simply navigate to the following URL in your web browser:
+If you want to share executed migrations across environments (e.g., staging or sandboxes),
+store them in the main database instead of the local filesystem:
+
+```ruby
+config.migrations_storage = :db
+```
+
+Or via environment variable:
+
+```sh
+export ACTUAL_DB_SCHEMA_MIGRATIONS_STORAGE="db"
+```
+
+If both are set, the initializer setting (`config.migrations_storage`) takes precedence.
+
+## 🌐 Web Interface
+
+Access the migration management UI at:
 ```
 http://localhost:3000/rails/phantom_migrations
 ```
-This page displays a list of phantom migrations for each database connection and provides options to view details and rollback them.
+
+View and manage:
+- **Migration Overview**: See all executed migrations with their status, branch, and database
+- **Phantom Migrations**: Identify migrations from other branches that need rollback
+- **Migration Source Code**: Browse the source code of every migration ever run (including the phantom ones)
+- **One-Click Actions**: Rollback or migrate individual migrations directly from the UI
+- **Broken Versions**: Detect and clean up orphaned migration records safely
+- **Schema Diffs**: Visual diff of schema changes annotated with their source migrations
 
 ## UI options
 
@@ -193,6 +284,8 @@ If `schema.rb` generates a diff, it can be helpful to find out which migrations
 
 By default, the task uses `db/schema.rb` and `db/migrate` as the schema and migrations paths. You can also provide custom paths as arguments.
 
+Alternatively, if you use Web UI, you can see this diff at `http://localhost:3000/rails/schema`. This way is often more convenient than running the Rake task manually.
+
 ### Usage
 
 Run the task with default paths:
@@ -290,7 +383,7 @@ rake actual_db_schema:delete_broken_versions["20250224103352 20250224103358"]
 rake actual_db_schema:delete_broken_versions["20250224103352 20250224103358", "primary"]
 ```
 
-## Development
+## 🏗️ 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

@@ -8,10 +8,11 @@ Gem::Specification.new do |spec|
   spec.authors = ["Andrei Kaleshka"]
   spec.email = ["ka8725@gmail.com"]
 
-  spec.summary = "Keep your DB and schema.rb consistent in dev branches."
+  spec.summary = "Keep DB schema in sync across branches effortlessly."
   spec.description = <<~DESC
-    Wipe out inconsistent DB and schema.rb when switching branches.
-    Just install this gem and use the standard rake db:migrate command.
+    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.
   DESC
   spec.homepage = "https://blog.widefix.com/actual-db-schema/"
   spec.license = "MIT"

data/app/views/actual_db_schema/migrations/show.html.erb

@@ -31,7 +31,13 @@
           </tr>
           <tr>
             <th>Path</th>
-            <td><%= migration[:filename] %></td>
+            <td>
+              <%= migration[:filename] %>
+              <% source = migration[:source].to_s %>
+              <% if source.present? %>
+                <span class="source-badge"><%= source.upcase %></span>
+              <% end %>
+            </td>
           </tr>
         </tbody>
       </table>

data/app/views/actual_db_schema/phantom_migrations/show.html.erb

@@ -31,7 +31,13 @@
           </tr>
           <tr>
             <th>Path</th>
-            <td><%= phantom_migration[:filename] %></td>
+            <td>
+              <%= phantom_migration[:filename] %>
+              <% source = phantom_migration[:source].to_s %>
+              <% if source.present? %>
+                <span class="source-badge"><%= source.upcase %></span>
+              <% end %>
+            </td>
           </tr>
         </tbody>
       </table>

data/app/views/actual_db_schema/shared/_style.html

@@ -158,4 +158,16 @@
   .schema-diff {
     margin-left: 8px;
   }
+
+  .source-badge {
+    display: inline-block;
+    margin-left: 8px;
+    padding: 2px 6px;
+    border-radius: 10px;
+    font-size: 11px;
+    font-weight: bold;
+    letter-spacing: 0.3px;
+    background-color: #e8f1ff;
+    color: #1d4ed8;
+  }
 </style>

data/lib/actual_db_schema/configuration.rb

@@ -4,16 +4,10 @@ module ActualDbSchema
   # Manages the configuration settings for the gem.
   class Configuration
     attr_accessor :enabled, :auto_rollback_disabled, :ui_enabled, :git_hooks_enabled, :multi_tenant_schemas,
-                  :console_migrations_enabled, :migrated_folder
+                  :console_migrations_enabled, :migrated_folder, :migrations_storage
 
     def initialize
-      @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?
-      @git_hooks_enabled = ENV["ACTUAL_DB_SCHEMA_GIT_HOOKS_ENABLED"].present?
-      @multi_tenant_schemas = nil
-      @console_migrations_enabled = ENV["ACTUAL_DB_SCHEMA_CONSOLE_MIGRATIONS_ENABLED"].present?
-      @migrated_folder = ENV["ACTUAL_DB_SCHEMA_MIGRATED_FOLDER"].present?
+      apply_defaults(default_settings)
     end
 
     def [](key)
@@ -22,6 +16,9 @@ module ActualDbSchema
 
     def []=(key, value)
       public_send("#{key}=", value)
+      return unless key.to_sym == :migrations_storage && defined?(ActualDbSchema::Store)
+
+      ActualDbSchema::Store.instance.reset_adapter
     end
 
     def fetch(key, default = nil)
@@ -31,5 +28,26 @@ module ActualDbSchema
         default
       end
     end
+
+    private
+
+    def default_settings
+      {
+        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?,
+        git_hooks_enabled: ENV["ACTUAL_DB_SCHEMA_GIT_HOOKS_ENABLED"].present?,
+        multi_tenant_schemas: nil,
+        console_migrations_enabled: ENV["ACTUAL_DB_SCHEMA_CONSOLE_MIGRATIONS_ENABLED"].present?,
+        migrated_folder: ENV["ACTUAL_DB_SCHEMA_MIGRATED_FOLDER"].present?,
+        migrations_storage: ENV.fetch("ACTUAL_DB_SCHEMA_MIGRATIONS_STORAGE", "file").to_sym
+      }
+    end
+
+    def apply_defaults(settings)
+      settings.each do |key, value|
+        instance_variable_set("@#{key}", value)
+      end
+    end
   end
 end

data/lib/actual_db_schema/engine.rb

@@ -12,5 +12,35 @@ module ActualDbSchema
         end
       end
     end
+
+    initializer "actual_db_schema.schema_dump_exclusions" do
+      ActiveSupport.on_load(:active_record) do
+        table_name = ActualDbSchema::Store::DbAdapter::TABLE_NAME
+
+        if defined?(ActiveRecord::SchemaDumper) && ActiveRecord::SchemaDumper.respond_to?(:ignore_tables)
+          ActiveRecord::SchemaDumper.ignore_tables |= [table_name]
+        end
+
+        next unless defined?(ActiveRecord::Tasks::DatabaseTasks)
+        next unless ActiveRecord::Tasks::DatabaseTasks.respond_to?(:structure_dump_flags)
+
+        flags = Array(ActiveRecord::Tasks::DatabaseTasks.structure_dump_flags)
+        adapter = ActualDbSchema.db_config[:adapter].to_s
+        database = ActualDbSchema.db_config[:database]
+        if database.nil? && ActiveRecord::Base.respond_to?(:connection_db_config)
+          database = ActiveRecord::Base.connection_db_config&.database
+        end
+
+        if adapter.match?(/postgres/i)
+          flag = "--exclude-table=#{table_name}*"
+          flags << flag unless flags.include?(flag)
+        elsif adapter.match?(/mysql/i) && database
+          flag = "--ignore-table=#{database}.#{table_name}"
+          flags << flag unless flags.include?(flag)
+        end
+
+        ActiveRecord::Tasks::DatabaseTasks.structure_dump_flags = flags
+      end
+    end
   end
 end

data/lib/actual_db_schema/migration.rb

@@ -5,7 +5,8 @@ module ActualDbSchema
   class Migration
     include Singleton
 
-    Migration = Struct.new(:status, :version, :name, :branch, :database, :filename, :phantom, keyword_init: true)
+    Migration = Struct.new(:status, :version, :name, :branch, :database, :filename, :phantom, :source,
+                           keyword_init: true)
 
     def all_phantom
       migrations = []
@@ -120,7 +121,8 @@ module ActualDbSchema
         branch: branch_for(migration.version),
         database: ActualDbSchema.db_config[:database],
         filename: migration.filename,
-        phantom: phantom?(migration)
+        phantom: phantom?(migration),
+        source: ActualDbSchema::Store.instance.source_for(migration.version)
       )
     end
 
@@ -129,8 +131,7 @@ module ActualDbSchema
     end
 
     def phantom?(migration)
-      migrated_folder = ActualDbSchema.config[:migrated_folder].presence || "/tmp/migrated"
-      migration.filename.include?(migrated_folder.to_s)
+      ActualDbSchema::Store.instance.stored_migration?(migration.filename)
     end
 
     def should_include?(status, migration)

data/lib/actual_db_schema/patches/migration_context.rb

@@ -71,7 +71,7 @@ module ActualDbSchema
       def migration_files
         paths = Array(migrations_paths)
         current_branch_files = Dir[*paths.flat_map { |path| "#{path}/**/[0-9]*_*.rb" }]
-        other_branches_files = Dir["#{ActualDbSchema.migrated_folder}/**/[0-9]*_*.rb"]
+        other_branches_files = ActualDbSchema::Store.instance.migration_files
         current_branch_versions = current_branch_files.map { |file| file.match(/(\d+)_/)[1] }
         filtered_other_branches_files = other_branches_files.reject do |file|
           version = file.match(/(\d+)_/)[1]
@@ -163,7 +163,7 @@ module ActualDbSchema
 
         migrations.uniq.each do |migration|
           count = migration_counts[migration.filename]
-          File.delete(migration.filename) if count == schema_count && File.exist?(migration.filename)
+          ActualDbSchema::Store.instance.delete(migration.filename) if count == schema_count
         end
       end
 

data/lib/actual_db_schema/schema_diff.rb

@@ -63,12 +63,12 @@ module ActualDbSchema
     end
 
     def migrated_folders
+      ActualDbSchema::Store.instance.materialize_all
       dirs = find_migrated_folders
 
-      if (configured_migrated_folder = ActualDbSchema.config[:migrated_folder].presence)
-        relative_migrated_folder = configured_migrated_folder.to_s.sub(%r{\A#{Regexp.escape(Rails.root.to_s)}/?}, "")
-        dirs << relative_migrated_folder unless dirs.include?(relative_migrated_folder)
-      end
+      configured_migrated_folder = ActualDbSchema.migrated_folder
+      relative_migrated_folder = configured_migrated_folder.to_s.sub(%r{\A#{Regexp.escape(Rails.root.to_s)}/?}, "")
+      dirs << relative_migrated_folder unless dirs.include?(relative_migrated_folder)
 
       dirs.map { |dir| dir.sub(%r{\A\./}, "") }.uniq
     end

data/lib/actual_db_schema/store.rb

@@ -1,44 +1,305 @@
 # frozen_string_literal: true
 
 module ActualDbSchema
-  # Stores the migrated files into the tmp folder
+  # Stores migration sources and metadata.
   class Store
     include Singleton
 
     Item = Struct.new(:version, :timestamp, :branch)
 
     def write(filename)
-      basename = File.basename(filename)
-      FileUtils.mkdir_p(folder)
-      FileUtils.copy(filename, folder.join(basename))
-      record_metadata(filename)
+      adapter.write(filename)
+      reset_source_cache
     end
 
     def read
-      return {} unless File.exist?(store_file)
+      adapter.read
+    end
+
+    def migration_files
+      adapter.migration_files
+    end
+
+    def delete(filename)
+      adapter.delete(filename)
+      reset_source_cache
+    end
+
+    def stored_migration?(filename)
+      adapter.stored_migration?(filename)
+    end
+
+    def source_for(version)
+      version = version.to_s
+
+      return :db if db_versions.key?(version)
+      return :file if file_versions.key?(version)
+
+      :unknown
+    end
+
+    def materialize_all
+      adapter.materialize_all
+    end
 
-      CSV.read(store_file).map { |line| Item.new(*line) }.index_by(&:version)
+    def reset_adapter
+      @adapter = nil
+      reset_source_cache
     end
 
     private
 
-    def record_metadata(filename)
-      version = File.basename(filename).scan(/(\d+)_.*\.rb/).first.first
-      CSV.open(store_file, "a") do |csv|
-        csv << [
-          version,
-          Time.current.iso8601,
-          Git.current_branch
-        ]
+    def adapter
+      @adapter ||= begin
+        storage = ActualDbSchema.config[:migrations_storage].to_s
+        storage == "db" ? DbAdapter.new : FileAdapter.new
+      end
+    end
+
+    def reset_source_cache
+      @db_versions = nil
+      @file_versions = nil
+    end
+
+    def db_versions
+      @db_versions ||= begin
+        connection = ActiveRecord::Base.connection
+        return {} unless connection.table_exists?(DbAdapter::TABLE_NAME)
+
+        table = connection.quote_table_name(DbAdapter::TABLE_NAME)
+        connection.select_values("SELECT version FROM #{table}").each_with_object({}) do |version, acc|
+          acc[version.to_s] = true
+        end
+      rescue StandardError
+        {}
       end
     end
 
-    def folder
-      ActualDbSchema.migrated_folder
+    def file_versions
+      @file_versions ||= FileAdapter.new.read
+    rescue StandardError
+      {}
     end
 
-    def store_file
-      folder.join("metadata.csv")
+    # Stores migrated files on the filesystem with metadata in CSV.
+    class FileAdapter
+      def write(filename)
+        basename = File.basename(filename)
+        FileUtils.mkdir_p(folder)
+        FileUtils.copy(filename, folder.join(basename))
+        record_metadata(filename)
+      end
+
+      def read
+        return {} unless File.exist?(store_file)
+
+        CSV.read(store_file).map { |line| Item.new(*line) }.index_by(&:version)
+      end
+
+      def migration_files
+        Dir["#{folder}/**/[0-9]*_*.rb"]
+      end
+
+      def delete(filename)
+        File.delete(filename) if File.exist?(filename)
+      end
+
+      def stored_migration?(filename)
+        filename.to_s.start_with?(folder.to_s)
+      end
+
+      def materialize_all
+        nil
+      end
+
+      private
+
+      def record_metadata(filename)
+        version = File.basename(filename).scan(/(\d+)_.*\.rb/).first.first
+        CSV.open(store_file, "a") do |csv|
+          csv << [
+            version,
+            Time.current.iso8601,
+            Git.current_branch
+          ]
+        end
+      end
+
+      def folder
+        ActualDbSchema.migrated_folder
+      end
+
+      def store_file
+        folder.join("metadata.csv")
+      end
+    end
+
+    # Stores migrated files in the database.
+    class DbAdapter
+      TABLE_NAME = "actual_db_schema_migrations"
+      RECORD_COLUMNS = %w[version filename content branch migrated_at].freeze
+
+      def write(filename)
+        ensure_table!
+
+        version = extract_version(filename)
+        return unless version
+
+        basename = File.basename(filename)
+        content = File.read(filename)
+        upsert_record(version, basename, content, Git.current_branch, Time.current)
+        write_cache_file(basename, content)
+      end
+
+      def read
+        return {} unless table_exists?
+
+        rows = connection.exec_query(<<~SQL.squish)
+          SELECT version, migrated_at, branch
+          FROM #{quoted_table}
+        SQL
+
+        rows.map do |row|
+          Item.new(row["version"].to_s, row["migrated_at"], row["branch"])
+        end.index_by(&:version)
+      end
+
+      def migration_files
+        materialize_all
+        Dir["#{folder}/**/[0-9]*_*.rb"]
+      end
+
+      def delete(filename)
+        version = extract_version(filename)
+        return unless version
+
+        if table_exists?
+          connection.execute(<<~SQL.squish)
+            DELETE FROM #{quoted_table}
+            WHERE #{quoted_column("version")} = #{connection.quote(version)}
+          SQL
+        end
+        File.delete(filename) if File.exist?(filename)
+      end
+
+      def stored_migration?(filename)
+        filename.to_s.start_with?(folder.to_s)
+      end
+
+      def materialize_all
+        return unless table_exists?
+
+        FileUtils.mkdir_p(folder)
+        rows = connection.exec_query(<<~SQL.squish)
+          SELECT filename, content
+          FROM #{quoted_table}
+        SQL
+
+        rows.each do |row|
+          write_cache_file(row["filename"], row["content"])
+        end
+      end
+
+      private
+
+      def upsert_record(version, basename, content, branch, migrated_at)
+        attributes = record_attributes(version, basename, content, branch, migrated_at)
+        record_exists?(version) ? update_record(attributes) : insert_record(attributes)
+      end
+
+      def record_attributes(version, basename, content, branch, migrated_at)
+        {
+          version: version,
+          filename: basename,
+          content: content,
+          branch: branch,
+          migrated_at: migrated_at
+        }
+      end
+
+      def update_record(attributes)
+        assignments = record_columns.reject { |column| column == "version" }.map do |column|
+          "#{quoted_column(column)} = #{connection.quote(attributes[column.to_sym])}"
+        end
+
+        connection.execute(<<~SQL)
+          UPDATE #{quoted_table}
+          SET #{assignments.join(", ")}
+          WHERE #{quoted_column("version")} = #{connection.quote(attributes[:version])}
+        SQL
+      end
+
+      def insert_record(attributes)
+        columns = record_columns
+        values = columns.map { |column| connection.quote(attributes[column.to_sym]) }
+
+        connection.execute(<<~SQL)
+          INSERT INTO #{quoted_table}
+            (#{columns.map { |column| quoted_column(column) }.join(", ")})
+          VALUES
+            (#{values.join(", ")})
+        SQL
+      end
+
+      def record_exists?(version)
+        connection.select_value(<<~SQL.squish).present?
+          SELECT 1
+          FROM #{quoted_table}
+          WHERE #{quoted_column("version")} = #{connection.quote(version)}
+          LIMIT 1
+        SQL
+      end
+
+      def ensure_table!
+        return if table_exists?
+
+        connection.create_table(TABLE_NAME) do |t|
+          t.string :version, null: false
+          t.string :filename, null: false
+          t.text :content, null: false
+          t.string :branch
+          t.datetime :migrated_at, null: false
+        end
+
+        connection.add_index(TABLE_NAME, :version, unique: true) unless connection.index_exists?(TABLE_NAME, :version)
+      end
+
+      def table_exists?
+        connection.table_exists?(TABLE_NAME)
+      end
+
+      def connection
+        ActiveRecord::Base.connection
+      end
+
+      def record_columns
+        RECORD_COLUMNS
+      end
+
+      def quoted_table
+        connection.quote_table_name(TABLE_NAME)
+      end
+
+      def quoted_column(name)
+        connection.quote_column_name(name)
+      end
+
+      def folder
+        ActualDbSchema.migrated_folder
+      end
+
+      def write_cache_file(filename, content)
+        FileUtils.mkdir_p(folder)
+        path = folder.join(File.basename(filename))
+        return if File.exist?(path) && File.read(path) == content
+
+        File.write(path, content)
+      end
+
+      def extract_version(filename)
+        match = File.basename(filename).scan(/(\d+)_.*\.rb/).first
+        match&.first
+      end
     end
   end
 end

data/lib/actual_db_schema/version.rb

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

data/lib/generators/actual_db_schema/templates/actual_db_schema.rb

@@ -30,5 +30,9 @@ if defined?(ActualDbSchema)
     # Define the migrated folder location.
     # config.migrated_folder = Rails.root.join("custom", "migrated")
     config.migrated_folder = Rails.root.join("tmp", "migrated")
+
+    # Choose where to store migrated files: :file or :db.
+    # config.migrations_storage = :db
+    config.migrations_storage = :file
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: actual_db_schema
 version: !ruby/object:Gem::Version
-  version: 0.8.6
+  version: 0.9.0
 platform: ruby
 authors:
 - Andrei Kaleshka
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2025-05-21 00:00:00.000000000 Z
+date: 2026-01-27 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activerecord
@@ -151,8 +151,9 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '0'
 description: |
-  Wipe out inconsistent DB and schema.rb when switching branches.
-  Just install this gem and use the standard rake db:migrate command.
+  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.
 email:
 - ka8725@gmail.com
 executables: []
@@ -253,6 +254,6 @@ requirements: []
 rubygems_version: 3.3.26
 signing_key:
 specification_version: 4
-summary: Keep your DB and schema.rb consistent in dev branches.
+summary: Keep DB schema in sync across branches effortlessly.
 test_files: []
 ...