database/sql Connection Pool — Middle¶

// database/sql/sql.go:438
type DB struct {
    // Atomic access only. At top of struct to prevent mis-alignment
    // on 32-bit platforms. Of type time.Duration.
    waitDuration atomic.Int64 // Total time waited for new connections.

    connector driver.Connector
    // numClosed is an atomic counter which represents a total number of
    // closed connections. Stmt.openStmt checks it before cleaning closed
    // connections in Stmt.css.
    numClosed atomic.Uint64

    mu           sync.Mutex // protects following fields
    freeConn     []*driverConn
    connRequests map[uint64]chan connRequest
    nextRequest  uint64 // Next key to use in connRequests.
    numOpen      int    // number of opened and pending open connections
    // Used to signal the need for new connections
    // a goroutine running connectionOpener() reads on this chan and
    // maybeOpenNewConnections sends on the chan (one send per needed
    // connection). It is closed during db.Close(). The close tells the
    // connectionOpener goroutine to exit.
    openerCh          chan struct{}
    closed            bool
    dep               map[finalCloser]depSet
    lastPut           map[*driverConn]string // stacktrace of last conn's put; debug only
    maxIdleCount      int                    // zero means defaultMaxIdleConns; negative means 0
    maxOpen           int                    // <= 0 means unlimited
    maxLifetime       time.Duration          // maximum amount of time a connection may be reused
    maxIdleTime       time.Duration          // maximum amount of time a connection may be idle before being closed
    cleanerCh         chan struct{}
    waitCount         int64 // Total number of connections waited for.
    maxIdleClosed     int64 // Total number of connections closed due to idle count.
    maxIdleTimeClosed int64 // Total number of connections closed due to idle time.
    maxLifetimeClosed int64 // Total number of connections closed due to max connection lifetime limit.

    stop func() // stop cancels the connection opener.
}

// database/sql/sql.go:380
type connRequest struct {
    conn *driverConn
    err  error
}

type connReuseStrategy uint8

const (
    alwaysNewConn   connReuseStrategy = iota // always open a new conn
    cachedOrNewConn                          // first try freeConn, then open new
)

// driverConn wraps a driver.Conn with a mutex, held during all calls.
type driverConn struct {
    db        *DB
    createdAt time.Time

    sync.Mutex  // guards following
    ci          driver.Conn
    needReset   bool // The connection session should be reset before use if true.
    closed      bool
    finalClosed bool // ci.Close has been called
    openStmt    map[*driverStmt]bool

    // guarded by db.mu
    inUse      bool
    returnedAt time.Time // Time the connection was created or returned.
    onPut      []func()  // code (with db.Mu held) run when conn is next returned
    dbmuClosed bool      // same as closed, but guarded by db.mu, for removeClosedStmtLocked
}

// database/sql/sql.go:823
func Open(driverName, dataSourceName string) (*DB, error) {
    driversMu.RLock()
    driveri, ok := drivers[driverName]
    driversMu.RUnlock()
    if !ok {
        return nil, fmt.Errorf("sql: unknown driver %q (forgotten import?)", driverName)
    }

    if driverCtx, ok := driveri.(driver.DriverContext); ok {
        connector, err := driverCtx.OpenConnector(dataSourceName)
        if err != nil {
            return nil, err
        }
        return OpenDB(connector), nil
    }

    return OpenDB(dsnConnector{dsn: dataSourceName, driver: driveri}), nil
}

// database/sql/sql.go:846
func OpenDB(c driver.Connector) *DB {
    ctx, cancel := context.WithCancel(context.Background())
    db := &DB{
        connector:    c,
        openerCh:     make(chan struct{}, connectionRequestQueueSize),
        lastPut:      make(map[*driverConn]string),
        connRequests: make(map[uint64]chan connRequest),
        stop:         cancel,
    }

    go db.connectionOpener(ctx)

    return db
}

// database/sql/sql.go:69
const connectionRequestQueueSize = 1000000

// database/sql/sql.go:1300
// conn returns a newly-opened or cached *driverConn.
func (db *DB) conn(ctx context.Context, strategy connReuseStrategy) (*driverConn, error) {
    db.mu.Lock()
    if db.closed {
        db.mu.Unlock()
        return nil, errDBClosed
    }
    // Check if the context is expired.
    select {
    default:
    case <-ctx.Done():
        db.mu.Unlock()
        return nil, ctx.Err()
    }
    lifetime := db.maxLifetime

    // Prefer a free connection, if possible.
    last := len(db.freeConn) - 1
    if strategy == cachedOrNewConn && last >= 0 {
        // Reuse the lowest idle time connection so we can close
        // connections which remain idle as soon as possible.
        conn := db.freeConn[last]
        db.freeConn = db.freeConn[:last]
        conn.inUse = true
        if conn.expired(lifetime) {
            db.maxLifetimeClosed++
            db.mu.Unlock()
            conn.Close()
            return nil, driver.ErrBadConn
        }
        db.mu.Unlock()

        // Reset the session if required.
        if err := conn.resetSession(ctx); errors.Is(err, driver.ErrBadConn) {
            conn.Close()
            return nil, err
        }

        return conn, nil
    }

    // Out of free connections or we were asked not to use one. If we're not
    // allowed to open any more connections, make a request and wait.
    if db.maxOpen > 0 && db.numOpen >= db.maxOpen {
        // Make the connRequest channel. It's buffered so that the
        // connectionOpener doesn't block while waiting for the req to be read.
        req := make(chan connRequest, 1)
        reqKey := db.nextRequestKeyLocked()
        db.connRequests[reqKey] = req
        db.waitCount++
        db.mu.Unlock()

        waitStart := nowFunc()

        // Timeout the connection request with the context.
        select {
        case <-ctx.Done():
            // Remove the connection request and ensure no value has been sent
            // on it after removing.
            db.mu.Lock()
            delete(db.connRequests, reqKey)
            db.mu.Unlock()

            db.waitDuration.Add(int64(time.Since(waitStart)))

            select {
            default:
            case ret, ok := <-req:
                if ok && ret.conn != nil {
                    db.putConn(ret.conn, ret.err, false)
                }
            }
            return nil, ctx.Err()
        case ret, ok := <-req:
            db.waitDuration.Add(int64(time.Since(waitStart)))

            if !ok {
                return nil, errDBClosed
            }
            // Only check if the connection is expired if the strategy is cachedOrNewConn.
            // If we require a new connection, just re-use the connection without looking
            // at the expiry time. If it is expired, it will be checked when it is placed
            // back into the connection pool.
            // This prioritizes giving a valid connection to a client over the exact connection
            // lifetime, which could expire exactly after this point anyway.
            if strategy == cachedOrNewConn && ret.err == nil && ret.conn.expired(lifetime) {
                db.mu.Lock()
                db.maxLifetimeClosed++
                db.mu.Unlock()
                ret.conn.Close()
                return nil, driver.ErrBadConn
            }
            if ret.conn == nil {
                return nil, ret.err
            }

            // Reset the session if required.
            if err := ret.conn.resetSession(ctx); errors.Is(err, driver.ErrBadConn) {
                ret.conn.Close()
                return nil, err
            }
            return ret.conn, ret.err
        }
    }

    db.numOpen++ // optimistically
    db.mu.Unlock()
    ci, err := db.connector.Connect(ctx)
    if err != nil {
        db.mu.Lock()
        db.numOpen-- // correct for earlier optimism
        db.maybeOpenNewConnections()
        db.mu.Unlock()
        return nil, err
    }
    db.mu.Lock()
    dc := &driverConn{
        db:         db,
        createdAt:  nowFunc(),
        returnedAt: nowFunc(),
        ci:         ci,
        inUse:      true,
    }
    db.addDepLocked(dc, dc)
    db.mu.Unlock()
    return dc, nil
}

req := make(chan connRequest, 1)
reqKey := db.nextRequestKeyLocked()
db.connRequests[reqKey] = req
db.waitCount++
db.mu.Unlock()

select {
case <-ctx.Done():
    ...
case ret, ok := <-req:
    ...
}

// database/sql/sql.go:1408
// putConn adds a connection to the db's free pool.
// err is optionally the last error that occurred on this connection.
func (db *DB) putConn(dc *driverConn, err error, resetSession bool) {
    if !errors.Is(err, driver.ErrBadConn) {
        if !dc.validateConnection(resetSession) {
            err = driver.ErrBadConn
        }
    }
    db.mu.Lock()
    if !dc.inUse {
        db.mu.Unlock()
        if debugGetPut {
            fmt.Printf("putConn(%v) DUPLICATE was: %s\n\nPREVIOUS was: %s",
                dc, stack(), db.lastPut[dc])
        }
        panic("sql: connection returned that was never out")
    }

    if !errors.Is(err, driver.ErrBadConn) && dc.expired(db.maxLifetime) {
        db.maxLifetimeClosed++
        err = driver.ErrBadConn
    }
    if debugGetPut {
        db.lastPut[dc] = stack()
    }
    dc.inUse = false
    dc.returnedAt = nowFunc()

    for _, fn := range dc.onPut {
        fn()
    }
    dc.onPut = nil

    if errors.Is(err, driver.ErrBadConn) {
        // Don't reuse bad connections.
        // Since the conn is considered bad and is being discarded, treat it
        // as closed. Don't decrement the open count here, finalClose will
        // take care of that.
        db.maybeOpenNewConnections()
        db.mu.Unlock()
        dc.Close()
        return
    }
    added := db.putConnDBLocked(dc, nil)
    db.mu.Unlock()

    if !added {
        dc.Close()
        return
    }
}

// Satisfy a connRequest or put the driverConn in the idle pool and return true
// or return false.
// putConnDBLocked will satisfy a connRequest if there is one, or it will
// return the *driverConn to the freeConn list if err == nil and the idle
// connection limit will not be exceeded.
// If err != nil, the value of dc is ignored.
// If err == nil, then dc must not equal nil.
// If a connRequest was fulfilled or the *driverConn was placed in the
// freeConn list, then true is returned, otherwise false is returned.
func (db *DB) putConnDBLocked(dc *driverConn, err error) bool {
    if db.closed {
        return false
    }
    if db.maxOpen > 0 && db.numOpen > db.maxOpen {
        return false
    }
    if c := len(db.connRequests); c > 0 {
        var req chan connRequest
        var reqKey uint64
        for reqKey, req = range db.connRequests {
            break
        }
        delete(db.connRequests, reqKey) // Remove from pending requests.
        if err == nil {
            dc.inUse = true
        }
        req <- connRequest{
            conn: dc,
            err:  err,
        }
        return true
    } else if err == nil && !db.closed {
        if db.maxIdleConnsLocked() > len(db.freeConn) {
            db.freeConn = append(db.freeConn, dc)
            db.startCleanerLocked()
            return true
        }
        db.maxIdleClosed++
    }
    return false
}

// database/sql/sql.go:1264
// Open one new connection
func (db *DB) openNewConnection(ctx context.Context) {
    // maybeOpenNewConnections has already executed db.numOpen++ before it sent
    // on db.openerCh. This function must execute db.numOpen-- if the
    // connection fails or is closed before returning.
    ci, err := db.connector.Connect(ctx)
    db.mu.Lock()
    defer db.mu.Unlock()
    if db.closed {
        if err == nil {
            ci.Close()
        }
        db.numOpen--
        return
    }
    if err != nil {
        db.numOpen--
        db.putConnDBLocked(nil, err)
        db.maybeOpenNewConnections()
        return
    }
    dc := &driverConn{
        db:         db,
        createdAt:  nowFunc(),
        returnedAt: nowFunc(),
        ci:         ci,
    }
    if db.putConnDBLocked(dc, err) {
        db.addDepLocked(dc, dc)
    } else {
        db.numOpen--
        ci.Close()
    }
}

// database/sql/sql.go:1232
// Assumes db.mu is locked.
// If there are connRequests and the connection limit hasn't been reached,
// then tell the connectionOpener to open new connections.
func (db *DB) maybeOpenNewConnections() {
    numRequests := len(db.connRequests)
    if db.maxOpen > 0 {
        numCanOpen := db.maxOpen - db.numOpen
        if numRequests > numCanOpen {
            numRequests = numCanOpen
        }
    }
    for numRequests > 0 {
        db.numOpen++ // optimistically
        numRequests--
        if db.closed {
            return
        }
        db.openerCh <- struct{}{}
    }
}

// database/sql/sql.go:1255
// Runs in a separate goroutine, opens new connections when requested.
func (db *DB) connectionOpener(ctx context.Context) {
    for {
        select {
        case <-ctx.Done():
            return
        case <-db.openerCh:
            db.openNewConnection(ctx)
        }
    }
}

// database/sql/sql.go:1077
// startCleanerLocked starts connectionCleaner if needed.
func (db *DB) startCleanerLocked() {
    if (db.maxLifetime > 0 || db.maxIdleTime > 0) && db.numOpen > 0 && db.cleanerCh == nil {
        db.cleanerCh = make(chan struct{}, 1)
        go db.connectionCleaner(db.shortestIdleTimeLocked())
    }
}

// database/sql/sql.go:1086
func (db *DB) connectionCleaner(d time.Duration) {
    const minInterval = time.Second
    if d < minInterval {
        d = minInterval
    }
    t := time.NewTimer(d)

    for {
        select {
        case <-t.C:
        case <-db.cleanerCh: // maxLifetime was changed or db was closed.
        }

        db.mu.Lock()

        d = db.shortestIdleTimeLocked()
        if db.closed || db.numOpen == 0 || d <= 0 {
            db.cleanerCh = nil
            db.mu.Unlock()
            return
        }

        d, closing := db.connectionCleanerRunLocked(d)
        db.mu.Unlock()
        for _, c := range closing {
            c.Close()
        }

        if d < minInterval {
            d = minInterval
        }
        if !t.Stop() {
            select {
            case <-t.C:
            default:
            }
        }
        t.Reset(d)
    }
}

// database/sql/sql.go:1128
func (db *DB) connectionCleanerRunLocked(d time.Duration) (time.Duration, []*driverConn) {
    var idleClosing int64
    var closing []*driverConn
    if db.maxIdleTime > 0 {
        // As freeConn is ordered by returnedAt process
        // in reverse order to minimise the work needed.
        idleSince := nowFunc().Add(-db.maxIdleTime)
        last := len(db.freeConn) - 1
        for i := last; i >= 0; i-- {
            c := db.freeConn[i]
            if c.returnedAt.Before(idleSince) {
                i++
                closing = db.freeConn[:i:i]
                db.freeConn = db.freeConn[i:]
                idleClosing = int64(len(closing))
                db.maxIdleTimeClosed += idleClosing
                break
            }
        }
        if len(db.freeConn) > 0 {
            c := db.freeConn[0]
            if d2 := c.returnedAt.Sub(idleSince); d2 < d {
                // Ensure idle connections are cleaned up as soon as
                // possible.
                d = d2
            }
        }
    }

    if db.maxLifetime > 0 {
        expiredSince := nowFunc().Add(-db.maxLifetime)
        for i := 0; i < len(db.freeConn); i++ {
            c := db.freeConn[i]
            if c.createdAt.Before(expiredSince) {
                closing = append(closing, c)

                last := len(db.freeConn) - 1
                // Use slow delete as order is required to ensure
                // connections are reused least idle time first.
                copy(db.freeConn[i:], db.freeConn[i+1:])
                db.freeConn[last] = nil
                db.freeConn = db.freeConn[:last]
                i--
            } else if c.createdAt.After(expiredSince) {
                // Find the first connection created after expiredSince.
                if d2 := c.createdAt.Sub(expiredSince); d2 < d {
                    d = d2
                }
            }
        }
        db.maxLifetimeClosed += int64(len(closing)) - idleClosing
    }

    return d, closing
}

// database/sql/sql.go:537 (continued from earlier)

// expired reports whether the driverConn has been used past the given timeout.
// The timeout argument may be the maximum lifetime, or it may be zero (no expiry).
func (dc *driverConn) expired(timeout time.Duration) bool {
    if timeout <= 0 {
        return false
    }
    return dc.createdAt.Add(timeout).Before(nowFunc())
}

// resetSession checks if the driver connection needs the session to be reset
// and if required, resets it.
func (dc *driverConn) resetSession(ctx context.Context) error {
    dc.Lock()
    defer dc.Unlock()

    if !dc.needReset {
        return nil
    }
    if cr, ok := dc.ci.(driver.SessionResetter); ok {
        return cr.ResetSession(ctx)
    }
    return nil
}

// validateConnection checks if the connection is valid and can
// still be used. It also marks the session for reset if required.
func (dc *driverConn) validateConnection(needsReset bool) bool {
    dc.Lock()
    defer dc.Unlock()

    if needsReset {
        dc.needReset = true
    }
    if cv, ok := dc.ci.(driver.Validator); ok {
        return cv.IsValid()
    }
    return true
}

// database/sql/sql.go:603
// the dc.db's Mutex is held.
func (dc *driverConn) closeDBLocked() func() error {
    dc.Lock()
    defer dc.Unlock()
    if dc.closed {
        return func() error { return errors.New("sql: duplicate driverConn close") }
    }
    dc.closed = true
    return dc.db.removeDepLocked(dc, dc)
}

func (dc *driverConn) Close() error {
    dc.Lock()
    if dc.closed {
        dc.Unlock()
        return errors.New("sql: duplicate driverConn close")
    }
    dc.closed = true
    dc.Unlock() // not defer; removeDep finalClose calls may need to lock

    // And now updates that require holding dc.mu.Lock.
    dc.db.mu.Lock()
    dc.dbmuClosed = true
    fn := dc.db.removeDepLocked(dc, dc)
    dc.db.mu.Unlock()
    return fn()
}

func (dc *driverConn) finalClose() error {
    var err error

    // Each *driverStmt has a lock to the dc. Copy the list out of the dc
    // before calling close on each stmt.
    var openStmt []*driverStmt
    withLock(dc, func() {
        openStmt = make([]*driverStmt, 0, len(dc.openStmt))
        for ds := range dc.openStmt {
            openStmt = append(openStmt, ds)
        }
        dc.openStmt = nil
    })
    for _, ds := range openStmt {
        ds.Close()
    }
    withLock(dc, func() {
        dc.finalClosed = true
        err = dc.ci.Close()
        dc.ci = nil
    })

    dc.db.mu.Lock()
    dc.db.numOpen--
    dc.db.maybeOpenNewConnections()
    dc.db.mu.Unlock()

    dc.db.numClosed.Add(1)
    return err
}

// database/sql/sql.go:1925
type Tx struct {
    db *DB

    // closemu prevents the transaction from closing while there
    // is an active query. It is held for read during queries
    // and exclusively during close.
    closemu sync.RWMutex

    // dc is owned exclusively until Commit or Rollback, at which point
    // it's returned with putConn.
    dc  *driverConn
    txi driver.Tx

    // releaseConn is called once the Tx is closed to release
    // any held driverConn back to the pool.
    releaseConn func(error)

    // done transitions from false to true exactly once, on Commit
    // or Rollback. once done, all operations fail with
    // ErrTxDone.
    done atomic.Bool

    // keepConnOnRollback is true if the connection is kept open after a Rollback failure.
    keepConnOnRollback bool

    // All Stmts prepared for this transaction. These will be closed after the
    // transaction has been committed or rolled back.
    stmts struct {
        sync.Mutex
        v []*Stmt
    }

    // cancel is called after done transitions from false to true.
    cancel func()

    // ctx lives for the life of the transaction.
    ctx context.Context
}

// database/sql/sql.go:1859
func (db *DB) BeginTx(ctx context.Context, opts *TxOptions) (*Tx, error) {
    var tx *Tx
    var err error
    for i := 0; i < maxBadConnRetries; i++ {
        tx, err = db.begin(ctx, opts, cachedOrNewConn)
        if !errors.Is(err, driver.ErrBadConn) {
            break
        }
    }
    if errors.Is(err, driver.ErrBadConn) {
        return db.begin(ctx, opts, alwaysNewConn)
    }
    return tx, err
}

// database/sql/sql.go:2598
type Stmt struct {
    // Immutable:
    db        *DB    // where we came from
    query     string // that created the Stmt
    stickyErr error  // if non-nil, this error is returned for all operations

    closemu sync.RWMutex // held exclusively during close, for read otherwise.

    // If Stmt is prepared on a Tx or Conn then cg is present and will
    // only ever grab a connection from cg.
    // If cg is nil then the Stmt must grab an arbitrary connection
    // from db and determine if it must call Conn.Prepare or use a cached statement.
    cg   stmtConnGrabber
    cgds *driverStmt

    // parentStmt is set when a transaction-specific statement
    // is requested from an identical statement prepared on the same
    // conn. parentStmt is used to track the dependency of this statement
    // on its originating ("parent") statement so that parentStmt may
    // be closed by the user without them having to know whether or not
    // any transactions are still using it.
    parentStmt *Stmt

    mu     sync.Mutex // protects the rest of the fields
    closed bool

    // css is a list of underlying driver statement interfaces
    // that are valid on particular connections. This is only
    // used if cg == nil and one is found that has idle
    // connections. If cg != nil, cgds is always used.
    css []connStmt

    // lastNumClosed is copied from db.numClosed when Stmt is created
    // without tx and closed connections in css are removed.
    lastNumClosed uint64
}

type connStmt struct {
    dc *driverConn
    ds *driverStmt
}

// database/sql/sql.go:3193
type Rows struct {
    dc          *driverConn // owned; must call releaseConn when closed to release
    releaseConn func(error)
    rowsi       driver.Rows
    cancel      func() // called when Rows is closed, may be nil.

    // closemu prevents Rows from closing while there
    // is an active streaming result. It is held for read during non-close operations
    // and exclusively during close.
    //
    // closemu guards lasterr and closed.
    closemu sync.RWMutex
    closed  bool
    lasterr error // non-nil only if closed is true

    // lastcols is only used in Scan, Next, and NextResultSet which are expected
    // not to be called concurrently.
    lastcols []driver.Value

    // raw is a buffer for RawBytes that persists between Scan calls.
    // This is used when the driver returns a mismatched type that requires
    // an allocation.
    raw []byte

    // hookNextDone is for testing.
    hookNextDone func()
}

case <-ctx.Done():
    db.mu.Lock()
    delete(db.connRequests, reqKey)
    db.mu.Unlock()

    db.waitDuration.Add(int64(time.Since(waitStart)))

    select {
    default:
    case ret, ok := <-req:
        if ok && ret.conn != nil {
            db.putConn(ret.conn, ret.err, false)
        }
    }
    return nil, ctx.Err()

// database/sql/sql.go:920
func (db *DB) SetMaxIdleConns(n int) {
    db.mu.Lock()
    if n > 0 {
        db.maxIdleCount = n
    } else {
        // No idle connections.
        db.maxIdleCount = -1
    }
    // Make sure maxIdle doesn't exceed maxOpen
    if db.maxOpen > 0 && db.maxIdleConnsLocked() > db.maxOpen {
        db.maxIdleCount = db.maxOpen
    }
    var closing []*driverConn
    idleCount := len(db.freeConn)
    maxIdle := db.maxIdleConnsLocked()
    if idleCount > maxIdle {
        closing = db.freeConn[maxIdle:]
        db.freeConn = db.freeConn[:maxIdle]
    }
    db.maxIdleClosed += int64(len(closing))
    db.mu.Unlock()
    for _, c := range closing {
        c.Close()
    }
}

func (db *DB) SetMaxOpenConns(n int) {
    db.mu.Lock()
    db.maxOpen = n
    if n < 0 {
        db.maxOpen = 0
    }
    syncMaxIdle := db.maxOpen > 0 && db.maxIdleConnsLocked() > db.maxOpen
    db.mu.Unlock()
    if syncMaxIdle {
        db.SetMaxIdleConns(n)
    }
}

func (db *DB) SetConnMaxLifetime(d time.Duration) {
    if d < 0 {
        d = 0
    }
    db.mu.Lock()
    // Wake cleaner up when lifetime is shortened.
    if d > 0 && d < db.maxLifetime && db.cleanerCh != nil {
        select {
        case db.cleanerCh <- struct{}{}:
        default:
        }
    }
    db.maxLifetime = d
    if db.numOpen > 0 && db.maxLifetime > 0 {
        db.startCleanerLocked()
    }
    db.mu.Unlock()
}

func (db *DB) SetConnMaxIdleTime(d time.Duration) {
    if d < 0 {
        d = 0
    }
    db.mu.Lock()
    defer db.mu.Unlock()

    // Wake cleaner up when idle time is shortened.
    if d > 0 && d < db.maxIdleTime && db.cleanerCh != nil {
        select {
        case db.cleanerCh <- struct{}{}:
        default:
        }
    }
    db.maxIdleTime = d
    if db.numOpen > 0 && db.maxIdleTime > 0 {
        db.startCleanerLocked()
    }
}

// database/sql/sql.go:891
const defaultMaxIdleConns = 2

func (db *DB) maxIdleConnsLocked() int {
    n := db.maxIdleCount
    switch {
    case n == 0:
        return defaultMaxIdleConns
    case n < 0:
        return 0
    default:
        return n
    }
}

// database/sql/sql.go:1056
type DBStats struct {
    MaxOpenConnections int // Maximum number of open connections to the database.

    // Pool Status
    OpenConnections int // The number of established connections both in use and idle.
    InUse           int // The number of connections currently in use.
    Idle            int // The number of idle connections.

    // Counters
    WaitCount         int64         // The total number of connections waited for.
    WaitDuration      time.Duration // The total time blocked waiting for a new connection.
    MaxIdleClosed     int64         // The total number of connections closed due to SetMaxIdleConns.
    MaxIdleTimeClosed int64         // The total number of connections closed due to SetConnMaxIdleTime.
    MaxLifetimeClosed int64         // The total number of connections closed due to SetConnMaxLifetime.
}

func (db *DB) Stats() DBStats {
    wait := db.waitDuration.Load()

    db.mu.Lock()
    defer db.mu.Unlock()

    stats := DBStats{
        MaxOpenConnections: db.maxOpen,

        Idle:            len(db.freeConn),
        OpenConnections: db.numOpen,
        InUse:           db.numOpen - len(db.freeConn),

        WaitCount:         db.waitCount,
        WaitDuration:      time.Duration(wait),
        MaxIdleClosed:     db.maxIdleClosed,
        MaxIdleTimeClosed: db.maxIdleTimeClosed,
        MaxLifetimeClosed: db.maxLifetimeClosed,
    }
    return stats
}

// database/sql/driver/driver.go:99
type Conn interface {
    Prepare(query string) (Stmt, error)
    Close() error
    Begin() (Tx, error)
}

// database/sql/driver/driver.go:144
type SessionResetter interface {
    ResetSession(ctx context.Context) error
}

// database/sql/driver/driver.go:150
type Validator interface {
    IsValid() bool
}

// database/sql/driver/driver.go:128
var ErrBadConn = errors.New("driver: bad connection")

const maxBadConnRetries = 2

// database/sql/sql.go:1648
func (db *DB) Exec(query string, args ...any) (Result, error) {
    return db.ExecContext(context.Background(), query, args...)
}

func (db *DB) ExecContext(ctx context.Context, query string, args ...any) (Result, error) {
    var res Result
    var err error
    for i := 0; i < maxBadConnRetries; i++ {
        res, err = db.exec(ctx, query, args, cachedOrNewConn)
        if !errors.Is(err, driver.ErrBadConn) {
            break
        }
    }
    if errors.Is(err, driver.ErrBadConn) {
        return db.exec(ctx, query, args, alwaysNewConn)
    }
    return res, err
}