QSqlDatabase Class

The QSqlDatabase class handles a connection to a database. More…

List of all members, including inherited members

Public Functions

Static Public Members

Detailed Description

A QSqlDatabase is a handle to a connection. Connections are kept in a list under their names: addDatabase() makes one with the driver for a kind of database, database() returns it from anywhere in the program, and removeDatabase() takes it out of the list again. A connection that is added without a name is the default connection, which QSqlQuery and the models use unless they are given another one.

QSqlDatabase db = QSqlDatabase::addDatabase("QSQLITE");
db.setDatabaseName("contacts.db");
if (!db.open())
    qFatal("%s", qPrintable(db.lastError().text()));

The handle is a value: copies of it stand for the same connection. Remove a connection only when its handles and queries are gone:

{
    QSqlDatabase db = QSqlDatabase::database("import");
    QSqlQuery query("SELECT name FROM people", db);
    // ...
}
QSqlDatabase::removeDatabase("import");

The name given to setDatabaseName() means what the driver makes of it. For QSQLITE it is the path of the database file, :memory: for a database that lives in memory, or an empty name for a temporary database.

Threads

The list of connections can be used from any thread. A connection itself, with its queries, belongs to the thread that uses it: do not use one connection from two threads at the same time. Give each thread its own connection, with cloneDatabase() for example.

See also QSqlQuery, QSqlDriver and Using Nt SQL.

Differences from Qt

Member Function Documentation

QSqlDatabase::QSqlDatabase()

Constructs an invalid handle, which stands for no connection. Use addDatabase() or database() to get a valid one.

See also isValid().

QSqlDatabase::QSqlDatabase(const QSqlDatabase &other)

Constructs a handle to the connection of other.

QSqlDatabase::~QSqlDatabase()

Destroys the handle. The connection is closed when its last handle is destroyed, which for a connection in the list is the one that removeDatabase() drops.

[static] QSqlDatabase QSqlDatabase::addDatabase(const QString &type, const QString &connectionName = QLatin1StringView(defaultConnection))

Adds a connection called connectionName to the list, with the driver for the kind of database type, and returns a handle to it. Without a name, it becomes the default connection. A connection of the same name that is in the list already is removed first.

If there is no driver for type, a warning is printed and the handle that is returned is not valid. The connection is closed: set the name of the database and call open().

See also database(), removeDatabase() and drivers().

[static] QSqlDatabase QSqlDatabase::addDatabase(QSqlDriver *driver, const QString &connectionName = QLatin1StringView(defaultConnection))

This is an overloaded function.

Adds a connection called connectionName that uses driver, an object of a driver class of the application, and returns a handle to it. The connection takes ownership of driver.

[static] QSqlDatabase QSqlDatabase::cloneDatabase(const QSqlDatabase &other, const QString &connectionName)

Adds a connection called connectionName that is set up like the connection other: with a new driver of the same kind and the same database name, user name, password, host name, port and options. Returns a handle to it, which is closed. Returns an invalid handle if other is not valid.

This gives another thread its own connection to the same database.

See also addDatabase().

[static] QSqlDatabase QSqlDatabase::cloneDatabase(const QString &other, const QString &connectionName)

This is an overloaded function.

Clones the connection that is called other in the list, as connectionName. Unlike database(), this does not open other, so it may be called from another thread than the one that uses other.

void QSqlDatabase::close()

Closes the connection. The queries on it become inactive and release what they hold of the database.

See also open().

bool QSqlDatabase::commit()

Commits the running transaction and returns true on success. With some databases this fails while a SELECT statement is active: finish the query first.

See also transaction(), rollback() and QSqlQuery::finish().

QString QSqlDatabase::connectionName() const

Returns the name of the connection in the list of connections. It is empty for an invalid handle and for a connection that was removed.

See also addDatabase().

[static] QStringList QSqlDatabase::connectionNames()

Returns the names of the connections in the list.

See also contains() and database().

QString QSqlDatabase::connectOptions() const

Returns the options of the connection.

See also setConnectOptions().

[static] bool QSqlDatabase::contains(const QString &connectionName = QLatin1StringView(defaultConnection))

Returns true if the list has a connection called connectionName, or a default connection; otherwise returns false.

See also connectionNames().

[static] QSqlDatabase QSqlDatabase::database(const QString &connectionName = QLatin1StringView(defaultConnection), bool open = true)

Returns a handle to the connection called connectionName, or to the default connection. If open is true and the connection is closed, it is opened; lastError() of the handle tells if that failed. Returns an invalid handle if there is no such connection.

See also addDatabase() and contains().

QString QSqlDatabase::databaseName() const

Returns the name of the database.

See also setDatabaseName().

QSqlDriver * QSqlDatabase::driver() const

Returns the driver of the connection. It is never nullptr: a handle without a connection has a driver that does nothing.

QString QSqlDatabase::driverName() const

Returns the name of the driver of the connection, as it was given to addDatabase(). It is empty for a connection that was added with a driver object.

[static] QStringList QSqlDatabase::drivers()

Returns the names of the kinds of databases that have a driver: the drivers that Nt was built with and those added with registerSqlDriver().

See also isDriverAvailable().

QString QSqlDatabase::hostName() const

Returns the name of the host of the database.

See also setHostName().

[static] bool QSqlDatabase::isDriverAvailable(const QString &name)

Returns true if there is a driver for the kind of database name; otherwise returns false.

See also drivers().

bool QSqlDatabase::isOpen() const

Returns true if the connection is open; otherwise returns false.

See also open().

bool QSqlDatabase::isOpenError() const

Returns true if the last attempt to open the connection failed; otherwise returns false.

See also lastError().

bool QSqlDatabase::isValid() const

Returns true if the handle stands for a connection that has a driver; otherwise returns false. A handle from addDatabase() with a kind of database that has no driver is not valid.

QSqlError QSqlDatabase::lastError() const

Returns the last error of the connection. Errors of a statement are found in QSqlQuery::lastError().

QSql::NumericalPrecisionPolicy QSqlDatabase::numericalPrecisionPolicy() const

Returns how queries on this connection return numbers of high precision.

See also setNumericalPrecisionPolicy().

bool QSqlDatabase::open()

Opens the connection with the database name, user name, password, host name, port and options that were set, and returns true on success. A connection that is open is closed first. On failure, lastError() tells why.

See also close(), isOpen() and lastError().

bool QSqlDatabase::open(const QString &user, const QString &password)

This is an overloaded function.

Opens the connection for the user user with the password password. The user name is kept as with setUserName(); the password is not kept.

QSqlDatabase & QSqlDatabase::operator=(const QSqlDatabase &other)

Makes this a handle to the connection of other and returns a reference to it.

QString QSqlDatabase::password() const

Returns the password that was set with setPassword().

See also setPassword().

int QSqlDatabase::port() const

Returns the port of the database, or -1 if none was set.

See also setPort().

QSqlIndex QSqlDatabase::primaryIndex(const QString &tablename) const

Returns the primary key of the table tablename, or an empty index if it has none.

See also tables() and record().

QSqlRecord QSqlDatabase::record(const QString &tablename) const

Returns the fields of the table or view tablename, in the order of its columns and without values, or an empty record if there is no such table.

See also tables() and primaryIndex().

[static] void QSqlDatabase::registerSqlDriver(const QString &name, QSqlDriverCreatorBase *creator)

Makes a driver of the application available under name, so that addDatabase() can be called with it. creator makes the driver objects; the list of drivers takes ownership of it. A driver that is registered under the name of one that is there already, a built-in one included, takes its place.

See also QSqlDriverCreator and drivers().

[static] void QSqlDatabase::removeDatabase(const QString &connectionName)

Removes the connection called connectionName from the list and closes it. Nothing happens if there is no such connection.

If handles or queries of the connection are still around, a warning is printed and they stop working. Let them go out of scope first.

See also addDatabase() and database().

bool QSqlDatabase::rollback()

Rolls the running transaction back and returns true on success.

See also transaction() and commit().

void QSqlDatabase::setConnectOptions(const QString &options = QString())

Sets the options of the connection to options, for the next open(): a list of names, or names with values, separated by semicolons, as in "QSQLITE_BUSY_TIMEOUT=2000;QSQLITE_OPEN_READONLY". The names are those of the driver.

See also connectOptions().

void QSqlDatabase::setDatabaseName(const QString &name)

Sets the name of the database to name. This has to happen before the connection is opened; what the name means depends on the driver.

See also databaseName() and open().

void QSqlDatabase::setHostName(const QString &host)

Sets the name of the host of the database to host, for the next open().

See also hostName().

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

Sets how the queries that are made on this connection from now on return numbers of high precision to precisionPolicy.

See also numericalPrecisionPolicy() and QSqlQuery::setNumericalPrecisionPolicy().

void QSqlDatabase::setPassword(const QString &password)

Sets the password to password, for the next open(). The password is kept in memory as plain text; use open() with a password to avoid that.

See also password().

void QSqlDatabase::setPort(int p)

Sets the port of the database to p, for the next open().

See also port().

void QSqlDatabase::setUserName(const QString &name)

Sets the name of the user to name, for the next open().

See also userName().

QStringList QSqlDatabase::tables(QSql::TableType type = QSql::Tables) const

Returns the names of the tables of the kinds type in the database. The connection has to be open.

See also record() and primaryIndex().

bool QSqlDatabase::transaction()

Starts a transaction and returns true on success. Returns false if the driver has no transactions.

See also commit(), rollback() and QSqlDriver::hasFeature().

QString QSqlDatabase::userName() const

Returns the name of the user.

See also setUserName().

Member Variable Documentation

[static] const char *const QSqlDatabase::defaultConnection

The name of the default connection: the one that addDatabase() makes and database() returns when they are called without a name.