` (optional) – Specify a database if using multiple databases.
#### Examples:
```sh
# Delete all broken migrations
rake actual_db_schema:delete_broken_versions
# Delete specific migrations
rake actual_db_schema:delete_broken_versions["20250224103352 20250224103358"]
# Delete specific migrations from a specific database
rake actual_db_schema:delete_broken_versions["20250224103352 20250224103358", "primary"]
```
## 🏗️ 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.
To install this gem onto your local machine, run `bundle exec rake install`.
To release a new version do the following in the order:
- update the version number in `version.rb`;
- update the CHANGELOG;
- `bundle install` to update `Gemfile.lock`;
- make the commit and push;
- run `bundle exec rake release`. This will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org);
- [announce the new release on GitHub](https://github.com/widefix/actual_db_schema/releases);
- close the milestone on GitHub.
### Running Tests with Specific Rails Versions
The following versions can be specifically tested using Appraisal
- 6.0
- 6.1
- 7.0
- 7.1
- edge
To run tests with a specific version of Rails using Appraisal:
- Run all tests with Rails 6.0:
```sh
bundle exec appraisal rails.6.0 rake test
```
- Run tests for a specific file:
```sh
bundle exec appraisal rails.6.0 rake test TEST=test/rake_task_test.rb
```
- Run a specific test:
```sh
bundle exec appraisal rails.6.0 rake test TEST=test/rake_task_test.rb TESTOPTS="--name=/db::db:rollback_branches#test_0003_keeps/"
```
By default, `rake test` runs tests using `SQLite3`. To explicitly run tests with `SQLite3`, `PostgreSQL`, or `MySQL`, you can use the following tasks:
- Run tests with `SQLite3`:
```sh
bundle exec rake test:sqlite3
```
- Run tests with `PostgreSQL` (requires Docker):
```sh
bundle exec rake test:postgresql
```
- Run tests with `MySQL` (requires Docker):
```sh
bundle exec rake test:mysql2
```
- Run tests for all supported adapters:
```sh
bundle exec rake test:all
```
## Contributing
Bug reports and pull requests are welcome on GitHub at https://github.com/widefix/actual_db_schema. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/widefix/actual_db_schema/blob/master/CODE_OF_CONDUCT.md).
## License
The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
## Code of Conduct
Everyone interacting in the ActualDbSchema project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/widefix/actual_db_schema/blob/master/CODE_OF_CONDUCT.md).
================================================
FILE: Rakefile
================================================
# frozen_string_literal: true
require "bundler/gem_tasks"
require "rake/testtask"
load "lib/tasks/test.rake"
Rake::TestTask.new(:test) do |t|
t.libs << "test"
t.libs << "lib"
t.test_files = FileList["test/**/test_*.rb", "test/**/*_test.rb"]
end
require "rubocop/rake_task"
RuboCop::RakeTask.new
task default: %i[test]
================================================
FILE: actual_db_schema.gemspec
================================================
# frozen_string_literal: true
require_relative "lib/actual_db_schema/version"
Gem::Specification.new do |spec|
spec.name = "actual_db_schema"
spec.version = ActualDbSchema::VERSION
spec.authors = ["Andrei Kaleshka"]
spec.email = ["ka8725@gmail.com"]
spec.summary = "Keep DB schema in sync across branches effortlessly."
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.
DESC
spec.homepage = "https://blog.widefix.com/actual-db-schema/"
spec.license = "MIT"
spec.required_ruby_version = ">= 2.7.0"
# spec.metadata["allowed_push_host"] = "TODO: Set to your gem server 'https://example.com'"
spec.metadata["homepage_uri"] = spec.homepage
spec.metadata["source_code_uri"] = "https://github.com/widefix/actual_db_schema"
spec.metadata["changelog_uri"] = "https://github.com/widefix/actual_db_schema/blob/main/CHANGELOG.md"
# Specify which files should be added to the gem when it is released.
# 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)})
end
end
spec.bindir = "exe"
spec.executables = spec.files.grep(%r{\Aexe/}) { |f| File.basename(f) }
spec.require_paths = ["lib"]
# 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"
spec.add_development_dependency "debug"
spec.add_development_dependency "rails"
spec.add_development_dependency "sqlite3"
spec.post_install_message = <<~MSG
Thank you for installing ActualDbSchema!
Next steps:
1. Run `rake actual_db_schema:install` to generate the initializer file and install
the post-checkout Git hook for automatic phantom migration rollback when switching branches.
2. Or, if you prefer environment variables, skip this step.
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
================================================
FILE: app/controllers/actual_db_schema/broken_versions_controller.rb
================================================
# frozen_string_literal: true
module ActualDbSchema
# Controller for managing broken migration versions.
class BrokenVersionsController < ActionController::Base
protect_from_forgery with: :exception
skip_before_action :verify_authenticity_token
def index; end
def delete
handle_delete(params[:id], params[:database])
redirect_to broken_versions_path
end
def delete_all
handle_delete_all
redirect_to broken_versions_path
end
private
def handle_delete(id, database)
ActualDbSchema::Migration.instance.delete(id, database)
flash[:notice] = "Migration #{id} was successfully deleted."
rescue StandardError => e
flash[:alert] = e.message
end
def handle_delete_all
ActualDbSchema::Migration.instance.delete_all
flash[:notice] = "All broken versions were successfully deleted."
rescue StandardError => e
flash[:alert] = e.message
end
helper_method def broken_versions
@broken_versions ||= ActualDbSchema::Migration.instance.broken_versions
end
end
end
================================================
FILE: app/controllers/actual_db_schema/migrations_controller.rb
================================================
# frozen_string_literal: true
module ActualDbSchema
# Controller to display the list of migrations for each database connection.
class MigrationsController < ActionController::Base
protect_from_forgery with: :exception
skip_before_action :verify_authenticity_token
def index; end
def show
render file: "#{Rails.root}/public/404.html", layout: false, status: :not_found unless migration
end
def rollback
handle_rollback(params[:id], params[:database])
redirect_to migrations_path
end
def migrate
handle_migrate(params[:id], params[:database])
redirect_to migrations_path
end
private
def handle_rollback(id, database)
ActualDbSchema::Migration.instance.rollback(id, database)
flash[:notice] = "Migration #{id} was successfully rolled back."
rescue StandardError => e
flash[:alert] = e.message
end
def handle_migrate(id, database)
ActualDbSchema::Migration.instance.migrate(id, database)
flash[:notice] = "Migration #{id} was successfully migrated."
rescue StandardError => e
flash[:alert] = e.message
end
helper_method def migrations
@migrations ||= ActualDbSchema::Migration.instance.all
query = params[:query].to_s.strip.downcase
return @migrations if query.blank?
@migrations.select do |migration|
file_name_matches = migration[:filename].include?(query)
content_matches = begin
File.read(migration[:filename]).downcase.include?(query)
rescue StandardError
false
end
file_name_matches || content_matches
end
end
helper_method def migration
@migration ||= ActualDbSchema::Migration.instance.find(params[:id], params[:database])
end
end
end
================================================
FILE: app/controllers/actual_db_schema/phantom_migrations_controller.rb
================================================
# frozen_string_literal: true
module ActualDbSchema
# Controller to display the list of phantom migrations for each database connection.
class PhantomMigrationsController < ActionController::Base
protect_from_forgery with: :exception
skip_before_action :verify_authenticity_token
def index; end
def show
render file: "#{Rails.root}/public/404.html", layout: false, status: :not_found unless phantom_migration
end
def rollback
handle_rollback(params[:id], params[:database])
redirect_to phantom_migrations_path
end
def rollback_all
handle_rollback_all
redirect_to phantom_migrations_path
end
private
def handle_rollback(id, database)
ActualDbSchema::Migration.instance.rollback(id, database)
flash[:notice] = "Migration #{id} was successfully rolled back."
rescue StandardError => e
flash[:alert] = e.message
end
def handle_rollback_all
ActualDbSchema::Migration.instance.rollback_all
flash[:notice] = "Migrations was successfully rolled back."
rescue StandardError => e
flash[:alert] = e.message
end
helper_method def phantom_migrations
@phantom_migrations ||= ActualDbSchema::Migration.instance.all_phantom
end
helper_method def phantom_migration
@phantom_migration ||= ActualDbSchema::Migration.instance.find(params[:id], params[:database])
end
end
end
================================================
FILE: app/controllers/actual_db_schema/schema_controller.rb
================================================
# frozen_string_literal: true
module ActualDbSchema
# Controller to display the database schema diff.
class SchemaController < ActionController::Base
protect_from_forgery with: :exception
skip_before_action :verify_authenticity_token
def index; end
private
helper_method def schema_diff_html
schema_path = Rails.configuration.active_record.schema_format == :sql ? "./db/structure.sql" : "./db/schema.rb"
schema_diff = ActualDbSchema::SchemaDiffHtml.new(schema_path, "db/migrate")
schema_diff.render_html(params[:table])
end
end
end
================================================
FILE: app/views/actual_db_schema/broken_versions/index.html.erb
================================================
Broken Versions
<%= render partial: 'actual_db_schema/shared/js' %>
<%= render partial: 'actual_db_schema/shared/style' %>
<% flash.each do |key, message| %>
<%= message %>
<% end %>
Broken Versions
These are versions that were migrated in the database, but the corresponding migration file is missing.
You can safely delete them from the database to clean up.
<%= link_to 'All Migrations', migrations_path, class: "top-button" %>
<% if broken_versions.present? %>
<%= button_to '✖ Delete all',
delete_all_broken_versions_path,
method: :post,
data: { confirm: 'These migrations do not have corresponding migration files. Proceeding will remove these entries from the `schema_migrations` table. Are you sure you want to continue?' },
class: 'button migration-action' %>
<% end %>
<% if broken_versions.present? %>
| Status |
Migration ID |
Branch |
Database |
Actions |
<% broken_versions.each do |version| %>
| <%= version[:status] %> |
<%= version[:version] %> |
<%= version[:branch] %> |
<%= version[:database] %> |
<%= button_to '✖ Delete',
delete_broken_version_path(id: version[:version], database: version[:database]),
method: :post,
data: { confirm: 'This migration does not have a corresponding migration file. Proceeding will remove its entry from the `schema_migrations` table. Are you sure you want to continue?' },
class: 'button migration-action' %>
|
<% end %>
<% else %>
No broken versions found.
<% end %>
<% flash.each do |key, message| %>
<%= message %>
<% end %>
Migrations
Red rows represent phantom migrations.
<%= link_to 'Phantom Migrations', phantom_migrations_path, class: "top-button" %>
<%= link_to 'Broken Versions', broken_versions_path, class: "top-button" %>
<%= link_to 'View Schema', schema_path, class: "top-button" %>
<%= form_tag migrations_path, method: :get, class: "search-form" do %>
🔍
<%= text_field_tag :query, params[:query], placeholder: "Search migrations by name or content", class: "search-input" %>
<% end %>
<% if migrations.present? %>
| Status |
Migration ID |
Name |
Branch |
Database |
Actions |
<% migrations.each do |migration| %>
| <%= migration[:status] %> |
<%= migration[:version] %> |
<%= migration[:name] %>
|
<%= migration[:branch] %> |
<%= migration[:database] %> |
<%= link_to '👁 Show',
migration_path(id: migration[:version], database: migration[:database]),
class: 'button' %>
<%= button_to '⎌ Rollback',
rollback_migration_path(id: migration[:version], database: migration[:database]),
method: :post,
class: 'button migration-action',
style: ('display: none;' if migration[:status] == "down") %>
<%= button_to '⬆ Migrate',
migrate_migration_path(id: migration[:version], database: migration[:database]),
method: :post,
class: 'button migration-action',
style: ('display: none;' if migration[:status] == "up" || migration[:phantom]) %>
|
<% end %>
<% else %>
No migrations found.
<% end %>
<% flash.each do |key, message| %>
<%= message %>
<% end %>
Migration <%= migration[:name] %> Details
| Status |
<%= migration[:status] %> |
| Migration ID |
<%= migration[:version] %> |
| Branch |
<%= migration[:branch] %> |
| Database |
<%= migration[:database] %> |
| Path |
<%= migration[:filename] %>
<% source = migration[:source].to_s %>
<% if source.present? %>
<%= source.upcase %>
<% end %>
|
Migration Code
<%= File.read(migration[:filename]) %>
<%= link_to '← Back', migrations_path, class: 'button' %>
<%= button_to '⎌ Rollback',
rollback_migration_path(id: migration[:version], database: migration[:database]),
method: :post,
class: 'button migration-action',
style: ('display: none;' if migration[:status] == "down") %>
<%= button_to '⬆ Migrate',
migrate_migration_path(id: migration[:version], database: migration[:database]),
method: :post,
class: 'button migration-action',
style: ('display: none;' if migration[:status] == "up" || migration[:phantom]) %>
<% flash.each do |key, message| %>
<%= message %>
<% end %>
Phantom Migrations
<%= link_to 'All Migrations', migrations_path, class: "top-button" %>
<% if phantom_migrations.present? %>
<%= button_to '⎌ Rollback all',
rollback_all_phantom_migrations_path,
method: :post,
class: 'button migration-action' %>
<% end %>
<% if phantom_migrations.present? %>
| Status |
Migration ID |
Name |
Branch |
Database |
Actions |
<% phantom_migrations.each do |migration| %>
| <%= migration[:status] %> |
<%= migration[:version] %> |
<%= migration[:name] %>
|
<%= migration[:branch] %> |
<%= migration[:database] %> |
<%= link_to '👁 Show',
phantom_migration_path(id: migration[:version], database: migration[:database]),
class: 'button' %>
<%= button_to '⎌ Rollback',
rollback_phantom_migration_path(id: migration[:version], database: migration[:database]),
method: :post,
class: 'button migration-action' %>
|
<% end %>
<% else %>
No phantom migrations found.
<% end %>
<% flash.each do |key, message| %>
<%= message %>
<% end %>
Phantom Migration <%= phantom_migration[:name] %> Details
| Status |
<%= phantom_migration[:status] %> |
| Migration ID |
<%= phantom_migration[:version] %> |
| Branch |
<%= phantom_migration[:branch] %> |
| Database |
<%= phantom_migration[:database] %> |
| Path |
<%= phantom_migration[:filename] %>
<% source = phantom_migration[:source].to_s %>
<% if source.present? %>
<%= source.upcase %>
<% end %>
|
Migration Code
<%= File.read(phantom_migration[:filename]) %>
<%= link_to '← Back', phantom_migrations_path, class: 'button' %>
<%= button_to '⎌ Rollback',
rollback_phantom_migration_path(id: params[:id], database: params[:database]),
method: :post,
class: 'button migration-action' %>
<% flash.each do |key, message| %>
<%= message %>
<% end %>
Database Schema
<%= link_to 'All Migrations', migrations_path, class: "top-button" %>
<%= form_tag schema_path, method: :get, class: "search-form" do %>
🔍
<%= text_field_tag :table, params[:table], placeholder: "Filter by table name", class: "search-input" %>
<% end %>
<%= raw schema_diff_html %>