Database client abstract class. More...

#include <drogon/orm/DbClient.h>

Inheritance diagram for drogon::orm::DbClient:

[legend]

Collaboration diagram for drogon::orm::DbClient:

[legend]

Public Member Functions
template<typename FUNCTION1, typename FUNCTION2, typename... Arguments>
void	execSqlAsync (const std::string &sql, FUNCTION1 &&rCallback, FUNCTION2 &&exceptCallback, Arguments &&...args) noexcept
	Async and nonblocking method.
template<typename... Arguments>
std::future< Result >	execSqlAsyncFuture (const std::string &sql, Arguments &&...args) noexcept
	Async and nonblocking method.
template<typename... Arguments>
Result	execSqlSync (const std::string &sql, Arguments &&...args) noexcept(false)
internal::SqlBinder	operator<< (const std::string &sql)
internal::SqlBinder	operator<< (std::string &&sql)
template<int N>
internal::SqlBinder	operator<< (const char(&sql)[N])
internal::SqlBinder	operator<< (const std::string_view &sql)
virtual std::shared_ptr< Transaction >	newTransaction (const std::function< void(bool)> &commitCallback=std::function< void(bool)>(), TransactionType transType=TransactionType::Deferred) noexcept(false)=0
	Create a transaction object.
std::shared_ptr< Transaction >	newTransaction (TransactionType transType) noexcept(false)
	Convenience overload: create a transaction with a specific locking mode.
virtual void	newTransactionAsync (const std::function< void(const std::shared_ptr< Transaction > &)> &callback, TransactionType transType=TransactionType::Deferred)=0
	Create a transaction object in asynchronous mode.
void	newTransactionAsync (TransactionType transType, const std::function< void(const std::shared_ptr< Transaction > &)> &callback)
virtual bool	hasAvailableConnections () const noexcept=0
	Check if there is a connection successfully established.
ClientType	type () const
const std::string &	connectionInfo () const
virtual void	setTimeout (double timeout)=0
	Set the Timeout value of execution of a SQL.
virtual void	closeAll ()=0
	Close all connections in the client. usually used by Drogon in the quit() method.

Static Public Member Functions
static std::shared_ptr< DbClient >	newPgClient (const std::string &connInfo, size_t connNum, bool autoBatch=false)
	Create a new database client with multiple connections;.
static std::shared_ptr< DbClient >	newMysqlClient (const std::string &connInfo, size_t connNum)
static std::shared_ptr< DbClient >	newSqlite3Client (const std::string &connInfo, size_t connNum)

Protected Attributes
ClientType	type_
std::string	connectionInfo_

Detailed Description

Database client abstract class.

Member Function Documentation

◆ closeAll()

virtual void drogon::orm::DbClient::closeAll ( )

pure virtual

Close all connections in the client. usually used by Drogon in the quit() method.

Implemented in drogon::orm::Transaction.

◆ execSqlAsync()

template<typename FUNCTION1, typename FUNCTION2, typename... Arguments>

void drogon::orm::DbClient::execSqlAsync	(	const std::string &	sql,
		FUNCTION1 &&	rCallback,
		FUNCTION2 &&	exceptCallback,
		Arguments &&...	args )

inlinenoexcept

Async and nonblocking method.

Parameters

sql	is the SQL statement to be executed;

Template Parameters

FUNCTION1	is usually the ResultCallback type;
FUNCTION2	is usually the ExceptionCallback type;

Parameters

rCallback	callback function;
exceptCallback	callback function on exception;
args	are parameters that are bound to placeholders in the sql parameter;

Note

If the number of args parameters is not zero, make sure that all criteria in the sql parameter set by bind parameters, for example:

select * from users where user_id > 10 limit 10 offset 10; //Not bad, no bind parameters are used.
select * from users where user_id > ? limit ? offset ?; //Good, fully use bind parameters.
select * from users where user_id > ? limit ? offset 10; //Bad, partially use bind parameters.

Strictly speaking, try not to splice SQL statements dynamically, Instead, use the constant sql string with placeholders and the bind parameters to execute sql. This rule makes the sql execute faster and more securely, and users should follow this rule when calling all methods of DbClient.

◆ hasAvailableConnections()

virtual bool drogon::orm::DbClient::hasAvailableConnections ( ) const

pure virtualnoexcept

Check if there is a connection successfully established.

Returns: true; false

◆ newPgClient()

std::shared_ptr< DbClient > drogon::orm::DbClient::newPgClient	(	const std::string &	connInfo,
		size_t	connNum,
		bool	autoBatch = false )

static

Create a new database client with multiple connections;.

Parameters

connInfo

Connection string with some parameters, each parameter setting is in the form keyword = value. Spaces around the equal sign are optional. To write an empty value, or a value containing spaces, surround it with single quotes, e.g., keyword = 'a value'. Single quotes and backslashes within the value must be escaped with a backslash, i.e., \' and \. Example: host=localhost port=5432 dbname=mydb connect_timeout=10 password='' The currently recognized parameter key words are:

host: can be either a host name or an IP address.
port: Port number to connect to at the server host.
dbname: The database name. Defaults to be the same as the user name.
user: user name to connect as. With PostgreSQL defaults to be the same as the operating system name of the user running the application.
password: Password to be used if the server demands password authentication.
client_encoding: The character set to be used on database connections.

For other key words on PostgreSQL, see the PostgreSQL documentation. Only a pair of key values is valid for Sqlite3, and its keyword is 'filename'.

Parameters

connNum The number of connections to database server;

◆ newTransaction()

virtual std::shared_ptr< Transaction > drogon::orm::DbClient::newTransaction	(	const std::function< void(bool)> &	commitCallback = std::function< void(bool)>(),
		TransactionType	transType = TransactionType::Deferred )

pure virtual

Create a transaction object.

Parameters

commitCallback the callback with which user can get the submitting result, The Boolean type parameter in the callback function indicates whether the transaction was submitted successfully.

Note: The callback only indicates the result of the 'commit' command, which is the last step of the transaction. If the transaction has been automatically or manually rolled back, the callback will never be executed. You can also use the setCommitCallback() method of a transaction object to set the callback.; A TimeoutError exception is thrown if the operation is timed out.

◆ newTransactionAsync() [1/2]

virtual void drogon::orm::DbClient::newTransactionAsync	(	const std::function< void(const std::shared_ptr< Transaction > &)> &	callback,
		TransactionType	transType = TransactionType::Deferred )

pure virtual

Create a transaction object in asynchronous mode.

Note: An empty shared_ptr object is returned via the callback if the operation is timed out.

◆ newTransactionAsync() [2/2]

void drogon::orm::DbClient::newTransactionAsync	(	TransactionType	transType,
		const std::function< void(const std::shared_ptr< Transaction > &)> &	callback )

inline

Convenience overload: create an async transaction with a specific locking mode, with transType as the first argument.

◆ operator<<()

internal::SqlBinder drogon::orm::DbClient::operator<< ( const std::string & sql )

Streaming-like method for sql execution. For more information, see the wiki page.

◆ setTimeout()

virtual void drogon::orm::DbClient::setTimeout ( double timeout )

pure virtual

Set the Timeout value of execution of a SQL.

Parameters

timeout in seconds, if the SQL result is not returned from the server within the timeout, a TimeoutError exception with "SQL execution timeout" string is generated and returned to the caller.

Note: set the timeout value to zero or negative for no limit on time. The default value is -1.0, this means there is no time limit if this method is not called.

The documentation for this class was generated from the following file:

orm_lib/inc/drogon/orm/DbClient.h

Public Member Functions

Static Public Member Functions

Protected Attributes

Detailed Description

Member Function Documentation

◆ closeAll()

◆ execSqlAsync()

◆ hasAvailableConnections()

◆ newPgClient()

◆ newTransaction()

◆ newTransactionAsync() [1/2]

◆ newTransactionAsync() [2/2]

◆ operator<<()

◆ setTimeout()