Connection Class Reference

#include <Pt/Db/Connection.h>

Database session for a registered driver. More...

Public Member Functions
	Connection (const std::string &driver)
	Creates a connection for driver.
	Connection (IConnection *conn)
	Takes ownership of the backend conn.
	~Connection ()
	Cancels a pending async operation and destroys the connection.
void	setActive (Pt::System::EventLoop &loop)
	Attaches loop for asynchronous operations.
void	cancel ()
	Cancels any pending async operation.
bool	ping ()
	Returns true if the backend still answers.
void	beginPing ()
	Starts an asynchronous ping.
bool	endPing ()
	Completes an asynchronous ping.
Pt::Signal &	pingFinished ()
	Signal emitted when an asynchronous ping completes.
long long	lastInsertId (const std::string &name=std::string())
	Returns the last generated row id.
bool	isIdle () const
	Returns true if no asynchronous operation is pending.
bool	hasTransaction () const
	Returns true if a transaction is active.
bool	isOpen () const
	Returns true if the database is open.
bool	operator! () const
	Returns true if the database is not open.
void	open (const std::string &connStr)
	Opens the database with connStr.
void	close ()
	Closes the database connection.
void	beginClose ()
	Starts an asynchronous close.
void	endClose ()
	Completes an asynchronous close.
Pt::Signal &	closeFinished ()
	Signal emitted when an asynchronous close completes.
void	beginOpen (const std::string &connStr)
	Starts an asynchronous open with connStr.
void	endOpen ()
	Completes an asynchronous open.
Pt::Signal &	openFinished ()
	Signal emitted when an asynchronous open completes.
size_type	execute (const std::string &query)
	Executes query and returns the number of rows changed.
void	beginExecute (const std::string &sql)
	Starts asynchronous execution of sql.
size_type	endExecute ()
	Completes asynchronous execution.
Pt::Signal &	executeFinished ()
	Signal emitted when asynchronous execution completes.
Result	select (const std::string &query)
	Executes query and returns a buffered result.
void	beginSelect (const std::string &sql)
	Starts an asynchronous select of sql.
Result	endSelect ()
	Completes an asynchronous select.
Pt::Signal &	selectFinished ()
	Signal emitted when an asynchronous select completes.
Statement	prepare (const std::string &query)
	Compiles query into a prepared statement.
Statement	prepareCached (const std::string &query)
	Compiles query and caches the prepared statement.
void	clearStatementCache ()
	Clears the prepared-statement cache.
void	beginPrepare (const std::string &query)
	Starts asynchronous compile of query.
Statement	endPrepare ()
	Completes asynchronous compile.
Pt::Signal &	prepareFinished ()
	Signal emitted when asynchronous prepare completes.
void	beginPrepareCached (const std::string &query)
	Starts asynchronous compile and cache of query.
Statement	endPrepareCached ()
	Completes asynchronous prepareCached.
Pt::Signal &	prepareCachedFinished ()
	Signal emitted when asynchronous prepareCached completes.
AsyncOpen	openAsync (const std::string &connStr)
	Returns an awaitable that opens the database with connStr.
AsyncClose	closeAsync ()
	Returns an awaitable that closes the database.
AsyncExecute	executeAsync (const std::string &sql)
	Returns an awaitable that executes sql.
AsyncSelect	selectAsync (const std::string &sql)
	Returns an awaitable that selects sql.
AsyncPing	pingAsync ()
	Returns an awaitable that pings the database.
IConnection *	impl ()
	Returns the backend implementation.
const IConnection *	impl () const
	Returns the backend implementation.

Detailed Description

Connection is the database handle the group described: a driver name allocates a backend, and open() establishes the session. The object is not copyable. Destroying it cancels a pending async operation and releases the backend.

The driver constructor takes a registered name such as "sqlite". The connection is not open after that call. The IConnection constructor takes ownership of an existing backend and is meant for tests and custom backends.

open() and close() are the synchronous session. The connection string is driver-specific and has no driver prefix. isOpen() reports the session. operator!() is true when the session is not open. ping() tests whether the backend still answers. lastInsertId() is the generated row id of the last insert; pass a sequence name on backends that use named sequences, or an empty string otherwise.

execute() runs SQL that does not return rows. select() runs a query and returns a buffered Result. prepare() compiles a Statement. prepareCached() compiles and caches by SQL text. clearStatementCache() drops that cache.

setActive() attaches an EventLoop for asynchronous work. The loop does not own the connection. Each async operation is a begin/end pair and a finished signal; the slot calls the matching end method. isIdle() is true when none is pending. cancel() aborts a pending operation. Starting another while one is pending throws InvalidConnection or ConnectionError.

When C++20 is available, openAsync(), closeAsync(), executeAsync(), selectAsync() and pingAsync() wrap those pairs for co_await.

hasTransaction() is true while a Transaction is active. Begin, commit and rollback are operations of that type.

Pt::Db::Connection conn("sqlite");
conn.open("file:app.db");
conn.execute("CREATE TABLE IF NOT EXISTS t(id INTEGER)");
Pt::Db::Result r = conn.select("SELECT id FROM t");
conn.close();

Constructor & Destructor Documentation

Connection()

Connection ( const std::string & driver )

explicit

Call open() to establish a session.

Exceptions

%InvalidConnection

if driver is not registered.

Member Function Documentation

endPing()

bool endPing

(

)

Returns

True if the backend still answers.

lastInsertId()

long long lastInsertId

(

const std::string &

name = std::string()

)

Pass a sequence name on backends that use named sequences, or an empty string otherwise.

beginClose()

void beginClose

(

)

Cancels any pending operation, then closes asynchronously.

endExecute()

size_type endExecute

(

)

Returns

Number of rows changed.

endSelect()

Result endSelect

(

)

Returns

Buffered result of the query.

endPrepare()

Statement endPrepare

(

)

Returns

Compiled statement.

endPrepareCached()

Statement endPrepareCached

(

)

Returns

Compiled statement.

executeAsync()

AsyncExecute executeAsync

(

const std::string &

sql

)

The awaitable yields the number of rows changed.

selectAsync()

AsyncSelect selectAsync

(

const std::string &

sql

)

The awaitable yields the buffered result.

pingAsync()

AsyncPing pingAsync

(

)

The awaitable yields true if the connection is alive.