Abstract base class for an SQL connection. More...

#include <Wt/Dbo/SqlConnection.h>

Inheritance diagram for Wt::Dbo::SqlConnection:

Public Member Functions
virtual	~SqlConnection ()
	Destructor.

virtual std::unique_ptr< SqlConnection >	clone () const =0
	Clones the connection.

virtual void	executeSql (const std::string &sql)
	Executes an SQL statement.

virtual void	executeSqlStateful (const std::string &sql)
	Executes a connection-stateful SQL statement.

virtual void	startTransaction ()=0
	Starts a transaction.

virtual void	commitTransaction ()=0
	Commits a transaction.

virtual void	rollbackTransaction ()=0
	Rolls back a transaction.

virtual SqlStatement *	getStatement (const std::string &id) const
	Returns the statement with the given id.

virtual void	saveStatement (const std::string &id, std::unique_ptr< SqlStatement > statement)
	Saves a statement with the given id.

virtual std::unique_ptr< SqlStatement >	prepareStatement (const std::string &sql)=0
	Prepares a statement.

void	setProperty (const std::string &name, const std::string &value)
	Sets a property.

std::string	property (const std::string &name) const
	Returns a property.

Methods that return dialect information
virtual std::string	autoincrementSql () const =0
	Returns the 'autoincrement' SQL type modifier.

virtual std::vector< std::string >	autoincrementCreateSequenceSql (const std::string &table, const std::string &id) const =0
	Returns the SQL statement(s) required to create an id sequence.

virtual std::vector< std::string >	autoincrementDropSequenceSql (const std::string &table, const std::string &id) const =0
	Returns the SQL statement(s) required to drop an id sequence.

virtual std::string	autoincrementType () const =0
	Returns the 'autoincrement' SQL type.

virtual std::string	autoincrementInsertInfix (const std::string &id) const
	Returns the infix for an 'autoincrement' insert statement.

virtual std::string	autoincrementInsertSuffix (const std::string &id) const =0
	Returns the suffix for an 'autoincrement' insert statement.

virtual void	prepareForDropTables ()
	Execute code before dropping the tables.

virtual const char *	dateTimeType (SqlDateTimeType type) const =0
	Returns the date/time type.

virtual const char *	blobType () const =0
	Returns the blob type.

virtual std::string	textType (int size) const
	Returns the text type.

virtual std::string	longLongType () const
	Returns the 64-bit integer type.

virtual const char *	booleanType () const
	Returns the boolean type.

virtual bool	supportUpdateCascade () const
	Returns true if the database supports Update Cascade.

virtual bool	requireSubqueryAlias () const
	Returns the true if the database require subquery alias.

virtual bool	usesRowsFromTo () const
	Returns whether the SQL dialect uses 'ROWS ? TO ?', limit or rownum for partial select results.

virtual bool	supportAlterTable () const
	Returns true if the backend support Alter Table.

virtual bool	supportDeferrableFKConstraint () const
	Returns true if the backend supports "deferrable initially deferred" foreign key constraints.

virtual const char *	alterTableConstraintString () const
	Returns the command used in alter table .. drop constraint ..

Protected Member Functions
virtual void	subscribe (const std::string &channel)
	Subscibe to a channel for notification.

virtual void	notify (const std::string &channel, const std::string &message)
	Send a notification on the channel.

virtual std::pair< std::string, std::string >	getNextNotify ()
	Returns the next notification recieved.

virtual void	setupNotify ()
	Setup the SqlConnection for notifications handleing.

virtual void	stopListen ()
	Stop listening for notifications.

Detailed Description

Abstract base class for an SQL connection.

An sql connection manages a single connection to a database. It also manages a map of previously prepared statements indexed by id's.

This class is part of Wt::Dbo's backend API, and should not be used directly.

All methods will throw an exception if they could not be completed.

Member Function Documentation

◆ alterTableConstraintString()

const char * Wt::Dbo::SqlConnection::alterTableConstraintString ( ) const

virtual

Returns the command used in alter table .. drop constraint ..

This method will return "constraint" by default. Default: ALTER TABLE .. DROP CONSTRAINT ..

Reimplemented in Wt::Dbo::backend::MySQL.

◆ autoincrementCreateSequenceSql()

virtual std::vector< std::string > Wt::Dbo::SqlConnection::autoincrementCreateSequenceSql	(	const std::string &	table,
		const std::string &	id
	)		const

pure virtual

Returns the SQL statement(s) required to create an id sequence.

This is used by Session::createTables() to create the id sequence for a table. The table's name and primary key are passed as arguments to this function and can be used to construct an SQL sequence that is unique for the table.

Implemented in Wt::Dbo::backend::Firebird, Wt::Dbo::backend::MSSQLServer, Wt::Dbo::backend::MySQL, Wt::Dbo::backend::Postgres, and Wt::Dbo::backend::Sqlite3.

◆ autoincrementDropSequenceSql()

virtual std::vector< std::string > Wt::Dbo::SqlConnection::autoincrementDropSequenceSql	(	const std::string &	table,
		const std::string &	id
	)		const

pure virtual

Returns the SQL statement(s) required to drop an id sequence.

This is used by Session::dropTables() to drop the id sequence for a table. The table's name and primary key are passed as arguments to this function and can be used to construct an SQL sequence that is unique for the table.

Implemented in Wt::Dbo::backend::Firebird, Wt::Dbo::backend::MSSQLServer, Wt::Dbo::backend::MySQL, Wt::Dbo::backend::Postgres, and Wt::Dbo::backend::Sqlite3.

◆ autoincrementInsertInfix()

std::string Wt::Dbo::SqlConnection::autoincrementInsertInfix ( const std::string & id ) const

virtual

Returns the infix for an 'autoincrement' insert statement.

This is inserted before the values part of the insert statement, since Microsoft SQL Server requires that the autoincrement id is returned with OUTPUT.

Returns an empty string by default.

Reimplemented in Wt::Dbo::backend::MSSQLServer.

◆ autoincrementInsertSuffix()

virtual std::string Wt::Dbo::SqlConnection::autoincrementInsertSuffix ( const std::string & id ) const

pure virtual

Returns the suffix for an 'autoincrement' insert statement.

This is appended to the insert statement, since some back-ends need to be indicated that they should return the autoincrement id.

Implemented in Wt::Dbo::backend::Firebird, Wt::Dbo::backend::MSSQLServer, Wt::Dbo::backend::MySQL, Wt::Dbo::backend::Postgres, and Wt::Dbo::backend::Sqlite3.

◆ autoincrementSql()

virtual std::string Wt::Dbo::SqlConnection::autoincrementSql ( ) const

pure virtual

Returns the 'autoincrement' SQL type modifier.

This is used by Session::createTables() to create the id column.

Implemented in Wt::Dbo::backend::Firebird, Wt::Dbo::backend::MSSQLServer, Wt::Dbo::backend::MySQL, Wt::Dbo::backend::Postgres, and Wt::Dbo::backend::Sqlite3.

◆ autoincrementType()

virtual std::string Wt::Dbo::SqlConnection::autoincrementType ( ) const

pure virtual

Returns the 'autoincrement' SQL type.

This is used by Session::createTables() to create the id column.

Implemented in Wt::Dbo::backend::Firebird, Wt::Dbo::backend::MSSQLServer, Wt::Dbo::backend::MySQL, Wt::Dbo::backend::Postgres, and Wt::Dbo::backend::Sqlite3.

◆ blobType()

virtual const char * Wt::Dbo::SqlConnection::blobType ( ) const

pure virtual

Returns the blob type.

See also: SqlStatement::bind(int, const std::vector<unsigned char>&)

Implemented in Wt::Dbo::backend::Firebird, Wt::Dbo::backend::MSSQLServer, Wt::Dbo::backend::MySQL, Wt::Dbo::backend::Postgres, and Wt::Dbo::backend::Sqlite3.

◆ booleanType()

const char * Wt::Dbo::SqlConnection::booleanType ( ) const

virtual

Returns the boolean type.

This method will return "boolean" by default.

Reimplemented in Wt::Dbo::backend::Firebird, and Wt::Dbo::backend::MSSQLServer.

◆ clone()

virtual std::unique_ptr< SqlConnection > Wt::Dbo::SqlConnection::clone ( ) const

pure virtual

Clones the connection.

Returns a new connection object that is configured like this object. This is used by connection pool implementations to create its connections.

Implemented in Wt::Dbo::backend::Firebird, Wt::Dbo::backend::MSSQLServer, Wt::Dbo::backend::MySQL, Wt::Dbo::backend::Postgres, and Wt::Dbo::backend::Sqlite3.

◆ commitTransaction()

virtual void Wt::Dbo::SqlConnection::commitTransaction ( )

pure virtual

Commits a transaction.

This function commits a transaction.

Implemented in Wt::Dbo::backend::Firebird, Wt::Dbo::backend::MSSQLServer, Wt::Dbo::backend::MySQL, Wt::Dbo::backend::Postgres, and Wt::Dbo::backend::Sqlite3.

◆ dateTimeType()

virtual const char * Wt::Dbo::SqlConnection::dateTimeType ( SqlDateTimeType type ) const

pure virtual

Returns the date/time type.

See also: SqlStatement::bind(int, const std::chrono::system_clock::time_point&, SqlDateTimeType)

Implemented in Wt::Dbo::backend::Firebird, Wt::Dbo::backend::MSSQLServer, Wt::Dbo::backend::MySQL, Wt::Dbo::backend::Postgres, and Wt::Dbo::backend::Sqlite3.

◆ executeSql()

void Wt::Dbo::SqlConnection::executeSql ( const std::string & sql )

virtual

Executes an SQL statement.

This is a convenience method for preparing a statement, executing it, and deleting it.

Reimplemented in Wt::Dbo::backend::MSSQLServer, Wt::Dbo::backend::MySQL, and Wt::Dbo::backend::Postgres.

◆ executeSqlStateful()

void Wt::Dbo::SqlConnection::executeSqlStateful ( const std::string & sql )

virtual

Executes a connection-stateful SQL statement.

This executes a statement, but also remembers the statement for when the native connection would be closed and reopened during the lifetime of this connection object. Then the statements are redone on the newly opened connection.

Such statements could be for example 'LISTEN' in a postgresql connection.

Note: These statements are only executed upon a reconnect for those backends that support automatic reconnect, but not when a connection is cloned.

◆ getNextNotify()

std::pair< std::string, std::string > Wt::Dbo::SqlConnection::getNextNotify ( )

protectedvirtual

Returns the next notification recieved.

This function listen for notification until a notification is recieved or until the stopListen() function is called.

If a notification was recieved, returns a pair with the first element being the name of the channel and the second element being the payload. In case stopListen() was called before recieving a notification, returns a pair of empty strings.

Warning: This function is currently only implemented for Postgres database and will throw an exeption if not used with Postgres. If you wish to use notification with another database, you should override this function and every other function used by Dbo::NotificationListener .; This function is used inside of a thread must take into account that notify() and subscribe() may be called while this function is running.

See also: stopListen(), subscribe(), notify()

Reimplemented in Wt::Dbo::backend::Postgres.

◆ getStatement()

SqlStatement * Wt::Dbo::SqlConnection::getStatement ( const std::string & id ) const

virtual

Returns the statement with the given id.

Returns nullptr if no such statement was already added.

See also: saveStatement()

◆ longLongType()

std::string Wt::Dbo::SqlConnection::longLongType ( ) const

virtual

Returns the 64-bit integer type.

This method will return "bigint" by default.

◆ notify()

void Wt::Dbo::SqlConnection::notify	(	const std::string &	channel,
		const std::string &	message
	)

protectedvirtual

Send a notification on the channel.

This function send a notifictation on the channel with the message as payload. This notification will be recieved by all connection that subscribed to the channel trough getNextNotify().

Warning: This function is currently only implemented for Postgres database and will throw an exeption if not used with Postgres. If you wish to use notification with another database, you should override this function and every other function used by Dbo::NotificationListener .

See also: subscribe(), getNextNotify()

Reimplemented in Wt::Dbo::backend::Postgres.

◆ prepareForDropTables()

void Wt::Dbo::SqlConnection::prepareForDropTables ( )

virtual

Execute code before dropping the tables.

This method is called before calling Session::dropTables(). The default implementation is empty.

Reimplemented in Wt::Dbo::backend::Firebird.

◆ prepareStatement()

virtual std::unique_ptr< SqlStatement > Wt::Dbo::SqlConnection::prepareStatement ( const std::string & sql )

pure virtual

Prepares a statement.

Returns the prepared statement.

Implemented in Wt::Dbo::backend::Firebird, Wt::Dbo::backend::MSSQLServer, Wt::Dbo::backend::MySQL, Wt::Dbo::backend::Postgres, and Wt::Dbo::backend::Sqlite3.

◆ property()

std::string Wt::Dbo::SqlConnection::property ( const std::string & name ) const

Returns a property.

Returns the property value, or an empty string if the property was not set.

See also: setProperty()

◆ requireSubqueryAlias()

bool Wt::Dbo::SqlConnection::requireSubqueryAlias ( ) const

virtual

Returns the true if the database require subquery alias.

This method will return false by default.

Reimplemented in Wt::Dbo::backend::MSSQLServer, Wt::Dbo::backend::MySQL, and Wt::Dbo::backend::Postgres.

◆ rollbackTransaction()

virtual void Wt::Dbo::SqlConnection::rollbackTransaction ( )

pure virtual

Rolls back a transaction.

This function rolls back a transaction.

Implemented in Wt::Dbo::backend::Firebird, Wt::Dbo::backend::MSSQLServer, Wt::Dbo::backend::MySQL, Wt::Dbo::backend::Postgres, and Wt::Dbo::backend::Sqlite3.

◆ saveStatement()

void Wt::Dbo::SqlConnection::saveStatement	(	const std::string &	id,
		std::unique_ptr< SqlStatement >	statement
	)

virtual

Saves a statement with the given id.

Saves the statement for future reuse using getStatement()

◆ setProperty()

void Wt::Dbo::SqlConnection::setProperty	(	const std::string &	name,
		const std::string &	value
	)

Sets a property.

Properties may tailor the backend behavior. Some properties are applicable to all backends, while some are backend specific.

General properties are:

show-queries: when value is "true", queries are shown as they are executed.

◆ setupNotify()

void Wt::Dbo::SqlConnection::setupNotify ( )

protectedvirtual

Setup the SqlConnection for notifications handleing.

This function setups everything needed to handle notification. It is called by Dbo::NotificationListener before starting the thread that will repetitively call getNextNotify() .

Warning: This function is currently only implemented for Postgres database and will throw an exeption if not used with Postgres. If you wish to use notification with another database, you should override this function and every other function used by Dbo::NotificationListener .

See also: getNextNotify()

Reimplemented in Wt::Dbo::backend::Postgres.

◆ startTransaction()

virtual void Wt::Dbo::SqlConnection::startTransaction ( )

pure virtual

Starts a transaction.

This function starts a transaction.

Implemented in Wt::Dbo::backend::Firebird, Wt::Dbo::backend::MSSQLServer, Wt::Dbo::backend::MySQL, Wt::Dbo::backend::Postgres, and Wt::Dbo::backend::Sqlite3.

◆ stopListen()

void Wt::Dbo::SqlConnection::stopListen ( )

protectedvirtual

Stop listening for notifications.

This function stops getNextNotify() from listening for notifications.

Warning: This function is currently only implemented for Postgres database and will throw an exeption if not used with Postgres. If you wish to use notification with another database, you should override this function and every other function used by Dbo::NotificationListener .

See also: getNextNotify()

Reimplemented in Wt::Dbo::backend::Postgres.

◆ subscribe()

void Wt::Dbo::SqlConnection::subscribe ( const std::string & channel )

protectedvirtual

Subscibe to a channel for notification.

This function does what is needed to receive the notifications sent on the given channel from the database.

Warning: This function is currently only implemented for Postgres database and will throw an exeption if not used with Postgres. If you wish to use notification with another database, you should override this function and every other function used by Dbo::NotificationListener .

See also: getNextNotify(), notify()

Reimplemented in Wt::Dbo::backend::Postgres.

◆ supportAlterTable()

bool Wt::Dbo::SqlConnection::supportAlterTable ( ) const

virtual

Returns true if the backend support Alter Table.

This method will return false by default.

Reimplemented in Wt::Dbo::backend::Firebird, Wt::Dbo::backend::MSSQLServer, Wt::Dbo::backend::MySQL, and Wt::Dbo::backend::Postgres.

◆ supportDeferrableFKConstraint()

bool Wt::Dbo::SqlConnection::supportDeferrableFKConstraint ( ) const

virtual

Returns true if the backend supports "deferrable initially deferred" foreign key constraints.

This method will return false by default.

Reimplemented in Wt::Dbo::backend::Postgres, and Wt::Dbo::backend::Sqlite3.

◆ supportUpdateCascade()

bool Wt::Dbo::SqlConnection::supportUpdateCascade ( ) const

virtual

Returns true if the database supports Update Cascade.

This method will return true by default. Was created for the oracle database which does not support Update Cascade.

◆ textType()

std::string Wt::Dbo::SqlConnection::textType ( int size ) const

virtual

Returns the text type.

This is the text type for a string. If size = -1, then a type should be returned which does not require size information, otherwise a type should be returned that limits the size of the stored string to size.

This method will return "text" by default if size = -1, and "varchar(size)" otherwise.

See also: SqlStatement::bind(int column, const std::string& value)

Reimplemented in Wt::Dbo::backend::Firebird, and Wt::Dbo::backend::MSSQLServer.

◆ usesRowsFromTo()

bool Wt::Dbo::SqlConnection::usesRowsFromTo ( ) const

virtual

Returns whether the SQL dialect uses 'ROWS ? TO ?', limit or rownum for partial select results.

This is an alternative SQL dialect option to the (non-standard) 'OFFSET ? LIMIT ?' syntax.

The default implementation returns LimitQuery::Limit.

Reimplemented in Wt::Dbo::backend::Firebird.

Public Member Functions

Protected Member Functions

Detailed Description

Member Function Documentation

◆ alterTableConstraintString()

◆ autoincrementCreateSequenceSql()

◆ autoincrementDropSequenceSql()

◆ autoincrementInsertInfix()

◆ autoincrementInsertSuffix()

◆ autoincrementSql()

◆ autoincrementType()

◆ blobType()

◆ booleanType()

◆ clone()

◆ commitTransaction()

◆ dateTimeType()

◆ executeSql()

◆ executeSqlStateful()

◆ getNextNotify()

◆ getStatement()

◆ longLongType()

◆ notify()

◆ prepareForDropTables()

◆ prepareStatement()

◆ property()

◆ requireSubqueryAlias()

◆ rollbackTransaction()

◆ saveStatement()

◆ setProperty()

◆ setupNotify()

◆ startTransaction()

◆ stopListen()

◆ subscribe()

◆ supportAlterTable()

◆ supportDeferrableFKConstraint()

◆ supportUpdateCascade()

◆ textType()

◆ usesRowsFromTo()