Connection limit exceeded in DuckDB ConnectionManager: hard limit or advisory threshold?

Connection Limit Enforcement

In current DuckDB releases, the max_connections limit is enforced as a hard cap. When the number of active Connection objects reaches this ceiling, any subsequent request for a new connection will immediately raise a Connection limit exceeded error. It does not function as an advisory threshold, nor does it queue requests until a slot becomes available.

Connection Reclamation and Pooling

DuckDB's ConnectionManager does not provide automatic reclamation of idle connections. A connection remains active until it is explicitly closed by the application or the parent process terminates. Because there is no built-in background reaper for stale connections, leaked handles will exhaust the max_connections quota, necessitating an application restart to clear the state.

Consequently, DuckDB does not provide a native connection pool abstraction for user code. Applications requiring high-frequency connection cycling or concurrent access must implement their own pooling logic or strictly adhere to a manual close() pattern.

Implementation Recommendations

1. Manual Lifecycle Management: Ensure every connection is wrapped in a try-finally block or a context manager (e.g., with in Python) to guarantee closure regardless of execution success.
2. External Pooling: If your application architecture requires a pool, implement a wrapper that manages a fixed set of connections and distributes them to workers.
3. Limit Verification: Since defaults and error strings can vary between major versions and builds, verify your specific environment using the following logic:

-- 1. Check current limit
SELECT * FROM duckdb_settings() WHERE name = 'max_connections';

-- 2. Attempt to open (limit + 1) connections to confirm the hard failure.

Assumptions and Constraints

This behavior assumes the use of DuckDB in its standard embedded mode. Users should be cautious when increasing max_connections for a single database file, as this does not automatically guarantee safe concurrent write performance or eliminate locking contention. If you are using a specific wrapper or a third-party driver, please specify the driver version, as some middleware may implement its own pooling layer independently of the DuckDB core.