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 the QDB_CONN_DFLT_SHARE flag to qdb_connect().
reuse: Like private, except that connections are returned to a pool rather than destroyed, and can be assigned from there to a new client for use in its duration.
share: Like unique, except that 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 the unique, reuse, and 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, by using the private or reuse mode or by not setting the QDB_CONN_DFLT_SHARE flag.