Run Migrations

This guide shows you how to run database migrations.

Setup Migrator

require "cql"
require "../migrations/*"

MyDB.init

config = CQL::MigratorConfig.new(
  schema_file_path: "src/schemas/app_schema.cr",
  schema_name: :AppSchema,
  auto_sync: true
)

migrator = MyDB.migrator(config)

Run All Pending Migrations

migrator.up
puts "Migrations complete"

Check Migration Status

puts "Applied: #{migrator.applied_migrations.size}"
puts "Pending: #{migrator.pending_migrations.size}"

Run to Specific Version

# Run up to migration 5
migrator.up_to(5)

Create Migration Script

# src/migrate.cr
require "./database"
require "../migrations/*"

MyDB.init

config = CQL::MigratorConfig.new(
  schema_file_path: "src/schemas/app_schema.cr",
  schema_name: :AppSchema,
  auto_sync: true
)

migrator = MyDB.migrator(config)

case ARGV[0]?
when "up"
  migrator.up
  puts "Migrated up"
when "down"
  migrator.down
  puts "Rolled back one migration"
when "status"
  puts "Applied: #{migrator.applied_migrations.size}"
  puts "Pending: #{migrator.pending_migrations.size}"
when "version"
  puts "Current version: #{migrator.current_version}"
else
  puts "Usage: crystal src/migrate.cr [up|down|status|version]"
end

Run From Command Line

# Run all pending migrations
crystal src/migrate.cr up

# Check status
crystal src/migrate.cr status

# Rollback one migration
crystal src/migrate.cr down

Auto-Run on Startup

Run migrations when your app starts:

# src/app.cr
require "./database"
require "../migrations/*"

def setup_database
  MyDB.init

  config = CQL::MigratorConfig.new(
    schema_file_path: "src/schemas/app_schema.cr",
    schema_name: :AppSchema,
    auto_sync: true
  )

  migrator = MyDB.migrator(config)

  pending = migrator.pending_migrations.size
  if pending > 0
    puts "Running #{pending} pending migration(s)..."
    migrator.up
  end
end

setup_database
# ... rest of your app

Verify Migrations Ran

migrator = MyDB.migrator(config)
migrator.up

# Verify
puts "Applied migrations:"
migrator.applied_migrations.each do |version|
  puts "  - #{version}"
end

Related

• Create a Migration

• Rollback Migrations

• Migration DSL Reference