Phoenix runs database migrations automatically at startup, but if a migration fails and the container is distroless (no shell access), you must clone the Phoenix repository locally, navigate to `src/phoenix/db`, set the `PHOENIX_SQL_DATABASE_URL` environment variable, and run Alembic commands (e.g., `alembic upgrade head` or `alembic stamp head`) from your local environment to manually resolve migration issues. This is the only supported way to recover from a dirty migration state when you can't shell into the container directly, as described in the official docs and repo instructions. For production, always pin the Phoenix version and test migrations in a staging environment before upgrading to avoid unexpected breaking changes or downtime.
If you need a shell for debugging or manual migration inside a container, you can build and run the `arizephoenix/phoenix:latest-debug` image, which includes a shell, or modify the Dockerfile to use a debug base image. For persistent issues, reach out to the Arize community Slack for support. Would you like more detail on the manual migration steps or Docker debug image usage?
Sources:
- <https://github.com/Arize-ai/phoenix/blob/main/src/phoenix/db/README.md|Phoenix DB README: Manual Migrations>
- <https://github.com/Arize-ai/phoenix/issues/3246|Phoenix Issue: Migration Errors & Alembic CLI>
