Is it possible to run database migrations without starting the server?

Siva M.

·Mar 11, 2026 12:23 AM·

Hey folks, Quick question. Is it possible to just run DB migrations and not start the Phoenix server?

15 comments

· Sorted by Oldest

RunLLM
APP
·
·
Yes, you can run Phoenix database migrations independently of starting the server by using the Alembic CLI. Navigate to the `src/phoenix/db` directory in the Phoenix project root and run Alembic commands such as `alembic upgrade head` to apply migrations or `alembic downgrade -1` to revert them. This approach is documented for resolving migration issues and is supported by the Phoenix codebase and CI practices, but you must have the Phoenix source code available locally to access the migration scripts—this is not possible with just the installed package or Docker image alone unless you extract the migration files yourself. For more details on migration reliability, manual intervention, and using Alembic for migration management, see the official documentation and related GitHub discussions. Would you like a step-by-step guide for running these commands or handling migration errors? Sources: - <https://arize.com/docs/phoenix/self-hosting/upgrade/migrations|Phoenix Migrations Documentation> - <https://github.com/Arize-ai/phoenix/pull/2820|GitHub PR: Alembic CLI Support>
💡 Hint: Mention RunLLM in the thread for followups.
Siva M.
·
·
RunLLM What about with the production Docker image distribution?
Roger Y.
·
·
I can’t think of a way to do this. are you not able to shutdown the server manually?
Roger Y.
·
·
we only add new database migrations for each major version bump
Siva M.
·
·
Roger, What is happening is that we are running Phoenix in K8s and we have large PostgreSQL database. While doing a 12.X -> 13.X Phoenix rolling upgrade the new Pods were stuck in a CrashLoopBackoff because liveliness probe fails. This was due migrations taking a long time. We would prefer not to run manual commands in PostgreSQL production database as outlined in the v13 migration doc. I would ideally like to run just the migrations in K8s initContainers before starting up the main container running the server. It would nice if there was a similar command to phoenix.server.main serve for migrations. With the help of Claude, I was testing out some of the migrations commands with Docker. I was able to get this to work. The async create_engine_and_run_migrations that runs on startup basically just calls create_engine.
docker run --rm --network phoenix_default \ -e PHOENIX_SQL_DATABASE_URL=postgresql://postgres:postgres@db:5432/postgres \ arizephoenix/phoenix \ -c "from phoenix.db.engines import create_engine; import os; create_engine(os.environ['PHOENIX_SQL_DATABASE_URL'], migrate=True); print('Migrations complete.')" Migrations complete.
Roger Y.
·
·
ok got it. thank you for the context
Siva M.
·
·
Roger this what I was kinda thinking about. https://github.com/Arize-ai/phoenix/pull/12072
1
Roger Y.
·
·
I just filed the same PR right before yours. I’ll add you as coauthor to my PR
😆1
Siva M.
·
·
Thank you Roger!
Roger Y.
·
·
np!
Siva M.
·
·
Got a curiosity question about this statement in your PR.
Phoenix's migrations are designed to be safe under concurrent execution — if two pods race, one will fail with a transient error, retry, find the database already at head, and exit cleanly.
Is this because Phoenix takes a Postgres application level lock?
Roger Y.
·
·
it’s because they’re DDL first (meaning the tables are locked)
👍1
Siva M.
·
·
Any updates on when this PR might be merged?
Roger Y.
·
·
it’s been released in v13.15.0. i appreciate your patience and thanks for checking in
Siva M.
·
·
Thank you!
👍1

RunLLM
APP
·
·
Yes, you can run Phoenix database migrations independently of starting the server by using the Alembic CLI. Navigate to the `src/phoenix/db` directory in the Phoenix project root and run Alembic commands such as `alembic upgrade head` to apply migrations or `alembic downgrade -1` to revert them. This approach is documented for resolving migration issues and is supported by the Phoenix codebase and CI practices, but you must have the Phoenix source code available locally to access the migration scripts—this is not possible with just the installed package or Docker image alone unless you extract the migration files yourself. For more details on migration reliability, manual intervention, and using Alembic for migration management, see the official documentation and related GitHub discussions. Would you like a step-by-step guide for running these commands or handling migration errors? Sources: - <https://arize.com/docs/phoenix/self-hosting/upgrade/migrations|Phoenix Migrations Documentation> - <https://github.com/Arize-ai/phoenix/pull/2820|GitHub PR: Alembic CLI Support>
💡 Hint: Mention RunLLM in the thread for followups.
Siva M.
·
·
RunLLM What about with the production Docker image distribution?
Roger Y.
·
·
I can’t think of a way to do this. are you not able to shutdown the server manually?
Roger Y.
·
·
we only add new database migrations for each major version bump
Siva M.
·
·
Roger, What is happening is that we are running Phoenix in K8s and we have large PostgreSQL database. While doing a 12.X -> 13.X Phoenix rolling upgrade the new Pods were stuck in a CrashLoopBackoff because liveliness probe fails. This was due migrations taking a long time. We would prefer not to run manual commands in PostgreSQL production database as outlined in the v13 migration doc. I would ideally like to run just the migrations in K8s initContainers before starting up the main container running the server. It would nice if there was a similar command to phoenix.server.main serve for migrations. With the help of Claude, I was testing out some of the migrations commands with Docker. I was able to get this to work. The async create_engine_and_run_migrations that runs on startup basically just calls create_engine.
docker run --rm --network phoenix_default \ -e PHOENIX_SQL_DATABASE_URL=postgresql://postgres:postgres@db:5432/postgres \ arizephoenix/phoenix \ -c "from phoenix.db.engines import create_engine; import os; create_engine(os.environ['PHOENIX_SQL_DATABASE_URL'], migrate=True); print('Migrations complete.')" Migrations complete.
Roger Y.
·
·
ok got it. thank you for the context
Siva M.
·
·
Roger this what I was kinda thinking about. https://github.com/Arize-ai/phoenix/pull/12072
1
Roger Y.
·
·
I just filed the same PR right before yours. I’ll add you as coauthor to my PR
😆1
Siva M.
·
·
Thank you Roger!
Roger Y.
·
·
np!
Siva M.
·
·
Got a curiosity question about this statement in your PR.
Phoenix's migrations are designed to be safe under concurrent execution — if two pods race, one will fail with a transient error, retry, find the database already at head, and exit cleanly.
Is this because Phoenix takes a Postgres application level lock?
Roger Y.
·
·
it’s because they’re DDL first (meaning the tables are locked)
👍1
Siva M.
·
·
Any updates on when this PR might be merged?
Roger Y.
·
·
it’s been released in v13.15.0. i appreciate your patience and thanks for checking in
Siva M.
·
·
Thank you!
👍1