public final class DataSource

A pool of connections to ONE database, whichever engine that database is.

DbPool pools SQLite and only SQLite – it opens connections from a file path, so there is nowhere to put a host, a user or a password. That left the server engines with the advice to share a single Database and accept that every handler queues behind whichever exchange is on the socket, because a Database over PostgreSQL or MySQL owns one wire connection and synchronizes every operation on it.

Queueing is the right default for a server whose database is a local file. It is the wrong one for a server whose database is a machine across a network that is perfectly happy to run eight statements at once: there the single connection is not a safety property, it is the bottleneck. This is the same pool for all three, so which engine is behind it stops being a question the application’s structure has to answer.

DataSource db = DataSource.open("postgres://user:pw@db.internal/app");
List rows = db.query("SELECT id, title FROM notes WHERE author = ?",
        new Object[] {author});

The convenience methods above borrow a connection, run one statement and release it, which is what a handler wants: it is the borrow held ACROSS unrelated work that empties a pool. inTransaction is the form for several statements that have to be one, and it holds exactly one connection for exactly the body.

Connections are opened lazily except the first, which is opened by open so that a wrong URL, an unreachable host or a refused password fails at start-up rather than on the first request that needed the database.

An in-memory SQLite database is pooled at size one, and a configuration asking for more is REFUSED rather than quietly reduced. Each connection to “:memory:” gets its OWN private database, so a pool of them hands successive requests different empty databases – the one case where a bigger pool is not slower but wrong, and a setting worth reporting rather than ignoring.