Odoo’s --db_replica_host connects read-only Odoo requests to a PostgreSQL replica while writes continue on the primary database. In a high-availability design, it can reduce load on the writer and let database reads continue through separate replica nodes.
It does not create a replica, manage failover, or replace backups. PostgreSQL tooling or your cloud database service must provide those parts. Odoo only tells the application where to find the read-only database endpoint.
What does --db_replica_host do?
Without this option, Odoo uses the normal --db_host for both reads and writes. When a replica host is configured, Odoo opens a separate read-only connection pool for controller routes explicitly marked as read-only.
Normal traffic
Read or write ───────────────► PostgreSQL primary
With --db_replica_host
Read-only route ─────────────► PostgreSQL replica
Write route ────────────────► PostgreSQL primary
Replica unavailable ───────► fallback to primaryThe replica uses the same Odoo database name. It inherits the database user, password, and SSL mode from the primary settings unless the corresponding db_replica_* option overrides them.
Configuration
The option can be supplied on the command line, in the Odoo configuration file, or through PGHOST_REPLICA.
# Odoo command line
odoo-bin --db_host=postgres-primary.internal \
--db_replica_host=postgres-read.internal \
--db_port=5432[options]
db_host = postgres-primary.internal
db_replica_host = postgres-read.internal
db_port = 5432
db_replica_port = 5432If db_replica_port is omitted, Odoo uses the primary database port. In Docker or Kubernetes, use environment variables such as PGHOST and PGHOST_REPLICA instead of storing credentials in a committed configuration file.
How requests behave
| Situation | Odoo behavior |
|---|---|
| Route is marked read-only | Odoo attempts to use the replica connection. |
| Route writes data | Odoo uses the primary connection. |
| Replica cannot be reached | Odoo falls back to the primary and temporarily avoids repeatedly retrying the failed replica. |
| Read-only route unexpectedly writes | Odoo logs the problem and retries on the primary. |
Only HTTP controller routes marked read-only use this feature. Most backend screens, forms, actions, and scheduled jobs include writes and should remain on the primary.
Replication can be slightly behind the primary. A user may therefore see old data if a page is served from the replica immediately after a write. Avoid replica routing for confirmation pages, checkout validation, inventory confirmation, and other read-after-write flows unless your consistency design handles that delay.
A recommended high-availability topology
┌─────────────────────┐
│ Load balancer │
└──────────┬──────────┘
│
┌────────────┴────────────┐
▼ ▼
Odoo node 1 Odoo node 2
│ │
┌──────────┴─────────────────────────┴──────────┐
│ │
▼ ▼
PostgreSQL primary PostgreSQL replicas
read + writes read-only traffic
│ │
└──────── replication and monitoring ─────────┘
All Odoo nodes also need shared filestore access.
Database and filestore backups run separately.For high availability, point db_host to a highly available writer endpoint, not directly to one PostgreSQL node. Point db_replica_host to a read endpoint that can distribute or fail over between replicas. Managed PostgreSQL services, Patroni, HAProxy, PgBouncer, or an equivalent platform can provide these endpoints.
Odoo 20 supports one db_replica_host value. Multiple replicas can still be used behind one read endpoint, so Odoo does not need a list of replica addresses.
What must be handled outside Odoo
- Replication: configure physical streaming replication or the replication model offered by your database provider.
- Automatic failover: promote another PostgreSQL node and update the writer endpoint when the primary fails.
- Connection limits: calculate the total allowed by PostgreSQL across all Odoo nodes, worker processes, cron workers, administration tools, and replicas.
- Security: allow the Odoo network to reach both endpoints and require TLS where the database crosses hosts.
- Monitoring: track replication lag, connection saturation, primary health, disk space, and replica availability.
- Shared files: PostgreSQL replication does not replicate the Odoo filestore. Store attachments in shared or object-based storage and include them in recovery planning.
- Backups: a replica is not a backup. Use tested point-in-time recovery and periodically verify database and filestore restoration.
Test it before production
Use --dev=replica in a development environment to simulate read-only routing without building a second server. This can expose controllers that were incorrectly marked read-only, but it cannot test replication lag or real failover.
For a production rehearsal, verify these cases:
- Read-only traffic reaches the replica.
- Writes always reach the primary.
- Odoo falls back cleanly when the replica is stopped.
- Read-after-write workflows do not expose unacceptable stale data.
- A primary failover reconnects through the writer endpoint.
- Replicas do not exhaust PostgreSQL connection limits.
- Database and filestore backups can be restored together.
What database approaches are actually new in Odoo 20?
One important correction: --db_replica_host is not completely new to Odoo 20. It is already present in the Odoo 19 code and documentation. Odoo 20 continues and expands this architecture, but older Odoo deployments can already use the option.
The database-management changes that are new or newly important in Odoo 20 are:
| Odoo 20 approach | What it improves |
|---|---|
| PostgreSQL 16 minimum | A newer supported database baseline with current PostgreSQL fixes and capabilities. |
| Replica-aware request routing | Separates eligible reads from writes and exposes whether a request used a read-only or read/write cursor. |
--db-system | A configurable system database for shared bus and maintenance operations. Keeping these operations separate can reduce noise in business databases and simplify architecture. |
| Cursor-mode diagnostics | Odoo 20 can highlight ro, rw, and ro->rw access, helping operators find misclassified routes and unexpected primary traffic. |
pgvector integration | Supports database-backed vector search for Odoo AI features. PostgreSQL 16 satisfies the extension version requirement. |
Bottom line
Use --db_replica_host as one part of a larger high-availability design. PostgreSQL replication provides the copy, the writer and read endpoints provide availability, and Odoo routes only safe read-only requests to the replica. Combined with Odoo 20’s PostgreSQL 16 baseline, configurable system database, and better cursor diagnostics, it provides a stronger database platform without hiding the operational work behind a single option.