pgpool

A PostgreSQL connection pooler written in Go that acts as a proxy between clients and PostgreSQL servers, managing connection pooling, query routing, and multiple authentication mechanisms.

Features

• Connection Pooling: Efficiently manages database connections per user with configurable limits
• Multiple Authentication Methods:
  • Clear Password (plaintext)
  • MD5 Password (with salt)
  • SCRAM-SHA-256 (Salted Challenge Response Authentication Mechanism)
  • Trust (no password)
• PostgreSQL Wire Protocol: Full implementation supporting 40+ message types
• Extended Query Support: Parse, Bind, Execute, and Sync operations
• Prepared Statement Caching: Triggers prepare implicitly if server connection misses preprared on new pairing
• Comprehensive testing: Integration testing and TPC-B full protocol benchmarking with other poolers

Quick Start

Installation

git clone https://github.com/everdance/pgpool.git
cd pgpool
go build -v -o pgpool .

Configuration

Create a pgpool.conf file in INI format:

[app]
addr = localhost:5433

[db]
id = 1
name = postgres
host = localhost:5432

[user]
dbid = 1
name = myuser
auth_type = scram
password = mypassword
max_conn = 20
max_clients = 100

Running

# Run with default config (config.ini)
./pgpool

# Run with custom config
./pgpool --config /path/to/config.ini

Command-Line Flags

Flag	Shorthand	Default	Description
--config	-c	./config.ini	Path to configuration file
--log-level	-l	info	Set log level: debug, info, warn, error
--verbose	-v	false	Enable debug logging (equivalent to --log-level debug)
--quiet	-q	false	Show errors only (equivalent to --log-level error)

Environment Variables:

• PGPOOL_LOG_LEVEL: Set default log level (overridden by command-line flags)

Configuration Reference

Application Section

Parameter	Description	Example
addr	Listening address(es), comma-separated	localhost:5433,0.0.0.0:5433

Database Section

Parameter	Description	Example
id	Unique database identifier	1
name	Database name	postgres
host	PostgreSQL server address	localhost:5432

User Section

Parameter	Description	Example
dbid	Link to database ID	1
name	Username	myuser
auth_type	Authentication method: password, md5, scram, or trust	scram
password	Password (clear password)	test
max_conn	Maximum server connections	20
max_clients	Maximum client connections	100

Authentication

Password

Clear Password, MD5 and SCRAM are supported for client to pgpool connection and pgpool to PostgreSQL server connection.

SCRAM (Salted Challenge Response Authentication Mechanism) is the default authentication method supported by PostgreSQL 14+.

Trust

No password required. Use only in trusted environments. PostgreSQL server must be configured to support trust authentication for the same user.

auth_type = trust
password =

Testing

Unit Tests

go test -v -race -coverprofile=coverage.txt ./pool/... ./proto/...

Integration tests

smoke test

The smoke suite tests SQL queries, transactions and prepared statements.

./run_smoke.sh

concurent test

The concurent suite tests the core pooling functions for multiple client connections

NUM_CONNECTIONS=100 QUERIES_PER_CONNECTION=10 ./run_concurrent.sh

Pgbench Benchmark Testing with other poolers together

Check Readme and example report

Report Snapshort

Protocol: extended

Throughput (TPS)

Connections	direct	pgpool	pgcat	pgbouncer
10	540.992544	629.573937	400.953194	508.470016
50	520.948243	513.098964	444.584482	719.135004

Average Latency (ms)

Connections	direct	pgpool	pgcat	pgbouncer
10	18.485	15.884	24.941	19.667
50	95.979	97.447	112.465	69.528

---

Protocol: prepared

Throughput (TPS)

Connections	direct	pgpool	pgcat	pgbouncer
10	603.806235	671.575983	NA	484.158180
50	571.118586	819.022499	NA	774.326083

Average Latency (ms)

Connections	direct	pgpool	pgcat	pgbouncer
10	16.562	14.890	NA	20.654
50	87.547	61.048	NA	64.572

---

TODO

• SSL support
• Session pooling
• Extended protocol performance optimization
• Enrich Statistics & Output
• Sharding?

License

This project is licensed under the MIT License.

See the LICENSE file for full details.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Acknowledgments

Built with Go's standard library and inspired by Pgbouncer.