Skip to main content
Available in arize-phoenix 14.0.0+ Phoenix now routes read-only queries to an optional PostgreSQL read replica when PHOENIX_SQL_DATABASE_READ_REPLICA_URL is set. This reduces CPU, I/O, and connection pool pressure on the primary database under high span ingestion load.

​
Configuration

Set both environment variables before starting the server: 
export PHOENIX_SQL_DATABASE_URL="postgresql://user:pass@primary-host:5432/phoenix"
export PHOENIX_SQL_DATABASE_READ_REPLICA_URL="postgresql://user:pass@replica-host:5432/phoenix"

phoenix serve
When PHOENIX_SQL_DATABASE_READ_REPLICA_URL is not set, Phoenix falls back to the primary for all queries — no configuration change is required for existing deployments.

​
What Routes to the Replica

The following are routed to the read replica when configured:
  • Dataloaders — span and trace attribute lookups
  • GraphQL query resolvers — all read-only queries
  • REST read endpoints — spans, traces, and sessions
  • Generative model store daemon — periodic model list refresh
Writes (span ingestion, mutations, migrations) always go to the primary.

​
Notes

  • PHOENIX_SQL_DATABASE_READ_REPLICA_URL is only supported for PostgreSQL. Setting it with a SQLite database logs a warning and is ignored.
  • The replica connection uses the same asyncpg driver as the primary.
  • Replication lag is not managed by Phoenix — reads may reflect slightly stale data depending on your PostgreSQL replication setup.