Database Access

Portable SQL connections, statements and results. More...

Topics
	Connections
	Open a database and run SQL on it.
	Statements
	Bind parameters and run prepared SQL.
	Results
	Buffered rows, column values and binary data.
	Cursors
	Fetch large results in batches.
	Transactions
	Begin, commit and roll back a unit of work.

Classes
class	DbError
	Base class for database errors. More...
class	ConnectionError
	Base class for connection errors. More...
class	AccessDenied
	Thrown when access to the database is denied. More...
class	InvalidConnection
	Thrown when the connection cannot be used. More...
class	QueryFailed
	Base class for query errors. More...
class	InvalidQuery
	Thrown when a query is invalid. More...
class	ConstraintMismatch
	Thrown when a database constraint is violated. More...
class	TypeMismatch
	Thrown on type mismatch, null access, or out-of-range values. More...

Detailed Description

This module is the portable SQL layer, so a caller opens a database, runs statements, and reads rows through the same types on every supported platform. The unit of work is a connection. Construct a Connection with a registered driver name, such as "sqlite". That allocates a backend; it does not open the database. open() takes a driver-specific connection string with no driver prefix.

Connection is not copyable. Statement, Result, Row, Value, Cursor and Blob are shared values: copying is cheap, and the backend lives until the last wrapper is destroyed.

Without an EventLoop every operation is synchronous and completes on the calling thread. setActive() attaches an EventLoop for asynchronous work. The loop does not own the connection: the code that creates it keeps it alive while an operation is still waiting on the loop. Asynchronous operations use a begin/end pair and a finished signal. The slot calls the matching end method. C++20 awaitables wrap the same pairs for co_await.

A Statement is a prepared query with named host variables. execute() runs a statement that does not return rows. select() returns a fully buffered Result. For a result that is too large to hold at once, getCursor() returns a Cursor that fetches batches.

A Transaction begins on a connection, commits or rolls back, and rolls back from the destructor if it is still active.

A failure that is specific to this module is a DbError. What each operation throws is documented on that member.

The rest of this chapter is the connection, then statements, then buffered results, then cursors, then transactions.