Data Migrate

To use data_migrate in your Rails project, add the gem to your Gemfile and run bundle install.

Rails Version Compatibility:

• Supports Rails 6.1 through 8.0.
• For Rails 6.0, use gem version 9.1.x:

gem 'data_migrate', '~> 9.1.0'

Note: When you run any provided rake tasks, a data_migrations table will be created in your database to track migration status, mirroring standard schema migrations.

To use data_migrate with Capistrano deployments, replace capistrano/rails/migrations with the data_migrate task in your Capfile. This ensures rake db:migrate:with_data is executed during every deploy.

require 'capistrano/data_migrate'

If your data migrations are located within Rails engines, update the data_migrations_path in your DataMigrate configuration to include the engine paths. For example, if your engines are in an engines folder:

DataMigrate.configure do |config|
  config.data_migrations_path = ['db/data'] + Dir['engines/**/db/data']
end

You can customize the behavior of data_migrate in an initializer (e.g., config/initializers/data_migrate.rb).

Important Notes:

• data_migrate respects ActiveRecord::Base.dump_schema_after_migration. If this is false, the data_schema.rb file will not be generated.
• To support Rails Engines, you can pass an array of paths to config.data_migrations_path to include engine-specific data directories.

DataMigrate.configure do |config|
  config.data_migrations_table_name = 'my_migrations_database_name'
  config.data_migrations_path = 'db/awesomepath/'
  config.data_template_path = Rails.root.join("lib", "awesomepath", "custom_data_migration.rb")
  config.db_configuration = {
    'host' => '127.0.0.1',
    'database' => 'awesome_database',
    'adapter' => 'mysql2',
    'username' => 'root',
    'password' => nil,
  }
  config.spec_name = 'primary'
end

The project distinguishes between two types of migrations:

1. Schema Migrations: Standard Rails migrations that modify the database structure. These are tracked in the standard schema_migrations table.
2. Data Migrations: Migrations specifically designed to manipulate data. These are tracked in a separate data schema table and are managed by DataMigrate::DataMigrator.

When running migrations, the project ensures that both schema and data migrations are sorted and executed in the correct order (typically schema migrations first, then data migrations).

You can generate a data migration using the Rails generator, just as you would for a schema migration. Data migrations are stored in db/data by default.

rails g data_migration add_this_to_that

You can execute schema migrations directly using DataMigrate::SchemaMigration.run. This method wraps ActiveRecord::MigrationContext to allow running migrations in a specific direction (e.g., :up or :down) for a given set of paths and a specific version.

Arguments:

• direction: The direction to run the migration (:up or :down).
• migration_paths: The paths to the migration files.
• version: The specific version to run to (or from).

Use the following methods to inspect the state of your data migrations:

• needs_migration?: Returns true if there are pending data migrations.
• migrations_status: Returns the status of all migrations (e.g., whether they are up or down).
• current_version: Returns the version of the last migrated data migration.