{"id":20313078,"url":"https://github.com/edoburu/docker-pgbouncer","last_synced_at":"2025-05-15T05:07:39.003Z","repository":{"id":31239242,"uuid":"116984972","full_name":"edoburu/docker-pgbouncer","owner":"edoburu","description":"Minimal PgBouncer image that is easy to configure","archived":false,"fork":false,"pushed_at":"2025-05-09T01:19:16.000Z","size":90,"stargazers_count":483,"open_issues_count":2,"forks_count":262,"subscribers_count":10,"default_branch":"master","last_synced_at":"2025-05-09T02:27:38.677Z","etag":null,"topics":["docker","kubernetes","pgbouncer","postgresql"],"latest_commit_sha":null,"homepage":"https://hub.docker.com/r/edoburu/pgbouncer/","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/edoburu.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2018-01-10T16:51:55.000Z","updated_at":"2025-05-09T01:11:27.000Z","dependencies_parsed_at":"2024-11-21T19:01:48.320Z","dependency_job_id":"4fd764d0-bbcc-4646-b956-853c0713a10c","html_url":"https://github.com/edoburu/docker-pgbouncer","commit_stats":{"total_commits":92,"total_committers":31,"mean_commits":2.967741935483871,"dds":0.5978260869565217,"last_synced_commit":"a45d457113057cb5f83e48c34fdf65050b89079a"},"previous_names":[],"tags_count":5,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/edoburu%2Fdocker-pgbouncer","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/edoburu%2Fdocker-pgbouncer/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/edoburu%2Fdocker-pgbouncer/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/edoburu%2Fdocker-pgbouncer/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/edoburu","download_url":"https://codeload.github.com/edoburu/docker-pgbouncer/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254276447,"owners_count":22043867,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["docker","kubernetes","pgbouncer","postgresql"],"created_at":"2024-11-14T18:09:11.187Z","updated_at":"2025-05-15T05:07:33.995Z","avatar_url":"https://github.com/edoburu.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"PgBouncer Docker image\n======================\n\nThis is a minimal PgBouncer image, based on Alpine Linux.\n\nFeatures:\n\n* Very small, quick to pull (just 15MB)\n* Configurable using environment variables\n* Uses standard Postgres port 5432, to work transparently for applications.\n* Includes PostgreSQL client tools such as ``psql``, ``pg_isready``\n* MD5 authentication by default.\n* `/etc/pgbouncer/pgbouncer.ini` and `/etc/pbbouncer/userlist.txt` are auto-created if they don't exist.\n\nWhy use PgBouncer\n-----------------\n\nPostgreSQL connections take up a lot of memory ([about 10MB per connection](http://hans.io/blog/2014/02/19/postgresql_connection)). There is also a significant startup cost to establish a connection with TLS, hence web applications gain performance by using persistent connections.\n\nBy placing PgBouncer in between the web application and the actual PostgreSQL database, the memory and start-up costs are reduced. The web application can keep persistent connections to PgBouncer, while PgBouncer only keeps a few connections to the actual PostgreSQL server. It can reuse the same connection for multiple clients.\n\nUsage\n-----\n\n```sh\ndocker run --rm \\\n    -e DATABASE_URL=\"postgres://user:pass@postgres-host/database\" \\\n    -p 5432:5432 \\\n    edoburu/pgbouncer\n```\n\nOr using separate variables:\n\n```sh\ndocker run --rm \\\n    -e DB_USER=user \\\n    -e DB_PASSWORD=pass \\\n    -e DB_HOST=postgres-host \\\n    -e DB_NAME=database \\\n    -p 5432:5432 \\\n    edoburu/pgbouncer\n```\n\nDuring startup we'll generate the necessary `userlist.txt` \u0026 `pgbouncer.ini` entries to match this information. Connecting should work as expected:\n\n```sh\npsql 'postgresql://user:pass@localhost/dbname'\n```\n\n\u003e [!NOTE]\n\u003e If you need quick multi-user setup you can use `DATABASE_URLS` (instead of `DATABASE_URL`) with a comma (`,`) separated list of URLs.\n\u003e\n\u003e ```sh\n\u003e docker run --rm \\\n\u003e     -e DATABASE_URLS=\"postgres://foo:123@postgres-host/foo,postgres://bar:456@postgres-host/bar\" \\\n\u003e     -p 5432:5432 \\\n\u003e     edoburu/pgbouncer\n\u003e ```\n\nConfiguration\n-------------\n\nAlmost all settings found in the [pgbouncer.ini](https://pgbouncer.github.io/config.html) can be defined as environment variables, except a few that make little sense in a Docker environment (like port numbers, syslog and pid settings). See the [entrypoint script](https://github.com/edoburu/docker-pgbouncer/blob/master/entrypoint.sh) for details. For example:\n\n```sh\ndocker run --rm \\\n    -e DATABASE_URL=\"postgres://user:pass@postgres-host/database\" \\\n    -e POOL_MODE=session \\\n    -e SERVER_RESET_QUERY=\"DISCARD ALL\" \\\n    -e MAX_CLIENT_CONN=100 \\\n    -p 5432:5432\n    edoburu/pgbouncer\n```\n\nKubernetes integration\n----------------------\n\nFor example in Kubernetes, see the [examples/kubernetes folder](https://github.com/edoburu/docker-pgbouncer/tree/master/examples/kubernetes).\n\nDocker Compose\n--------------\n\nFor example in Docker Compose, see the [examples/docker-compose folder](https://github.com/edoburu/docker-pgbouncer/tree/master/examples/docker-compose).\n\nPostgreSQL configuration\n------------------------\n\nMake sure PostgreSQL at least accepts connections from the machine where PgBouncer runs! Update `listen_addresses` in `postgresql.conf` and accept incoming connections from your IP range (e.g. `10.0.0.0/8`) in `pg_hba.conf`:\n\n```conf\n# TYPE  DATABASE        USER            ADDRESS                 METHOD\nhost    all             all             10.0.0.0/8              md5\n```\n\nUsing a custom configuration\n----------------------------\n\nWhen the default `pgbouncer.ini` is not sufficient, or you'd like to let multiple users connect through a single PgBouncer instance, mount an updated configuration:\n\n```sh\ndocker run --rm \\\n    -e DB_USER=user \\\n    -e DB_PASSWORD=pass \\\n    -e DB_HOST=postgres-host \\\n    -e DB_NAME=database \\\n    -v pgbouncer.ini:/etc/pgbouncer/pgbouncer.ini:ro\n    -p 5432:5432\n    edoburu/pgbouncer\n```\n\nOr extend the `Dockerfile`:\n\n```Dockerfile\nFROM edoburu/pgbouncer:1.11.0\nCOPY pgbouncer.ini userlist.txt /etc/pgbouncer/\n```\n\nWhen the `pgbouncer.ini` file exists, the startup script will not override it. An extra entry will be written to `userlist.txt` when `DATABASE_URL` contains credentials, or `DB_USER` and `DB_PASSWORD` are defined.\n\nThe `userlist.txt` file uses the following format:\n\n```txt\n\"username\" \"plaintext-password\"\n```\n\nor:\n\n```txt\n\"username\" \"md5\u003cmd5 of password + username\u003e\"\n```\n\nUse [examples/generate-userlist](https://github.com/edoburu/docker-pgbouncer/blob/master/examples/generate-userlist) to generate this file:\n\n```sh\nexamples/generate-userlist \u003e\u003e userlist.txt\n```\n\nYou can also connect with a single user to PgBouncer, and from there retrieve the actual database password\nby setting ``AUTH_USER``. See the example from: \u003chttps://www.cybertec-postgresql.com/en/pgbouncer-authentication-made-easy/\u003e\n\nConnecting to the admin console\n-------------------------------\n\nWhen an *admin user* is defined, and it has a password in the `userlist.txt`, it can connect to the special `pgbouncer` database:\n\n```sh\npsql postgres://postgres@hostname-of-container/pgbouncer  # outside container\npsql postgres://127.0.0.1/pgbouncer                       # inside container\n```\n\nHence this requires a custom configuration, or a mount of a custom ``userlist.txt`` in the docker file.\nVarious [admin console commands](https://pgbouncer.github.io/usage.html#admin-console) can be executed, for example:\n\n```sql\nSHOW STATS;\nSHOW SERVERS;\nSHOW CLIENTS;\nSHOW POOLS;\n```\n\nAnd it allows temporary disconnecting the backend database (e.g. for restarts) while the web applications keep a connection to PgBouncer:\n\n```sql\nPAUSE;\nRESUME;\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fedoburu%2Fdocker-pgbouncer","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fedoburu%2Fdocker-pgbouncer","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fedoburu%2Fdocker-pgbouncer/lists"}