CopperSpice API  1.9.1
QSqlDriver Class Referenceabstract

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

Inheritance diagram for QSqlDriver:
QObject

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 QSqlResultcreateResult () 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< QStringdynamicPropertyNames () const
 
virtual bool event (QEvent *event)
 
virtual bool eventFilter (QObject *watched, QEvent *event)
 
template<typename 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 QMetaObjectmetaObject () const
 
void moveToThread (QThread *targetThread)
 
QString objectName () const
 
QObject * parent () const
 
template<class T = QVariant>
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)
 
QThreadthread () 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 QMetaObjectstaticMetaObject ()
 
static QString tr (const char *text, const char *comment=nullptr, std::optional< int > numArg=std::optional< int >())
 
- Properties inherited from QObject
 objectName
 

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

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

ConstantValueDescription
QSqlDriver::Transactions0Whether the driver supports SQL transactions.
QSqlDriver::QuerySize1Whether 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::BLOB2Whether the driver supports Binary Large Object fields.
QSqlDriver::Unicode3Whether the driver supports Unicode strings if the database server does.
QSqlDriver::PreparedQueries4Whether the driver supports prepared query execution.
QSqlDriver::NamedPlaceholders5Whether the driver supports the use of named placeholders.
QSqlDriver::PositionalPlaceholders6Whether the driver supports the use of positional placeholders.
QSqlDriver::LastInsertId7Whether the driver supports returning the Id of the last touched row.
QSqlDriver::BatchOperations8Whether the driver supports batched operations, see QSqlQuery::execBatch()
QSqlDriver::SimpleLocking9Whether the driver disallows a write lock on a table while other queries have a read lock on it.
QSqlDriver::LowPrecisionNumbers10Whether the driver allows fetching numerical values with low precision.
QSqlDriver::EventNotifications11Whether the driver supports database event notifications.
QSqlDriver::FinishQuery12Whether the driver can do any low-level resource cleanup when QSqlQuery::finish() is called.
QSqlDriver::MultipleResultSets13Whether 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()

This enum contains a list of SQL identifier types.

ConstantValueDescription
QSqlDriver::FieldName0A SQL field name
QSqlDriver::TableName1A SQL table name

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

ConstantValueDescription
QSqlDriver::WhereStatement0An SQL WHERE statement (e.g., WHERE f = 5).
QSqlDriver::SelectStatement1An SQL SELECT statement (e.g., SELECT f FROM t).
QSqlDriver::UpdateStatement2An SQL UPDATE statement (e.g., UPDATE TABLE t set f = 1).
QSqlDriver::InsertStatement3An SQL INSERT statement (e.g., INSERT INTO t (f) values (1)).
QSqlDriver::DeleteStatement4An 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
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()