slash_migrate 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: e02b861e967a6d80fde6d69853c8222cbb16bee08c698d4566673f7f3baf34ec
+  data.tar.gz: dd3e18fb6ee29dbb2882112062c87659a3d62569773d62256cdb1f7866142fcd
+SHA512:
+  metadata.gz: d96ec25095737a5cb6a48b8fd6abcd63635f1bd6487df203d7e910f180f8378654a95b91113f04a09fa908997e8f373c9d8eb9462346809c3ce053ef9b17a625
+  data.tar.gz: 86548b278ba6c311b89ab96f23e887bebd57cd40d3156d0869bdd76e6ae1850f891a225b8c1e50ad556899bc4649c9cee3b250ec7a91bc9bf98eacc7a74b3293

data/CHANGELOG.md

@@ -0,0 +1,21 @@
+# Changelog
+
+All notable changes to this project are documented here. The format is based on
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project
+adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.0] - 2026-05-27
+
+### Added
+
+- Initial release: a development-only, self-mounting Rails engine that serves a
+  GUI for common database migrations at `/rails/migrate`.
+- Browse tables, columns, indexes, and foreign keys.
+- Create models and migrations with column types, `null` / `default`, indexes
+  (including unique), and `references` / foreign keys.
+- Add, edit, and drop columns; add and drop indexes.
+- Run, roll back, and delete pending migrations.
+- A live preview of the migration and model code each action will generate.
+- `SlashMigrate.configure` for `mount_path` and `enabled_environments`.
+
+[0.1.0]: https://github.com/firstdraft/slash_migrate/releases/tag/v0.1.0

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright Raghu Betina
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,74 @@
+# slash_migrate
+
+A development-only Rails engine that gives you a GUI for everyday database
+migrations. Mount it, visit `/rails/migrate`, and create models, design columns
+and indexes, and modify existing tables — while it shows you the exact migration
+code it will write, so you pick up the commands as you go.
+
+It's built for people still getting comfortable with Active Record migrations.
+
+> **Development only.** slash_migrate writes real files to `db/migrate` and
+> `app/models` and runs real migrations against your database. It mounts in your
+> development environment only (configurable) and should never be loaded in
+> production.
+
+## Installation
+
+Add it to the `development` group of your `Gemfile`:
+
+```ruby
+group :development do
+  gem "slash_migrate"
+end
+```
+
+Then install:
+
+```bash
+bundle install
+```
+
+There's no `routes.rb` change to make — the engine mounts itself at
+`/rails/migrate` in development. Start your server and visit
+<http://localhost:3000/rails/migrate>.
+
+## What you can do
+
+- Browse your tables, columns, indexes, and foreign keys.
+- Create a model and its migration, with column types, `null` / `default`,
+  indexes (including unique), and `references` / foreign keys.
+- Add, edit, or drop columns on an existing table.
+- Add or drop indexes.
+- Run, roll back, or delete pending migrations.
+
+Every screen previews the migration (and model) code it will generate before you
+commit to it.
+
+## Configuration
+
+The defaults suit most apps. To change them, add an initializer:
+
+```ruby
+# config/initializers/slash_migrate.rb
+SlashMigrate.configure do |config|
+  config.mount_path = "/rails/migrate"          # where the engine mounts
+  config.enabled_environments = ["development"]  # environments it runs in
+end
+```
+
+The engine mounts itself when routes are drawn, which happens after your
+initializers run — so overriding these values here takes effect.
+
+## Requirements
+
+- Ruby >= 3.4
+- Rails >= 8.1.3
+
+## Contributing
+
+Bug reports and pull requests are welcome at
+<https://github.com/firstdraft/slash_migrate>.
+
+## License
+
+Released under the [MIT License](MIT-LICENSE).

data/Rakefile

@@ -0,0 +1,6 @@
+require "bundler/setup"
+
+APP_RAKEFILE = File.expand_path("spec/dummy/Rakefile", __dir__)
+load "rails/tasks/engine.rake"
+
+require "bundler/gem_tasks"

data/app/controllers/slash_migrate/application_controller.rb

@@ -0,0 +1,15 @@
+module SlashMigrate
+  class ApplicationController < ActionController::Base
+    # Make the engine's view helpers (sm_icon, ruby_code_body, callouts, …)
+    # available in every engine view, regardless of how the host app configures
+    # helper inclusion.
+    helper SlashMigrate::ApplicationHelper
+
+    # A builder refuses to write a migration whose name duplicates an existing
+    # one (two same-named migrations break db:migrate); surface it as a friendly
+    # alert rather than a 500.
+    rescue_from MigrationFileWriter::DuplicateError do |error|
+      redirect_to migrations_path, alert: error.message
+    end
+  end
+end

data/app/controllers/slash_migrate/assets_controller.rb

@@ -0,0 +1,26 @@
+module SlashMigrate
+  # Serves the engine's vendored, precompiled JS/CSS straight from the gem, so
+  # the UI works identically no matter how the host app handles assets (or
+  # whether it has an asset pipeline at all). Files live under lib/ specifically
+  # so the host's pipeline never scans or fingerprints them.
+  class AssetsController < ActionController::Base
+    # These are static files, served by GET. Rails' forgery protection otherwise
+    # raises InvalidCrossOriginRequest when returning JavaScript over a plain GET
+    # (its cross-origin <script> defense), which would block our own bundle.
+    skip_forgery_protection
+
+    ASSET_DIR = SlashMigrate::Engine.root.join("lib/slash_migrate/assets")
+    CONTENT_TYPES = {".js" => "text/javascript", ".css" => "text/css"}.freeze
+
+    def show
+      # File.basename strips any path components, so :name can only ever resolve
+      # to a file directly inside ASSET_DIR — no directory traversal.
+      path = ASSET_DIR.join(File.basename(params[:name].to_s))
+      raise ActionController::RoutingError, "Asset not found: #{params[:name]}" unless path.file?
+
+      send_file path,
+        type: CONTENT_TYPES.fetch(path.extname, "application/octet-stream"),
+        disposition: "inline"
+    end
+  end
+end

data/app/controllers/slash_migrate/columns_controller.rb

@@ -0,0 +1,106 @@
+module SlashMigrate
+  class ColumnsController < ApplicationController
+    before_action :require_table
+
+    def new
+      @migration = AddColumnsMigration.new(table: @table)
+      @existing_tables = inspector.table_names
+    end
+
+    def preview
+      @migration = AddColumnsMigration.from_params(table: @table, rows: params[:attributes])
+      @hint = "Add a column to see the migration it will generate." unless @migration.any?
+      render :preview, layout: false
+    rescue => e
+      @error = e.message
+      render :preview, layout: false
+    end
+
+    def create
+      migration = AddColumnsMigration.from_params(table: @table, rows: params[:attributes])
+
+      unless migration.any?
+        redirect_to(new_table_column_path(@table), alert: "Add at least one column.")
+        return
+      end
+
+      written = migration.write!
+      redirect_to migrations_path,
+        notice: "Created #{written.join(", ")}. Run it below to apply."
+    end
+
+    def edit
+      @column = find_column
+      head :not_found and return unless @column
+
+      @drop_migration = DropColumnMigration.new(table: @table, column: @column)
+      @drop_caveat = drop_caveat
+    end
+
+    def drop
+      column = find_column
+      head :not_found and return unless column
+
+      written = DropColumnMigration.new(table: @table, column: column).write!
+      redirect_to migrations_path,
+        notice: "Created #{written.join(", ")}. Run it below to apply."
+    end
+
+    def update_preview
+      original = find_column
+      @migration = original && EditColumnMigration.new(table: @table, original: original, desired: desired_column)
+      @hint = "Change a value to see the migration it will generate." unless @migration&.changed?
+      render :update_preview, layout: false
+    rescue => e
+      @error = e.message
+      render :update_preview, layout: false
+    end
+
+    def update
+      original = find_column
+      head :not_found and return unless original
+
+      migration = EditColumnMigration.new(table: @table, original: original, desired: desired_column)
+
+      unless migration.changed?
+        redirect_to(edit_table_column_path(@table, params[:name]), alert: "No changes to apply.")
+        return
+      end
+
+      written = migration.write!
+      redirect_to migrations_path,
+        notice: "Created #{written.join(", ")}. Run it below to apply."
+    end
+
+    private
+
+    def require_table
+      @table = params[:table_id]
+      head :not_found unless inspector.exists?(@table)
+    end
+
+    def find_column
+      ar_column = inspector.table(@table).columns.find { |column| column.name == params[:name] }
+      ar_column && Column.from_schema(ar_column)
+    end
+
+    # remove_column re-adds the column on rollback, but not the index or foreign
+    # key that were on it — so say so when either is present.
+    def drop_caveat
+      table = inspector.table(@table)
+      dependents = []
+      dependents << "index" if table.indexes.any? { |index| Array(index.columns).include?(@column.name) }
+      dependents << "foreign key" if table.foreign_keys.any? { |fk| fk.column == @column.name }
+      base = "db:rollback re-adds the column, but the data in it is gone for good"
+      dependents.empty? ? "#{base}." : "#{base} — and its #{dependents.join(" and ")} won't be restored."
+    end
+
+    def desired_column
+      Column.from_params(params.fetch(:column, {}))
+    end
+
+    def inspector
+      @inspector ||= SchemaInspector.new
+    end
+  end
+end

data/app/controllers/slash_migrate/indexes_controller.rb

@@ -0,0 +1,54 @@
+module SlashMigrate
+  class IndexesController < ApplicationController
+    before_action :require_table
+
+    def new
+      @columns = inspector.table(@table).columns.map(&:name)
+      @migration = AddIndexMigration.new(table: @table)
+    end
+
+    def preview
+      @migration = build_migration
+      @hint = "Pick a column to index to see the migration it will generate." unless @migration.any?
+      render :preview, layout: false
+    rescue => e
+      @error = e.message
+      render :preview, layout: false
+    end
+
+    def create
+      migration = build_migration
+
+      unless migration.any?
+        redirect_to(new_table_index_path(@table), alert: "Pick at least one column to index.")
+        return
+      end
+
+      written = migration.write!
+      redirect_to migrations_path, notice: "Created #{written.join(", ")}. Run it below to apply."
+    end
+
+    def drop
+      index = inspector.table(@table).indexes.find { |candidate| candidate.name == params[:name] }
+      head :not_found and return unless index
+
+      written = DropIndexMigration.new(table: @table, index: index).write!
+      redirect_to migrations_path, notice: "Created #{written.join(", ")}. Run it below to apply."
+    end
+
+    private
+
+    def build_migration
+      AddIndexMigration.from_params(table: @table, columns: params[:columns], unique: params[:unique], name: params[:name])
+    end
+
+    def require_table
+      @table = params[:table_id]
+      head :not_found unless inspector.exists?(@table)
+    end
+
+    def inspector
+      @inspector ||= SchemaInspector.new
+    end
+  end
+end

data/app/controllers/slash_migrate/migrations_controller.rb

@@ -0,0 +1,41 @@
+module SlashMigrate
+  class MigrationsController < ApplicationController
+    def index
+      @migrations = runner.status
+      @pending = runner.pending?
+    end
+
+    def run
+      finish(runner.migrate, "Migrated.", "rails db:migrate")
+    end
+
+    def rollback
+      finish(runner.rollback, "Rolled back the last migration.", "rails db:rollback")
+    end
+
+    def destroy
+      result = runner.delete(params[:version])
+      flash[result.success? ? :notice : :alert] = result.output
+      redirect_to migrations_path
+    end
+
+    private
+
+    def runner
+      @runner ||= MigrationRunner.new
+    end
+
+    # Post/redirect/get: stash the (truncated) command output in the flash so a
+    # refresh doesn't re-run the task.
+    def finish(result, message, command)
+      flash[:migrate_output] = result.output.to_s.last(3000)
+      flash[:migrate_command] = command
+      if result.success?
+        flash[:notice] = message
+      else
+        flash[:alert] = "Command failed — see the output below."
+      end
+      redirect_to migrations_path
+    end
+  end
+end

data/app/controllers/slash_migrate/models_controller.rb

@@ -0,0 +1,49 @@
+module SlashMigrate
+  class ModelsController < ApplicationController
+    def new
+      @builder = MigrationBuilder.new(name: "")
+      @existing_tables = inspector.table_names
+    end
+
+    # Live preview: rebuilds the migration + model source on every (debounced)
+    # form change and streams it back. Pure string building, no disk writes.
+    def preview
+      @builder = build_builder
+
+      if @builder.name_present?
+        @table_exists = inspector.exists?(@builder.table_name)
+      else
+        @hint = "Enter a model name to see the migration it will generate."
+      end
+
+      render :preview, layout: false
+    rescue => e
+      # Partial/invalid input shouldn't 500 the live preview; show the problem.
+      @error = e.message
+      render :preview, layout: false
+    end
+
+    def create
+      builder = build_builder
+
+      if inspector.exists?(builder.table_name)
+        redirect_to(new_model_path, alert: "A table named #{builder.table_name} already exists.")
+        return
+      end
+
+      written = builder.write!
+      redirect_to migrations_path,
+        notice: "Created #{written.join(", ")}. Run it below to apply."
+    end
+
+    private
+
+    def build_builder
+      MigrationBuilder.from_params(name: params[:model_name], rows: params[:attributes])
+    end
+
+    def inspector
+      @inspector ||= SchemaInspector.new
+    end
+  end
+end

data/app/controllers/slash_migrate/tables_controller.rb

@@ -0,0 +1,19 @@
+module SlashMigrate
+  class TablesController < ApplicationController
+    def index
+      @table_names = inspector.table_names
+    end
+
+    def show
+      head :not_found and return unless inspector.exists?(params[:id])
+
+      @table = inspector.table(params[:id])
+    end
+
+    private
+
+    def inspector
+      @inspector ||= SchemaInspector.new
+    end
+  end
+end

data/app/helpers/slash_migrate/application_helper.rb

@@ -0,0 +1,168 @@
+module SlashMigrate
+  module ApplicationHelper
+    # Inline 16px SVG icons, ported from the design's stroke set. Returned with
+    # width/height of 1em so they scale with surrounding text; per-context CSS
+    # (.btn svg, .nav-link svg, …) overrides the size where needed.
+    ICON_PATHS = {
+      database: %(<ellipse cx="8" cy="3.5" rx="5.5" ry="2"/><path d="M2.5 3.5v9c0 1.1 2.46 2 5.5 2s5.5-.9 5.5-2v-9"/><path d="M2.5 8c0 1.1 2.46 2 5.5 2s5.5-.9 5.5-2"/>),
+      plus: %(<path d="M8 3v10M3 8h10"/>),
+      arrow_right: %(<path d="M3 8h10M9 4l4 4-4 4"/>),
+      arrow_left: %(<path d="M13 8H3M7 4L3 8l4 4"/>),
+      chevron: %(<path d="M6 4l4 4-4 4"/>),
+      history: %(<path d="M2.5 8a5.5 5.5 0 1 0 1.6-3.9"/><path d="M2 2v3h3"/><path d="M8 5v3.5l2 1.2"/>),
+      info: %(<circle cx="8" cy="8" r="6"/><path d="M8 7.2v3.6M8 5.2v.01"/>),
+      warn: %(<path d="M8 2.5l6 11H2l6-11Z"/><path d="M8 6.5v3M8 11.4v.01"/>),
+      check: %(<path d="M3 8.5l3.5 3.5L13 5"/>),
+      x: %(<path d="M4 4l8 8M12 4l-8 8"/>),
+      trash: %(<path d="M3 4.5h10M6.5 4.5V3a1 1 0 0 1 1-1h1a1 1 0 0 1 1 1v1.5M5 4.5l.5 8a1 1 0 0 0 1 .9h3a1 1 0 0 0 1-.9l.5-8"/>),
+      play: %(<path d="M5 3.5v9l8-4.5z"/>),
+      rotate: %(<path d="M13.5 8a5.5 5.5 0 1 1-1.6-3.9"/><path d="M14 2v3h-3"/>),
+      file: %(<path d="M9 1.5H4.5A1.5 1.5 0 0 0 3 3v10a1.5 1.5 0 0 0 1.5 1.5h7A1.5 1.5 0 0 0 13 13V5.5z"/><path d="M9 1.5V5.5H13"/>),
+      terminal: %(<rect x="2" y="3" width="12" height="10" rx="1.5"/><path d="M5 7l2 1.5L5 10M8.5 10h2.5"/>),
+      key: %(<circle cx="6" cy="10" r="3"/><path d="M8.1 7.9 13 3M11 5l2 2M9.5 6.5L11.5 8.5"/>),
+      lock: %(<rect x="3.5" y="7" width="9" height="6.5" rx="1.5"/><path d="M5.5 7V5.2a2.5 2.5 0 0 1 5 0V7"/>)
+    }.freeze
+    FILLED_ICONS = %i[play].freeze
+
+    def sm_icon(name)
+      name = name.to_sym
+      inner = ICON_PATHS.fetch(name)
+      head =
+        if FILLED_ICONS.include?(name)
+          %(<svg xmlns="http://www.w3.org/2000/svg" width="1em" height="1em" viewBox="0 0 16 16" fill="currentColor" aria-hidden="true">)
+        else
+          %(<svg xmlns="http://www.w3.org/2000/svg" width="1em" height="1em" viewBox="0 0 16 16" fill="none" stroke="currentColor" stroke-width="1.4" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true">)
+        end
+      (head + inner + "</svg>").html_safe
+    end
+
+    # A top-nav link with its icon and active state.
+    def nav_link(label, url, icon, active: false)
+      link_to url, class: "nav-link#{" is-active" if active}" do
+        safe_join([sm_icon(icon), label], " ")
+      end
+    end
+
+    # The column types worth showing first, in teaching order. Anything else the
+    # database supports follows, alphabetically.
+    COMMON_COLUMN_TYPES = %w[string text integer boolean references datetime date decimal float].freeze
+
+    # The column types this app's database actually supports, read from the
+    # adapter (so Postgres surfaces uuid/jsonb/etc., SQLite its smaller set), with
+    # the everyday types pinned to the top. `references` is a Rails association
+    # helper rather than a native type, so it's added unless asked otherwise
+    # (change_column can't target it). Note: virtual types a gem adds via the
+    # table-definition API — e.g. money-rails' monetize — aren't reported here.
+    def available_column_types(include_references: true)
+      native = ActiveRecord::Base.connection.native_database_types.keys.map(&:to_s) - ["primary_key"]
+      native << "references" if include_references
+      native.uniq!
+      common = COMMON_COLUMN_TYPES.select { |type| native.include?(type) }
+      common + (native - common).sort
+    end
+
+    # The 14-digit UTC version a migration generated right now would carry. Shown
+    # in preview filenames and ticked forward each second client-side, so students
+    # see where that number comes from.
+    def migration_version
+      Time.now.utc.strftime("%Y%m%d%H%M%S")
+    end
+
+    # Which nav item to highlight, derived from the controller handling the request.
+    def nav_section
+      case controller_name
+      when "models" then :new
+      when "migrations" then :migrations
+      else :tables # tables, columns, indexes all live under "Tables"
+      end
+    end
+
+    # Renders Ruby source as the syntax-highlighted lines of a `.code-body`. A
+    # small, purpose-built tokenizer — enough to colour migrations and models,
+    # not a general Ruby parser.
+    def ruby_code_body(source)
+      lines = source.to_s.split("\n", -1)
+      lines.pop if lines.last == "" # trailing newline shouldn't draw a blank line
+      rendered = lines.map { |line| "<span>#{highlight_ruby_line(line)}</span>" }.join
+      %(<div class="code-lines">#{rendered}</div>).html_safe
+    end
+
+    # Renders raw command output as plain monochrome lines (no gutter, no tinting)
+    # — the way a real terminal shows it.
+    def terminal_body(output)
+      lines = output.to_s.split("\n", -1)
+      lines.pop if lines.last == ""
+      rendered = lines.map { |line| "<span>#{line.empty? ? "&nbsp;" : ERB::Util.html_escape(line)}</span>" }.join
+      %(<div class="code-lines">#{rendered}</div>).html_safe
+    end
+
+    private
+
+    RUBY_KEYWORDS = %w[
+      class def end if elsif else unless do return nil true false module
+      up down change
+    ].freeze
+    RUBY_METHODS = %w[
+      create_table add_column remove_column change_column rename_column rename_table
+      add_reference remove_reference add_index remove_index drop_table change_table
+      add_foreign_key remove_foreign_key change_column_null change_column_default execute
+      belongs_to has_many has_one validates references string text integer bigint
+      float decimal boolean date datetime time timestamps binary json
+      null default limit precision scale index unique foreign_key to_table from to comment
+    ].freeze
+    RUBY_TOKEN = %r{
+      "(?:[^"\\]|\\.)*"      # double-quoted string
+      |'(?:[^'\\]|\\.)*'     # single-quoted string
+      |:[a-z_]\w*            # symbol
+      |[A-Z][\w:]*           # constant or class name
+      |[a-z_]\w*[?!]?        # identifier or method
+      |\d+\.\d+              # float
+      |\d+                   # integer
+      |\#.*                  # comment to end of line
+      |[^\s\w]               # punctuation
+    }x
+
+    def highlight_ruby_line(line)
+      return "&nbsp;" if line.empty?
+
+      leading = line[/\A\s*/]
+      rest = line[leading.length..]
+      out = +""
+      out << ERB::Util.html_escape(leading) unless leading.empty?
+      return out + span("cm", rest) if rest.start_with?("#")
+
+      last = 0
+      rest.scan(RUBY_TOKEN) do
+        token = Regexp.last_match[0]
+        start = Regexp.last_match.begin(0)
+        out << ERB::Util.html_escape(rest[last...start]) if start > last
+        out << span(ruby_token_class(token), token)
+        last = Regexp.last_match.end(0)
+      end
+      out << ERB::Util.html_escape(rest[last..]) if last < rest.length
+      out
+    end
+
+    def ruby_token_class(token)
+      case token
+      when /\A["']/ then "s"
+      when /\A:/ then "sy"
+      when /\A#/ then "cm"
+      when /\A\d/ then "n"
+      when /\A[A-Z]/ then "c"
+      else
+        if RUBY_KEYWORDS.include?(token)
+          "k"
+        elsif RUBY_METHODS.include?(token)
+          "m"
+        else
+          "p"
+        end
+      end
+    end
+
+    def span(klass, text)
+      %(<em class="tk-#{klass}">#{ERB::Util.html_escape(text)}</em>)
+    end
+  end
+end

data/app/jobs/slash_migrate/application_job.rb

@@ -0,0 +1,4 @@
+module SlashMigrate
+  class ApplicationJob < ActiveJob::Base
+  end
+end

data/app/mailers/slash_migrate/application_mailer.rb

@@ -0,0 +1,6 @@
+module SlashMigrate
+  class ApplicationMailer < ActionMailer::Base
+    default from: "from@example.com"
+    layout "mailer"
+  end
+end

data/app/models/slash_migrate/application_record.rb

@@ -0,0 +1,5 @@
+module SlashMigrate
+  class ApplicationRecord < ActiveRecord::Base
+    self.abstract_class = true
+  end
+end