standalone-migrations

Rails migrations in non-Rails (and non Ruby) projects. COMPATIBILITY

The gem version tracks the newest Rails version it supports.

8.1.1 drops Rails 6.0, 6.1, 7.0 and 7.1, all of which are past their end-of-life. If your Gemfile pins a Rails version, Bundler resolves you to 8.1.0 automatically and nothing changes. If it does not pin one — or you install with gem install — you will get 8.1.1 and Rails 8.1 alongside it, so pin gem 'standalone_migrations', '8.1.0' to stay where you are.

Dropping those Rails versions does not affect your existing migration files. Rails 8.1 still ships ActiveRecord::Migration compatibility shims all the way back to [4.2], so migrations written years ago continue to run unchanged.

CONTRIBUTE

Standalone Migrations relies on the contributions of the open-source community! To submit a fix or an enhancement fork the repository, make your changes, add your name to the Contributors section in README.markdown, and send us a pull request! If you're active and do good work we'll add you as a collaborator!

USAGE

Install Ruby (3.2 or newer), RubyGems and a ruby-database driver (e.g. gem install pg or gem install mysql2) then:

$ gem install standalone_migrations

or use a Gemfile (and then bundle install):

source 'https://rubygems.org'

gem 'standalone_migrations'
gem 'pg' # or mysql2

Add to Rakefile in your projects base directory:

require 'standalone_migrations'
StandaloneMigrations::Tasks.load_tasks

Add database configuration to db/config.yml in your projects base directory e.g.:

development:
  adapter: sqlite3
  database: db/development.sqlite3
  pool: 5
  timeout: 5000

production:
  adapter: mysql2
  encoding: utf8
  reconnect: false
  database: somedatabase_dev
  pool: 5
  username: root
  password:
  socket: /var/run/mysqld/mysqld.sock

test: &test
  adapter: sqlite3
  database: db/test.sqlite3
  pool: 5
  timeout: 5000

To create a new database migration:

rake db:new_migration name=foo_bar_migration
edit db/migrate/20081220234130_foo_bar_migration.rb

If you really want to, you can just execute raw SQL:

def up
  execute "insert into foo values (123,'something');"
end

def down
  execute "delete from foo where field='something';"
end

To apply your newest migration:

rake db:migrate

To migrate to a specific version (for example to rollback)

rake db:migrate VERSION=20081220234130

To migrate a specific database (for example your "testing" database)

rake db:migrate RAILS_ENV=test

To execute a specific up/down of one single migration

rake db:migrate:up VERSION=20081220234130

To revert your last migration

rake db:rollback

To revert your last 3 migrations

rake db:rollback STEP=3

Custom configuration

By default, Standalone Migrations will assume there exists a "db/" directory in your project. But if for some reason you need a specific directory structure to work with, you can use a configuration file named .standalone_migrations in the root of your project containing the following:

db:
    seeds: db/seeds.rb
    migrate: db/migrate
    schema: db/schema.rb
config:
    database: db/config.yml

These are the configurable options available. You can omit any of the keys and Standalone Migrations will assume the default values.

on_loaded callbacks

If you would like to use an external library such as foreigner with standalone migrations, you can add the following to your Rakefile:

require 'foreigner'

StandaloneMigrations.on_loaded do
  Foreigner.load
end

Multiple database support

Structure

Create a custom configuration file for each database and name them .database_name.standalone_migrations. The same conditions apply as described under Custom Configuration, however you are most likely want to specify all options to avoid conflicts and errors.

An example set up would look like this:

app/
|-- db/
|   |-- migrate/
|   |   |-- db1/
|   |   |   |-- 001_migration.rb
|   |   |
|   |   |-- db2/
|   |       |-- 001_migration.rb
|   |
|   |-- config_db1.yml
|   |-- config_db2.yml
|   |-- seeds_db1.rb
|   |-- seeds_db2.rb
|   |-- schema_db1.rb
|   |-- schema_db2.rb
|
|-- .db1.standalone_migrations
|-- .db2.standalone_migrations

Sample config file:

db:
    seeds: db/seeds_db1.rb
    migrate: db/migrate/db1
    schema: db/schema_db1.rb
config:
    database: db/config_db1.yml

Of course you can achieve a different layout by simply editing the paths.

Running

You can run the Rake tasks on a particular database by passing the DATABASE environment variable to it:

$ rake db:version DATABASE=db1

Combined with the environment selector:

$ rake db:migrate DATABASE=db2 RAILS_ENV=production

Changing environment config in runtime

If you are using Heroku or have to create or change your connection configuration based on runtime aspects (maybe environment variables), you can use the StandaloneMigrations::Configurator.environments_config method. Check the usage example:

require 'standalone_migrations'
StandaloneMigrations::Tasks.load_tasks

StandaloneMigrations::Configurator.environments_config do |env|

  env.on "production" do
    if ENV['DB_HOST']
      {
        :adapter  => 'postgresql',
        :host     => ENV['DB_HOST'],
        :username => ENV['DB_USER'],
        :password => ENV['DB_PASSWORD'],
        :database => ENV['DB_NAME'],
        :encoding => 'utf8'
      }
    end
  end

end

The block's value is what gets used, so do not use return here — a return inside the block aborts the rest of your Rakefile instead of handing the hash back. Let the if be the last expression: it evaluates to your new config hash when the branch is taken, and to nil otherwise, which leaves the environment unchanged.

On Heroku you do not need this at all. Rails reads DATABASE_URL itself and merges it into the current environment's configuration after this block runs, so a hash returned here is discarded whenever DATABASE_URL is set. Just set DATABASE_URL and let Rails handle it; use environments_config for settings Rails' URL handling does not already cover.

Put this in your Rakefile below the StandaloneMigrations::Tasks.load_tasks call, as in the example above -- that call is what locates your db/config.yml, so a block placed above it is ignored. If you want to change some configuration, call the #on method on the object received as argument in your block passed to ::environments_config method call. The #on method receives the key to the configuration that you want to change within the block. The block should return your new configuration hash or nil if you want the configuration to stay the same.

Your logic to decide the new configuration need to access some data in your current configuration? Then you should receive the configuration in your block, like this:

require 'standalone_migrations'
StandaloneMigrations::Tasks.load_tasks

StandaloneMigrations::Configurator.environments_config do |env|

  env.on "my_custom_config" do |current_custom_config|
    p current_custom_config
    # => the values on your current "my_custom_config" environment
    nil
  end

end

Exporting Generated SQL

If instead of the database-agnostic schema.rb file you'd like to save the database-specific SQL generated by the migrations, simply add this to your Rakefile.

require 'standalone_migrations'
StandaloneMigrations::Tasks.load_tasks
ActiveRecord.schema_format = :sql

You should see a db/structure.sql file the next time you run a migration.

Contributors

• Todd Huss
• Michael Grosser
• Ricardo Valeriano
• Two Bit Labs
• Windandtides
• Eric Lindvall
• Steve Hodgkiss
• Rich Meyers
• Wes Bailey
• Robert J. Berger
• Federico Builes
• Gazler
• Yuu Yamashita
• Koen Punt
• Parker Moore
• Marcell Jusztin
• Eric Hayes
• Yi Wen
• Jonathan Rochkind
• Michael Mikhailov
• Benjamin Dobell
• Hassan Mahmoud
• Marco Adkins
• Mithun James
• Sarah Ridge
• John Bachir
• Pysis
• Charlton Trezevant