This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
This is an Elixir library that provides a Phoenix LiveDashboard page for managing Ecto data migrations. It allows viewing, running, and monitoring data migrations with real-time log streaming through Phoenix PubSub.
The project supports multiple database adapters (PostgreSQL, MySQL, MSSQL, SQLite) and uses environment variables to switch between them during testing:
-
ECTO_ADAPTER environment variable controls which database adapter tests run against
pg- PostgreSQL (Test.PGRepo)myxql- MySQL (Test.MyXQLRepo)tds- SQL Server/MSSQL (Test.TDSRepo)sqliteor unset - SQLite (Test.SQLiteRepo, default)
-
Database connection details for local testing (via docker-compose):
- PostgreSQL: localhost:15435
- MySQL: localhost:13306
- SQL Server: localhost:11433
Run tests for a specific database adapter:
ECTO_ADAPTER=sqlite mix test
ECTO_ADAPTER=pg mix test
ECTO_ADAPTER=myxql mix test
ECTO_ADAPTER=tds mix testRun tests for all adapters sequentially:
mix test.allRun a single test file:
ECTO_ADAPTER=pg mix test test/data_migration/live_dashboard/page_test.exsStart database containers (required before running tests):
docker-compose up -dStop database containers:
docker-compose downFormat code:
mix formatCompile with warnings as errors:
mix compile --force --warnings-as-errorsStart the development dashboard (uses Tidewave at port 4011):
mix tidewaveGet dependencies:
mix deps.get-
DataMigration.LiveDashboard.Page (
lib/data_migration/live_dashboard/page.ex)- Phoenix LiveView page that integrates with LiveDashboard
- Lists all data migrations from configured Ecto repos and folders
- Provides UI to run migrations up/down with confirmation
- Streams logs in real-time via PubSub as migrations execute
- Uses
Ecto.Migratorfor migration discovery and execution - Caches migration list in
:persistent_termfor performance - In dev mode, automatically recompiles migrations on each page load
-
DataMigration (
lib/data_migration.ex)pending/2lists the data migrations that have not run;run/4runs one by versionuse DataMigration, repeatable: truemarks a data migration thatrun/4may run again; anything else, including a plainuse Ecto.Migration, is one-shot
-
DataMigration.Logger (
lib/data_migration/logger.ex)- Custom logger backend that captures Ecto migration logs
- Implements both
:gen_event(legacy) and:logger_handler(OTP 21+) behaviors - Filters logs by MFA (module/function/arity) patterns
- Broadcasts captured logs to Phoenix PubSub topic
- Automatically captures logs from:
Ecto.Adapters.SQL,Ecto.Migration.Runner,Ecto.Migrator
The LiveDashboard page is configured in the Phoenix router with a 3-tuple:
{PubSubServer, %{Repo => [migration_folders]}, options}Example:
{MyApp.PubSub, %{MyApp.Repo => ["data_migrations"]}, [topic: "custom-topic"]}- Uses
Ecto.Migrator.migrations/3to get migration status - Compiles migration files dynamically with
Code.require_file/2 - Extracts metadata: id, name, file path, status (:up or :down)
- Matches migration files by glob pattern:
*.exsin configured folders
- test/support/ contains test repos for each database adapter
- test/support/conn_case.ex provides test helpers
- test/support/endpoint.ex is a minimal Phoenix endpoint for testing
- Tests are adapter-specific and selected at runtime via environment variable
- CI runs the full test suite against all adapters sequentially
- When adding Ecto-related features, ensure compatibility with all four adapters (pg, myxql, tds, sqlite)
- The logger captures logs based on MFA patterns - be mindful of what gets captured
- Migration status is queried on each page load but cached in persistent_term
- The page requires
allow_destructive_actions: truein LiveDashboard config to enable migration execution - ANSI color codes are stripped from logs before displaying in the UI