improve benchmarks (#114)

Author: vadv

.github/workflows/bench-aws-fargate.yml

@@ -14,35 +14,30 @@ on:
         default: 'true'
         type: boolean
       fargate_cpu:
-        description: 'Fargate CPU units (1024=1vCPU, 2048=2vCPU, 4096=4vCPU, 8192=8vCPU, 16384=16vCPU)'
+        description: 'Fargate CPU units (8192=8vCPU, 16384=16vCPU)'
         required: false
         default: '16384'
         type: choice
         options:
-          - '2048'
-          - '4096'
           - '8192'
           - '16384'
       fargate_memory:
-        description: 'Fargate memory in MB (must be compatible with CPU)'
+        description: 'Fargate memory in MB (32GB, 64GB, 120GB)'
         required: false
         default: '32768'
         type: choice
         options:
-          - '4096'
-          - '8192'
-          - '16384'
           - '32768'
           - '61440'
           - '122880'
       doorman_workers:
         description: 'Number of worker threads for pg_doorman and odyssey'
         required: false
-        default: '4'
+        default: '12'
       pgbench_jobs:
         description: 'Number of threads (-j) for pgbench (global override)'
         required: false
-        default: ''
+        default: '4'
 
 env:
   REGISTRY: ghcr.io

benches/bench.feature

@@ -7,12 +7,24 @@ title: Home
 
 ## PgDoorman: PostgreSQL Pooler
 
-PgDoorman is a stable and good alternative to [PgBouncer](https://www.pgbouncer.org/), [Odyssey](https://github.com/yandex/odyssey), or [PgCat](https://github.com/postgresml/pgcat) (based on it).
-It has created with the Unix philosophy in mind. Developing was focused on perfomance, efficience and reliability.
-Also, PgDoorman has the improved driver support for languages like Go (pgx), .NET (npgsql), and asynchronous drivers for Python and Node.js.
+PgDoorman is a stable and high-performance alternative to [PgBouncer](https://www.pgbouncer.org/), [Odyssey](https://github.com/yandex/odyssey), or [PgCat](https://github.com/postgresml/pgcat).
+It was created with the Unix philosophy in mind. Development focused on performance, efficiency, and reliability.
+Additionally, PgDoorman provides improved driver support for languages like Go (pgx), .NET (npgsql), and asynchronous drivers for Python and Node.js.
 
 [:fontawesome-solid-download: Get PgDoorman {{ version }}](tutorials/installation.md){ .md-button .md-button--primary }
 
+### Quick Start
+
+Run PgDoorman instantly using Docker:
+
+```bash
+docker run -p 6432:6432 \
+  -v $(pwd)/pg_doorman.toml:/etc/pg_doorman/pg_doorman.toml \
+  ghcr.io/ozontech/pg_doorman
+```
+
+*For more details, see the [Installation Guide](tutorials/installation.md).*
+
 
 ### Why not multi-PgBouncer?
 
@@ -33,7 +45,7 @@ Some of the key differences include:
 
 - Performance improvements compared to PgCat/PgBouncer/Odyssey.
 - Support for extended protocol with popular programming language drivers.
-- Enhanced monitoring metrics to improve visibility into database activity..
+- Enhanced monitoring metrics to improve visibility into database activity.
 - Careful resource management to avoid memory issues (`max_memory_usage`, `message_size_to_be_stream`).
 - SCRAM client/server authentication support.
 - [Gracefully binary upgrade](tutorials/binary-upgrade.md).

documentation/docs/index.md

@@ -8,6 +8,14 @@ title: Overview
 
 PgDoorman is a high-performance PostgreSQL connection pooler based on PgCat. It acts as a middleware between your applications and PostgreSQL servers, efficiently managing database connections to improve performance and resource utilization.
 
+```mermaid
+graph LR
+    App1[Application A] --> Pooler(PgDoorman)
+    App2[Application B] --> Pooler
+    App3[Application C] --> Pooler
+    Pooler --> DB[(PostgreSQL)]
+```
+
 When an application connects to PgDoorman, it behaves exactly like a PostgreSQL server. Behind the scenes, PgDoorman either creates a new connection to the actual PostgreSQL server or reuses an existing connection from its pool, significantly reducing connection overhead.
 
 ## Key Benefits
@@ -21,23 +29,21 @@ When an application connects to PgDoorman, it behaves exactly like a PostgreSQL
 
 To maintain proper transaction semantics while providing efficient connection pooling, PgDoorman supports multiple pooling modes:
 
-### Session Pooling
+### Transaction Pooling
 
-In session pooling mode:
+!!! success "Recommended for most use cases"
+    In transaction pooling mode, a client is assigned a server connection only for the duration of a transaction. Once the transaction ends, the connection is released back into the pool.
 
-- Each client is assigned a dedicated server connection for the entire duration of the client connection
-- The server connection remains exclusively allocated to that client until disconnection
-- After the client disconnects, the server connection is released back into the pool for reuse
-- This mode is ideal for applications that rely on session-level features like temporary tables or session variables
+- **High Efficiency**: Connections are shared between clients, allowing thousands of clients to share a small pool.
+- **Ideal for**: Applications with many short-lived connections or those that don't rely on session state.
 
-### Transaction Pooling
+### Session Pooling
 
-In transaction pooling mode:
+!!! info "Useful for specific legacy needs"
+    In session pooling mode, each client is assigned a dedicated server connection for the entire duration of the client connection.
 
-- A client is assigned a server connection only for the duration of a transaction
-- Once PgDoorman detects the end of a transaction, the server connection is immediately released back into the pool
-- This mode allows for higher connection efficiency as connections are shared between clients
-- Ideal for applications with many short-lived connections or those that don't rely on session state
+- **Exclusive Allocation**: The connection remains exclusively allocated to that client until disconnection.
+- **Support for Session Features**: Ideal for applications that rely on temporary tables or session variables.
 
 ## Administration
 

documentation/docs/tutorials/overview.md

@@ -0,0 +1,10 @@
+# Troubleshooting
+
+This guide helps you resolve common issues when using PgDoorman.
+
+# TODO
+
+---
+
+!!! tip "Still having issues?"
+    If you encounter a problem not listed here, please [open an issue on GitHub](https://github.com/ozontech/pg_doorman/issues).

documentation/docs/tutorials/troubleshooting.md

@@ -44,39 +44,49 @@ theme:
     - navigation.sections
     - navigation.indexes
     - navigation.top
+    - navigation.breadcrumbs
+    - navigation.expand
+    - toc.follow
+    - search.highlight
+    - search.share
+    - search.suggest
 markdown_extensions:
   - tables
   - attr_list
   - admonition
   - pymdownx.details
-  - pymdownx.superfences
+  - pymdownx.superfences:
+      custom_fences:
+        - name: mermaid
+          class: mermaid
+          format: !!python/name:pymdownx.superfences.fence_code_format
   - pymdownx.highlight:
       anchor_linenums: true
       line_spans: __span
       pygments_lang_class: true
   - pymdownx.inlinehilite
   - pymdownx.snippets
-  - pymdownx.superfences
   - md_in_html
   - pymdownx.blocks.caption
   - pymdownx.emoji:
       emoji_index: !!python/name:material.extensions.emoji.twemoji
       emoji_generator: !!python/name:material.extensions.emoji.to_svg
 nav:
-    - index.md
-    - 'Getting started':
-        - 'tutorials/overview.md'
-        - 'tutorials/installation.md'
-        - 'tutorials/basic-usage.md'
-        - 'tutorials/binary-upgrade.md'
-        - 'tutorials/patroni-proxy.md'
-        - 'tutorials/contributing.md'
-        - 'changelog.md' 
+    - Home: index.md
+    - Overview: tutorials/overview.md
+    - Installation: tutorials/installation.md
+    - 'User Guide':
+        - tutorials/basic-usage.md
+        - tutorials/binary-upgrade.md
+        - tutorials/patroni-proxy.md
+        - tutorials/troubleshooting.md
+    - Benchmarks: benchmarks.md
     - 'Reference':
-        - 'reference/general.md'
-        - 'reference/pool.md'
-        - 'reference/prometheus.md'
-    - benchmarks.md
+        - reference/general.md
+        - reference/pool.md
+        - reference/prometheus.md
+    - Changelog: changelog.md
+    - Contributing: tutorials/contributing.md
 plugins:
   - search
   - autorefs

documentation/mkdocs.yml

@@ -61,13 +61,14 @@ cargo test --test bdd -- --tags @bench
 
 You can parameterize benchmarks using environment variables:
 
-- `BENCH_DOORMAN_WORKERS`: Number of worker threads for `pg_doorman` (default: 4)
-- `BENCH_ODYSSEY_WORKERS`: Number of workers for `odyssey` (default: 4)
+- `BENCH_DOORMAN_WORKERS`: Number of worker threads for `pg_doorman` (default: 12)
+- `BENCH_ODYSSEY_WORKERS`: Number of workers for `odyssey` (default: 12)
 - `BENCH_PGBENCH_JOBS`: Global number of threads (`-j`) for `pgbench`. If set, it overrides all specific job settings.
 - `BENCH_PGBENCH_JOBS_C1`: Number of threads for 1-client tests (default: 1)
-- `BENCH_PGBENCH_JOBS_C40`: Number of threads for 40-client tests (default: 2)
-- `BENCH_PGBENCH_JOBS_C80`: Number of threads for 80-client tests (default: 4)
+- `BENCH_PGBENCH_JOBS_C40`: Number of threads for 40-client tests (default: 4)
 - `BENCH_PGBENCH_JOBS_C120`: Number of threads for 120-client tests (default: 4)
+- `BENCH_PGBENCH_JOBS_C500`: Number of threads for 500-client tests (default: 4)
+- `BENCH_PGBENCH_JOBS_C10000`: Number of threads for 10,000-client tests (default: 4)
 - `FARGATE_CPU`: AWS Fargate CPU units (optional, for reporting)
 - `FARGATE_MEMORY`: AWS Fargate memory in MB (optional, for reporting)
 

tests/bdd/README.md

@@ -1006,52 +1006,62 @@ pub async fn generate_benchmark_markdown_table(world: &mut DoormanWorld) {
     let simple_configs: Vec<(&str, &str)> = vec![
         ("simple_c1", "1 client"),
         ("simple_c40", "40 clients"),
-        ("simple_c80", "80 clients"),
         ("simple_c120", "120 clients"),
+        ("simple_c500", "500 clients"),
+        ("simple_c10000", "10,000 clients"),
         ("simple_connect_c1", "1 client + Reconnect"),
         ("simple_connect_c40", "40 clients + Reconnect"),
-        ("simple_connect_c80", "80 clients + Reconnect"),
         ("simple_connect_c120", "120 clients + Reconnect"),
+        ("simple_connect_c500", "500 clients + Reconnect"),
+        ("simple_connect_c10000", "10,000 clients + Reconnect"),
         ("ssl_simple_c1", "1 client + SSL"),
         ("ssl_simple_c40", "40 clients + SSL"),
-        ("ssl_simple_c80", "80 clients + SSL"),
         ("ssl_simple_c120", "120 clients + SSL"),
+        ("ssl_simple_c500", "500 clients + SSL"),
+        ("ssl_simple_c10000", "10,000 clients + SSL"),
     ];
 
     // Extended Protocol tests
     let extended_configs: Vec<(&str, &str)> = vec![
         ("extended_c1", "1 client"),
         ("extended_c40", "40 clients"),
-        ("extended_c80", "80 clients"),
         ("extended_c120", "120 clients"),
+        ("extended_c500", "500 clients"),
+        ("extended_c10000", "10,000 clients"),
         ("extended_connect_c1", "1 client + Reconnect"),
         ("extended_connect_c40", "40 clients + Reconnect"),
-        ("extended_connect_c80", "80 clients + Reconnect"),
         ("extended_connect_c120", "120 clients + Reconnect"),
+        ("extended_connect_c500", "500 clients + Reconnect"),
+        ("extended_connect_c10000", "10,000 clients + Reconnect"),
         ("ssl_extended_c1", "1 client + SSL"),
         ("ssl_extended_c40", "40 clients + SSL"),
-        ("ssl_extended_c80", "80 clients + SSL"),
         ("ssl_extended_c120", "120 clients + SSL"),
+        ("ssl_extended_c500", "500 clients + SSL"),
+        ("ssl_extended_c10000", "10,000 clients + SSL"),
         ("ssl_connect_c1", "1 client + SSL + Reconnect"),
         ("ssl_connect_c40", "40 clients + SSL + Reconnect"),
-        ("ssl_connect_c80", "80 clients + SSL + Reconnect"),
         ("ssl_connect_c120", "120 clients + SSL + Reconnect"),
+        ("ssl_connect_c500", "500 clients + SSL + Reconnect"),
+        ("ssl_connect_c10000", "10,000 clients + SSL + Reconnect"),
     ];
 
     // Prepared Protocol tests
     let prepared_configs: Vec<(&str, &str)> = vec![
         ("prepared_c1", "1 client"),
         ("prepared_c40", "40 clients"),
-        ("prepared_c80", "80 clients"),
         ("prepared_c120", "120 clients"),
+        ("prepared_c500", "500 clients"),
+        ("prepared_c10000", "10,000 clients"),
         ("prepared_connect_c1", "1 client + Reconnect"),
         ("prepared_connect_c40", "40 clients + Reconnect"),
-        ("prepared_connect_c80", "80 clients + Reconnect"),
         ("prepared_connect_c120", "120 clients + Reconnect"),
+        ("prepared_connect_c500", "500 clients + Reconnect"),
+        ("prepared_connect_c10000", "10,000 clients + Reconnect"),
         ("ssl_prepared_c1", "1 client + SSL"),
         ("ssl_prepared_c40", "40 clients + SSL"),
-        ("ssl_prepared_c80", "80 clients + SSL"),
         ("ssl_prepared_c120", "120 clients + SSL"),
+        ("ssl_prepared_c500", "500 clients + SSL"),
+        ("ssl_prepared_c10000", "10,000 clients + SSL"),
     ];
 
     let simple_table = generate_table(&simple_configs, &world.bench_results);
@@ -1068,11 +1078,11 @@ pub async fn generate_benchmark_markdown_table(world: &mut DoormanWorld) {
     let doorman_workers = std::env::var("BENCH_DOORMAN_WORKERS")
         .ok()
         .filter(|s| !s.is_empty())
-        .unwrap_or_else(|| "4".to_string());
+        .unwrap_or_else(|| "12".to_string());
     let odyssey_workers = std::env::var("BENCH_ODYSSEY_WORKERS")
         .ok()
         .filter(|s| !s.is_empty())
-        .unwrap_or_else(|| "4".to_string());
+        .unwrap_or_else(|| "12".to_string());
     let pgbench_jobs = std::env::var("BENCH_PGBENCH_JOBS")
         .ok()
         .filter(|s| !s.is_empty());
@@ -1095,7 +1105,7 @@ pub async fn generate_benchmark_markdown_table(world: &mut DoormanWorld) {
     if let Some(jobs) = pgbench_jobs {
         env_info.push(format!("- **pgbench jobs**: {} (global override)", jobs));
     } else {
-        env_info.push("- **pgbench jobs**: variable (c1: 1, c40: 2, c80: 4, c120: 4)".to_string());
+        env_info.push("- **pgbench jobs**: variable (c1: 1, c40: 4, c120: 4, c500: 4, c10k: 4)".to_string());
     }
 
     // Record end time

tests/bdd/pgbench_helper.rs

@@ -142,58 +142,62 @@ impl DoormanWorld {
         let doorman_workers = std::env::var("BENCH_DOORMAN_WORKERS")
             .ok()
             .filter(|s| !s.is_empty())
-            .unwrap_or_else(|| "4".to_string());
+            .unwrap_or_else(|| "12".to_string());
         result = result.replace("${DOORMAN_WORKERS}", &doorman_workers);
 
         let odyssey_workers = std::env::var("BENCH_ODYSSEY_WORKERS")
             .ok()
             .filter(|s| !s.is_empty())
-            .unwrap_or_else(|| "4".to_string());
+            .unwrap_or_else(|| "12".to_string());
         result = result.replace("${ODYSSEY_WORKERS}", &odyssey_workers);
 
         // pgbench jobs can be overridden globally or specifically for client counts
         let global_pgbench_jobs = std::env::var("BENCH_PGBENCH_JOBS")
             .ok()
             .filter(|s| !s.is_empty());
 
-        let pgbench_jobs_c1 = global_pgbench_jobs
+        // C1 always needs 1 thread to avoid pgbench error: "number of clients (1) must be a multiple of number of threads"
+        let pgbench_jobs_c1 = "1".to_string();
+        result = result.replace("${PGBENCH_JOBS_C1}", &pgbench_jobs_c1);
+
+        let pgbench_jobs_c40 = global_pgbench_jobs
             .clone()
             .or_else(|| {
-                std::env::var("BENCH_PGBENCH_JOBS_C1")
+                std::env::var("BENCH_PGBENCH_JOBS_C40")
                     .ok()
                     .filter(|s| !s.is_empty())
             })
-            .unwrap_or_else(|| "1".to_string());
-        result = result.replace("${PGBENCH_JOBS_C1}", &pgbench_jobs_c1);
+            .unwrap_or_else(|| "4".to_string());
+        result = result.replace("${PGBENCH_JOBS_C40}", &pgbench_jobs_c40);
 
-        let pgbench_jobs_c40 = global_pgbench_jobs
+        let pgbench_jobs_c120 = global_pgbench_jobs
             .clone()
             .or_else(|| {
-                std::env::var("BENCH_PGBENCH_JOBS_C40")
+                std::env::var("BENCH_PGBENCH_JOBS_C120")
                     .ok()
                     .filter(|s| !s.is_empty())
             })
-            .unwrap_or_else(|| "2".to_string());
-        result = result.replace("${PGBENCH_JOBS_C40}", &pgbench_jobs_c40);
+            .unwrap_or_else(|| "4".to_string());
+        result = result.replace("${PGBENCH_JOBS_C120}", &pgbench_jobs_c120);
 
-        let pgbench_jobs_c80 = global_pgbench_jobs
+        let pgbench_jobs_c500 = global_pgbench_jobs
             .clone()
             .or_else(|| {
-                std::env::var("BENCH_PGBENCH_JOBS_C80")
+                std::env::var("BENCH_PGBENCH_JOBS_C500")
                     .ok()
                     .filter(|s| !s.is_empty())
             })
             .unwrap_or_else(|| "4".to_string());
-        result = result.replace("${PGBENCH_JOBS_C80}", &pgbench_jobs_c80);
+        result = result.replace("${PGBENCH_JOBS_C500}", &pgbench_jobs_c500);
 
-        let pgbench_jobs_c120 = global_pgbench_jobs
+        let pgbench_jobs_c10000 = global_pgbench_jobs
             .or_else(|| {
-                std::env::var("BENCH_PGBENCH_JOBS_C120")
+                std::env::var("BENCH_PGBENCH_JOBS_C10000")
                     .ok()
                     .filter(|s| !s.is_empty())
             })
             .unwrap_or_else(|| "4".to_string());
-        result = result.replace("${PGBENCH_JOBS_C120}", &pgbench_jobs_c120);
+        result = result.replace("${PGBENCH_JOBS_C10000}", &pgbench_jobs_c10000);
 
         result
     }