Breaking Changes in Phoenix v13.0, User Action Required?

[nomadlogic]

Hello, it looks like v13.0 of Phoenix was released today. The release page states "Breaking Changes" but doesn't mention if there is any user or admin action required when upgrading from previous versions of Phoenix. Any guidance here would be helpful.

[dosubot[bot]]

Hi @nomadlogic! I'm Dosu and I’m helping the phoenix team.

Phoenix v13.0 introduces several breaking changes, but most users won't need to take manual action for a standard upgrade. The main changes are:

• A new partial index on session id is added to the database. This migration runs automatically and typically requires no user or admin intervention, though it may take time depending on your data size. If you run custom SQL queries against PostgreSQL using chained arrow operators (like attributes -> 'session' ->> 'id'), you may need to update them to use the #>> path operator to benefit from the new index—Phoenix's built-in queries already use the correct form, so this only affects custom SQL usage (details).
• The runExperiment API has changed: the datasetVersionId parameter is removed. You now select versions using the DatasetSelector interface, passing versionId and splits as properties of the dataset argument. Update any client code that uses runExperiment accordingly (migration guide).
• If you deploy Phoenix on Kubernetes with Helm, ensure the PHOENIX_SECRET environment variable is persisted across upgrades. If it changes, all existing API keys become invalid—even though they still appear in the UI. Manage PHOENIX_SECRET with a Kubernetes Secret that isn't recreated by Helm, or use an external secrets manager (more info).

Database migrations run automatically at startup and are designed to be seamless. Manual intervention is rarely needed unless you have a complex or customized setup. If you ever need to downgrade Phoenix, be aware that schema downgrades are not automatic and require manual steps (migration docs).

For a full list of breaking changes and migration details, see the MIGRATION.md in the repo.

To reply, just mention @dosu.

---

^{How did I do? Good | Irrelevant | Incorrect | Verbose | Hallucination | Report 🐛 | Other}

   

[RogerHYang]

Thanks so much for reaching out.

We generally tie database migrations to major version releases, and that’s where we document any required or recommended steps in MIGRATION.md.

For the upgrade from v12.x → v13.0.0, here’s what to keep in mind:

Possible Admin Action

Database

This release adds a partial index on spans.attributes for session ID. The migration runs automatically on startup.

• For most users (including SQLite and typical PostgreSQL deployments), no action is needed.
• For very large PostgreSQL databases (hundreds of GiB or more), the migration runs inside a transaction and may hold a table lock for an extended period. If that applies to your setup, we recommend pre-creating the index concurrently before upgrading. You’ll find the exact SQL statement in MIGRATION.md.

If You Use These Integrations

Azure OpenAI

• We’ve moved to the OpenAI v1 API.
• You’ll need openai>=2.14.0.
• The api_version parameter is no longer required.

AWS Bedrock

• We now use aioboto3 instead of boto3.
• If you’re using Bedrock, install aioboto3.

Summary

For most users, upgrading to v13 is simply a version bump. The index migration runs automatically, and the other changes only apply if you’re using Azure OpenAI or Bedrock.