QSqlDriver Class
The QSqlDriver class is an abstract base class for accessing specific SQL databases. More…
| Header | #include <QSqlDriver> |
|---|---|
| CMake | target_link_libraries(app PRIVATE Nt::Sql) |
| Module | Nt SQL C++ Classes |
| Inherits | QObject |
List of all members, including inherited members
Public Types
| enum | DriverFeature |
| enum | StatementType |
| enum | IdentifierType |
| enum | NotificationSource |
| enum | DbmsType |
Public Functions
| QSqlDriver(QObject *parent = nullptr) | |
| ~QSqlDriver() | |
| virtual bool | isOpen() const |
| bool | isOpenError() const |
| virtual bool | beginTransaction() |
| virtual bool | commitTransaction() |
| virtual bool | rollbackTransaction() |
| virtual QStringList | tables(QSql::TableType tableType) const |
| virtual QSqlIndex | primaryIndex(const QString &tableName) const |
| virtual QSqlRecord | record(const QString &tableName) const |
| virtual QString | formatValue(const QSqlField &field, bool trimStrings = false) const |
| virtual QString | escapeIdentifier(const QString &identifier, IdentifierType type) const |
| virtual QString | sqlStatement(StatementType type, const QString &tableName, const QSqlRecord &rec, bool preparedStatement) const |
| QSqlError | lastError() const |
| virtual QVariant | handle() const |
| virtual bool | hasFeature(DriverFeature f) const |
| virtual void | close() |
| virtual QSqlResult * | createResult() const |
| virtual bool | open(const QString &db, const QString &user = QString(), const QString &password = QString(), const QString &host = QString(), int port = -1, const QString &connOpts = QString()) |
| virtual bool | subscribeToNotification(const QString &name) |
| virtual bool | unsubscribeFromNotification(const QString &name) |
| virtual QStringList | subscribedToNotifications() const |
| virtual bool | isIdentifierEscaped(const QString &identifier, IdentifierType type) const |
| virtual QString | stripDelimiters(const QString &identifier, IdentifierType type) const |
| virtual int | maximumIdentifierLength(IdentifierType type) const |
| void | setNumericalPrecisionPolicy(QSql::NumericalPrecisionPolicy precisionPolicy) |
| QSql::NumericalPrecisionPolicy | numericalPrecisionPolicy() const |
| DbmsType | dbmsType() const |
Public Slots
| virtual bool | cancelQuery() |
Signals
| void | notification(const QString &name, QSqlDriver::NotificationSource source, const QVariant &payload) |
Protected Functions
| virtual void | setOpen(bool open) |
| virtual void | setOpenError(bool error) |
| virtual void | setLastError(const QSqlError &error) |
| void | setDbmsType(DbmsType type) |
Detailed Description
A driver connects Nt SQL to one kind of database. Applications use QSqlDatabase and QSqlQuery and rarely meet the driver; it is there to be subclassed, in order to add a database. A subclass implements open(), close(), hasFeature() and createResult(), together with a QSqlResult subclass that runs the statements, and usually tables(), record() and primaryIndex(). It is made available with QSqlDatabase::registerSqlDriver(), or handed to QSqlDatabase::addDatabase() directly.
The driver also writes the SQL of QSqlTableModel: sqlStatement() makes the statements, escapeIdentifier() quotes names and formatValue() writes values as literals.
See also QSqlDatabase and QSqlResult.
Differences from Qt
Drivers are compiled in or registered with QSqlDatabase::registerSqlDriver(); there are no driver plugins. The only driver that comes with Nt is QSQLITE.
Member Type Documentation
enum QSqlDriver::DbmsType
The database systems that a driver can be connected to.
| Constant | Description |
|---|---|
QSqlDriver::UnknownDbms | An unknown system. |
QSqlDriver::MSSqlServer | Microsoft SQL Server. |
QSqlDriver::MySqlServer | MySQL or MariaDB. |
QSqlDriver::PostgreSQL | PostgreSQL. |
QSqlDriver::Oracle | Oracle Database. |
QSqlDriver::Sybase | Sybase. |
QSqlDriver::SQLite | SQLite. |
QSqlDriver::Interbase | Interbase or Firebird. |
QSqlDriver::DB2 | IBM Db2. |
QSqlDriver::MimerSQL | Mimer SQL. |
enum QSqlDriver::DriverFeature
What a driver can do, as told by hasFeature().
| Constant | Description |
|---|---|
QSqlDriver::Transactions | The driver has transactions. |
QSqlDriver::QuerySize | The driver knows the number of rows of a query before fetching them. |
QSqlDriver::BLOB | The driver stores binary data. |
QSqlDriver::Unicode | The driver stores Unicode text. |
QSqlDriver::PreparedQueries | The driver prepares statements. |
QSqlDriver::NamedPlaceholders | The driver has placeholders with names, such as :id. |
QSqlDriver::PositionalPlaceholders | The driver has placeholders that are written ?. |
QSqlDriver::LastInsertId | The driver tells the identifier of the row that was inserted last. |
QSqlDriver::BatchOperations | The driver runs a statement for a batch of values in one call. |
QSqlDriver::SimpleLocking | The driver locks a whole table while it is read, so that writing to it has to wait. |
QSqlDriver::LowPrecisionNumbers | The driver can return numbers with less precision. |
QSqlDriver::EventNotifications | The driver delivers notifications of the database. |
QSqlDriver::FinishQuery | The driver releases the resources of a query that is finished. |
QSqlDriver::MultipleResultSets | The driver returns several result sets for one statement. |
QSqlDriver::CancelQuery | The driver can cancel a running query. |
enum QSqlDriver::IdentifierType
The kinds of identifiers that escapeIdentifier() quotes.
| Constant | Description |
|---|---|
QSqlDriver::FieldName | The name of a field. |
QSqlDriver::TableName | The name of a table. |
enum QSqlDriver::NotificationSource
Where a notification of the database comes from.
| Constant | Description |
|---|---|
QSqlDriver::UnknownSource | The source is not known. |
QSqlDriver::SelfSource | The notification comes from this connection. |
QSqlDriver::OtherSource | The notification comes from another connection. |
enum QSqlDriver::StatementType
The kinds of statements that sqlStatement() writes.
| Constant | Description |
|---|---|
QSqlDriver::WhereStatement | A WHERE clause that selects the row with the values of a record. |
QSqlDriver::SelectStatement | A SELECT statement for the fields of a record. |
QSqlDriver::UpdateStatement | An UPDATE statement that sets the fields of a record, without a WHERE clause. |
QSqlDriver::InsertStatement | An INSERT statement for the fields of a record. |
QSqlDriver::DeleteStatement | A DELETE statement, without a WHERE clause. |
Member Function Documentation
QSqlDriver::QSqlDriver(QObject *parent = nullptr)
Constructs a driver with the given parent.
QSqlDriver::~QSqlDriver()
Destroys the driver. A subclass closes its connection in its own destructor.
bool QSqlDriver::beginTransaction()
Starts a transaction and returns true on success. The base implementation does nothing and returns false.
See also commitTransaction() and rollbackTransaction().
bool QSqlDriver::cancelQuery()
Tries to cancel the query that is running and returns true on success. The base implementation returns false.
void QSqlDriver::close()
Closes the connection to the database. An implementation calls setOpen() and setOpenError() with false.
See also open().
bool QSqlDriver::commitTransaction()
Commits the running transaction and returns true on success. The base implementation does nothing and returns false.
See also beginTransaction().
QSqlResult * QSqlDriver::createResult() const
Returns a new result for a query on this connection. The caller owns it; a QSqlQuery takes it over.
DbmsType QSqlDriver::dbmsType() const
Returns the database system that the driver is connected to.
See also setDbmsType().
QString QSqlDriver::escapeIdentifier(const QString &identifier, IdentifierType type) const
Returns identifier quoted the way the database wants the name of a field or a table, as type tells, to be quoted. The base implementation returns identifier unchanged.
See also isIdentifierEscaped() and stripDelimiters().
QString QSqlDriver::formatValue(const QSqlField &field, bool trimStrings = false) const
Returns the value of field written as a literal that can be put into an SQL statement. A null value gives NULL; text is put between single quotes, with the quotes inside it doubled, and loses the spaces at its end if trimStrings is true; a date, a time or a date and time is written in ISO 8601 between quotes; a boolean is written as 1 or 0; a byte array is written as a hexadecimal X'...' literal.
QVariant QSqlDriver::handle() const
Returns the handle of the connection in the client library of the database, for code that calls the library directly. The base implementation returns an invalid QVariant.
bool QSqlDriver::hasFeature(DriverFeature f) const
Returns true if the driver has the feature f; otherwise returns false.
bool QSqlDriver::isIdentifierEscaped(const QString &identifier, IdentifierType type) const
Returns true if identifier is quoted the way escapeIdentifier() quotes a name of the kind type; otherwise returns false. The base implementation tests for a name between double quotes.
See also stripDelimiters().
bool QSqlDriver::isOpen() const
Returns true if the connection to the database is open; otherwise returns false.
See also setOpen() and isOpenError().
bool QSqlDriver::isOpenError() const
Returns true if the last attempt to open the connection failed; otherwise returns false.
See also setOpenError() and lastError().
QSqlError QSqlDriver::lastError() const
Returns the last error of the connection.
See also setLastError().
int QSqlDriver::maximumIdentifierLength(IdentifierType type) const
Returns the largest length that the database allows for a name of the kind type. The base implementation returns the largest int.
void QSqlDriver::notification(const QString &name, QSqlDriver::NotificationSource source, const QVariant &payload)
This signal is emitted when the database delivers the notification name that the driver subscribed to, from source and with the data payload.
See also subscribeToNotification().
QSql::NumericalPrecisionPolicy QSqlDriver::numericalPrecisionPolicy() const
Returns how the results created by this driver return numbers of high precision.
See also setNumericalPrecisionPolicy().
bool QSqlDriver::open(const QString &db, const QString &user = QString(), const QString &password = QString(), const QString &host = QString(), int port = -1, const QString &connOpts = QString())
Opens a connection to the database db for the user user with the password password, on the host host and the port port, with the options connOpts. An implementation returns true and calls setOpen() on success, and calls setLastError() and setOpenError() otherwise.
See also close() and QSqlDatabase::open().
QSqlIndex QSqlDriver::primaryIndex(const QString &tableName) const
Returns the primary key of the table tableName, or an empty index if it has none. The base implementation returns an empty index.
QSqlRecord QSqlDriver::record(const QString &tableName) const
Returns the fields of the table tableName, without values, or an empty record if there is no such table. The base implementation returns an empty record.
bool QSqlDriver::rollbackTransaction()
Rolls the running transaction back and returns true on success. The base implementation does nothing and returns false.
See also beginTransaction().
void QSqlDriver::setDbmsType(DbmsType type)
Sets the database system that the driver is connected to, to type. Called by subclasses.
See also dbmsType().
void QSqlDriver::setLastError(const QSqlError &error)
Sets the last error of the connection to error. Called by subclasses.
See also lastError().
void QSqlDriver::setNumericalPrecisionPolicy(QSql::NumericalPrecisionPolicy precisionPolicy)
Sets how the results created by this driver return numbers of high precision to precisionPolicy.
See also numericalPrecisionPolicy().
void QSqlDriver::setOpen(bool open)
Sets whether the connection is open to open. Called by subclasses.
See also isOpen().
void QSqlDriver::setOpenError(bool error)
Sets whether opening the connection failed to error. An error also marks the connection as closed. Called by subclasses.
See also isOpenError().
QString QSqlDriver::sqlStatement(StatementType type, const QString &tableName, const QSqlRecord &rec, bool preparedStatement) const
Returns an SQL statement of the kind type for the table tableName and the generated fields of rec. With preparedStatement the values are written as ? placeholders, to be bound in the order of the fields; without it they are written as literals with formatValue(). A WHERE clause compares a null value with IS NULL in both forms, so a null value has no placeholder. Returns an empty string if there is nothing to write.
See also formatValue() and escapeIdentifier().
QString QSqlDriver::stripDelimiters(const QString &identifier, IdentifierType type) const
Returns identifier without the quotes around it, if it is quoted as a name of the kind type; otherwise returns it unchanged.
See also isIdentifierEscaped().
QStringList QSqlDriver::subscribedToNotifications() const
Returns the names of the notifications that the driver is subscribed to. The base implementation returns an empty list.
See also subscribeToNotification().
bool QSqlDriver::subscribeToNotification(const QString &name)
Subscribes to the notification name of the database and returns true on success. The base implementation returns false.
See also notification() and unsubscribeFromNotification().
QStringList QSqlDriver::tables(QSql::TableType tableType) const
Returns the names of the tables of the kinds tableType in the database. The base implementation returns an empty list.
bool QSqlDriver::unsubscribeFromNotification(const QString &name)
Ends the subscription to the notification name and returns true on success. The base implementation returns false.
See also subscribeToNotification().