Safe Ecto Migrations

As an Elixir developer who cares about system up-time and avoiding “scheduled maintenance” windows, and more importantly avoiding “unscheduled maintenance” windows 😉, this guide dives deep into Ecto database migrations and how they can be used safely in production systems.

This is guide comes in a 4 part series of posts. The guide helps you:

1. Understand Ecto migrations
2. Migrate and rollback the database using Mix releases
3. Avoid pitfalls during migrations

This guide includes a set of recipes for common migration scenarios. You can jump ahead to those, but it is helpful to understand what’s going on at a deeper level and to get your project setup ahead of time for running migrations in a production environment and

Note: This guide uses PostgreSQL and may differ if you’re using a different database. I’ll note where differences may be, but I do not go into depth on different database systems. This was also written using Ecto 3.6.x.

Guide Table of Contents

• Part 1: Anatomy of an Ecto migration
  • Inspect SQL
  • Migration Options
  • Inspecting Locks In a Query
  • Safeguards in the database
  • Add a lock_timeout
  • Statement Timeout
• Part 2: How to migrate Mix Release projects
  • Release Module
  • Start the Release
  • Check migration status
  • Run the migrations
  • OMG ROLL IT BACK
• Part 3: Migration Recipes
  • Adding an index
  • Adding a reference or foreign key
  • Adding a column with a default value
  • Changing the type of a column
  • Removing a column
  • Renaming a column
  • Renaming a table
  • Adding a check constraint
  • Setting NOT NULL on an existing column
  • Adding a JSON column
  • References
  • Reference Material
• Part 4: Backfilling Data
  • Bad
  • Good
  • Batching Deterministic Data
  • Batching Arbitrary Data
  • We’re Done!