Fix Odoo Could Not Connect to PostgreSQL

Q: My Docker PostgreSQL container starts fine but Odoo still can't connect — why?

PostgreSQL takes a few seconds to be ready after the container starts. Add a depends_on with a healthcheck in docker-compose.yml, or use a startup retry loop.

Reading the Error Message

Odoo's PostgreSQL connection errors are specific. The most common ones and what they mean:

could not connect to server: Connection refused — PostgreSQL is not running, or not listening on the expected host/port.
FATAL: role "odoo" does not exist — the PostgreSQL user Odoo is configured to use has not been created.
FATAL: pg_hba.conf rejects connection — PostgreSQL is running but its access rules block the connection.
could not connect to server: No such file or directory — Odoo is trying to connect via Unix socket but the socket file is not where it expects.

Step 1 — Confirm PostgreSQL Is Running

sudo systemctl status postgresql
# or Docker:
docker ps | grep postgres
docker logs postgres_container_name | tail -20

If it is not running, start it:

sudo systemctl start postgresql

Step 2 — Check odoo.conf Connection Settings

# /etc/odoo/odoo.conf
[options]
db_host = False        # False = Unix socket (same machine), or IP/hostname
db_port = False        # False = default 5432
db_user = odoo
db_password = yourpassword
db_name = False        # False = use the database selected at login

Common mistakes:

Setting db_host = localhost when PostgreSQL only has a Unix socket configured (or vice versa).
Using db_host = False (socket) in a Docker container where PostgreSQL is in a separate container — you must use TCP.

Step 3 — Socket vs TCP Connection

When db_host = False, Odoo connects via Unix socket at /var/run/postgresql/.s.PGSQL.5432. This works perfectly when Odoo and PostgreSQL are on the same machine. In Docker, each container has its own filesystem — sockets do not cross container boundaries. Use TCP:

# In docker-compose.yml, the PostgreSQL service name becomes the hostname:
db_host = db        # matches the service name in docker-compose.yml
db_port = 5432

Step 4 — Create the PostgreSQL User

sudo -u postgres psql -c "CREATE USER odoo WITH PASSWORD 'yourpassword' CREATEDB;"
# Verify:
sudo -u postgres psql -c "\du"

The CREATEDB privilege is required so Odoo can create new databases from the database manager.

Step 5 — Fix pg_hba.conf

This file controls who can connect to PostgreSQL from where. Find it:

sudo -u postgres psql -c "SHOW hba_file;"

A typical working entry for local TCP connections:

# TYPE  DATABASE  USER   ADDRESS        METHOD
host    all       odoo   127.0.0.1/32   scram-sha-256
# For Docker (allow from the Docker bridge network):
host    all       odoo   172.17.0.0/16  scram-sha-256

After editing pg_hba.conf, reload PostgreSQL (no restart needed):

sudo systemctl reload postgresql
# or:
sudo -u postgres psql -c "SELECT pg_reload_conf();"

Step 6 — Fix listen_addresses

PostgreSQL only listens on localhost by default. For Docker or remote connections:

# /etc/postgresql/16/main/postgresql.conf
listen_addresses = '*'    # all interfaces, or specific IP

This requires a full PostgreSQL restart (not just reload).

Step 7 — Docker Network Troubleshooting

# Find the PostgreSQL container IP:
docker inspect postgres_container | grep IPAddress

# Test TCP connectivity from the Odoo container:
docker exec odoo_container bash -c "apt-get install -y netcat-openbsd && nc -zv db 5432"

# Or use the Docker network name:
docker network ls
docker network inspect deploymonkey_dm-network

How DeployMonkey Handles This

Every DeployMonkey instance is provisioned with PostgreSQL pre-configured: correct user, password, pg_hba.conf entries, and Docker network routing. You never have to debug socket vs TCP or pg_hba rejections — the stack comes up connected. See Optimize PostgreSQL for Odoo for tuning after you are connected.

Start free at deploymonkey.app.

Frequently Asked Questions

Should PostgreSQL listen on a public IP?

No. PostgreSQL should only be reachable from the Odoo application server, ideally via a private network or Unix socket. Never expose PostgreSQL to the public internet.

What does "peer authentication failed" mean?

Peer authentication checks that the OS username matches the PostgreSQL username. If you are running Odoo as user odoo but connecting as PostgreSQL user odoo via socket, the OS user also needs to be odoo. Switch to scram-sha-256 method in pg_hba.conf to use a password instead.

Can I use PostgreSQL 16 with Odoo 17?

Yes — Odoo 17 and 19 are both compatible with PostgreSQL 14–16. PostgreSQL 16 is recommended for performance improvements.

My Docker PostgreSQL container starts fine but Odoo still can't connect — why?

PostgreSQL takes a few seconds to be ready to accept connections after the container starts. Add a depends_on with a healthcheck in docker-compose.yml, or use a startup retry loop in the Odoo entrypoint.