Connection pooling
Opening a database connection is expensive: a TCP handshake, TLS, authentication and session setup can easily take longer than the query you wanted to run. Driftwood keeps a pool of open connections and hands them out on demand, so most requests skip all of that.
Configuring the pool
The pool is created once, when your application starts, and shared by every request handler. Its size is the most important setting: too small and requests queue for a connection, too large and the database spends its memory on idle sessions.
[pool]
min_idle = 2
max_size = 16
acquire_timeout = "5s"
idle_timeout = "10m"
A good starting point for max_size is twice the number of CPU cores on the database server, divided by the number of application instances.
Timeouts
| Setting | Default | Meaning |
|---|---|---|
acquire_timeout | 30s | How long a request waits for a free connection. |
idle_timeout | 10m | Idle connections older than this are closed. |
max_lifetime | 30m | Connections are recycled after this, even if busy. |
Warning: setting acquire_timeout higher than your HTTP request timeout means a slow pool turns into failed requests instead of fast errors.
Health checks
Before handing out a connection that has been idle for more than a minute, the pool runs a cheap ping. Broken connections are dropped and replaced transparently, so a database restart costs at most one failed ping per connection rather than one failed request.