https://github.com/shahradelahi/docker-pgbouncer
A Tiny PgBouncer Docker image based on Alpine Linux.
https://github.com/shahradelahi/docker-pgbouncer
docker pgbouncer postgres
Last synced: 9 months ago
JSON representation
A Tiny PgBouncer Docker image based on Alpine Linux.
- Host: GitHub
- URL: https://github.com/shahradelahi/docker-pgbouncer
- Owner: shahradelahi
- License: gpl-3.0
- Archived: true
- Created: 2023-11-30T13:49:19.000Z (over 2 years ago)
- Default Branch: main
- Last Pushed: 2025-04-08T14:34:52.000Z (about 1 year ago)
- Last Synced: 2025-09-12T04:44:41.081Z (10 months ago)
- Topics: docker, pgbouncer, postgres
- Language: Shell
- Homepage: https://hub.docker.com/r/litehex/pgbouncer/
- Size: 46.9 KB
- Stars: 35
- Watchers: 2
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
> [!WARNING]
> Not this project is no longer maintained. Use [edoburu/docker-pgbouncer](https://github.com/edoburu/docker-pgbouncer) instead.
# PgBouncer Docker image
A very minimal PgBouncer Docker image based on Alpine Linux.
### Features
- Tiny image size (about 10 MB)
- Fully configurable via environment variables
- Support for multiple databases
- Support for standalone user administration database
- Support for custom configuration file
### Quickstart
```bash
docker run --rm \
-e DATABASE_URL="postgres://:@:/" \
-e USER_="" \
-p 6432:6432 \
litehex/pgbouncer
```
Or add credentials separately:
```bash
docker run --rm \
-e DB_NAME="" \
-e DB_USER="" \
-e DB_PASSWORD="" \
-e DB_HOST="" \
-p 6432:6432 \
litehex/pgbouncer
```
Then you should be able to connect to PgBouncer:
```bash
psql "postgresql://:@127.0.0.1:6432/"
```
### Environment variables
To configure, please refer to official [PgBouncer documentation](https://www.pgbouncer.org/config.html) and use them as
environment variables with the following format:
```text
# -e =
```
##### Example:
```bash
docker run --rm \
-e MAX_CLIENT_CONN=100 \
-e DEFAULT_POOL_SIZE=20 \
-p 6432:6432 \
litehex/pgbouncer
```
### Examples
#### Use a custom configuration
Please note that by going this way, you cannot use any option from environment variables. This method is only useful if
you just want to run PgBouncer on Docker.
```bash
docker run --rm \
-v /path/to/pgbouncer.ini:/etc/pgbouncer/pgbouncer.ini \
-p 6432:6432 \
litehex/pgbouncer
```
#### Create a PgBouncer user
To define a user and add them to the users section of the auth file, you need to use the following environment
pattern:
```text
USER_ =
```
##### Example:
```bash
docker run --rm \
-e USER_UNICORN=securepassword \
-p 6432:6432 \
litehex/pgbouncer
```
#### Assign a user to a database
This method is useful when you want to create a user and assign it to multiple databases.
```bash
docker run --rm \
-e DB_="host= port= dbname= auth_user=" \
-e USER_="" \
-p 6432:6432 \
litehex/pgbouncer
```
#### Create multiple databases with isolated users access
```bash
docker run --rm \
-e DB_FIRST="host= port= dbname= auth_user=fu" \
-e USER_FU="" \
-e DB_SECOND="host= port= dbname= password= auth_user=su" \
-e USER_SU="" \
-p 6432:6432 \
litehex/pgbouncer
```
#### Use docker-compose and the ability to use multiple databases
To define multiple databases, you have to provide environment variables with the following format:
```text
DB_URL_ =
```
Or you can use the following format(Its same as PgBouncer config):
```text
DB_ = host= port= //...
```
```yaml
version: '3'
services:
storage-bouncer:
container_name: 'storage-bouncer'
image: 'litehex/pgbouncer:latest'
restart: unless-stopped
ports:
- '6432:6432'
environment:
- DB_URL_READ=postgres://:@:/
- DB_URL_WRITE=postgres://:@:/
- DB_THIRD="host= port= dbname=
```
#### Create an admin user and connect to PgBouncer
For defining an admin you have to use `ADMIN_USERS` and `ADMIN_PASSWORD` environment variables, it will create a user
with given credentials and adds it to config file.
##### 1. Create credentials
```bash
export ADMIN_USER=superuser
export ADMIN_PASSWORD=$(openssl rand -base64 32)
```
##### 2. Add credentials to docker command
```bash
docker run --rm \
-e ADMIN_USER=$ADMIN_USER \
-e ADMIN_PASSWORD=$ADMIN_PASSWORD \
-p 6432:6432 \
litehex/pgbouncer
```
##### 3. Connect to PgBouncer administration database
```bash
echo $ADMIN_PASSWORD | psql -h localhost -p 6432 -U $ADMIN_USER pgbouncer
# Or
psql "postgresql://$ADMIN_USER:$ADMIN_PASSWORD@localhost:6432/pgbouncer"
```
### Credits
This project was inspired by [`edoburu/docker-pgbouncer`](https://github.com/edoburu/docker-pgbouncer) and thanks
to [`edoburu`](https://github.com/edoburu) for their great work.
### License
This project is licensed under the GPL-3.0 License - see the [LICENSE](LICENSE) file for details