What the agent does
The agent reads the project's own migration habits before it judges a new one. In a Phoenix app like hexpm/hexpm, priv/repo/migrations holds 213 files from 20140128201839_add_users_table.exs to 20261017120000_add_public_to_organization_users.exs, and priv/repo/structure.sql is a pg_dump of 3003 lines whose schema_migrations inserts stop at 20260612000000; the test alias in mix.exs runs ecto.create --quiet, ecto.load --skip-if-loaded, ecto.migrate and then test, so every migration newer than the dump runs on top of it and a pull request never has to regenerate the dump. config/config.exs sets migration_timestamps: [type: :utc_datetime_usec], the README requires the pg_trgm and pgcrypto modules or migrations fail, and .github/workflows/main.yml runs mix ecto.setup as a "Verify seeds" step and the suite against a postgres:18 service.
The recent files are the house style the review applies. 20261016130000_add_user_to_organization_invitations.exs uses change with reversible modify :email, :text, null: true, from: {:text, null: false}, a named check constraint, and a partial unique index with where: "accepted_at IS NULL AND revoked_at IS NULL". 20261016140000_add_organization_invitation_blocks.exs is written as up and down because it adds sent_at with null: false, default: fragment("NOW()") and then backfills with execute "UPDATE organization_invitations SET sent_at = updated_at", which change could not reverse. 20260417120000_optimize_audit_logs_indexes.exs and 20260814120300_index_releases_by_stable_semver_sort_key.exs set @disable_ddl_transaction true and @disable_migration_lock true and build every index with concurrently: true or CREATE INDEX CONCURRENTLY, using drop_if_exists and create_if_not_exists so a retry after a failure is safe. lib/hexpm/release_tasks.ex explains why: every app pod runs migrate() at boot, serialised by a session-level advisory lock polled with pg_try_advisory_lock rather than Ecto's transaction lock, because the transaction lock deadlocks with CREATE INDEX CONCURRENTLY.
With those read, the agent starts a Postgres of the version CI uses, runs mix deps.get, mix ecto.create and mix ecto.load, migrates to the pull request's base, and then runs the new migrations with mix ecto.migrate --log-migrations-sql while a second connection watches pg_locks and pg_stat_activity for AccessExclusiveLock on populated tables. It rolls them back with mix ecto.rollback --step for the number of new files and migrates again, which catches an execute without a down and a change that Ecto cannot invert. For each statement it checks what the repository's own files establish: a null: false column on an existing table without a default, an index on a large table (the repository already treats audit_logs and releases that way) without concurrently and the two module attributes, a type change through modify that rewrites the table, a backfill UPDATE without a WHERE in the same file as the DDL, timestamps that are not utc_datetime_usec, a references without on_delete, an unnamed constraint, and anything that would break when two pods run the migration at once.
Then it runs mix test for the contexts the schema change touches and mix format --check-formatted, and writes the review onto the pull request: one comment per statement that locks, rewrites or cannot be reversed, each with the safe sequence from the repository's own precedent (split the index into a concurrent file with the attributes, add the column nullable then backfill in batches then add the constraint, name the constraint), plus a summary of what ran, what locks it saw and how long each migration took in the sandbox. It changes no migration itself.
Start it with one API call
POST https://api.phoenix.so/o/{org}/sessions with this body:
{
"agent": "claude",
"input": "Review the Ecto migrations added in the open pull request. Read mix.exs's aliases, config/config.exs, lib/hexpm/release_tasks.ex and the ten most recent files in priv/repo/migrations for the project's conventions: reversible change blocks with from:, up and down when a file backfills with execute, and @disable_ddl_transaction with @disable_migration_lock and concurrently: true for indexes. Start a Postgres of the version the CI workflow uses with the pg_trgm and pgcrypto modules, run mix ecto.create and mix ecto.load, migrate to the pull request's base, then run the new migrations with --log-migrations-sql while a second connection watches pg_locks, then mix ecto.rollback --step for the number of new files and mix ecto.migrate again. Run mix test for the contexts the schema touches. Comment on the pull request for any statement that locks or rewrites a populated table, builds an index without concurrently and the two module attributes, adds a non-null column without a default, backfills without a down, changes a type in place, or cannot run safely from several app instances at once, each with the safe sequence from the repository's own recent migrations. Do not change the migrations yourself.",
"resources": [
{
"url": "https://github.com/your-org/your-phoenix-app/pull/123"
}
]
}- Get an API key. In the console, open Settings, then API keys, and create a key for your org. Send it in the Authorization header as a Bearer token.
- Send the request. POST the body in request.json to https://api.phoenix.so/o/{org}/sessions, with your repository as the resources URL. The run starts in its own cloud sandbox.
- Read what came back. Follow the run on its live stream or wait for the run.completed webhook, then read the result and its trajectory.
What comes back
What comes back is a review on the pull request: a comment on each migration statement that locks, rewrites, cannot be rolled back or would race another pod, with the safer version written against the repository's own precedent, and a summary comment with the sequence that ran (ecto.load, migrate, rollback, migrate), the locks observed on the second connection, the time each migration took on the fresh database, and the mix test result for the touched contexts. A migration with nothing to say gets a short approval note with the same summary.
The session read names the repository and the pull request URL, and the transcript keeps every command with its output: the SQL Ecto logged for each migration, the pg_locks queries, the rollback and the second migrate, so a reviewer can see what was observed rather than take the comment's word for it.
Before merging, a human still decides. The agent's numbers come from an empty database, so a reviewer reads the comment about a rewrite or a non-concurrent index with the production row counts in mind, checks that a suggested two-step change has both steps in the right order, and confirms that a migration marked with @disable_ddl_transaction has nothing else in the file that needed the transaction.
Run it on every pull request that adds a migration
In the Project, add an automation with this prompt and a github trigger on pull_request.opened and pull_request.synchronize, so every push to a pull request gets a review; the trigger adds the pull request event after the prompt. Only work by an owner, member or collaborator fires it, pull requests from forks never do, and max_runs_per_hour caps the automation between 1 and 30.
To run it only when priv/repo/migrations/ changes, receive GitHub's pull_request webhook on your own server, check the changed files, and send this body with the pull request URL in resources and a request_id that is a UUID v5 of the head SHA, so a redelivery returns the same run. The key's webhook_url then reports run.completed, run.failed or run.cancelled for each.
The use case this job follows, with its automation and trigger: Review every pull request.
Why run it on Rush?
A migration review by eye misses what only a database shows: which lock a modify takes, whether change can invert an execute, whether an index build would block the next pod's boot-time migrate(). The agent runs the file up and down on a fresh Postgres of the CI version in its own sandbox, watches pg_locks from a second connection, and keeps the SQL Ecto logged, so the comment points at an observed statement rather than a guess.
It also applies the project's own precedent rather than a generic checklist: the concurrent-index pattern with its two module attributes, the up and down split for backfills, the from: option on modify, all read from recent files in the same directory. Every pull request gets the same review in parallel, each in its own sandbox, and a push to the branch starts a fresh one.
Frequently asked questions
Does it run against production data?
No. It runs on an empty Postgres built from structure.sql plus the migrations, so its timings say nothing about a large table. Paste the row counts of the tables the migration touches into input and the comments use them when they weigh a rewrite or a non-concurrent index.
Does the pull request need structure.sql regenerated?
Not in this repository. The test alias loads the dump with --skip-if-loaded and then migrates, and the dump's schema_migrations already trails the newest files, so a pull request adds a migration file and nothing else. The agent says so when a pull request regenerates the dump for no reason.
What does it say about change versus up and down?
It follows the files already there: change with from: on modify when Ecto can invert every statement, up and down as soon as the file has an execute. A change block containing execute fails the rollback step in the sandbox, and the comment shows that output.
Why does it care about several app instances?
Because release_tasks.ex runs migrate() on every pod at boot under a polled advisory lock, and the comments in that file explain the deadlock a transactional index build causes against CREATE INDEX CONCURRENTLY. A migration that is safe once but not under that lock gets a comment with the @disable_migration_lock pattern the repository uses.