Sharing connections between clients

You can allow multiple clients to share a database connection. This is controlled by the -C option. The connection modes are:

unique

Each individual client request gets a new connection. This mode exists for pre-3.3.1 SQLite libraries, which were not thread-safe in any way.

private

Each client has a private persistent connection for its session; this connection is created when the client attaches and destroyed when it detaches. This mode is the backward-compatible mode; it is also the mode that must be used when you don't pass QDB_CONN_DFLT_SHARE flag to qdb_connect().

reuse

Like private, except that connections are returned to a pool rather than being destroyed, and can be assigned from there to a new client for use in its duration.

share

Like unique, except a connection pool is also used. This mode multiplexes all clients over a small number of active database connections.

Connection sharing exists because a non-negligible amount of work must be done to establish a database connection—QDB must allocate memory, access files, attach databases and callback functions, configure connection parameters, and more. If clients do not assume any state, then this processing work can be avoided. The QDB server detects if connection parameters have been changed by a client, and restores them when the connection moves in or out of the pool in unique, reuse, or share modes.

This connection sharing should be safe (unless the client destructively modifies the environment via SQL, such as by executing a DETACH DATABASE statement). However, for full backward compatibility, connection sharing can be overridden on each qdb_connect() call, and the default libqdb access mode is private.

If a client is leaving open transactions across multiple calls to qdb_statement(), then it needs a dedicated connection (private or reuse, or it shouldn't set the QDB_CONN_DFLT_SHARE flag).