migsupo 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 9f22d99bd89a407d32621aadf871aa3a6059291b338aa2df6b9f12cd29fa6abf
+  data.tar.gz: 555ccc440d31b410b015f4975b3835f590fa15e900c759d166b3ad1cbb842327
+SHA512:
+  metadata.gz: c9d49e0b2092d947a31783bad5c5052b658da6be8b383f4473e91d0afa82e59a0f198288fcffd9eeb03b3a787b85771cefa2bac502fd806616d8460bd5419362
+  data.tar.gz: cb2ff4341a47c1c646b32cce37dc771b1e85acb1d42d97b42394f8d15f174716707495d118731d8043a8d468eb8fd17414f041ceff7001b23fc4b0539c5c89cb

data/README.md

@@ -0,0 +1,246 @@
+# Migsupo
+
+Migsupo is a Rails gem that generates migration files from the diff between a **Schemafile** (your desired schema) and the current database state.
+
+It is inspired by [ridgepole](https://github.com/ridgepole/ridgepole) but with a key difference: instead of applying schema changes directly to the database, Migsupo generates standard Rails migration files that you can review, modify, and run through the normal `rails db:migrate` workflow.
+
+## How It Works
+
+```
+Schemafile          →  migsupo  →  db/migrate/*.rb  →  rails db:migrate  →  DB
+(desired state)                    (auto-generated)                          ↓
+                                                                      db/schema.rb
+                                                                      (managed by Rails)
+```
+
+You define your desired schema in a `Schemafile` using the same DSL as ridgepole. Migsupo compares it against the current database and generates migration files for any differences.
+
+### File Responsibilities
+
+| File | Managed by | Purpose |
+|---|---|---|
+| `Schemafile` | You | Declares the desired schema state |
+| `db/migrate/*.rb` | Migsupo (generated) + you (reviewed) | Incremental changes to apply |
+| `db/schema.rb` | Rails | Snapshot of the current schema after migrations — do not edit manually |
+
+The `Schemafile` and `db/schema.rb` are intentionally separate. Rails owns `db/schema.rb` and keeps it in sync after every `rails db:migrate`. The `Schemafile` is yours to manage — Rails never touches it.
+
+## Installation
+
+Add to your `Gemfile`:
+
+```ruby
+gem "migsupo"
+```
+
+Then run:
+
+```bash
+bundle install
+```
+
+## Getting Started
+
+### 1. Create a Schemafile
+
+Create a `Schemafile` in your Rails root. For existing projects, you can use `db/schema.rb` as a reference — copy the `create_table` and `add_index` blocks as-is (without the `ActiveRecord::Schema.define` wrapper).
+
+```bash
+# Example: use schema.rb as a starting point
+grep -v "ActiveRecord::Schema\|^end$\|^#\|version:" db/schema.rb > Schemafile
+```
+
+From this point on, the `Schemafile` is yours to manage. Rails will not touch it.
+
+### 2. Edit the Schemafile to describe your desired schema
+
+```ruby
+# Schemafile
+
+create_table "users", force: :cascade do |t|
+  t.string  "name",  null: false
+  t.string  "email", null: false
+  t.integer "age"
+  t.timestamps
+end
+
+add_index "users", ["email"], name: "index_users_on_email", unique: true
+
+create_table "posts", force: :cascade do |t|
+  t.string     "title",   null: false
+  t.text       "body"
+  t.references "user"
+  t.timestamps
+end
+```
+
+### 3. Generate migration files
+
+```bash
+rails db:generate_migration
+```
+
+Migsupo compares the Schemafile against the current database and writes migration files to `db/migrate/`.
+
+### 4. Review and run migrations
+
+```bash
+# Review the generated files
+cat db/migrate/20260324120000_create_users.rb
+
+# Apply to the database
+rails db:migrate
+```
+
+## Commands
+
+### `rails db:generate_migration`
+
+Generate migration files for all differences between the Schemafile and the current database.
+
+```bash
+rails db:generate_migration
+rails db:generate_migration SCHEMAFILE=db/Schemafile
+rails db:generate_migration OUTPUT_DIR=db/migrate
+rails db:generate_migration DRY_RUN=true    # print to stdout, no files written
+rails db:generate_migration VERBOSE=true    # also print diff summary
+```
+
+### `rails db:generate_migration:diff`
+
+Print a human-readable diff between the Schemafile and the current database. No files are written.
+
+```bash
+rails db:generate_migration:diff
+```
+
+### `rails db:generate_migration:check`
+
+Exit with code 1 if the Schemafile and the current database are not in sync. Useful in CI pipelines.
+
+```bash
+rails db:generate_migration:check
+```
+
+## Environment Variables
+
+| Variable | Default | Description |
+|---|---|---|
+| `SCHEMAFILE` | `Schemafile` | Path to the Schemafile |
+| `OUTPUT_DIR` | `db/migrate` | Output directory for generated migration files |
+| `LOADER` | `activerecord` | Schema loader: `activerecord` or `schema_rb` |
+| `DRY_RUN` | `false` | Print migrations to stdout instead of writing files |
+| `VERBOSE` | `false` | Print diff summary before generating files |
+
+### Loaders
+
+- **`activerecord`** (default): Reads the current schema directly from the database via `ActiveRecord::Base.connection`. Always reflects the true current state.
+- **`schema_rb`**: Reads from `db/schema.rb` without a live database connection. Useful for offline environments, but only as accurate as the last `rails db:migrate` run.
+
+## Configuration
+
+You can configure Migsupo in an initializer:
+
+```ruby
+# config/initializers/migsupo.rb
+Migsupo.configure do |config|
+  config.schemafile_path   = Rails.root.join("db/Schemafile")
+  config.migrations_dir    = Rails.root.join("db/migrate")
+  config.ignored_tables    = %w[schema_migrations ar_internal_metadata]
+  config.migration_version = "7.1"  # defaults to current Rails version
+
+  # Explicit rename hints (see "Column Renames" below)
+  config.rename_hints = {
+    "users" => { "full_name" => "name" }
+  }
+end
+```
+
+## Generated Migration Examples
+
+### New table
+
+```ruby
+class CreateUsers < ActiveRecord::Migration[7.1]
+  def change
+    create_table :users do |t|
+      t.string :name, null: false
+      t.string :email, null: false
+      t.integer :age
+
+      t.timestamps
+    end
+
+    add_index :users, [:email], name: "index_users_on_email", unique: true
+  end
+end
+```
+
+### Add columns
+
+```ruby
+class AddColumnsToUsers < ActiveRecord::Migration[7.1]
+  def change
+    add_column :users, :phone, :string
+    add_index  :users, [:phone], name: "index_users_on_phone"
+  end
+end
+```
+
+### Change column type (uses explicit `up`/`down`)
+
+```ruby
+class ModifyUsers < ActiveRecord::Migration[7.1]
+  def up
+    change_column :users, :age, :bigint
+  end
+
+  def down
+    change_column :users, :age, :integer
+  end
+end
+```
+
+## Column Renames
+
+Migsupo cannot automatically distinguish a rename from a drop + add, so rename detection is **opt-in** via `rename_hints`. Without a hint, Migsupo will emit `remove_column` + `add_column`, which would cause data loss.
+
+```ruby
+# config/initializers/migsupo.rb
+Migsupo.configure do |config|
+  config.rename_hints = {
+    "users" => { "full_name" => "name" }
+  }
+end
+```
+
+This generates `rename_column` instead of `remove_column` + `add_column`.
+
+## CI Integration
+
+Use `db:generate_migration:check` to verify that your Schemafile and database are always in sync after all migrations have been applied:
+
+```yaml
+# .github/workflows/ci.yml
+- name: Check schema sync
+  run: bundle exec rails db:generate_migration:check
+```
+
+## Comparison with ridgepole
+
+| | ridgepole | migsupo |
+|---|---|---|
+| Schema definition | Schemafile | Schemafile (compatible) |
+| How changes are applied | Directly to DB | Generates Rails migration files |
+| Rails migration workflow | Bypassed | Preserved |
+| Rollback support | No | Yes (via `rails db:rollback`) |
+| Review before applying | Not built-in | Yes (review generated files) |
+
+## Requirements
+
+- Ruby >= 3.0
+- Rails >= 6.1
+
+## License
+
+MIT

data/lib/migsupo/configuration.rb

@@ -0,0 +1,19 @@
+module Migsupo
+  class Configuration
+    attr_accessor :schemafile_path
+    attr_accessor :migrations_dir
+    attr_accessor :loader
+    attr_accessor :ignored_tables
+    attr_accessor :rename_hints
+    attr_accessor :migration_version
+
+    def initialize
+      @schemafile_path   = "Schemafile"
+      @migrations_dir    = "db/migrate"
+      @loader            = :active_record
+      @ignored_tables    = %w[schema_migrations ar_internal_metadata]
+      @rename_hints      = {}
+      @migration_version = nil
+    end
+  end
+end

data/lib/migsupo/differ/diff.rb

@@ -0,0 +1,22 @@
+module Migsupo
+  module Differ
+    class Diff
+      attr_reader :operations
+
+      def initialize(operations: [])
+        @operations = operations.freeze
+        freeze
+      end
+
+      def empty?
+        @operations.empty?
+      end
+
+      def to_s
+        return "No changes." if empty?
+
+        @operations.map(&:to_s).join("\n")
+      end
+    end
+  end
+end

data/lib/migsupo/differ/diff_calculator.rb

@@ -0,0 +1,123 @@
+require "set"
+require_relative "diff"
+require_relative "operations/create_table"
+require_relative "operations/drop_table"
+require_relative "operations/add_column"
+require_relative "operations/remove_column"
+require_relative "operations/change_column"
+require_relative "operations/rename_column"
+require_relative "operations/add_index"
+require_relative "operations/remove_index"
+
+module Migsupo
+  module Differ
+    class DiffCalculator
+      def initialize(rename_hints: {})
+        @rename_hints = rename_hints
+      end
+
+      def calculate(desired:, current:)
+        operations = []
+
+        desired_names = Set.new(desired.tables.keys)
+        current_names = Set.new(current.tables.keys)
+
+        (desired_names - current_names).each do |name|
+          operations << Operations::CreateTable.new(desired.tables[name])
+        end
+
+        (current_names - desired_names).each do |name|
+          operations << Operations::DropTable.new(current.tables[name])
+        end
+
+        (desired_names & current_names).each do |name|
+          operations.concat(diff_table(desired.tables[name], current.tables[name]))
+        end
+
+        Diff.new(operations: operations)
+      end
+
+      private
+
+      def diff_table(desired, current)
+        operations = []
+        operations.concat(diff_columns(desired, current))
+        operations.concat(diff_indexes(desired, current))
+        operations
+      end
+
+      def diff_columns(desired, current)
+        desired_cols = desired.columns.each_with_object({}) { |c, h| h[c.name] = c }
+        current_cols = current.columns.each_with_object({}) { |c, h| h[c.name] = c }
+
+        added   = desired_cols.keys - current_cols.keys
+        removed = current_cols.keys - desired_cols.keys
+
+        hints = @rename_hints[desired.name] || {}
+        operations = apply_rename_hints(desired.name, hints, added, removed, desired_cols, current_cols)
+
+        # Remaining added/removed after renames
+        renamed_old = operations.select { |op| op.is_a?(Operations::RenameColumn) }.map(&:old_name)
+        renamed_new = operations.select { |op| op.is_a?(Operations::RenameColumn) }.map(&:new_name)
+
+        (added - renamed_new).each do |name|
+          operations << Operations::AddColumn.new(table_name: desired.name, column: desired_cols[name])
+        end
+
+        (removed - renamed_old).each do |name|
+          operations << Operations::RemoveColumn.new(table_name: desired.name, column: current_cols[name])
+        end
+
+        (desired_cols.keys & current_cols.keys).each do |name|
+          next if desired_cols[name] == current_cols[name]
+
+          operations << Operations::ChangeColumn.new(
+            table_name: desired.name,
+            new_column:  desired_cols[name],
+            old_column:  current_cols[name]
+          )
+        end
+
+        operations
+      end
+
+      def apply_rename_hints(table_name, hints, added, removed, desired_cols, current_cols)
+        operations = []
+        hints.each do |old_name, new_name|
+          next unless removed.include?(old_name) && added.include?(new_name)
+
+          operations << Operations::RenameColumn.new(
+            table_name: table_name,
+            old_name:   old_name,
+            new_name:   new_name
+          )
+        end
+        operations
+      end
+
+      def diff_indexes(desired, current)
+        desired_idxs = desired.indexes.each_with_object({}) { |i, h| h[i.name] = i }
+        current_idxs = current.indexes.each_with_object({}) { |i, h| h[i.name] = i }
+
+        operations = []
+
+        (desired_idxs.keys - current_idxs.keys).each do |name|
+          operations << Operations::AddIndex.new(table_name: desired.name, index: desired_idxs[name])
+        end
+
+        (current_idxs.keys - desired_idxs.keys).each do |name|
+          operations << Operations::RemoveIndex.new(table_name: desired.name, index: current_idxs[name])
+        end
+
+        (desired_idxs.keys & current_idxs.keys).each do |name|
+          next if desired_idxs[name] == current_idxs[name]
+
+          operations << Operations::RemoveIndex.new(table_name: desired.name, index: current_idxs[name])
+          operations << Operations::AddIndex.new(table_name: desired.name, index: desired_idxs[name])
+        end
+
+        operations
+      end
+    end
+  end
+end

data/lib/migsupo/differ/operations/add_column.rb

@@ -0,0 +1,27 @@
+module Migsupo
+  module Differ
+    module Operations
+      class AddColumn
+        attr_reader :table_name, :column
+
+        def initialize(table_name:, column:)
+          @table_name = table_name.to_s
+          @column     = column
+          freeze
+        end
+
+        def migration_type
+          :add_column
+        end
+
+        def reversible?
+          true
+        end
+
+        def to_s
+          "add_column #{table_name}.#{column.name} (#{column.type})"
+        end
+      end
+    end
+  end
+end

data/lib/migsupo/differ/operations/add_index.rb

@@ -0,0 +1,27 @@
+module Migsupo
+  module Differ
+    module Operations
+      class AddIndex
+        attr_reader :table_name, :index
+
+        def initialize(table_name:, index:)
+          @table_name = table_name.to_s
+          @index      = index
+          freeze
+        end
+
+        def migration_type
+          :add_index
+        end
+
+        def reversible?
+          true
+        end
+
+        def to_s
+          "add_index #{table_name} [#{index.columns.join(', ')}]"
+        end
+      end
+    end
+  end
+end

data/lib/migsupo/differ/operations/change_column.rb

@@ -0,0 +1,33 @@
+module Migsupo
+  module Differ
+    module Operations
+      class ChangeColumn
+        attr_reader :table_name, :new_column, :old_column
+
+        def initialize(table_name:, new_column:, old_column:)
+          @table_name = table_name.to_s
+          @new_column = new_column
+          @old_column = old_column
+          freeze
+        end
+
+        def column_name
+          @new_column.name
+        end
+
+        def migration_type
+          :change_column
+        end
+
+        # change_column is irreversible in Rails unless we provide explicit up/down
+        def reversible?
+          false
+        end
+
+        def to_s
+          "change_column #{table_name}.#{column_name} (#{old_column.type} -> #{new_column.type})"
+        end
+      end
+    end
+  end
+end

data/lib/migsupo/differ/operations/create_table.rb

@@ -0,0 +1,30 @@
+module Migsupo
+  module Differ
+    module Operations
+      class CreateTable
+        attr_reader :table
+
+        def initialize(table)
+          @table = table
+          freeze
+        end
+
+        def table_name
+          @table.name
+        end
+
+        def migration_type
+          :create_table
+        end
+
+        def reversible?
+          true
+        end
+
+        def to_s
+          "create_table #{table_name}"
+        end
+      end
+    end
+  end
+end

data/lib/migsupo/differ/operations/drop_table.rb

@@ -0,0 +1,30 @@
+module Migsupo
+  module Differ
+    module Operations
+      class DropTable
+        attr_reader :table
+
+        def initialize(table)
+          @table = table
+          freeze
+        end
+
+        def table_name
+          @table.name
+        end
+
+        def migration_type
+          :drop_table
+        end
+
+        def reversible?
+          true
+        end
+
+        def to_s
+          "drop_table #{table_name}"
+        end
+      end
+    end
+  end
+end

data/lib/migsupo/differ/operations/remove_column.rb

@@ -0,0 +1,31 @@
+module Migsupo
+  module Differ
+    module Operations
+      class RemoveColumn
+        attr_reader :table_name, :column
+
+        def initialize(table_name:, column:)
+          @table_name = table_name.to_s
+          @column     = column
+          freeze
+        end
+
+        def column_name
+          @column.name
+        end
+
+        def migration_type
+          :remove_column
+        end
+
+        def reversible?
+          true
+        end
+
+        def to_s
+          "remove_column #{table_name}.#{column_name}"
+        end
+      end
+    end
+  end
+end

data/lib/migsupo/differ/operations/remove_index.rb

@@ -0,0 +1,27 @@
+module Migsupo
+  module Differ
+    module Operations
+      class RemoveIndex
+        attr_reader :table_name, :index
+
+        def initialize(table_name:, index:)
+          @table_name = table_name.to_s
+          @index      = index
+          freeze
+        end
+
+        def migration_type
+          :remove_index
+        end
+
+        def reversible?
+          true
+        end
+
+        def to_s
+          "remove_index #{table_name} [#{index.columns.join(', ')}]"
+        end
+      end
+    end
+  end
+end

data/lib/migsupo/differ/operations/rename_column.rb

@@ -0,0 +1,28 @@
+module Migsupo
+  module Differ
+    module Operations
+      class RenameColumn
+        attr_reader :table_name, :old_name, :new_name
+
+        def initialize(table_name:, old_name:, new_name:)
+          @table_name = table_name.to_s
+          @old_name   = old_name.to_s
+          @new_name   = new_name.to_s
+          freeze
+        end
+
+        def migration_type
+          :rename_column
+        end
+
+        def reversible?
+          true
+        end
+
+        def to_s
+          "rename_column #{table_name}.#{old_name} -> #{new_name}"
+        end
+      end
+    end
+  end
+end