{"id":29094200,"url":"https://github.com/wetransfer/departure","last_synced_at":"2025-06-28T09:10:47.070Z","repository":{"id":40545576,"uuid":"181469777","full_name":"WeTransfer/departure","owner":"WeTransfer","description":"WeTransfer's fork of departurerb/departure, to accelerate Rails 5.2 support. See the link for the original repo:","archived":false,"fork":false,"pushed_at":"2022-05-03T12:24:55.000Z","size":478,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":13,"default_branch":"master","last_synced_at":"2023-04-10T15:01:36.694Z","etag":null,"topics":["wt-branch-protection-default"],"latest_commit_sha":null,"homepage":"https://github.com/departurerb/departure","language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/WeTransfer.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2019-04-15T11:06:21.000Z","updated_at":"2023-04-10T15:01:36.694Z","dependencies_parsed_at":"2022-08-09T22:50:25.379Z","dependency_job_id":null,"html_url":"https://github.com/WeTransfer/departure","commit_stats":null,"previous_names":[],"tags_count":null,"template":null,"template_full_name":null,"purl":"pkg:github/WeTransfer/departure","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/WeTransfer%2Fdeparture","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/WeTransfer%2Fdeparture/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/WeTransfer%2Fdeparture/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/WeTransfer%2Fdeparture/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/WeTransfer","download_url":"https://codeload.github.com/WeTransfer/departure/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/WeTransfer%2Fdeparture/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":262403828,"owners_count":23305692,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["wt-branch-protection-default"],"created_at":"2025-06-28T09:10:46.073Z","updated_at":"2025-06-28T09:10:47.062Z","avatar_url":"https://github.com/WeTransfer.png","language":"Ruby","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Departure [![Build Status](https://travis-ci.org/departurerb/departure.svg?branch=master)](https://travis-ci.org/departurerb/departure) [![Code Climate](https://codeclimate.com/github/departurerb/departure/badges/gpa.svg)](https://codeclimate.com/github/departurerb/departure)\n\nDeparture is an **ActiveRecord connection adapter** that allows running\n**MySQL online and non-blocking DDL** through `ActiveRecord::Migration` without needing\n    to use a different DSL other than Rails' migrations DSL.\n\nIt uses `pt-online-schema-change` command-line tool of\n[Percona\nToolkit](https://www.percona.com/doc/percona-toolkit/2.0/pt-online-schema-change.html)\nwhich runs MySQL alter table statements without downtime.\n\n## Rename from \"Percona Migrator\"\n\nThis project was formerly known as \"Percona Migrator\", but this incurs in an\ninfringement of Percona's trade mark policy and thus has to be renamed. Said\nname is likely to cause confusion as to the source of the wrapper.\n\nThe next major versions will use \"Departure\" as gem name.\n\n## Installation\n\nDeparture relies on `pt-online-schema-change` from [Percona\nToolkit](https://www.percona.com/doc/percona-toolkit/2.0/pt-online-schema-change.html)\n\n### Mac\n\n`brew install percona-toolkit`\n\nIf when running a migration you see an error like:\n\n```\nPerconaMigrator::Error: Cannot connect to MySQL: Cannot connect to MySQL because\nthe Perl DBI module is not installed or not found.\n```\n\nYou also need to install the DBI and DBD::MySQL modules from `cpan`.\n\n```\n$ sudo cpan\ncpan\u003e install DBI\ncpan\u003e install DBD::mysql\n```\n\n### Linux\n\n#### Ubuntu/Debian based\n\n`apt-get install percona-toolkit`\n\n#### Arch Linux\n\n`pacman -S percona-toolkit perl-dbd-mysql`\n\n#### Other distros\n\nFor other Linux distributions check out the [Percona Toolkit download\npage](https://www.percona.com/downloads/percona-toolkit/) to find the package\nthat fits your distribution.\n\nYou can also get it from [Percona's apt repository](https://www.percona.com/doc/percona-xtradb-cluster/5.5/installation/apt_repo.html)\n\nOnce installed, add this line to your application's Gemfile:\n\n```ruby\ngem 'departure'\n```\n\nAnd then execute:\n\n    $ bundle\n\nOr install it yourself as:\n\n    $ gem install departure\n\n## Usage\n\nOnce you added it to your app's Gemfile, you can create and run Rails migrations\nas usual.\n\nAll the `ALTER TABLE` statements will be executed with\n`pt-online-schema-change`, which will provide additional output to the\nmigration.\n\n### pt-online-schema-change arguments\n\n#### with environment variable\n\nYou can specify any `pt-online-schema-change` arguments when running the\nmigration. All what you pass in the PERCONA_ARGS env var, will be bypassed to the\nbinary, overwriting any default values. Note the format is the same as in\n`pt-online-schema-change`. Check the full list in [Percona Toolkit\ndocumentation](https://www.percona.com/doc/percona-toolkit/2.2/pt-online-schema-change.html#options)\n\n```ruby\n$ PERCONA_ARGS='--chunk-time=1' bundle exec rake db:migrate:up VERSION=xxx\n```\n\nor even mulitple arguments\n\n```ruby\n$ PERCONA_ARGS='--chunk-time=1 --critical-load=55' bundle exec rake db:migrate:up VERSION=xxx\n```\n\nUse caution when using PERCONA_ARGS with `db:migrate`, as your args will be applied\nto every call that Departure makes to pt-osc.\n\n#### with global configuration\n\nYou can specify any `pt-online-schema-change` arguments in global gem configuration\nusing `global_percona_args` option.\n\n```ruby\nDeparture.configure do |config|\n  config.global_percona_args = '--chunk-time=1 --critical-load=55'\nend\n```\n\nUnlike using `PERCONA_ARGS`, options provided with global configuration will be applied\nevery time sql command is executed via `pt-online-schema-change`.\n\nArguments provided in global configuration can be overwritten with `PERCONA_ARGS` env variable.\n\nWe recommend using this option with caution and only when you understand the consequences.\n\n### LHM support\n\nIf you moved to Soundcloud's [Lhm](https://github.com/soundcloud/lhm) already,\nwe got you covered. Departure overrides Lhm's DSL so that all the alter\nstatements also go through `pt-online-schema-change` as well.\n\nYou can keep your Lhm migrations and start using Rails migration's DSL back\nagain in your next migration.\n\n## Configuration\n\nYou can override any of the default values from an initializer:\n\n```ruby\nDeparture.configure do |config|\n  config.tmp_path = '/tmp/'\nend\n```\n\nIt's strongly recommended to name it after this gems name, such as\n`config/initializers/departure.rb`\n\n## How it works\n\nWhen booting your Rails app, Departure extends the\n`ActiveRecord::Migration#migrate` method to reset the connection and reestablish\nit using the `DepartureAdapter` instead of the one you defined in your\n`config/database.yml`.\n\nThen, when any migration DSL methods such as `add_column` or `create_table` are\nexecuted, they all go to the\n[DepartureAdapter](https://github.com/departurerb/departure/blob/master/lib/active_record/connection_adapters/departure_adapter.rb).\nThere, the methods that require `ALTER TABLE` SQL statements, like `add_column`,\nare overriden to get executed with\n[Departure::Runner](https://github.com/departurerb/departure/blob/master/lib/departure/runner.rb),\nwhich deals with the `pt-online-schema-change` binary. All the others, like\n`create_table`, are delegated to the ActiveRecord's built in Mysql2Adapter and\nso they follow the regular path.\n\n[Departure::Runner](https://github.com/departurerb/departure/blob/master/lib/departure/runner.rb)\nspawns a new process that runs the `pt-online-schema-change` binary present in\nthe system, with the appropriate arguments for the generated SQL.\n\nWhen any errors occur, an `ActiveRecord::StatementInvalid` exception is\nraised and the migration is aborted, as all other ActiveRecord connection\nadapters.\n\n## Trouleshooting\n\n### Error creating new table: DBD::mysql::db do failed: Can't write; duplicate key in table (TABLE_NAME)\nThere is a [known bug](https://bugs.launchpad.net/percona-toolkit/+bug/1498128) in percona-toolkit version 2.2.15\nthat prevents schema changes when a table has constraints. You should upgrade to a version later than 2.2.17 to fix the issue.\n\n## Development\n\nAfter checking out the repo, run `bin/setup` to install dependencies. Then, run\n`rake spec` to run the tests. You can also run `bin/console` for an interactive\nprompt that will allow you to experiment.\n\nTo install this gem onto your local machine, run `bundle exec rake install`. To\nrelease a new version, update the version number in `version.rb`, and then run\n`bundle exec rake release`, which will create a git tag for the version, push\ngit commits and tags, and push the `.gem` file to\n[rubygems.org](https://rubygems.org).\n\n## Contributing\n\nBug reports and pull requests are welcome on GitHub at\nhttps://github.com/departurerb/departure. They need to be opened against\n`master` or `v3.2` only if the changes fix a bug in Rails 3.2 apps.\n\nPlease note that this project is released with a Contributor Code of Conduct. By\nparticipating in this project you agree to abide by its terms.\n\nCheck the code of conduct [here](CODE_OF_CONDUCT.md)\n\n## Changelog\n\nYou can consult the changelog [here](CHANGELOG.md)\n\n## License\n\nThe gem is available as open source under the terms of the [MIT\nLicense](http://opensource.org/licenses/MIT).\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwetransfer%2Fdeparture","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fwetransfer%2Fdeparture","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwetransfer%2Fdeparture/lists"}