Repository: launchbadge/sqlx
File: sqlx-core/src/pool/options.rs (Rust)

Code before:
    ///
    /// We've chosen not to assert `min_connections <= max_connections` anywhere
    /// because it shouldn't break anything internally if the condition doesn't hold,
    /// and if the application allows either value to be dynamically set
    /// then it should be checking this condition itself and returning
    /// a nicer error than a panic anyway.
    ///
    /// [`max_lifetime`]: Self::max_lifetime
    /// [`idle_timeout`]: Self::idle_timeout
    /// [`max_connections`]: Self::max_connections
    pub fn min_connections(mut self, min: u32) -> Self {
        self.min_connections = min;
        self
    }

    /// Get the minimum number of connections to maintain at all times.
    pub fn get_min_connections(&self) -> u32 {
        self.min_connections
    }

    /// Set a threshold for reporting excessive time taken to acquire a connection from
    /// the connection pool. When the threshold is exceeded, a warning is logged.
    ///
    /// Defaults to a value that should not typically be exceeded by the pool enlarging
    /// itself with an additional new connection.
    pub fn acquire_slow_after(mut self, value: Duration) -> Self {
        self.acquire_slow_after = value;
        self
    }

    /// Get the threshold for reporting excessive time taken to acquire a connection.
    pub fn get_acquire_slow_after(&self) -> Duration {
        self.acquire_slow_after
    }

    /// Set the maximum amount of time to spend waiting for a connection in [`Pool::acquire()`].
    ///
    /// Caps the total amount of time `Pool::acquire()` can spend waiting across multiple phases:
    ///
    /// * First, it may need to wait for a permit from the semaphore, which grants it the privilege
    ///   of opening a connection or popping one from the idle queue.
    /// * If an existing idle connection is acquired, by default it will be checked for liveness
    ///   and integrity before being returned, which may require executing a command on the
    ///   connection. This can be disabled with [`test_before_acquire(false)`][Self::test_before_acquire].
    ///     * If [`before_acquire`][Self::before_acquire] is set, that will also be executed.
    /// * If a new connection needs to be opened, that will obviously require I/O, handshaking,
    ///   and initialization commands.
    ///     * If [`after_connect`][Self::after_connect] is set, that will also be executed.
    pub fn acquire_timeout(mut self, timeout: Duration) -> Self {
        self.acquire_timeout = timeout;
        self

Review comment (performance):
Not everyone is going to want to log slow acquires, or want them logged at `WARN`.

IMO this should be more like [`ConnectOptions::log_slow_statements()`](https://docs.rs/sqlx/latest/sqlx/trait.ConnectOptions.html#tymethod.log_slow_statements) which takes a `LevelFilter` and a `Duration`; I'd call it `log_slow_acquires()`.

Or, to have a separate setter for the threshold (so a getter makes sense):

```rust
impl<DB: Database> PoolOptions<DB> {

    /// Log when a [`Pool::acquire()`] call takes longer than a certain threshold, indicating high load.
    ///
    /// Change the threshold duration with [`.slow_acquire_threshold()`][Self::slow_acquire_threshold]
    /// or get the current value with [`.get_slow_acquire_threshold()`][Self::get_slow_acquire_threshold].
    ///
    /// Set to [`LevelFilter::Warn`] by default. 
    /// Set to [`LevelFilter::Off`] to disable slow-acquire logging.
    pub fn log_slow_acquires(mut self, level: LevelFilter) -> Self {
        // ...
    }

    /// Set the threshold duration at which a [`Pool::acquire()`] call is considered "slow" and should be logged.
    pub fn slow_acquire_threshold(mut self, threshold: Duration) -> Self {
        // .. 
    }

    /// Get the threshold duration at which a [`Pool::acquire()`] call is considered "slow" and should be logged.
    pub fn get_slow_acquire_threshold(&self) -> Duration {
        // ..
    }
}
```

Code after:
    /// When the pool is built, this many connections will be automatically spun up.
    ///
    /// If any connection is reaped by [`max_lifetime`] or [`idle_timeout`], or explicitly closed,
    /// and it brings the connection count below this amount, a new connection will be opened to
    /// replace it.
    ///
    /// This is only done on a best-effort basis, however. The routine that maintains this value
    /// has a deadline so it doesn't wait forever if the database is being slow or returning errors.
    ///
    /// This value is clamped internally to not exceed [`max_connections`].
    ///
    /// We've chosen not to assert `min_connections <= max_connections` anywhere
    /// because it shouldn't break anything internally if the condition doesn't hold,
    /// and if the application allows either value to be dynamically set
    /// then it should be checking this condition itself and returning
    /// a nicer error than a panic anyway.
    ///
    /// [`max_lifetime`]: Self::max_lifetime
    /// [`idle_timeout`]: Self::idle_timeout
    /// [`max_connections`]: Self::max_connections
    pub fn min_connections(mut self, min: u32) -> Self {
        self.min_connections = min;
        self
    }

    /// Get the minimum number of connections to maintain at all times.
    pub fn get_min_connections(&self) -> u32 {
        self.min_connections
    }

    /// Enable logging of time taken to acquire a connection from the connection pool via
    /// [`Pool::acquire()`].
    ///
    /// If slow acquire logging is also enabled, this level is used for acquires that are not
    /// considered slow.
    pub fn acquire_time_level(mut self, level: LevelFilter) -> Self {
        self.acquire_time_level = level;
        self
    }

    /// Log excessive time taken to acquire a connection at a different log level than time taken
    /// for faster connection acquires via [`Pool::acquire()`].
    pub fn acquire_slow_level(mut self, level: LevelFilter) -> Self {
        self.acquire_slow_level = level;
        self
    }

    /// Set a threshold for reporting excessive time taken to acquire a connection from
    /// the connection pool via [`Pool::acquire()`]. When the threshold is exceeded, a warning is logged.
    ///
    /// Defaults to a value that should not typically be exceeded by the pool enlarging