### Install Data Migrate Gem

Source: https://context7.com/ilyakatz/data-migrate/llms.txt

After adding the gem to your Gemfile, run bundle install to install it.

```bash
bundle install
```

--------------------------------

### Setup or Migrate Database

Source: https://context7.com/ilyakatz/data-migrate/llms.txt

Runs database setup (create + schema load) if the database does not exist, or runs `db:migrate:with_data` if it does. This is the data-aware equivalent of `db:prepare`.

```bash
rake db:prepare:with_data
```

--------------------------------

### Install data_migrate Gem

Source: https://github.com/ilyakatz/data-migrate/blob/main/README.md

Add the data_migrate gem to your project's Gemfile and run bundle install.

```ruby
gem 'data_migrate'
```

--------------------------------

### Example Data Migration File for a Rails Engine

Source: https://context7.com/ilyakatz/data-migrate/llms.txt

An example of a data migration file within a Rails engine. This migration backfills invoice totals by summing line item amounts.

```ruby
# engines/billing/db/data/20240201000000_backfill_invoice_totals.rb
class BackfillInvoiceTotals < ActiveRecord::Migration[7.1]
  def up
    Billing::Invoice.find_each do |invoice|
      invoice.update_column(:total_cents, invoice.line_items.sum(:amount_cents))
    end
  end

  def down
    raise ActiveRecord::IrreversibleMigration
  end
end
```

--------------------------------

### Get Current Migration Version

Source: https://context7.com/ilyakatz/data-migrate/llms.txt

Retrieves the current version numbers for data migrations or both data and schema migrations. This is useful for checking the database's migration state.

```bash
rake data:version
```

```text
# Current data version: 20240101120000
```

```bash
rake db:version:with_data
```

```text
# Current Schema version: 20240110000000
# Current Data version: 20240101120000
```

--------------------------------

### Run Single Schema/Data Migration (Both Types)

Source: https://context7.com/ilyakatz/data-migrate/llms.txt

Applies or reverts a migration for a given version. By default, schema migrations take precedence. Use `BOTH=true` to run both schema and data migrations for the specified version.

```bash
# Run up for version (schema takes precedence by default)
rake db:migrate:up:with_data VERSION=20240101120000
```

```bash
# Run up for BOTH schema and data at the same version
rake db:migrate:up:with_data VERSION=20240101120000 BOTH=true
```

```bash
# Roll back both at the same version
rake db:migrate:down:with_data VERSION=20240101120000 BOTH=true
```

--------------------------------

### Load Schema Files

Source: https://context7.com/ilyakatz/data-migrate/llms.txt

Seeds the database from `data_schema.rb` and optionally `schema.rb` without re-running migrations. This is useful for setting up new environments.

```bash
# Load only the data schema
rake data:schema:load
```

```bash
# Load both schema.rb and data_schema.rb
rake db:schema:load:with_data
```

```bash
# Load structure.sql + data_schema.rb
rake db:structure:load:with_data
```

--------------------------------

### Step Forward in Migrations

Source: https://context7.com/ilyakatz/data-migrate/llms.txt

Applies the next pending migration without running all pending ones. Use `STEP=n` to apply multiple pending migrations.

```bash
rake data:forward
```

```bash
rake data:forward STEP=2
```

```bash
rake db:forward:with_data STEP=1
```

--------------------------------

### Output for Schema + Data Migrations

Source: https://context7.com/ilyakatz/data-migrate/llms.txt

This output distinguishes between schema and data migrations, showing the version, name, and execution time for each.

```text
== Schema ======================================================================
== 20240110000000 AddSlugToPosts: migrating ====================================
-- add_column(:posts, :slug, :string)
== 20240110000000 AddSlugToPosts: migrated (0.0215s) ===========================

== Data ========================================================================
== 20240115000000 BackfillPostSlugs: migrating =================================
== 20240115000000 BackfillPostSlugs: migrated (1.2041s) ========================
```

--------------------------------

### Expected Output for Data Migration

Source: https://context7.com/ilyakatz/data-migrate/llms.txt

This shows the typical output when running data migrations, indicating the migration version, name, and execution time.

```text
== 20240101120000 TitleizePostTitles: migrating ================================
-- Post.find_each ...
== 20240101120000 TitleizePostTitles: migrated (0.3412s) =======================
```

--------------------------------

### Run Pending Data Migrations

Source: https://context7.com/ilyakatz/data-migrate/llms.txt

Execute all pending data migrations. You can specify a target version or suppress verbose output.

```bash
# Run all pending data migrations
rake data:migrate

# Migrate to a specific version
rake data:migrate VERSION=20240101120000

# Suppress verbose output
rake data:migrate VERBOSE=false
```

--------------------------------

### Run a Single Data Migration

Source: https://context7.com/ilyakatz/data-migrate/llms.txt

Applies or reverts a specific data migration using its version number. Ensure the `VERSION` is correctly formatted.

```bash
# Apply a specific data migration
rake data:migrate:up VERSION=20240101120000
```

```bash
# Revert a specific data migration
rake data:migrate:down VERSION=20240101120000
```

--------------------------------

### Multi-Path / Rails Engine Support

Source: https://context7.com/ilyakatz/data-migrate/llms.txt

Configure multiple data migration directories to ensure that data migrations from Rails engines are discovered and run together with the host application's migrations.

```APIDOC
## Multi-Path / Rails Engine Support

Configure multiple data migration directories so that engine data migrations are discovered and run together with the host app's migrations.

### Configuration in `config/initializers/data_migrate.rb`

```ruby
# config/initializers/data_migrate.rb
DataMigrate.configure do |config|
  config.data_migrations_path = ['db/data'] + Dir['engines/**/db/data']
end
```

### Engine Migration File Example

```ruby
# engines/billing/db/data/20240201000000_backfill_invoice_totals.rb
class BackfillInvoiceTotals < ActiveRecord::Migration[7.1]
  def up
    Billing::Invoice.find_each do |invoice|
      invoice.update_column(:total_cents, invoice.line_items.sum(:amount_cents))
    end
  end

  def down
    raise ActiveRecord::IrreversibleMigration
  end
end
```
```

--------------------------------

### List Data Rake Tasks

Source: https://github.com/ilyakatz/data-migrate/blob/main/README.md

Lists all available Rake tasks related to data migrations. Use these tasks to manage your data schema versions.

```bash
rake -T data
```

--------------------------------

### Programmatic API for Data Migration Status Checks

Source: https://context7.com/ilyakatz/data-migrate/llms.txt

Use the `DataMigrate::DatabaseTasks` and `DataMigrate::DataMigrator` classes to programmatically check for pending migrations, retrieve migration lists, and run specific migrations.

```ruby
# Check whether any data migrations are pending
if DataMigrate::DataMigrator.needs_migration?
  puts "Pending data migrations detected!"
end
```

```ruby
# Retrieve all pending (data + schema) migrations sorted by version
pending = DataMigrate::DatabaseTasks.pending_migrations
pending.each { |m| puts "#{m[:kind]} #{m[:version]} #{m[:name]}" }
```

```ruby
# Retrieve only pending data migrations
DataMigrate::DatabaseTasks.pending_data_migrations.each do |m|
  puts "data #{m[:version]} #{m[:name]}"
end
```

```ruby
# Retrieve past (applied) migrations, newest first
DataMigrate::DatabaseTasks.past_migrations.first(5).each do |m|
  puts "#{m[:kind]} #{m[:version]}"
end
```

```ruby
# Run a specific migration in a given direction programmatically
DataMigrate::DatabaseTasks.run_migration(
  { version: 20240101120000, kind: :data },
  :up
)
```

```ruby
# Get the current data migration version
puts DataMigrate::DataMigrator.current_version
# => 20240101120000
```

--------------------------------

### `DataMigrate::StatusService` — Migration Status Output

Source: https://context7.com/ilyakatz/data-migrate/llms.txt

Dumps a formatted status table for data migrations to any IO stream, useful for monitoring and debugging.

```APIDOC
## `DataMigrate::StatusService` — Migration Status Output

Dumps a formatted status table for data migrations to any IO stream.

### Printing Status to STDOUT

```ruby
# Print to STDOUT (default)
DataMigrate::StatusService.dump
```

### Capturing Status Output

```ruby
# Capture status output in tests or custom tooling
stream = StringIO.new
DataMigrate::StatusService.dump(ActiveRecord::Base.connection, stream)
puts stream.string
# =>
# database: my_app_test
#
#  Status   Migration ID    Migration Name
# --------------------------------------------------
#    up     20230410000000  Titleize post titles
#   down    20240101120000  Populate computed scores
```
```

--------------------------------

### Configure DataMigrate for Rails Engines

Source: https://github.com/ilyakatz/data-migrate/blob/main/README.md

Add this configuration to your initializer to include data migration paths from Rails engines. It extends the default path with directories found in engine subfolders.

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

--------------------------------

### Configure Data Migrate Gem

Source: https://context7.com/ilyakatz/data-migrate/llms.txt

Customize the data migration tracking table name, storage path, migration template, and database connection using a configuration block in an initializer.

```ruby
# config/initializers/data_migrate.rb
DataMigrate.configure do |config|
  # Name of the tracking table (default: "data_migrations")
  config.data_migrations_table_name = 'data_migrations'

  # Directory (or array of directories) where data migration files live
  # (default: "db/data/")
  config.data_migrations_path = 'db/data/'

  # Custom ERB template for generated migration files
  config.data_template_path = Rails.root.join('lib', 'templates', 'data_migration.rb')

  # Optional: point at a different database entirely
  config.db_configuration = {
    'adapter'  => 'postgresql',
    'host'     => '127.0.0.1',
    'database' => 'my_app_data',
    'username' => 'postgres',
    'password' => nil,
  }

  # ActiveRecord spec name for multi-DB setups (e.g. "primary", "animals")
  config.spec_name = 'primary'
end
```

--------------------------------

### Run Tests for Specific Rails Versions

Source: https://github.com/ilyakatz/data-migrate/blob/main/README.md

Use the 'bundle exec appraisal' command to execute tests against different Rails versions. This is useful for ensuring compatibility across the Rails ecosystem.

```bash
bundle exec appraisal rails-6.1 rspec
```

```bash
bundle exec appraisal rails-7.0 rspec
```

```bash
bundle exec appraisal rails-7.1 rspec
```

```bash
bundle exec appraisal rails-7.2 rspec
```

```bash
bundle exec appraisal rails-8.0 rspec
```

--------------------------------

### Run Schema and Data Migrations Together

Source: https://context7.com/ilyakatz/data-migrate/llms.txt

This task runs both ActiveRecord schema migrations and data migrations in interleaved ascending version order, recommended for production deployments. You can target a specific version or suppress output.

```bash
# Run all pending schema AND data migrations (interleaved by version)
rake db:migrate:with_data

# Target a specific version
rake db:migrate:with_data VERSION=20240115000000

# Suppress output
rake db:migrate:with_data VERBOSE=false
```

--------------------------------

### Dumping Data Migration Status to an IO Stream

Source: https://context7.com/ilyakatz/data-migrate/llms.txt

Utilize `DataMigrate::StatusService` to output a formatted status table of data migrations. This can be directed to STDOUT or captured in a `StringIO` object for testing or custom tooling.

```ruby
# Print to STDOUT (default)
DataMigrate::StatusService.dump
```

```ruby
# Capture status output in tests or custom tooling
stream = StringIO.new
DataMigrate::StatusService.dump(ActiveRecord::Base.connection, stream)
puts stream.string
# =>
# database: my_app_test
#
#  Status   Migration ID    Migration Name
# --------------------------------------------------
#    up     20230410000000  Titleize post titles
#   down    20240101120000  Populate computed scores
```

--------------------------------

### Data Migration File Skeleton

Source: https://context7.com/ilyakatz/data-migrate/llms.txt

This is a skeleton of a generated data migration file, including the class definition with up and down methods. The down method raises an IrreversibleMigration error by default.

```ruby
# db/data/20240101120000_titleize_post_titles.rb
class TitleizePostTitles < ActiveRecord::Migration[7.1]
  def up
    Post.find_each do |post|
      post.update_column(:title, post.title.titleize)
    end
  end

  def down
    raise ActiveRecord::IrreversibleMigration
  end
end
```

--------------------------------

### Configure Data Migrate Gem

Source: https://github.com/ilyakatz/data-migrate/blob/main/README.md

Customizes data_migrate settings such as the migrations table name, path, template path, database connection details, and spec name. This configuration is typically done in an initializer file.

```ruby
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
```

--------------------------------

### Generate a Data Migration in Rails

Source: https://github.com/ilyakatz/data-migrate/blob/main/README.md

Use the rails generate command to create a new data migration file, similar to schema migrations.

```ruby
rails g data_migration add_this_to_that
```

--------------------------------

### `DataMigrate::SchemaDumper` — Dump Data Schema Version

Source: https://context7.com/ilyakatz/data-migrate/llms.txt

Writes the current data version to any IO stream, producing the content for `db/data_schema.rb`.

```APIDOC
## `DataMigrate::SchemaDumper` — Dump Data Schema Version

Writes the current data version to any IO stream, producing the `db/data_schema.rb` content.

### Writing to a File

```ruby
# Write to a file
File.open(Rails.root.join('db', 'data_schema.rb'), 'w:utf-8') do |f|
  DataMigrate::SchemaDumper.dump(ActiveRecord::Base.connection, f)
end
```

### Inspecting in Memory

```ruby
# Inspect in memory
output = StringIO.new
DataMigrate::SchemaDumper.dump(ActiveRecord::Base.connection, output)
puts output.string
# => DataMigrate::Data.define(version: 2024_01_01_120000)
```
```

--------------------------------

### Configure Multiple Data Migration Paths in Rails

Source: https://context7.com/ilyakatz/data-migrate/llms.txt

Extend the data migration paths to include directories from Rails engines. This ensures that engine-specific data migrations are discovered and run with the host application's migrations.

```ruby
# config/initializers/data_migrate.rb
DataMigrate.configure do |config|
  config.data_migrations_path = ['db/data'] + Dir['engines/**/db/data']
end
```

--------------------------------

### `DataMigrate::DatabaseTasks` — Programmatic API

Source: https://context7.com/ilyakatz/data-migrate/llms.txt

Provides the Ruby API used internally by all Rake tasks. This is useful for custom Rake tasks or scripts that need to interact with data migrations programmatically.

```APIDOC
## `DataMigrate::DatabaseTasks` — Programmatic API

Provides the Ruby API used internally by all Rake tasks. Useful for custom Rake tasks or scripts.

### Checking for Pending Migrations

```ruby
# Check whether any data migrations are pending
if DataMigrate::DataMigrator.needs_migration?
  puts "Pending data migrations detected!"
end
```

### Retrieving Pending Migrations

```ruby
# Retrieve all pending (data + schema) migrations sorted by version
pending = DataMigrate::DatabaseTasks.pending_migrations
pending.each { |m| puts "#{m[:kind]} #{m[:version]} #{m[:name]}" }

# Retrieve only pending data migrations
DataMigrate::DatabaseTasks.pending_data_migrations.each do |m|
  puts "data #{m[:version]} #{m[:name]}"
end
```

### Retrieving Past Migrations

```ruby
# Retrieve past (applied) migrations, newest first
DataMigrate::DatabaseTasks.past_migrations.first(5).each do |m|
  puts "#{m[:kind]} #{m[:version]}"
end
```

### Running a Specific Migration Programmatically

```ruby
# Run a specific migration in a given direction programmatically
DataMigrate::DatabaseTasks.run_migration(
  { version: 20240101120000, kind: :data },
  :up
)
```

### Getting the Current Data Migration Version

```ruby
# Get the current data migration version
puts DataMigrate::DataMigrator.current_version
# => 20240101120000
```
```

--------------------------------

### Show Data Migration Status

Source: https://context7.com/ilyakatz/data-migrate/llms.txt

Displays the status of data migrations, indicating which have been applied (`up`) and which are pending (`down`).

```bash
rake data:migrate:status
```

```text
database: my_app_development

 Status   Migration ID    Migration Name
--------------------------------------------------
   up     20230410000000  Titleize post titles
   up     20231201000000  Backfill user slugs
  down    20240101120000  Populate computed scores
```

--------------------------------

### Roll Back Data Migrations

Source: https://context7.com/ilyakatz/data-migrate/llms.txt

Roll back the most recently applied data migration. Use STEP=n to roll back multiple steps.

```bash
# Roll back the last data migration
rake data:rollback

# Roll back the last 3 data migrations
rake data:rollback STEP=3
```

--------------------------------

### Redo a Data Migration

Source: https://context7.com/ilyakatz/data-migrate/llms.txt

Rolls back and then re-applies the last data migration or a specific version. This is useful for re-running a migration that may have had issues.

```bash
# Redo the last data migration
rake data:migrate:redo
```

```bash
# Redo a specific version
rake data:migrate:redo VERSION=20240101120000
```

--------------------------------

### Show Combined Schema + Data Migration Status

Source: https://context7.com/ilyakatz/data-migrate/llms.txt

Provides a unified status table for both schema and data migrations, including a `Type` column to differentiate them. This helps in understanding the overall migration state.

```bash
rake db:migrate:status:with_data
```

```text
database: my_app_development

 Status    Type      Migration ID    Migration Name
------------------------------------------------------------
   up     schema   20230101000000   Create users
   up     schema   20230410000000   Add slug to posts
   up       data   20230410000001   Backfill post slugs
  down     data    20240101120000   Populate computed scores
```

--------------------------------

### Dumping Data Schema Version to an IO Stream

Source: https://context7.com/ilyakatz/data-migrate/llms.txt

Use `DataMigrate::SchemaDumper` to write the current data migration version to an IO stream, generating content for `db/data_schema.rb` or for in-memory inspection.

```ruby
# Write to a file
File.open(Rails.root.join('db', 'data_schema.rb'), 'w:utf-8') do |f|
  DataMigrate::SchemaDumper.dump(ActiveRecord::Base.connection, f)
end
```

```ruby
# Inspect in memory
output = StringIO.new
DataMigrate::SchemaDumper.dump(ActiveRecord::Base.connection, output)
puts output.string
# => DataMigrate::Data.define(version: 2024_01_01_120000)
```

--------------------------------

### Capistrano Configuration for Data Migrations

Source: https://context7.com/ilyakatz/data-migrate/llms.txt

Configure Capistrano to automatically run data migrations. Set `conditionally_migrate` to true to skip if no migration files have changed. Specify the `migration_role` for the server that will run migrations.

```ruby
require 'capistrano/data_migrate'
```

```ruby
# config/deploy.rb
set :conditionally_migrate, true   # skip when no migration files changed
set :migration_role, :db           # which server role runs migrations
```

--------------------------------

### Roll Back Schema or Data Migration

Source: https://context7.com/ilyakatz/data-migrate/llms.txt

Rolls back the most recently applied migration, whether it was a schema or data migration. Use `STEP=n` to roll back multiple steps.

```bash
rake db:rollback:with_data
```

```bash
# Roll back 2 steps across both kinds
rake db:rollback:with_data STEP=2
```

--------------------------------

### Generate a Data Migration File

Source: https://context7.com/ilyakatz/data-migrate/llms.txt

Use the rails generator to create a new timestamped data migration file with up and down methods. You can optionally provide attribute hints for informational purposes.

```bash
# Basic generation
rails g data_migration titleize_post_titles

# With attribute hints (informational — no schema change is made)
rails g data_migration add_slugs_to_users name:string slug:string
```

--------------------------------

### Capistrano Integration for Migrations

Source: https://context7.com/ilyakatz/data-migrate/llms.txt

Replaces the standard `capistrano/rails/migrations` task to run `db:migrate:with_data` on every deploy. Set `conditionally_migrate: true` to skip if neither `db/migrate` nor `db/data` changed.

```ruby
# Replace the standard `capistrano/rails/migrations` task to run `db:migrate:with_data` on every deploy.
# Set `conditionally_migrate: true` to skip if neither `db/migrate` nor `db/data` changed.

```

--------------------------------

### Dump Data Schema File

Source: https://context7.com/ilyakatz/data-migrate/llms.txt

Writes the current data migration version to `db/data_schema.rb`. This task is automatically called after each migration and respects `ActiveRecord::Base.dump_schema_after_migration`.

```bash
rake data:dump
```

```ruby
# db/data_schema.rb (auto-generated)
DataMigrate::Data.define(version: 2024_01_01_120000)
```

--------------------------------

### Add Data Migrate to Gemfile

Source: https://context7.com/ilyakatz/data-migrate/llms.txt

Add this line to your Gemfile to include the data_migrate gem in your Rails application.

```ruby
# Gemfile
gem 'data_migrate'
```

--------------------------------

### CI Guard for Pending Migrations

Source: https://context7.com/ilyakatz/data-migrate/llms.txt

Raises an error if any data or schema migrations are pending, printing their details. This is ideal for CI pre-deploy checks to prevent deployments with unapplied migrations.

```bash
rake data:abort_if_pending_migrations
```

```bash
rake db:abort_if_pending_migrations:with_data
```

```text
You have 1 pending migration:
     20240101120000 PopulateComputedScores
Run `rake data:migrate` to update your database then try again.
```

--------------------------------

### Capistrano Integration

Source: https://context7.com/ilyakatz/data-migrate/llms.txt

Configure Capistrano to automatically run data migrations during deployment. The `conditionally_migrate` option skips migrations if no files have changed, and `migration_role` specifies the server role responsible for running migrations.

```APIDOC
## Capistrano Integration

During `cap production deploy`, Capistrano will automatically call `rake db:migrate:with_data` on the designated migration server.

### Configuration in `config/deploy.rb`

```ruby
# config/deploy.rb
set :conditionally_migrate, true   # skip when no migration files changed
set :migration_role, :db           # which server role runs migrations
```
```

--------------------------------

### Add data_migrate Gem for Rails 6.0

Source: https://github.com/ilyakatz/data-migrate/blob/main/README.md

For Rails 6.0, specify version 9.1.x of the data_migrate gem in your Gemfile.

```ruby
gem 'data_migrate', '~> 9.1.0'
```

--------------------------------

### Integrate Capistrano with Data Migrate

Source: https://github.com/ilyakatz/data-migrate/blob/main/README.md

Adds data_migrate Rake tasks to Capistrano deployments. This ensures that data migrations are run automatically during the deployment process.

```ruby
require 'capistrano/data_migrate'
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.