From 6a1bc3068dcac252d812e5eb412db42528e8bda7 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Gonzalo=20G=C3=B3mez=20Gracia?=
 <gongomgra@users.noreply.github.com>
Date: Mon, 30 Oct 2023 12:02:24 +0100
Subject: [PATCH] [bitnami/pgbouncer] Document how to connect PgBouncer with N
 PostgreSQL (#52229)

[bitnami/pgbouncer] Document how to connect PgBouncer with N PostgreSQL servers

Signed-off-by: Gonzalo Gomez Gracia <gonzalog@vmware.com>
---
 bitnami/pgbouncer/README.md | 75 +++++++++++++++++++++++++++++++++++++
 1 file changed, 75 insertions(+)

diff --git a/bitnami/pgbouncer/README.md b/bitnami/pgbouncer/README.md
index 2de7edb04bf5..8ebc48a37e99 100644
--- a/bitnami/pgbouncer/README.md
+++ b/bitnami/pgbouncer/README.md
@@ -89,6 +89,8 @@ The Bitnami PgBouncer container requires a running PostgreSQL installation to co
 * `PGBOUNCER_SET_DATABASE_USER`: Whether to include the backend PostgreSQL username in the database string. Default **no**.
 * `PGBOUNCER_SET_DATABASE_PASSWORD`: Whether to include the backend PostgreSQL password in the database string. Default **no**.
 * `PGBOUNCER_CONNECT_QUERY`: Query which will be executed after a connection is established. No Defaults.
+* `PGBOUNCER_DSN_${i}`: PgBouncer configuration string for extra PostgreSQL server, where `i` is a number starting at zero (`0`).
+* `PGBOUNCER_USERLIST_FILE`: Custom PgBouncer userlists file with connection credentials for any extra PostgreSQL backend. Required line format (including quotes): `"<postresql-user>" "<password>"`.
 
 ### Port and address binding
 
@@ -275,6 +277,79 @@ docker-compose restart pgbouncer
 
 Refer to the [server configuration](https://www.pgbouncer.org/usage.html) manual for the complete list of configuration options.
 
+### How to connect with multiple PostgreSQL servers
+
+It is possible to connect a single PgBouncer instance with multiple PostgreSQL backends. By using as many `PGBOUNCER_DSN_${i}` environment variables (with `i` starting at zero, `0`) as needed, and the `PGBOUNCER_USERLIST_FILE` variable pointing to a mounted volume with the required credentials for any extra PostgreSQL database in the format `"<postgresql-user>" "<password>"`.
+
+The PgBouncer initialization process requires one PostgreSQL backend to be configured using the different `POSTGRESQL_*` variables listed in the [backend PostgreSQL connection](#backend-postgresql-connection), but the rest of backends connections can be provided using the method explained in this section. An example `docker-compose.yaml` for this scenario can be found below
+
+```yaml
+  pg1:
+    image: docker.io/bitnami/postgresql:14
+    volumes:
+      - 'pg1_data:/bitnami/postgresql'
+    environment:
+      - POSTGRESQL_PASSWORD=password1
+      - POSTGRESQL_DATABASE=db1
+
+  pg2:
+    image: docker.io/bitnami/postgresql:15
+    volumes:
+      - 'pg2_data:/bitnami/postgresql'
+    environment:
+      - POSTGRESQL_PASSWORD=password2
+      - POSTGRESQL_DATABASE=db2
+
+  pg3:
+    image: docker.io/bitnami/postgresql:14
+    volumes:
+      - 'pg3_data:/bitnami/postgresql'
+    environment:
+      - POSTGRESQL_PASSWORD=password3
+      - POSTGRESQL_DATABASE=db3
+
+  pgbouncer:
+    image: docker.io/bitnami/pgbouncer:1
+    ports:
+      - 6432:6432
+    volumes:
+      - './userlists.txt:/bitnami/userlists.txt'
+    environment:
+      - POSTGRESQL_HOST=pg1
+      - POSTGRESQL_PASSWORD=password1
+      - POSTGRESQL_DATABASE=db1
+      - PGBOUNCER_AUTH_TYPE=trust
+      - PGBOUNCER_USERLIST_FILE=/bitnami/userlists.txt
+      - PGBOUNCER_DSN_0=pg1=host=pg1 port=5432 dbname=db1
+      - PGBOUNCER_DSN_1=pg2=host=pg2 port=5432 dbname=db2
+      - PGBOUNCER_DSN_2=pg3=host=pg3 port=5432 dbname=db3
+volumes:
+  pg1_data:
+    driver: local
+  pg2_data:
+    driver: local
+  pg3_data:
+    driver: local
+```
+
+And this is the content of the `userlists.txt` file:
+
+```text
+"postgres" "password1"
+"postgres" "password2"
+"postgres" "password3"
+```
+
+Once initialized, the scenario above provides access to three diferent PostgreSQL backends from a single PgBouncer instance. As an example, you can request the PostgreSQL version of the backend server number two (notice it is the only running PostgreSQL 15.x in this scenario):
+
+```bash
+$ docker exec -it -u root debian-11-pgbouncer-1 psql -p 6432 -U postgres pg2 -c "show server_version;"
+ server_version
+ ----------------
+  15.4
+  (1 row)
+```
+
 ## Contributing
 
 We'd love for you to contribute to this container. You can request new features by creating an [issue](https://github.com/bitnami/containers/issues) or submitting a [pull request](https://github.com/bitnami/containers/pulls) with your contribution.