How to Deploy and Secure PgBouncer on Easypanel

PgBouncer is a lightweight PostgreSQL connection pooler. Instead of allowing every application request to open a new PostgreSQL connection, applications connect to PgBouncer, which reuses a smaller pool of database connections.

This guide shows how to deploy PgBouncer as an Easypanel App service, connect multiple PostgreSQL databases, use SCRAM authentication, access the PgBouncer admin console, and restrict database access to specific IP addresses.

What you need

Before starting, make sure you have:

• An Easypanel project.

• Reachable PostgreSQL servers or Easypanel PostgreSQL services.

• Database users and passwords for each PostgreSQL database.

• The public IP addresses that should be allowed to connect.

• A non-HTTP port available on the server, such as 6432.

For a pinned image version, use:

edoburu/pgbouncer:v1.26.1-p0

Avoid latest in production so deployments are reproducible.

1. Create a PgBouncer App service

1. Open your Easypanel project.

2. Select New Service.

3. Choose App.

4. Name the service, for example pgbouncer.

5. Open Source.

6. Choose Docker Image.

7. Enter:

PgBouncer listens on port 5432 inside this container. You can publish a different external port, such as 6432.

2. Create pgbouncer.ini

In Easypanel, open the PgBouncer service and go to Storage. Add a File mount:

•  Mount path: /etc/pgbouncer/pgbouncer.ini

Paste the following configuration and replace the database hostnames, aliases, and limits for your environment:

[databases]
app_pg1 = host=db_pgdemo port=5432 dbname=pgdemo pool_size=40 max_db_connections=50
app_pg2 = host=db_pgdemo1 port=5432 dbname=pgdemo1 pool_size=40 max_db_connections=50

[pgbouncer]
listen_addr = 0.0.0.0
listen_port = 5432

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

pool_mode = transaction
max_client_conn = 500
default_pool_size = 40
reserve_pool_size = 5
reserve_pool_timeout = 5
max_db_connections = 50

server_tls_sslmode = disable

server_idle_timeout = 600
query_wait_timeout = 120
client_login_timeout = 10

log_connections = 0
log_disconnections = 0
log_pooler_errors = 1
stats_period = 60

Important: use database aliases

Clients should connect to the PgBouncer aliases from the [databases] section:

• app_pg1 routes to database pgdemo

• app_pg2 routes to database pgdemo1

For example, the application connects to /app_pg1, not directly to /pgdemo.

Avoid inline comments

PgBouncer does not support comments after a setting value. This will fail:

pool_mode = transaction ; this breaks PgBouncer

Use a separate comment line instead:

; Transaction pooling is recommended for most web applications.
pool_mode = transaction

3. Create userlist.txt for SCRAM authentication

PgBouncer needs a user list containing the users allowed to authenticate.

In Storage, add another File mount:

•  Mount path: /etc/pgbouncer/userlist.txt

The format is:

"app_user" "SCRAM-SHA-256$4096:eycQQDvwiqzh/eyJstOy8w==$0ogMm/4jsZIq6lvvIFR2tbYhj8r6IzoJ2JtsBMv9gWI=:hneNE4M5pEaeEr8Y8MMealnREjTSuv9lfZwPK/Scubo="

How to generate a valid SCRAM from Postgres database.

open database console in EasyPanel, you will get a valid SCRAM. Remember to change password and username as per your choice ( these username and password will be used in your app, userlist.txt file only hold SCRAM-SHA-256 )

CREATE ROLE app_user WITH LOGIN PASSWORD 'your_secure_password';
GRANT CONNECT ON DATABASE pgdemo1 TO app_user;

SELECT rolname,
       rolpassword LIKE 'SCRAM-SHA-256%' AS uses_scram
FROM pg_authid
WHERE rolname = 'app_user';

SELECT '"' || rolname || '" "' || rolpassword || '"' FROM pg_authid WHERE rolname = 'app_user';

Create a PgBouncer-only admin user

pgbouncer_admin does not need to remain a PostgreSQL user. It exists only for the PgBouncer admin console.

Create it temporarily in PostgreSQL to generate a valid SCRAM verifier:

CREATE ROLE pgbouncer_admin WITH LOGIN PASSWORD '{{PGBOUNCER_ADMIN_PASSWORD}}';

SELECT concat('"', rolname, '" "', rolpassword, '"')
FROM pg_authid
WHERE rolname = 'pgbouncer_admin';

DROP ROLE pgbouncer_admin;

Copy the query output into userlist.txt:

Keep the chosen password private. You will use it to connect to the PgBouncer admin console.

4. Publish the PgBouncer TCP port

PgBouncer is a PostgreSQL TCP service, not an HTTP application. Do not use Easypanel Domains for this.

Open the service Ports section and add:

• Published port: 6432

• Target port: 5432

This means:

• Clients connect to your server on port 6432.

• Easypanel forwards traffic to PgBouncer on port 5432 inside the container.

Your application connection string will look like this:

postgresql://app_user:{{APP_PASSWORD}}@your-server.example.com:6432/app_pg1?sslmode=disable

5. Deploy the service

Select Deploy in Easypanel.

6. Test the PgBouncer admin console

Connect to the special pgbouncer database with the admin user:

psql "postgresql://pgbouncer_admin:{{PGBOUNCER_ADMIN_PASSWORD}}@your-server.example.com:6432/pgbouncer?sslmode=disable"

Useful commands include:

SHOW POOLS;
SHOW STATS;
SHOW CLIENTS;
SHOW SERVERS;
SHOW DATABASES;
SHOW USERS;

SHOW POOLS; is usually the first command to run. It shows client connections, waiting clients, active backend connections, and the pool mode for each database and user.

7. Restrict PgBouncer access to selected IP addresses

Publishing port 6432 makes the PgBouncer listener reachable from the internet unless a firewall or access rule blocks it.

PgBouncer can restrict access using an HBA file.

Update pgbouncer.ini

Change the authentication section to:

auth_type = hba
auth_file = /etc/pgbouncer/userlist.txt
auth_hba_file = /etc/pgbouncer/pg_hba.conf
admin_users = pgbouncer_admin

The auth_file still holds the SCRAM credentials. The HBA file decides which source IP addresses may attempt authentication.

Create pg_hba.conf

In Easypanel Storage, add another File mount:

•  Mount path: /etc/pgbouncer/pg_hba.conf

Example configuration:

# Database app_pg1: permit app_user only from approved IPs.
host    app_pg1    app_user          203.0.113.10/32    scram-sha-256
host    app_pg1    app_user          198.51.100.25/32   scram-sha-256

# Database app_pg2: permit pgdemo1 only from approved IPs.
host    app_pg2    pgdemo1           203.0.113.10/32    scram-sha-256
host    app_pg2    pgdemo1           198.51.100.25/32   scram-sha-256

# Restrict PgBouncer administration to management IPs only.
host    pgbouncer  pgbouncer_admin   203.0.113.10/32    scram-sha-256
host    pgbouncer  pgbouncer_admin   198.51.100.25/32   scram-sha-256

Replace the example addresses with real public IP addresses.

PgBouncer denies access when no HBA rule matches. Do not add a broad rule such as 0.0.0.0/0 unless public access is intentional.

8. Reload PgBouncer after file changes

After changing pgbouncer.ini, userlist.txt, or pg_hba.conf, deploy the service through Easypanel.

If the file is mounted and updated but PgBouncer still appears to use old credentials, open the Easypanel service shell and reload the running process:

kill -HUP 1

grep '^"pgbouncer_admin"' /etc/pgbouncer/userlist.txt
grep -E '^(auth_type|auth_file|admin_users)[[:space:]]*=' /etc/pgbouncer/pgbouncer.ini