Install PgBouncer for Odoo step by step

🎯 Objective of this chapter

By the end of this chapter you will have:

• PgBouncer installed correctly

• Working asa proxy between Odoo and PostgreSQL

• Without breaking Odoo

• Ready for optimization and hardening

👉 We are not going to tune it yet.

First: make it work well.

🧱 Recommended architecture

sudo apt update
sudo apt install pgbouncer

sudo dnf install pgbouncer

Verify:

pgbouncer --version

📁 Step 2 – Important files

You will usually find:

• Main config:

  /etc/pgbouncer/pgbouncer.ini

• Users:

  /etc/pgbouncer/userlist.txt

• Service:

  pgbouncer.service

⚙️ Step 3 – Minimum PgBouncer configuration

Edit /etc/pgbouncer/pgbouncer.ini:

[databases]
odoo = host=127.0.0.1 port=5432 dbname=odoo

[pgbouncer]
listen_addr = 0.0.0.0
listen_port = 6432

auth_type = scram-sha-256
auth_file = /etc/pgbouncer/userlist.txt

pool_mode = transaction

max_client_conn = 500
default_pool_size = 20

log_connections = yes
log_disconnections = yes

👉 Important notes

• pool_mode = transaction → the only safe mode for Odoo

• listen_port = 6432 → standard PgBouncer port

• odoo must match the DB name

👤 Step 4 – Create the user file

Edit /etc/pgbouncer/userlist.txt:

Format:

"user" "password"

Example:

"odoo" "SCRAM-SHA-256$4096:..."

👉 Must match exactlywith the PostgreSQL user.

If you are not using SCRAM yet:

ALTER USER odoo WITH PASSWORD 'secure_password';

(PostgreSQL will generate the SCRAM hash)

🔐 Step 5 – Verify access to PostgreSQL

Make sure PgBouncercan connectto PostgreSQL:

• pg_hba.conf must allow:

  • localhost

  • user odoo

  • method scram-sha-256 or md5

Example:

host    all     odoo    127.0.0.1/32    scram-sha-256

Restart PostgreSQL if you change this.

▶️ Step 6 – Start PgBouncer

sudo systemctl enable pgbouncer
sudo systemctl start pgbouncer

Verify:

sudo systemctl status pgbouncer

And that the port is open:

ss -lntp | grep 6432

🔌 Step 7 – Test manual connection

From the server:

psql -h 127.0.0.1 -p 6432 -U odoo odoo

If you enter:

👉 PgBouncer is working correctly.

If it fails:

• check logs

• check auth

• check pg_hba.conf

• 
  

🔁 Step 8 – Connect Odoo to PgBouncer

Edit odoo.conf:

db_host = 127.0.0.1
db_port = 6432
db_user = odoo
db_password = secure_password

⚠️ Odoo MUST NOT connect directly to PostgreSQL

Restart Odoo:

systemctl restart odoo

👀 Step 9 – See that Odoo is now going through PgBouncer

In PgBouncer:

psql -p 6432 -U odoo pgbouncer

Then:

SHOW POOLS;
SHOW CLIENTS;

If you see activity:

👉 Odoo is now using PgBouncer.

❌ Common errors at this stage

• Connecting Odoo to PostgreSQL "just for testing"

• Incorrect pool mode

• Different password between PgBouncer and PostgreSQL

• pg_hba.conf blocking connections

• Not restarting services after changes

📌 Conclusion

Now you have:

• PgBouncer installed

• Decoupled connections

• Stable base for optimization

👉 You still haven't achieved maximum performance,

butyou have already avoided collapse.

👉 Next chapter

Basic PgBouncer configuration optimized for Odoo

There we start to:

• calculate pools

• avoid starvation

• prepare real production

Next chapter ->