🔌 pg-conn-bench

[⚠ WARNING THIS IS SOME AI GENERATED SHIT ]

pg-conn-bench is a high-throughput benchmarking tool to evaluate how many PostgreSQL connections per second your database can handle. It allows you to define structured experiments consisting of multiple tests with varying concurrency and SQL execution behavior.

📈 Features include:

• Multiple test definitions per experiment
• Custom duration and time resolution
• Optional SQL query per test (or just open/close)
• Latency and throughput graphs
• Quantile-based performance summaries
• Failure tracking and reporting

---

🚀 Getting Started

1. Clone the repository

git clone https://github.com/your-org/pg-conn-bench.git
cd pg-conn-bench

2. Install dependencies We recommend using uv for fast dependency management:

uv venv
source .venv/bin/activate
uv pip install asyncpg numpy asciichartpy pyyaml rich

pip install asyncpg numpy asciichartpy pyyaml rich

▶️ Running a Benchmark

1. Create an experiment file:

duration: 8
resolution: 0.5
dsn: "postgres://user@host:port/dbname?sslmode=require"
tests:
  - name: c1
    concurrency: 1
  - name: c2
    concurrency: 2
  - name: c4
    concurrency: 4
  - name: c8
    concurrency: 8

2. Run the benchmark using an experiment file:

uv run main.py example.yml

🧪 Example Use Case

Test how connection throughput scales with increasing concurrency: SQL Load Testing Test SQL performance at a fixed concurrency:

duration: 10
resolution: 1.0
dsn: "postgres://user@host:port/dbname?sslmode=require"
tests:
  - name: SELECT 1
    concurrency: 100
    sql: "SELECT 1"
  - name: Heavy Join
    concurrency: 20
    sql: "SELECT * FROM generate_series(1, 10000) g1 JOIN generate_series(1, 10000) g2 ON g1=g2 LIMIT 1"

📊 Output

The script produces:

• 📉 Line chart showing average latency or connections/sec per bucket
• 📋 Rich table summarizing:
• 20th to 100th percentile of bucketed throughput
• Failure count and failure rate per test

📋 Quantile Table

┏━━━━━━┳━━━━━━━━━━━┳━━━━━━━━━━━┳━━━━━━━━━━━┳━━━━━━━━━━━┳━━━━━━━━━━━━┳━━━━━━━━━━┳━━━━━━━━━━━┓
┃ Test ┃ 20th %ile ┃ 40th %ile ┃ 60th %ile ┃ 80th %ile ┃ 100th %ile ┃ Failures ┃ Fail Rate ┃
┡━━━━━━╇━━━━━━━━━━━╇━━━━━━━━━━━╇━━━━━━━━━━━╇━━━━━━━━━━━╇━━━━━━━━━━━━╇━━━━━━━━━━╇━━━━━━━━━━━┩
│ c1   │      3.80 │      4.00 │      4.00 │      5.00 │       6.00 │        0 │     0.0 % │
└──────┴───────────┴───────────┴───────────┴───────────┴────────────┴──────────┴───────────┘

📈 ASCII Chart

📈 Connections/sec per 0.5s Bucket:
   6.1 ┼╮
   5.4 ┤│
   4.7 ┤│
   4.0 ┤│ ╭╮
   3.3 ┤│ ││
   2.6 ┤│ ││
   1.9 ┤╰╮││
   1.2 ┤ ╰╯╰

⚙️ Configuration Options

Top-level experiment config keys

Key	Type	Description
name	string	Name to identify the test in output
concurrency	int	Number of concurrent workers to launch
sql	string?	Optional SQL to run. If omitted, connect/close only

Test-level keys

Key	Type	Description
name	string	Name to identify the test in output
concurrency	int	Number of concurrent workers to launch
sql	string?	Optional SQL to run. If omitted, connect/close only