Enforce min_pool_size with prewarm and retain replenishment (#135)

Author: vadv

documentation/en/src/changelog.md

@@ -2,8 +2,14 @@
 
 ### 3.3.1 <small>Feb 26, 2026</small>
 
+**Bug Fixes:**
+
+- **Minimum pool size enforcement (`min_pool_size`)**: The `min_pool_size` user setting is now enforced at runtime. After each connection retain cycle, pg_doorman checks pool sizes and creates new connections to maintain the configured minimum. Previously, `min_pool_size` was accepted in config but never applied — pools started empty and could drop to 0 connections even with `min_pool_size` set. Replenishment stops on the first connection failure to avoid hammering an unavailable server.
+
 **Improvements:**
 
+- **Pool prewarm at startup**: When `min_pool_size` is configured, pg_doorman now creates the minimum number of connections immediately at startup, before the first retain cycle. Previously, pools started empty and connections were only created lazily on first client request or after the first retain interval (default 60s). This eliminates cold-start latency for the first clients connecting after pg_doorman restart.
+
 - **Configurable connection scaling parameters**: New `general` settings `scaling_warm_pool_ratio`, `scaling_fast_retries`, and `scaling_cooldown_sleep` allow tuning connection pool scaling behavior. All three can be overridden at the pool level. `scaling_cooldown_sleep` uses the human-readable `Duration` type (e.g. `"10ms"`, `"1s"`) consistent with other timeout fields.
 
 - **`max_concurrent_creates` setting**: Controls the maximum number of server connections that can be created concurrently per pool. Uses a semaphore instead of a mutex for parallel connection creation.

pg_doorman.toml

@@ -483,6 +483,7 @@ password = "md5dd9a0f26a4302744db881776a09bbfad"
 pool_size = 40
 
 # Minimum connections to maintain in the pool.
+# Prewarmed at startup, then maintained by retain cycle.
 # Must be <= pool_size.
 # min_pool_size = 5
 

pg_doorman.yaml

@@ -527,6 +527,7 @@ pools:
         pool_size: 40
 
       # Minimum connections to maintain in the pool.
+      # Prewarmed at startup, then maintained by retain cycle.
       # Must be <= pool_size.
         # min_pool_size: 5
 

src/app/generate/fields.yaml

@@ -1079,11 +1079,13 @@ fields:
       config:
         en: |
           Minimum connections to maintain in the pool.
+          Prewarmed at startup, then maintained by retain cycle.
           Must be <= pool_size.
         ru: |
           Минимальное количество соединений для поддержания в пуле.
+          Создаются при старте (prewarm), затем поддерживаются retain-циклом.
           Должно быть <= pool_size.
-      doc: "The minimum number of connections to maintain in the pool for this user. This helps with performance by keeping connections ready. If specified, it must be less than or equal to pool_size."
+      doc: "The minimum number of connections to maintain in the pool for this user. Connections are prewarmed at startup (before the first retain cycle) and then maintained by periodic replenishment. If specified, it must be less than or equal to pool_size."
       default: "None"
 
     pool_mode:

src/pool/inner.rs

@@ -8,6 +8,8 @@ use std::{
     },
 };
 
+use log::warn;
+
 use crate::utils::clock;
 
 use parking_lot::Mutex;
@@ -596,6 +598,56 @@ impl Pool {
         self.inner.config.timeouts
     }
 
+    /// Creates new connections to bring the pool up to the desired count.
+    /// Returns the number of connections successfully created.
+    /// Stops on the first creation failure to avoid hammering a failing server.
+    pub async fn replenish(&self, count: usize) -> usize {
+        let mut created = 0;
+        for _ in 0..count {
+            // Check if there's still room in the pool
+            {
+                let slots = self.inner.slots.lock();
+                if slots.size >= slots.max_size {
+                    break;
+                }
+            }
+
+            // Create a new connection
+            let obj = match self.inner.server_pool.create().await {
+                Ok(obj) => obj,
+                Err(e) => {
+                    warn!(
+                        "[pool: {}] failed to create connection during replenish: {}",
+                        self.inner.server_pool.address(),
+                        e
+                    );
+                    break;
+                }
+            };
+
+            let lifetime_ms = self.inner.server_pool.lifetime_ms();
+            let inner = ObjectInner {
+                obj,
+                metrics: Metrics::new_with_lifetime(lifetime_ms),
+            };
+
+            {
+                let mut slots = self.inner.slots.lock();
+                if slots.size >= slots.max_size {
+                    break;
+                }
+                slots.size += 1;
+                match self.inner.config.queue_mode {
+                    QueueMode::Fifo => slots.vec.push_back(inner),
+                    QueueMode::Lifo => slots.vec.push_front(inner),
+                }
+            }
+
+            created += 1;
+        }
+        created
+    }
+
     /// Closes this Pool.
     pub fn close(&self) {
         self.resize(0);

src/pool/mod.rs

@@ -858,6 +858,11 @@ impl ServerPool {
         }
     }
 
+    /// Returns the address of this pool.
+    pub fn address(&self) -> &Address {
+        &self.address
+    }
+
     /// Returns the base lifetime in milliseconds for connections in this pool.
     pub fn lifetime_ms(&self) -> u64 {
         self.lifetime_ms

src/pool/retain.rs

@@ -1,7 +1,7 @@
 use std::sync::atomic::{AtomicUsize, Ordering};
 use std::sync::Arc;
 
-use log::info;
+use log::{info, warn};
 
 use crate::config::get_config;
 
@@ -102,12 +102,67 @@ pub async fn retain_connections() {
         }
     );
 
+    // Prewarm pools with min_pool_size before the first retain cycle
+    for (_, pool) in get_all_pools().iter() {
+        if let Some(min_pool_size) = pool.settings.user.min_pool_size {
+            let min = min_pool_size as usize;
+            let created = pool.database.replenish(min).await;
+            if created > 0 {
+                info!(
+                    "[pool: {}][user: {}] prewarmed {} connection{} (min_pool_size: {})",
+                    pool.address.pool_name,
+                    pool.address.username,
+                    created,
+                    if created == 1 { "" } else { "s" },
+                    min,
+                );
+            } else {
+                warn!(
+                    "[pool: {}][user: {}] prewarm failed — could not create connections (min_pool_size: {})",
+                    pool.address.pool_name,
+                    pool.address.username,
+                    min,
+                );
+            }
+        }
+    }
+
     loop {
         interval.tick().await;
         for (_, pool) in get_all_pools().iter() {
             pool.retain_pool_connections(count.clone(), retain_max);
         }
         count.store(0, Ordering::Relaxed);
+
+        // Replenish pools below min_pool_size
+        for (_, pool) in get_all_pools().iter() {
+            if let Some(min_pool_size) = pool.settings.user.min_pool_size {
+                let min = min_pool_size as usize;
+                let current_size = pool.database.status().size;
+                if current_size < min {
+                    let deficit = min - current_size;
+                    let created = pool.database.replenish(deficit).await;
+                    if created > 0 {
+                        info!(
+                            "[pool: {}][user: {}] replenished {} connection{} (min_pool_size: {})",
+                            pool.address.pool_name,
+                            pool.address.username,
+                            created,
+                            if created == 1 { "" } else { "s" },
+                            min,
+                        );
+                    } else {
+                        warn!(
+                            "[pool: {}][user: {}] failed to replenish connections (deficit: {}, min_pool_size: {})",
+                            pool.address.pool_name,
+                            pool.address.username,
+                            deficit,
+                            min,
+                        );
+                    }
+                }
+            }
+        }
     }
 }
 

tests/bdd/features/min-pool-size.feature

@@ -0,0 +1,118 @@
+@rust @rust-3 @min-pool-size
+Feature: min_pool_size enforcement
+  Test that min_pool_size setting is enforced at runtime.
+  After each retain cycle, pg_doorman should replenish pools below min_pool_size.
+
+  Background:
+    Given PostgreSQL started with pg_hba.conf:
+      """
+      local all all trust
+      host all all 127.0.0.1/32 trust
+      """
+    And fixtures from "tests/fixture.sql" applied
+
+  @replenish-after-startup
+  Scenario: Pool replenishes to min_pool_size after startup
+    Given pg_doorman started with config:
+      """
+      [general]
+      host = "127.0.0.1"
+      port = ${DOORMAN_PORT}
+      admin_username = "admin"
+      admin_password = "admin"
+      pg_hba.content = "host all all 127.0.0.1/32 trust"
+      retain_connections_time = 500
+      server_lifetime = 60000
+
+      [pools.example_db]
+      server_host = "127.0.0.1"
+      server_port = ${PG_PORT}
+
+      [[pools.example_db.users]]
+      username = "example_user_1"
+      password = ""
+      pool_size = 5
+      min_pool_size = 3
+      """
+    # Wait for at least 2 retain cycles so replenish can create connections
+    When we sleep for 1500 milliseconds
+    # Check server connections via admin console
+    When we create admin session "admin1" to pg_doorman as "admin" with password "admin"
+    And we execute "SHOW SERVERS" on admin session "admin1" and store row count
+    Then admin session "admin1" row count should be greater than or equal to 3
+
+  @prewarm-at-startup
+  Scenario: Pool is prewarmed at startup before retain cycle
+    Given pg_doorman started with config:
+      """
+      [general]
+      host = "127.0.0.1"
+      port = ${DOORMAN_PORT}
+      admin_username = "admin"
+      admin_password = "admin"
+      pg_hba.content = "host all all 127.0.0.1/32 trust"
+      retain_connections_time = 60000
+      server_lifetime = 60000
+
+      [pools.example_db]
+      server_host = "127.0.0.1"
+      server_port = ${PG_PORT}
+
+      [[pools.example_db.users]]
+      username = "example_user_1"
+      password = ""
+      pool_size = 5
+      min_pool_size = 2
+      """
+    # Wait for prewarm to complete, but retain cycle (60s) has NOT fired yet
+    When we sleep for 1000 milliseconds
+    When we create admin session "admin1" to pg_doorman as "admin" with password "admin"
+    And we execute "SHOW SERVERS" on admin session "admin1" and store row count
+    Then admin session "admin1" row count should be greater than or equal to 2
+
+  @maintain-after-expiry
+  Scenario: Pool maintains min_pool_size after connections expire
+    Given pg_doorman started with config:
+      """
+      [general]
+      host = "127.0.0.1"
+      port = ${DOORMAN_PORT}
+      admin_username = "admin"
+      admin_password = "admin"
+      pg_hba.content = "host all all 127.0.0.1/32 trust"
+      retain_connections_time = 500
+      server_lifetime = 1000
+      server_idle_check_timeout = 0
+
+      [pools.example_db]
+      server_host = "127.0.0.1"
+      server_port = ${PG_PORT}
+
+      [[pools.example_db.users]]
+      username = "example_user_1"
+      password = ""
+      pool_size = 5
+      min_pool_size = 2
+      """
+    # Create a session and make a query to establish at least 1 backend connection
+    When we create session "one" to pg_doorman as "example_user_1" with password "" and database "example_db"
+    And we send Parse "" with query "SELECT pg_backend_pid()" to session "one"
+    And we send Bind "" to "" with params "" to session "one"
+    And we send Execute "" to session "one"
+    And we send Sync to session "one"
+    Then we remember backend_pid from session "one" as "first_pid"
+    # Wait for replenish to bring pool up to min_pool_size
+    When we sleep for 2000 milliseconds
+    When we create admin session "admin1" to pg_doorman as "admin" with password "admin"
+    And we execute "SHOW SERVERS" on admin session "admin1" and store row count
+    Then admin session "admin1" row count should be greater than or equal to 2
+    # Wait for server_lifetime (1s ±20% jitter) to expire and retain to close + replenish
+    When we sleep for 3000 milliseconds
+    And we execute "SHOW SERVERS" on admin session "admin1" and store row count
+    Then admin session "admin1" row count should be greater than or equal to 2
+    # Verify the backend was replaced (new PID after lifetime expiry)
+    When we send Parse "" with query "SELECT pg_backend_pid()" to session "one"
+    And we send Bind "" to "" with params "" to session "one"
+    And we send Execute "" to session "one"
+    And we send Sync to session "one"
+    Then we verify backend_pid from session "one" is different from "first_pid"