const class sql::SqlConnPool

sys::Obj
  sql::SqlConnPool

Source

SqlConnPool manages a pool of reusable SQL connections

autoCommit

Bool autoCommit

Source

autoCommit sets the autoCommit mode used by connections in the pool. Applied when a connection is opened and restored when it is released, so a callback cannot leave the mode changed for the next borrower. Changing it at runtime takes effect per connection on its next release.

If auto-commit is true then each statement is executed and committed as an individual transaction. Otherwise statements are grouped into transaction which must be closed via SqlConn.commit or SqlConn.rollback.

checkoutTimeout

const Duration checkoutTimeout := 30sec

Source

Max time to block waiting for a connection to become available in the pool before raising TimeoutErr. Opening a new connection is bounded separately by connectTimeout.

close

Void close()

Source

Close all connections, stop houseKeeping, and raise exception on any new executes

connectTimeout

const Duration? connectTimeout := 10sec

Source

Max time to wait when opening a new connection before raising TimeoutErr, or null to wait as long as the driver allows, which may be forever if the server stalls the handshake. Enforced by the driver via the 'connectTimeout' and 'socketTimeout' connection properties. JDBC resolves it in whole seconds; anything under a second is rounded up to one second.

execute

Void execute(|SqlConn| f)

Source

Allocate a SQL connection inside the given callback. If a connection cannot be acquired before checkoutTimeout elapses then a TimeoutErr is raised. Do not close the connection inside the callback.

houseKeepingFreq

const Duration houseKeepingFreq := 30sec

Source

How often the pool runs houseKeeping: close connections idle past linger, retire connections older than maxLifetime, ping idle connections due a keepAlive, and warn about connections held past leakWarn. Scheduled by the pool; callers do not drive it.

isClosed

Bool isClosed()

Source

Return if close has been called.

keepAliveFreq

const Duration? keepAliveFreq := 2min

Source

How long an idle connection may sit before houseKeeping pings it, or null to never ping idle connections. A failed ping evicts the connection. Must be less than linger to have any effect. A ping does not count as a use and does not defer linger.

leakTrace

const Bool leakTrace := false

Source

Capture a stack trace at every checkout and include it in the leakWarn warning. Costs a stack fill per checkout, so it is off by default.

leakWarn

const Duration leakWarn := 2min

Source

Time a connection may be held by an execute callback before a warning is logged that it may be stuck or leaked. The warning is logged once per checkout.

linger

const Duration linger := 5min

Source

Time to linger an idle connection before closing it.

log

const Log log := Log.get("sqlPool")

Source

Logger

make

new make(|This|? f)

Source

It-block construtor

maxConns

const Int maxConns := 10

Source

Max number of simultaneous connections to allow before blocking threads

maxLifetime

const Duration maxLifetime := 30min

Source

Max lifetime of a connection before it is retired, regardless of how recently it was used. This protects against database and network infrastructure that kills long lived connections. Connections in use are never retired until released back to the pool.

onClose

protected virtual Void onClose(SqlConn c)

Source

onClose is invoked just before a connection is closed by the pool.

onOpen

protected virtual Void onOpen(SqlConn c)

Source

onOpen is invoked just after a connection is opened by the pool.

password

const Str? password

Source

Connection password

queryTimeout

const Duration? queryTimeout := 1min

Source

Default timeout applied to every statement created on connections from this pool, or null for no timeout. Restored when a connection is released, so a callback that changes the connection's timeout cannot leave it changed for the next borrower. Applies per execution, so a batch must complete within it. JDBC resolves it in whole seconds; anything under a second is rounded up to one second.

stats

Str:Obj stats()

Source

Snapshot of the pool's gauges and cumulative counters:

• total: Connections the pool holds, including slots still being opened
• active: Connections currently checked out. A slot reserved for a connection that is still opening counts here.
• idle: Connections available for checkout. A connection held by a keepAlive ping counts here.
• waiting: Threads blocked waiting for a connection
• maxConns: SqlConnPool.maxConns
• checkouts: Connections handed to an execute callback
• checkoutTimeouts: Checkouts that gave up after SqlConnPool.checkoutTimeout
• opened: Connections opened against the database
• retired: Connections closed for age: idle past SqlConnPool.linger, or older than SqlConnPool.maxLifetime
• evicted: Connections closed as broken: failed validation on checkout, failed after an execute callback raised, or failed a keepAlive ping
• leakWarnings: Warnings logged for connections held past SqlConnPool.leakWarn

uri

const Str uri

Source

Connection URI

username

const Str? username

Source

Connection username

validateAfterIdle

const Duration? validateAfterIdle := 500ms

Source

Ping a connection on checkout only if it has been idle at least this long, or null to never ping on checkout. The ping costs a database round trip. Governs checkout only: a connection is always validated after an execute callback raises.

validationTimeout

const Duration validationTimeout := 3sec

Source

Max time a liveness ping may take before the connection is treated as broken. JDBC resolves this in whole seconds; anything under a second is rounded up to one second.