Abstract base class for accessing SQL databases. More...

Inheritance diagram for QSqlDriver:

Public Types
enum	DriverFeature

enum	IdentifierType

enum	StatementType

Public Signals
void	notification (const QString &name, QSqlDriver::NotificationSource source, const QVariant &payload)

Public Signals inherited from QObject
void	destroyed (QObject *obj=nullptr)

void	objectNameChanged (const QString &objectName)

Public Methods
	QSqlDriver (QObject *parent=nullptr)

	~QSqlDriver ()

virtual bool	beginTransaction ()

virtual void	close () = 0

virtual bool	commitTransaction ()

virtual QSqlResult *	createResult () const = 0

virtual QString	escapeIdentifier (const QString &identifier, IdentifierType type) const

virtual QString	formatValue (const QSqlField &field, bool trimStrings=false) const

virtual QVariant	handle () const

virtual bool	hasFeature (DriverFeature feature) const = 0

virtual bool	isIdentifierEscaped (const QString &identifier, IdentifierType type) const

virtual bool	isOpen () const

bool	isOpenError () const

QSqlError	lastError () const

QSql::NumericalPrecisionPolicy	numericalPrecisionPolicy () const

virtual bool	open (const QString &db, const QString &user=QString (), const QString &password=QString (), const QString &host=QString (), int port=-1, const QString &options=QString ()) = 0

virtual QSqlIndex	primaryIndex (const QString &tableName) const

virtual QSqlRecord	record (const QString &tableName) const

virtual bool	rollbackTransaction ()

void	setNumericalPrecisionPolicy (QSql::NumericalPrecisionPolicy precisionPolicy)

virtual QString	sqlStatement (StatementType type, const QString &tableName, const QSqlRecord &rec, bool preparedStatement) const

virtual QString	stripDelimiters (const QString &identifier, IdentifierType type) const

virtual QStringList	subscribedToNotifications () const

virtual bool	subscribeToNotification (const QString &name)

virtual QStringList	tables (QSql::TableType tableType) const

virtual bool	unsubscribeFromNotification (const QString &name)

Public Methods inherited from QObject
	QObject (QObject *parent=nullptr)

	~QObject ()

bool	blockSignals (bool block)

const QList< QObject * > &	children () const

bool	connect (const QObject *sender, const QString &signalMethod, const QString &location, const QString &slotMethod, Qt::ConnectionType type=Qt::AutoConnection)

bool	connect (const QObject *sender, const QString &signalMethod, const QString &slotMethod, Qt::ConnectionType type=Qt::AutoConnection)

bool	disconnect (const QObject *receiver, const QString &slotMethod=QString ()) const

bool	disconnect (const QString &signalMethod, const QString &location, const QObject *receiver=nullptr, const QString &slotMethod=QString ()) const

bool	disconnect (const QString &signalMethod=QString (), const QObject *receiver=nullptr, const QString &slotMethod=QString ()) const

void	dumpObjectInfo ()

void	dumpObjectTree ()

QList< QString >	dynamicPropertyNames () const

virtual bool	event (QEvent *event)

virtual bool	eventFilter (QObject watched, QEvent event)

template<typename T >
T	findChild (const QString &childName=QString ()) const

template<class T >
QList< T >	findChildren (const QRegularExpression &regExp, Qt::FindChildOptions options=Qt::FindChildrenRecursively) const

template<class T >
QList< T >	findChildren (const QString &childName=QString (), Qt::FindChildOptions options=Qt::FindChildrenRecursively) const

bool	inherits (const QString &className) const

void	installEventFilter (QObject *filterObj)

bool	isWidgetType () const

bool	isWindowType () const

void	killTimer (int id)

const QMetaObject *	metaObject () const

void	moveToThread (QThread *targetThread)

QString	objectName () const

QObject *	parent () const

template<class T = QVariant>
T	property (const QString &name) const

void	removeEventFilter (QObject *obj)

void	setObjectName (const QString &name)

void	setParent (QObject *parent)

bool	setProperty (const QString &name, const QVariant &value)

bool	signalsBlocked () const

int	startTimer (int interval, Qt::TimerType timerType=Qt::CoarseTimer)

QThread *	thread () const

Protected Methods
virtual void	setLastError (const QSqlError &error)

virtual void	setOpen (bool open)

virtual void	setOpenError (bool error)

Protected Methods inherited from QObject
virtual void	childEvent (QChildEvent *event)

virtual void	connectNotify (const QMetaMethod &signalMethod) const

virtual void	customEvent (QEvent *event)

virtual void	disconnectNotify (const QMetaMethod &signalMethod) const

bool	isSignalConnected (const QMetaMethod &signalMethod) const

int	receivers (const QString &signal) const

QObject *	sender () const

int	senderSignalIndex () const

virtual void	timerEvent (QTimerEvent *event)

Friends
class	QSqlDatabase

Additional Inherited Members
Public Slots inherited from QObject
void	deleteLater ()

Static Public Methods inherited from QObject
static bool	connect (const QObject sender, const QMetaMethod &signalMethod, const QObject receiver, const QMetaMethod &slotMethod, Qt::ConnectionType type=Qt::AutoConnection)

static bool	connect (const QObject sender, const QString &signalMethod, const QObject receiver, const QString &slotMethod, Qt::ConnectionType type=Qt::AutoConnection, const QString &location=QString ())

static bool	connect (const QObject sender, const QString &signalMethod, const QString &location, const QObject receiver, const QString &slotMethod, Qt::ConnectionType type=Qt::AutoConnection)

template<class Sender , class SignalClass , class... SignalArgs, class Receiver , class SlotClass , class... SlotArgs, class SlotReturn >
static bool	connect (const Sender sender, void (SignalClass::signalMethod)(SignalArgs...), const Receiver receiver, SlotReturn (SlotClass::slotMethod)(SlotArgs...), Qt::ConnectionType type=Qt::AutoConnection)

template<class Sender , class SignalClass , class... SignalArgs, class Receiver , class T >
static bool	connect (const Sender sender, void (SignalClass::signalMethod)(SignalArgs...), const Receiver *receiver, T slotLambda, Qt::ConnectionType type=Qt::AutoConnection)

static bool	disconnect (const QObject sender, const QMetaMethod &signalMethod, const QObject receiver, const QMetaMethod &slotMethod)

static bool	disconnect (const QObject sender, const QString &signalMethod, const QObject receiver, const QString &slotMethod)

static bool	disconnect (const QObject sender, const QString &signalMethod, const QString &location, const QObject receiver, const QString &slotMethod)

static bool	disconnect (const QObject sender, std::nullptr_t, const QObject receiver, std::nullptr_t)

template<class Sender , class SignalClass , class... SignalArgs, class Receiver , class SlotClass , class... SlotArgs, class SlotReturn >
static bool	disconnect (const Sender sender, void (SignalClass::signalMethod)(SignalArgs...), const Receiver receiver, SlotReturn (SlotClass::slotMethod)(SlotArgs...))

template<class Sender , class SignalClass , class... SignalArgs, class Receiver >
static bool	disconnect (const Sender sender, void (SignalClass::signalMethod)(SignalArgs...), const Receiver *receiver, std::nullptr_t slotMethod=nullptr)

template<class Sender , class SignalClass , class... SignalArgs, class Receiver , class T >
static bool	disconnect (const Sender sender, void (SignalClass::signalMethod)(SignalArgs...), const Receiver *receiver, T slotMethod)

static QMetaObject &	staticMetaObject ()

static QString	tr (const char text, const char comment=nullptr, std::optional< int > numArg=std::optional< int >())

Properties inherited from QObject
	objectName

Related Functions inherited from QObject
T	qobject_cast (QObject *object)

	QObjectList

Detailed Description

The QSqlDriver class is an abstract base class used for accessing SQL databases. This class should not be used directly, use QSqlDatabase instead. If you want to create your own SQL drivers, inherit from QSqlDriver and override the pure virtual methods which you need.

See also: QSqlDatabase, QSqlResult

Member Enumeration Documentation

enum QSqlDriver::DriverFeature

This enum contains a list of features a driver might support. Use hasFeature() to query whether a feature is supported or not.

Constant	Value	Description
`QSqlDriver::Transactions`	`0`	Whether the driver supports SQL transactions.
`QSqlDriver::QuerySize`	`1`	Whether the database is capable of reporting the size of a query. Some databases do not support returning the size (i.e. number of rows returned) of a query, in which case QSqlQuery::size() will return -1.
`QSqlDriver::BLOB`	`2`	Whether the driver supports Binary Large Object fields.
`QSqlDriver::Unicode`	`3`	Whether the driver supports Unicode strings if the database server does.
`QSqlDriver::PreparedQueries`	`4`	Whether the driver supports prepared query execution.
`QSqlDriver::NamedPlaceholders`	`5`	Whether the driver supports the use of named placeholders.
`QSqlDriver::PositionalPlaceholders`	`6`	Whether the driver supports the use of positional placeholders.
`QSqlDriver::LastInsertId`	`7`	Whether the driver supports returning the Id of the last touched row.
`QSqlDriver::BatchOperations`	`8`	Whether the driver supports batched operations, see QSqlQuery::execBatch()
`QSqlDriver::SimpleLocking`	`9`	Whether the driver disallows a write lock on a table while other queries have a read lock on it.
`QSqlDriver::LowPrecisionNumbers`	`10`	Whether the driver allows fetching numerical values with low precision.
`QSqlDriver::EventNotifications`	`11`	Whether the driver supports database event notifications.
`QSqlDriver::FinishQuery`	`12`	Whether the driver can do any low-level resource cleanup when QSqlQuery::finish() is called.
`QSqlDriver::MultipleResultSets`	`13`	Whether the driver can access multiple result sets returned from batched statements or stored procedures.

Refer to SQL Drivers documentation for more information about SQL Driver features.

See also: hasFeature()

enum QSqlDriver::IdentifierType

This enum contains a list of SQL identifier types.

Constant	Value	Description
`QSqlDriver::FieldName`	`0`	A SQL field name
`QSqlDriver::TableName`	`1`	A SQL table name

enum QSqlDriver::StatementType

This enum contains a list of SQL statement (or clause) types the driver can create.

Constant	Value	Description
`QSqlDriver::WhereStatement`	`0`	An SQL `WHERE` statement (e.g., `WHERE f = 5`).
`QSqlDriver::SelectStatement`	`1`	An SQL `SELECT` statement (e.g., `SELECT f FROM t`).
`QSqlDriver::UpdateStatement`	`2`	An SQL `UPDATE` statement (e.g., `UPDATE TABLE t set f = 1`).
`QSqlDriver::InsertStatement`	`3`	An SQL `INSERT` statement (e.g., `INSERT INTO t (f) values (1)`).
`QSqlDriver::DeleteStatement`	`4`	An SQL `DELETE` statement (e.g., `DELETE FROM t`).

See also: sqlStatement()

Constructor & Destructor Documentation

QSqlDriver::QSqlDriver ( QObject * parent = nullptr )

explicit

Constructs a new driver with the given parent.

QSqlDriver::~QSqlDriver ( )

Destroys the QSqlDriver and frees any allocated resources.

Method Documentation

bool QSqlDriver::beginTransaction ( )

virtual

This method called to begin a transaction. Returns true if successful, otherwise false is returned. The default implementation does nothing and returns false.

See also: commitTransaction(), rollbackTransaction()

void QSqlDriver::close ( )

pure virtual

Inherited classes must override this method in order to close the database connection. Returns true if successful, otherwise false is returned.

See also: open(), setOpen()

bool QSqlDriver::commitTransaction ( )

virtual

This method is called to commit a transaction. Returns true if successful, otherwise false is returned. The default implementation does nothing and returns false.

See also: beginTransaction(), rollbackTransaction()

QSqlResult * QSqlDriver::createResult ( ) const

pure virtual

Creates an empty SQL result on the database. Inherited classes must override this method and return a QSqlResult object which is appropriate for their database to the caller.

QString QSqlDriver::escapeIdentifier	(	const QString &	identifier,
		IdentifierType	type
	)		const

virtual

Returns the identifier escaped according to the database rules. The given identifier can either be a table name or field name, dependent on type. The default implementation does nothing.

See also: isIdentifierEscaped()

QString QSqlDriver::formatValue	(	const QSqlField &	field,
		bool	trimStrings = `false`
	)		const

virtual

Returns a string representation of the field value for the database. This is used, for example, when constructing INSERT and UPDATE statements. The default implementation returns the value formatted as a string according to the following rules.

If field is character data, the value is returned enclosed in single quotation marks, which is appropriate for many SQL databases. Any embedded single-quote characters are escaped (replaced with two single-quote characters). If trimStrings is true, all trailing whitespace is trimmed from the field.
If field is date/time data, the value is formatted in ISO format and enclosed in single quotation marks. If the date/time data is invalid, "NULL" is returned.
If field is bytearray data, and the driver can edit binary fields, the value is formatted as a hexadecimal string.
For any other field type, toString() is called on its value and the result of this is returned.

See also: QVariant::toString()

QVariant QSqlDriver::handle ( ) const

virtual

Returns the low level database handle wrapped in a QVariant or an invalid variant if there is no handle. The handle can become a stale pointer if the connection is modified. For example, if you close the connection it might become invalid. The handle might be a nullptr if the connection has not been opened.

The following example retrieves the handle for a connection to an sqlite database. The handle is database dependent.

QSqlDatabase db = ...;
QVariant v = db.driver()->handle();
 
if (v.canConvert<sqlite3 *>()) {
   sqlite3 *handle = v.value<sqlite3 *>();
 
   if (handle != nullptr) {
      // use the database
   }
}

This sample code shows how to retrieve the handle for PostgreSQL or MySQL.

if (v.canConvert<PGconn *>()) {
   PGconn *handle = v.value<PGconn *>();
 
   if (handle != nullptr) {
      // use the database
   }
}
 
if (v.canConvert<MYSQL *>()) {
   MYSQL *handle = v.value<MYSQL *>();
 
   if (handle != nullptr) {
      // use the database
   }
}

See also: QSqlResult::handle()

bool QSqlDriver::hasFeature ( DriverFeature feature ) const

pure virtual

Returns true if the driver supports the given feature, otherwise returns false. Some databases need to call open() before this can be determined.

See also: DriverFeature

bool QSqlDriver::isIdentifierEscaped	(	const QString &	identifier,
		IdentifierType	type
	)		const

virtual

Returns whether identifier is escaped according to the database rules. The identifier can either be a table name or field name, dependent on type.

See also: stripDelimiters(), escapeIdentifier()

bool QSqlDriver::isOpen ( ) const

virtual

Returns true if the database connection is open, otherwise returns false.

bool QSqlDriver::isOpenError ( ) const

Returns true if the there was an error opening the database connection, otherwise returns false.

QSqlError QSqlDriver::lastError ( ) const

Returns a QSqlError object which contains information about the last error that occurred on the database.

See also: setLastError()

void QSqlDriver::notification	(	const QString &	name,
		QSqlDriver::NotificationSource	source,
		const QVariant &	payload
	)

signal

This signal is emitted when the database posts an event notification which the driver subscribes to. The name identifies the event notification, source indicates the signal source and payload holds the extra data which may be delivered with the notification.

See also: subscribeToNotification()

QSql::NumericalPrecisionPolicy QSqlDriver::numericalPrecisionPolicy ( ) const

Returns the current default precision policy for the database connection.

See also: QSql::NumericalPrecisionPolicy, setNumericalPrecisionPolicy(), QSqlQuery::numericalPrecisionPolicy(), QSqlQuery::setNumericalPrecisionPolicy()

bool QSqlDriver::open	(	const QString &	db,
		const QString &	user = `QString()`,
		const QString &	password = `QString()`,
		const QString &	host = `QString()`,
		int	port = `-1`,
		const QString &	options = `QString()`
	)

pure virtual

Inherited classes must override this method to open a connection for the database db with user and password. The other parameters indicate the host, port, and connection options. The method must return true on success and false on failure.

See also: setOpen()

QSqlIndex QSqlDriver::primaryIndex ( const QString & tableName ) const

virtual

Returns the primary index for table tableName. Returns an empty QSqlIndex if the table does not have a primary index. The default implementation returns an empty index.

QSqlRecord QSqlDriver::record ( const QString & tableName ) const

virtual

Returns a QSqlRecord populated with the names of the fields in table tableName. If no such table exists, an empty record is returned. The default implementation returns an empty record.

bool QSqlDriver::rollbackTransaction ( )

virtual

This method is called to rollback a transaction. If successful it will return true, otherwise false is returned. The default implementation does nothing and returns false.

See also: beginTransaction(), commitTransaction()

void QSqlDriver::setLastError ( const QSqlError & error )

protectedvirtual

This method is used to set the value of the last error, error, that occurred on the database.

See also: lastError()

void QSqlDriver::setNumericalPrecisionPolicy ( QSql::NumericalPrecisionPolicy precisionPolicy )

Sets the default numerical precision policy used by queries created by this driver to precisionPolicy. Setting the default precision policy does not affect any currently active queries.

See also: QSql::NumericalPrecisionPolicy, numericalPrecisionPolicy(), QSqlQuery::setNumericalPrecisionPolicy(), QSqlQuery::numericalPrecisionPolicy()

void QSqlDriver::setOpen ( bool open )

protectedvirtual

This method sets the open state of the database to open. Inherited classes can call this method to report the status of open().

See also: open(), setOpenError()

void QSqlDriver::setOpenError ( bool error )

protectedvirtual

This method sets the open error state of the database to error. Inherited classes can call this method to report the status of open(). If error is true the open state of the database is set to closed.

See also: isOpenError(), open(), setOpen()

QString QSqlDriver::sqlStatement	(	StatementType	type,
		const QString &	tableName,
		const QSqlRecord &	rec,
		bool	preparedStatement
	)		const

virtual

Returns an SQL statement of type for the given tableName with the values from rec. If preparedStatement is true, the string will contain placeholders instead of values. This method can be used to manipulate tables without having to worry about database-dependent SQL dialects. For non-prepared statements the values will be properly escaped.

QString QSqlDriver::stripDelimiters	(	const QString &	identifier,
		IdentifierType	type
	)		const

virtual

Returns the identifier with the leading and trailing delimiters removed, identifier can either be a table name or field name, dependent on type. If identifier does not have leading and trailing delimiter characters, identifier is returned without modification.

See also: isIdentifierEscaped()

QStringList QSqlDriver::subscribedToNotifications ( ) const

virtual

Returns a list of the names of the event notifications that are currently subscribed to.

See also: subscribeToNotification(), unsubscribeFromNotification()

bool QSqlDriver::subscribeToNotification ( const QString & name )

virtual

This method is called to subscribe to event notifications from the database. The name identifies the event notification. If successful returns true, otherwise returns false.

The database must be open when this function is called. When the database is closed by calling close() all subscribed event notifications are automatically unsubscribed. Calling open() on an already open database may implicitly cause close() to be called, which will cause the driver to unsubscribe from all event notifications.

When an event notification identified by name is posted by the database the notification() signal is emitted.

See also: unsubscribeFromNotification(), subscribedToNotifications(), QSqlDriver::hasFeature()

QStringList QSqlDriver::tables ( QSql::TableType tableType ) const

virtual

Returns a list of the names of the tables in the database. The default implementation returns an empty list.

The tableType argument describes what types of tables should be returned. Due to binary compatibility, the string contains the value of the enum QSql::TableTypes as text. An empty string should be treated as QSql::Tables for backward compatibility.

bool QSqlDriver::unsubscribeFromNotification ( const QString & name )

virtual

This method is called to unsubscribe from event notifications from the database. The name identifies the event notification. If successful returns true, otherwise returns false.

The database must be open when this function is called. All subscribed event notifications are automatically unsubscribed from when the close() function is called. After calling this function the notification() signal will no longer be emitted when an event notification identified by name is posted by the database.

See also: subscribeToNotification(), subscribedToNotifications()

Public Types

Public Signals

Public Methods

Protected Methods

Friends

Additional Inherited Members

Detailed Description

Member Enumeration Documentation

Constructor & Destructor Documentation

Method Documentation