departure 7.0.0 → 8.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c90b332f5ca8002ae23bedaab9b368f2aa89c103ab287aa593f5563901e9bb10
-  data.tar.gz: 46c52d6ce29dda0c0358cca5da19bfd5ebbe327e626c3c4c332fa7189df17759
+  metadata.gz: 7c430a93842e6abdfa3f64de47ae938c782d53bbaba75ba532baee057b25d471
+  data.tar.gz: 0eeaaeaa8a9d6cf83885ab94b4ad1aae833d73f1fd1f9da87414476f5eede157
 SHA512:
-  metadata.gz: dd21cf4f7b78ea979a92424540dde3a0e8bad9d1acf891f334352e5e6f9cc372d0c4fa897d9afb88d1cb282504a65895c00a87b467a52f6ca2423501c7f68af0
-  data.tar.gz: 4b9b1112c42fd3b823eeb613bbde33ec596da1a7b2e1371ef2f87960b60a4c40a21a7d43bd2222269b2a8e71bd00c91bfa5d044ff5c2dce489cc299473b73a22
+  metadata.gz: 4e0b56e69008ab1885216db89d106775ef10198819d2da007476820921c8c382c79aba3d63637a99276c321723112796936b03b5b099db3a629bbe80d9da21f4
+  data.tar.gz: d9de074bdaa985d016e83ad61745e3c77930e9262bc5dea7e4d7a5b9db75d86c66db9f2929d14f474f91f1ffbb3397a553b6c4e60fc0c5dd2e9800db15a04ee6

data/.github/workflows/test.yml

@@ -3,7 +3,7 @@ name: Test
 on: [push, pull_request]
 
 jobs:
-  test:
+  test_mysql:
     strategy:
       fail-fast: false
       matrix:
@@ -12,10 +12,9 @@ jobs:
           - 3.3
           - 3.4
         gemfile:
-          - gemfiles/rails_7_0.gemfile
-          - gemfiles/rails_7_1.gemfile
           - gemfiles/rails_7_2.gemfile
           - gemfiles/rails_8_0.gemfile
+          - gemfiles/rails_8_1.gemfile
     env:
       PERCONA_DB_USER: root
       PERCONA_DB_PASSWORD: root
@@ -37,18 +36,55 @@ jobs:
         run: sudo systemctl start mysql.service
       - run: bin/setup
       - run: bundle exec rake
+
+  test_trilogy:
+    strategy:
+      fail-fast: false
+      matrix:
+        ruby:
+          - 3.2
+          - 3.3
+          - 3.4
+        gemfile:
+          - gemfiles/rails_8_1.gemfile
+    env:
+      DB_ADAPTER: "trilogy"
+      PERCONA_DB_USER: root
+      PERCONA_DB_PASSWORD: root
+      BUNDLE_GEMFILE: ${{ matrix.gemfile }}
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: ${{ matrix.ruby }}
+          bundler-cache: true
+      - name: "Add Percona GPG key"
+        run: sudo apt-key adv --keyserver hkp://keyserver.ubuntu.com:80 --recv-keys 9334A25F8507EFA5
+      - name: "Add Percona APT repository"
+        run: echo "deb http://repo.percona.com/apt `lsb_release -cs` main" | sudo tee -a /etc/apt/sources.list
+      - run: sudo apt-get update -qq
+      - run: sudo apt-get install percona-toolkit
+      - name: Start MySQL server
+        run: sudo systemctl start mysql.service
+      - name: Configure MySQL for Trilogy
+        run: |
+          sudo mysql -u root -proot -e "ALTER USER 'root'@'localhost' IDENTIFIED WITH mysql_native_password BY 'root'; FLUSH PRIVILEGES;"
+      - run: bin/setup
+      - run: bundle exec rake
+
   lint:
     strategy:
       fail-fast: false
     env:
       PERCONA_DB_USER: root
       PERCONA_DB_PASSWORD: root
-      BUNDLE_GEMFILE: gemfiles/rails_7_1.gemfile
+      BUNDLE_GEMFILE: gemfiles/rails_8_1.gemfile
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
       - uses: ruby/setup-ruby@v1
         with:
-          ruby-version: 3.3
+          ruby-version: 3.4
           bundler-cache: true
       - run: bundle exec rubocop --parallel

data/AGENTS.md

@@ -0,0 +1,75 @@
+# Context
+
+Departure is a Ruby gem that wraps Rails ActiveRecord migrations using `ALTER TABLE` statements with `pt-online-schema-change` (Percona Toolkit) so DDL runs online and non-blocking.
+
+It must stay aware of how the ActiveRecord API changes across versions and supports all currently supported versions of Rails and Ruby.
+
+It supports both the `mysql2` and `trilogy` database adapter gems (trilogy on Rails 8.1+).
+
+# Project Layout
+
+- `lib/active_record/connection_adapters/` — per-Rails-version connection adapters:
+  - `rails_7_2_departure_adapter.rb`
+  - `rails_8_0_departure_adapter.rb`
+  - `rails_8_1_mysql2_adapter.rb`
+  - `rails_8_1_trilogy_adapter.rb`
+  - `for_alter.rb`, `patch_connection_handling.rb` — shared behavior
+- `lib/departure/rails_adapter.rb` — version dispatch. `Departure::RailsAdapter.for(ar_version, db_connection_adapter:)` selects the right adapter class. New Rails/adapter combinations are wired in here.
+- `lib/departure/railtie.rb` — Rails integration entry point; calls `RailsAdapter.register_integrations`.
+- `lib/departure/runner.rb`, `cli_generator.rb`, `command.rb` — intercept ALTER statements and shell out to `pt-online-schema-change`.
+- `lib/departure/rails_patches/` — targeted patches against ActiveRecord internals.
+- `lib/lhm/` — LHM DSL compatibility shim.
+- `spec/dummy/` — minimal Rails app used by integration specs.
+
+# Adapter Selection
+
+1. If the database config specifies `trilogy` (Rails 8.1+), use the trilogy adapter.
+2. Otherwise default to `mysql2`.
+
+Selection lives in `Departure::RailsAdapter.for`. When adding a new Rails version, add a `V<MAJOR>_<MINOR>_*Adapter` subclass of `BaseAdapter` and update the dispatch logic.
+
+# Development
+
+- `docker-compose.yml` brings up a MySQL database container and a Rails container with the gem mounted in.
+- The `Appraisal` gem manages Rails version dependencies; configurations live in `Appraisals` and generated gemfiles in `gemfiles/`.
+- Local gems are vendored to `tmp/local_gems` (mounted at `/app/vendor/bundle`) so debugging tools like `pry` can step through ActiveRecord internals.
+
+## Required env vars
+Set by `docker-compose.yml`; if running outside Docker, export them yourself:
+
+- `PERCONA_DB_USER`
+- `PERCONA_DB_PASSWORD`
+- `PERCONA_DB_HOST`
+- `PERCONA_DB_NAME`
+- `DB_ADAPTER=trilogy` — only when running against trilogy (Rails 8.1)
+
+## External dependencies
+
+- `pt-online-schema-change` from Percona Toolkit must be on `PATH` — the gem shells out to it. CI installs it from the Percona APT repo.
+- MySQL server. Trilogy requires `mysql_native_password` auth, not `caching_sha2_password`. CI runs `ALTER USER ... IDENTIFIED WITH mysql_native_password` followed by `FLUSH PRIVILEGES` before the trilogy job.
+
+# Testing
+
+- Be sure that changes are valid against both `rubocop` and the `rspec` suites.
+- The supported test matrix is defined in `.github/workflows/test.yml`:
+  - **mysql2:** Ruby 3.2 / 3.3 / 3.4 × Rails 7.2 / 8.0 / 8.1
+  - **trilogy:** Ruby 3.2 / 3.3 / 3.4 × Rails 8.1 only
+  - **lint:** Ruby 3.4 with the Rails 8.1 gemfile
+- Run inside Docker via `appraisal`:
+  - Full suite: `docker compose exec rails bundle exec appraisal rails-8-1 bundle exec rspec spec`
+  - Single example: `docker compose exec rails bundle exec appraisal rails-8-1 bundle exec rspec spec/path/to_spec.rb:LINE`
+  - Trilogy run: prepend `DB_ADAPTER=trilogy` to the rspec command (rails-8-1 only)
+  - Lint: `docker compose exec rails bundle exec appraisal rails-8-1 bundle exec rubocop --parallel`
+
+# Adding a Rails version
+
+1. Add an `appraise '<rails-x-y>' do ... end` block in `Appraisals`.
+2. `bundle exec appraisal generate && bundle exec appraisal install`
+3. Add a matching `V<X>_<Y>_*Adapter` class in `lib/departure/rails_adapter.rb` and a connection-adapter file under `lib/active_record/connection_adapters/`.
+4. Update the `gemfile:` matrix in `.github/workflows/test.yml`. Add a separate `test_trilogy` entry only if trilogy is supported on that version.
+
+# Conventions
+
+- Follow the existing adapter naming pattern: `rails_<MAJOR>_<MINOR>_<DRIVER>_adapter.rb` and register through `Departure::RailsAdapter`. Don't introduce a parallel registration path.
+- User-visible changes go in `CHANGELOG.md` (Keep a Changelog format).
+- Release process is documented in `RELEASING.md`.

data/Appraisals

@@ -1,15 +1,14 @@
-appraise 'rails-7-0' do
-  gem 'rails', '7.0.8'
-end
-
-appraise 'rails-7-1' do
-  gem 'rails', '7.1.3'
-end
-
 appraise 'rails-7-2' do
+  gem 'bigdecimal'
   gem 'rails', '7.2.2.1'
 end
 
 appraise 'rails-8-0' do
+  gem 'bigdecimal'
   gem 'rails', '8.0.2.1'
 end
+
+appraise 'rails-8-1' do
+  gem 'rails', '8.1.1'
+  gem 'trilogy'
+end

data/CHANGELOG.md

@@ -4,6 +4,28 @@ This project adheres to [Semantic Versioning](http://semver.org/).
 
 Please follow the format in [Keep a Changelog](http://keepachangelog.com/)
 
+## [NEXT]
+
+## [8.1.0] - 2026-05-28
+
+- [Add Rails 8.1 Trilogy adapter support](https://github.com/departurerb/departure/pull/132)
+
+## [8.0.2] - 2026-04-30
+
+- [Fix Rails multi-database migrations](https://github.com/departurerb/departure/pull/138)
+
+## [8.0.1] - 2025-12-12
+
+- [Remove stderr message "Including for_alter statements"](https://github.com/departurerb/departure/pull/136)
+
+## [8.0.0] - 2025-11-24
+
+- Bump [appraisal to 2.5.0](https://github.com/departurerb/departure/pull/129)
+- Add support for [Rails 8.1](https://github.com/departurerb/departure/pull/128)
+- Skinnify Departure [to remove most non pt-online-schema-change](https://github.com/departurerb/departure/pull/131) responsibility from departure
+- Inherit from [Mysql2 Adapter instead of AbstractMysqlAdapter](https://github.com/departurerb/departure/pull/130)
+- Remove Support for [Rails 7.0 and Rails 7.1](https://github.com/departurerb/departure/pull/135)
+  
 ## [7.0.0] - 2025-08-21
 
 - Drop Ruby 3.1 support.  Add >= 3.2 ruby support in gemspec.  EOL for 3.1.0 was 2025-03-31

data/Dockerfile

@@ -1,4 +1,4 @@
-FROM ruby:3.0
+FROM ruby:3.4
 MAINTAINER muffinista@gmail.com
 
 # Install apt based dependencies required to run Rails as
@@ -14,17 +14,10 @@ RUN apt-get update && apt-get install -y \
 RUN mkdir -p /app /app/lib/departure
 WORKDIR /app
 
-# Copy the Gemfile as well as the Gemfile.lock and install
-# the RubyGems. This is a separate step so the dependencies
-# will be cached unless changes to one of those two files
-# are made.
-COPY departure.gemspec Gemfile ./
-COPY lib/departure/version.rb ./lib/departure/
+# Install bundler - dependencies will be installed via volume mount
+RUN gem install bundler
 
-RUN gem install bundler && bundle install --jobs 20 --retry 5
-
-# Copy the main application.
-COPY . ./
+# Project root will be mounted as volume for live development
 
 # The main command to run when the container starts. Also
 # tell the Rails dev server to bind to all interfaces by

data/Gemfile.lock

@@ -1,10 +1,10 @@
 PATH
   remote: .
   specs:
-    departure (7.0.0)
-      activerecord (>= 7.0.1)
+    departure (8.1.0)
+      activerecord (>= 7.2.0)
       mysql2 (>= 0.4.0, < 0.6.0)
-      railties (>= 7.0.1)
+      railties (>= 7.2.0)
 
 GEM
   remote: https://rubygems.org/
@@ -44,7 +44,7 @@ GEM
       securerandom (>= 0.3)
       tzinfo (~> 2.0, >= 2.0.5)
       uri (>= 0.13.1)
-    appraisal (2.4.1)
+    appraisal (2.5.0)
       bundler
       rake
       thor (>= 0.14.0)
@@ -86,6 +86,8 @@ GEM
     minitest (5.25.5)
     mutex_m (0.3.0)
     mysql2 (0.5.6)
+    nokogiri (1.18.7-aarch64-linux-gnu)
+      racc (~> 1.4)
     nokogiri (1.18.7-arm64-darwin)
       racc (~> 1.4)
     nokogiri (1.18.7-x86_64-linux-gnu)
@@ -191,6 +193,7 @@ GEM
     zeitwerk (2.6.18)
 
 PLATFORMS
+  aarch64-linux
   arm64-darwin-21
   arm64-darwin-22
   arm64-darwin-23
@@ -198,7 +201,7 @@ PLATFORMS
   x86_64-linux
 
 DEPENDENCIES
-  appraisal (~> 2.4.1)
+  appraisal (~> 2.5.0)
   base64
   climate_control (~> 0.0.3)
   codeclimate-test-reporter (~> 1.0.3)

data/README.md

@@ -151,9 +151,16 @@ It's strongly recommended to name it after this gems name, such as
 
 All configuration options are configurable from the `Departure.configure` block example below
 
-|Option|Default|What it Controls|
-|---|---|---|
-|disable_rails_advisory_lock_patch|false|When truthy, disables a patch in at least rails 7.1 and 7.2 where rails throws ConcurrentMigrationErrors due to the inability to release the advisory lock in migrations|
+| Option                            | Default | What it Controls                                                                                                                                                          |
+|-----------------------------------|---------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| disable_rails_advisory_lock_patch | false   | When truthy, disables a patch in at least rails 7.1 and 7.2 where rails throws ConcurrentMigrationErrors due to the inability to release the advisory lock in migrations  |
+
+### Trilogy Adapter Support
+
+Starting in Rails 8.1 we add support for the use of the trilogy database adapter gem.  Logic for selecting an adapter follows this logic
+
+1. If the database configuration specifies 'trilogy' use the trilogy adapter
+2. Default to mysql2
 
 ### Disable on per-migration basis
 
@@ -213,6 +220,85 @@ When any errors occur, an `ActiveRecord::StatementInvalid` exception is
 raised and the migration is aborted, as all other ActiveRecord connection
 adapters.
 
+### Rails multi-database applications
+
+Rails multi-database applications expect `bin/rails db:migrate` to run
+migrations for every configured database. Rails 8.1 does this through
+`ActiveRecord::Tasks::DatabaseTasks.migrate_all`, which temporarily switches the
+migration connection to each database configuration before running that
+database's migrations.
+
+Departure supports that flow by restoring Rails' migration connection identity
+after each migration. During the migration body, Departure can still reconnect
+with the Percona adapter so `ALTER TABLE` statements go through
+`pt-online-schema-change`. After the migration finishes, Rails gets back the
+same `ActiveRecord::Base.connection_specification_name` it had before Departure
+swapped adapters, so the next configured database can be migrated normally.
+
+### Diagram
+
+```mermaid
+ flowchart TB
+      %% User Level
+      subgraph "Rails Application"
+          Migration["Rails Migration<br/>(ActiveRecord::Migration)"]
+          DSL["Migration DSL<br/>(add_column, create_table, etc.)"]
+      end
+
+      %% Core Departure Components
+      subgraph "Departure System"
+          RailsAdapter["RailsAdapter<br/>(Version Detection)"]
+          DepartureAdapter["Rails81Mysql2Adapter<br/>(Connection Adapter)"]
+          Runner["Runner<br/>(Query Interceptor)"]
+          Command["Command<br/>(Process Executor)"]
+          CliGenerator["CliGenerator<br/>(Command Builder)"]
+      end
+
+      %% External Components
+      subgraph "External Tools"
+          PTOSC["pt-online-schema-change<br/>(Percona Toolkit)"]
+          MySQL["MySQL Database"]
+      end
+
+      %% LHM Integration
+      subgraph "LHM Integration"
+          LhmAdapter["Lhm::Adapter<br/>(DSL Translator)"]
+          LhmMigration["LHM Migration"]
+      end
+
+      %% Flow connections
+      Migration --> DSL
+      DSL --> DepartureAdapter
+      DepartureAdapter --> Runner
+      Runner --> |"Non-ALTER statements"| MySQL
+      CliGenerator --> Command
+      Command --> PTOSC
+      PTOSC --> MySQL
+
+      %% LHM Flow
+      LhmMigration --> LhmAdapter
+      LhmAdapter --> DSL
+
+      %% Configuration Flow
+      RailsAdapter --> |"Registers"| DepartureAdapter
+
+      %% Decision Points
+      Runner --> |"Check: ALTER TABLE?"| DecisionNode{{"ALTER TABLE<br/>Statement?"}}
+      DecisionNode --> |"Yes"| CliGenerator
+      DecisionNode --> |"No"| MySQL
+
+      %% Styling
+      classDef departure fill:#e1f5fe
+      classDef external fill:#fff3e0
+      classDef rails fill:#e8f5e8
+      classDef lhm fill:#fce4ec
+
+      class RailsAdapter,DepartureAdapter,Runner,Command,CliGenerator departure
+      class PTOSC,MySQL external
+      class Migration,DSL rails
+      class LhmAdapter,LhmMigration lhm
+```
+
 ## Trouleshooting
 
 ### Error creating new table: DBD::mysql::db do failed: Can't write; duplicate key in table (TABLE_NAME)
@@ -221,6 +307,24 @@ that prevents schema changes when a table has constraints. You should upgrade to
 
 ## Development
 
+### Setup
+
+#### Docker Compose
+
+You can bring up the docker-compose setup and bash into rails in order to not install dependencies on your system
+
+Gems are available on your local file system from tmp/local_gems directory.  We need this due to changes in 
+internals of ActiveRecord and needing to run things like pry to debug how they work.
+
+```
+docker compose up
+docker compose exec rails bash
+bundle install
+# off to the races
+```
+
+#### Manual
+
 After checking out the repo, run `bin/setup` to install dependencies. Then, run
 `rake spec` to run the tests. You can also run `bin/console` for an interactive
 prompt that will allow you to experiment.
@@ -231,6 +335,26 @@ release a new version, update the version number in `version.rb`, and then run
 git commits and tags, and push the `.gem` file to
 [rubygems.org](https://rubygems.org).
 
+### Appraisal
+
+All versions of supported rails are defined in the [Appraisals file](./Appraisals) in project root
+
+#### Usage
+
+Say you want to run a specific test under a version of rails defined in Appraisal `rails-8-0`
+
+```
+bundle exec appraisal rails-8-0 bundle install
+bundle exec appraisal rails-8-0 bundle exec rspec spec/lhm/column_with_sql_spec.rb:50
+```
+
+#### Adding Versions
+
+- Add the version to [Appraisals file](./Appraisals)
+- Run `bundle exec appraisal generate`
+- Run `bundle exec appraisal install`
+- updates ci [test.yml](./.github/workflows/test.yml) in the `gemfile:` section
+
 ## Contributing
 
 Bug reports and pull requests are welcome on GitHub at

data/config.yml.erb

@@ -1,5 +1,9 @@
 username: <%= ENV['PERCONA_DB_USER'] || 'root' %>
-password: <%= ENV['PERCONA_DB_PASSWORD'] || '' %> 
-database: <%= ENV['PERCONA_DB_NAME'] || 'departure_test' %> 
-hostname: <%= ENV['PERCONA_DB_HOST'] || 'localhost' %>
-socket: <%= ENV['PERCONA_DB_SOCKET'] || '' %>
+password: <%= ENV['PERCONA_DB_PASSWORD'] || '' %>
+database: <%= ENV['PERCONA_DB_NAME'] || 'departure_test' %>
+<% if ENV['PERCONA_DB_SOCKET'] && !ENV['PERCONA_DB_SOCKET'].empty? %>
+socket: <%= ENV['PERCONA_DB_SOCKET'] %>
+<% else %>
+host: <%= ENV['PERCONA_DB_HOST'] || 'localhost' %>
+port: <%= ENV['PERCONA_DB_PORT'] || 3306 %>
+<% end %>

data/departure.gemspec

@@ -8,9 +8,8 @@ require 'departure/version'
 Gem::Specification.new do |spec|
   spec.name          = 'departure'
   spec.version       = Departure::VERSION
-  spec.authors       = ['Ilya Zayats', 'Pau Pérez', 'Fran Casas', 'Jorge Morante', 'Enrico Stano', 'Adrian Serafin', 'Kirk Haines', 'Guillermo Iguaran']
-  spec.email         = ['ilya.zayats@redbooth.com', 'pau.perez@redbooth.com', 'nflamel@gmail.com', 'jorge.morante@redbooth.com', 'adrian@softmad.pl', 'wyhaines@gmail.com', 'guilleiguaran@gmail.com']
-
+  spec.authors       = ['Ilya Zayats', 'Pau Pérez', 'Fran Casas', 'Jorge Morante', 'Enrico Stano', 'Adrian Serafin', 'Kirk Haines', 'Guillermo Iguaran', 'Austin Story', 'Douglas Soares de Andrade']
+  spec.email         = ['ilya.zayats@redbooth.com', 'pau.perez@redbooth.com', 'nflamel@gmail.com', 'jorge.morante@redbooth.com', 'adrian@softmad.pl', 'wyhaines@gmail.com', 'guilleiguaran@gmail.com', 'lonnieastory@gmail.com', 'douglas@51street.dev']
   spec.summary       = %q(pt-online-schema-change runner for ActiveRecord migrations)
   spec.description   = %q(Execute your ActiveRecord migrations with Percona's pt-online-schema-change. Formerly known as Percona Migrator.)
   spec.homepage      = 'https://github.com/departurerb/departure'
@@ -21,11 +20,11 @@ Gem::Specification.new do |spec|
 
   spec.required_ruby_version = '>= 3.2.0'
 
-  spec.add_runtime_dependency 'railties', '>= 7.0.1'
-  spec.add_runtime_dependency 'activerecord', '>= 7.0.1'
+  spec.add_runtime_dependency 'railties', '>= 7.2.0'
+  spec.add_runtime_dependency 'activerecord', '>= 7.2.0'
   spec.add_runtime_dependency 'mysql2', '>= 0.4.0', '< 0.6.0'
 
-  spec.add_development_dependency 'appraisal', '~> 2.4.1'
+  spec.add_development_dependency 'appraisal', '~> 2.5.0'
   spec.add_development_dependency 'rake', '>= 10.0'
   spec.add_development_dependency 'rspec', '~> 3.4', '>= 3.4.0'
   spec.add_development_dependency 'rspec-its', '~> 1.2'

data/docker-compose.yml

@@ -16,7 +16,11 @@ services:
       - db
     tty: true
     stdin_open: true
+    volumes:
+      - .:/app
+      - ./tmp/local_gems:/app/vendor/bundle
     environment:
+      BUNDLE_PATH: /app/vendor/bundle
       PERCONA_DB_USER: root
       PERCONA_DB_HOST: db
       PERCONA_DB_PASSWORD:

data/gemfiles/rails_7_2.gemfile

@@ -3,6 +3,7 @@
 source 'https://rubygems.org'
 
 gem 'base64'
+gem 'bigdecimal'
 gem 'codeclimate-test-reporter', '~> 1.0.3', group: :test, require: nil
 gem 'lhm'
 gem 'logger'