QSqlDatabase Class

成员函数文档

QSqlDatabase::QSqlDatabase()

创建一个空的、无效的 QSqlDatabase 对象。请使用addDatabase()、removeDatabase() 和database() 来获取有效的 QSqlDatabase 对象。

[explicit protected] QSqlDatabase::QSqlDatabase(QSqlDriver *driver)

使用给定的driver 建立数据库连接。

[explicit protected] QSqlDatabase::QSqlDatabase(const QString &type)

创建一个使用type 所引用的驱动程序的QSqlDatabase连接。如果无法识别type ，则该数据库连接将无法正常工作。

当前可用的驱动程序类型包括：

其他第三方驱动程序（包括您自己的自定义驱动程序）可以动态加载。

另请参阅 “SQL 数据库驱动程序”、“registerSqlDriver()”和“drivers()”。

QSqlDatabase::QSqlDatabase(const QSqlDatabase &other)

创建other 的副本。

[noexcept] QSqlDatabase::~QSqlDatabase()

销毁该对象并释放所有已分配的资源。

另请参阅 close()。

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

使用驱动程序type 和连接名connectionName 将一个数据库添加到数据库连接列表中。如果已经存在名为connectionName 的数据库连接，则该连接将被删除。

该数据库连接由connectionName 引用。该函数返回新添加的数据库连接。

如果type 不可用或无法加载，isValid() 将返回false 。

如果未指定connectionName ，新连接将作为应用程序的默认连接；此后对database()的调用若不带连接名称参数，将返回该默认连接。若此处提供了connectionName ，请使用database(connectionName)来获取该连接。

在使用连接之前，必须对其进行初始化。例如，调用以下函数中的部分或全部：setDatabaseName()、setUserName()、setPassword()、setHostName()、setPort() 和setConnectOptions()，最后调用open()。

注意：此函数是线程安全的。

另请参阅 database(),removeDatabase() 以及《线程与 SQL 模块》。

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

当您希望使用自己实例化的driver 建立数据库连接时，此重载非常有用。这可能是您自己的数据库驱动程序，也可能是您需要自行实例化某个Qt XML驱动程序。 如果这样做，建议将驱动程序代码包含在您的应用程序中。例如，您可以像这样使用自定义的 QPSQL 驱动程序建立 PostgreSQL 连接：

PGconn *con = PQconnectdb("host=server user=bart password=simpson dbname=springfield");
QPSQLDriver *drv = new QPSQLDriver(con);
QSqlDatabase db = QSqlDatabase::addDatabase(drv); // becomes the new default connection
QSqlQuery query;
query.exec("SELECT NAME, ID FROM STAFF");

上述代码建立了 PostgreSQL 连接，并实例化了一个 QPSQLDriver 对象。 接下来，调用 addDatabase() 将该连接添加到已知连接列表中，以便Qt SQL 类能够使用它。当使用连接句柄（或一组句柄）实例化驱动程序时，Qt 会假设您已经打开了数据库连接。

请记住，您必须将应用程序与数据库客户端库进行链接。请确保客户端库位于链接器的搜索路径中，并在您的.pro 文件中添加类似以下的行：

unix:LIBS += -lpq
win32:LIBS += libpqdll.lib

上述方法适用于所有提供的驱动程序。唯一的区别在于驱动程序构造函数的参数。下表列出了 Qt 附带的驱动程序、其源代码文件以及构造函数参数：

另请参阅 drivers()。

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

克隆数据库连接other ，并将其存储为connectionName 。原始数据库中的所有设置（例如databaseName()、hostName()等）均会被复制过来。如果other 是一个无效的数据库，则不执行任何操作。返回新创建的数据库连接。

注意：此函数是可重入的。

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

克隆数据库连接other ，并将其存储为connectionName 。原始数据库中的所有设置（例如databaseName()、hostName()等）均会被复制过来。如果other 是一个无效的数据库，则不执行任何操作。返回新创建的数据库连接。

当在与other 所表示的数据库不同的线程中克隆数据库时，此重载非常有用。

void QSqlDatabase::close()

关闭数据库连接，释放已获取的资源，并使所有与该数据库关联的现有QSqlQuery 对象失效。

此操作也会影响该QSqlDatabase 对象的所有副本。

另请参阅 removeDatabase()。

bool QSqlDatabase::commit()

如果驱动程序支持事务且已调用transaction()，则将事务提交到数据库。如果操作成功，则返回true ；否则返回false 。

调用lastError() 获取有关错误的信息。

另请参阅 QSqlQuery::isActive()、QSqlDriver::hasFeature() 和rollback()。

QString QSqlDatabase::connectOptions() const

返回用于此连接的连接选项字符串。该字符串可能为空。

另请参阅 setConnectOptions()。

QString QSqlDatabase::connectionName() const

返回连接名称，该名称可能为空。

另请参阅 addDatabase()。

[static] QStringList QSqlDatabase::connectionNames()

返回一个包含所有连接名称的列表。

注意：此函数是线程安全的。

另请参阅 contains()、database()，以及《线程与 SQL 模块》。

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

如果数据库连接列表中包含 `connectionName`，则返回 `true `；否则返回 `false`。

注意：此函数是线程安全的。

另请参阅 connectionNames()、database() 以及《线程与 SQL 模块》。

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

返回名为connectionName 的数据库连接。该数据库连接必须已通过addDatabase()函数添加。如果open 为true（默认值），且该数据库连接尚未打开，则此时会打开该连接。如果未指定connectionName ，则使用默认连接。如果connectionName 在数据库列表中不存在，则返回一个无效的连接。

注意：此函数是线程安全的。

另请参阅 isOpen() 以及《线程与 SQL 模块》。

QString QSqlDatabase::databaseName() const

返回连接的数据库名称，该名称可能为空。

另请参阅 setDatabaseName()。

QSqlDriver *QSqlDatabase::driver() const

返回用于访问数据库连接的数据库驱动程序。

另请参阅 addDatabase() 和drivers()。

QString QSqlDatabase::driverName() const

返回连接的驱动程序名称。

另请参阅 addDatabase() 和driver()。

[static] QStringList QSqlDatabase::drivers()

返回所有可用数据库驱动程序的列表。

另请参阅 registerSqlDriver()。

QString QSqlDatabase::hostName() const

返回连接的主机名；该值可能为空。

另请参阅 setHostName()。

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

如果名为name 的驱动程序可用，则返回true ；否则返回false 。

另请参阅 drivers()。

bool QSqlDatabase::isOpen() const

如果数据库连接当前处于打开状态，则返回true ；否则返回false 。

bool QSqlDatabase::isOpenError() const

如果打开数据库连接时发生错误，则返回true ；否则返回false 。可通过lastError()函数获取错误信息。

bool QSqlDatabase::isValid() const

如果QSqlDatabase 具有有效的驱动程序，则返回true 。

示例：

QSqlDatabase db;
qDebug() << db.isValid();    // Returns false

db=QSqlDatabase::database("sales");
qDebug() << db.isValid();    // Returns \c true if "sales" connection exists

QSqlDatabase::removeDatabase("sales");
qDebug() << db.isValid();    // Returns false

QSqlError QSqlDatabase::lastError() const

返回有关数据库中最近发生的错误的信息。

与单个查询相关的故障由 `QSqlQuery::lastError()` 报告。

另请参阅 QSqlError 和QSqlQuery::lastError()。

[since 6.8] bool QSqlDatabase::moveToThread(QThread *targetThread)

更改QSqlDatabase 及其关联驱动程序的线程亲和性。该函数成功执行时返回true 。事件处理将在targetThread 中继续进行。

在此操作过程中，必须确保没有QSqlQuery 与该实例绑定，否则QSqlDatabase 将无法移动到指定的线程，且函数将返回false 。

由于关联的驱动程序继承自QObject ，将QObject 移至另一个线程的所有限制也适用于此函数。

该函数在 Qt 6.8 中引入。

另请参阅 QObject::moveToThread() 以及《线程与 SQL 模块》。

QSql::NumericalPrecisionPolicy QSqlDatabase::numericalPrecisionPolicy() const

返回 numericalPrecisionPolicy。

另请参阅 ` setNumericalPrecisionPolicy()`。

bool QSqlDatabase::open()

使用当前连接参数打开数据库连接。成功时返回true ；否则返回false 。可通过lastError()获取错误信息。

另请参阅 lastError()、setDatabaseName()、setUserName()、setPassword()、setHostName()、setPort()，以及setConnectOptions()。

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

使用给定的user 名称和password 建立数据库连接。成功时返回true ；否则返回false 。可通过lastError()函数获取错误信息。

该函数不会存储传入的密码。相反，密码会直接传递给驱动程序以建立连接，随后即被丢弃。

另请参阅 lastError()。

QString QSqlDatabase::password() const

返回连接的密码。如果未通过setPassword()设置密码，或者在open()调用中已指定密码，或者未使用密码，则返回空字符串。

另请参阅 setPassword()。

int QSqlDatabase::port() const

返回连接的端口号。如果端口号尚未设置，则该值为未定义。

另请参阅 setPort()。

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

返回表tablename 的主索引。如果不存在主索引，则返回空的QSqlIndex 。

另请参阅 tables() 和record()。

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

返回一个QSqlRecord ，其中填充了名为tablename 的表（或视图）中所有字段的名称。字段在记录中的出现顺序未定义。如果不存在此类表（或视图），则返回一个空记录。

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

该函数在 SQL 框架中注册了一个名为name 的新 SQL 驱动程序。如果您拥有自定义的 SQL 驱动程序，但不想将其编译为插件，此功能将非常有用。

示例：

QSqlDatabase::registerSqlDriver("MYDRIVER", new QSqlDriverCreator<QSqlDriver>);
QVERIFY(QSqlDatabase::drivers().contains("MYDRIVER"));
QSqlDatabase db = QSqlDatabase::addDatabase("MYDRIVER");
QVERIFY(db.isValid());

QSqlDatabase 该函数会接管 `creator ` 指针的所有权，因此您切勿自行将其删除。

另请参阅 drivers()。

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

将数据库连接connectionName 从数据库连接列表中移除。

示例：

// WRONG
QSqlDatabase db = QSqlDatabase::database("sales");
QSqlQuery query("SELECT NAME, DOB FROM EMPLOYEES", db);
QSqlDatabase::removeDatabase("sales"); // will output a warning
// "db" is now a dangling invalid database connection,
// "query" contains an invalid result set

正确的操作方法：

{
    QSqlDatabase db = QSqlDatabase::database("sales");
    QSqlQuery query("SELECT NAME, DOB FROM EMPLOYEES", db);
}
// Both "db" and "query" are destroyed because they are out of scope
QSqlDatabase::removeDatabase("sales"); // correct

若要移除默认连接（该连接可能是通过调用addDatabase()但未指定连接名而创建的），可通过在由database()返回的数据库上调用connectionName()来获取默认连接名。请注意，如果未创建默认数据库，则会返回一个无效的数据库。

注意：此函数是线程安全的。

另请参阅 database()、connectionName() 以及《线程与 SQL 模块》。

bool QSqlDatabase::rollback()

如果驱动程序支持事务且已调用transaction()，则回滚数据库中的事务。如果操作成功，则返回true ；否则返回false 。

调用lastError() 获取错误信息。

另请参阅 QSqlQuery::isActive()、QSqlDriver::hasFeature() 和commit()。

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

设置数据库特有的options 。必须在打开连接之前执行此操作，否则将无效。另一种方法是先关闭连接，调用QSqlDatabase::setConnectOptions()，然后再次通过open()打开连接。

options 字符串的格式为以分号分隔的选项名称列表或“选项=值”对列表。具体选项取决于所使用的数据库客户端，并在“SQL数据库驱动程序”页面中针对每个插件进行了说明。

示例：

db.setConnectOptions("SSL_KEY=client-key.pem;SSL_CERT=client-cert.pem;SSL_CA=ca-cert.pem;CLIENT_IGNORE_SPACE=1"); // use an SSL connection to the server
if (!db.open()) {
    db.setConnectOptions(); // clears the connect option string
    // ...
}
// ...
// PostgreSQL connection
db.setConnectOptions("requiressl=1"); // enable PostgreSQL SSL connections
if (!db.open()) {
    db.setConnectOptions(); // clear options
    // ...
}
// ...
// ODBC connection
db.setConnectOptions("SQL_ATTR_ACCESS_MODE=SQL_MODE_READ_ONLY;SQL_ATTR_TRACE=SQL_OPT_TRACE_ON"); // set ODBC options
if (!db.open()) {
    db.setConnectOptions(); // don't try to set this option
    // ...
}
}

有关不同选项的更多信息，请参阅客户端库文档。

另请参阅 connectOptions()。

void QSqlDatabase::setDatabaseName(const QString &name)

将连接的数据库名称设置为name 。要使该设置生效，必须在连接被opened之前设置数据库名称。或者，您可以先调用close() 建立连接，设置数据库名称，然后再次调用open()。

对于 QSQLITE 驱动程序，如果指定的数据库名不存在，则会为您创建该文件，除非设置了 QSQLITE_OPEN_READONLY 选项。

此外，name 可以设置为":memory:" ，这将创建一个仅在应用程序生命周期内可用的临时数据库。

对于 QOCI（Oracle）驱动程序，数据库名称即为 TNS 服务名称。

对于 QODBC 驱动程序，name 可以是 DSN、DSN 文件名（在这种情况下，文件必须具有.dsn 扩展名）或连接字符串。

例如，Microsoft Access 用户可以使用以下连接字符串直接打开“.mdb ”文件，而无需在 ODBC 管理器中创建 DSN 条目：

// ...
QSqlDatabase db = QSqlDatabase::addDatabase("QODBC");
db.setDatabaseName("DRIVER={Microsoft Access Driver (*.mdb, *.accdb)};FIL={MS Access};DBQ=myaccessfile.mdb");
if (db.open()) {
    // success!
}
// ...

该参数没有默认值。

另请参阅 databaseName()、setUserName()、setPassword()、setHostName()、setPort()、setConnectOptions() 以及open()。

void QSqlDatabase::setHostName(const QString &host)

将连接的主机名设置为host 。要使该设置生效，必须在连接被opened之前设置主机名。或者，您可以先对连接调用close()，设置主机名，然后再次调用open()。

该参数没有默认值。

另请参阅 hostName()、setUserName()、setPassword()、setDatabaseName()、setPort()、setConnectOptions() 和open()。

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

将numericalPrecisionPolicy 设置为precisionPolicy 。

另请参阅 numericalPrecisionPolicy()。

void QSqlDatabase::setPassword(const QString &password)

将连接的密码设置为password 。要使该设置生效，必须在建立连接之前完成密码设置opened 。或者，您可以先调用close()建立连接，设置密码后，再再次调用open()。

该参数没有默认值。

另请参阅 password()、setUserName()、setDatabaseName()、setHostName()、setPort()、setConnectOptions() 和open()。

void QSqlDatabase::setPort(int port)

将连接的端口号设置为port 。要使该设置生效，必须在建立连接之前 opened 。或者，您可以调用close()来获取连接，设置端口号，然后再次调用open()。

该参数没有默认值。

另请参阅 port()、setUserName()、setPassword()、setHostName()、setDatabaseName()、setConnectOptions() 以及open()。

void QSqlDatabase::setUserName(const QString &name)

将连接的用户名设置为name 。要使该设置生效，必须在建立连接之前 opened 该用户名。或者，您可以先调用close() 建立连接，设置用户名后，再再次调用open()。

该参数没有默认值。

另请参阅 userName()、setDatabaseName()、setPassword()、setHostName()、setPort()、setConnectOptions() 以及open()。

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

返回数据库中所有表、系统表和视图的列表，具体内容由参数type 指定。

另请参阅 primaryIndex() 和record()。

[since 6.8] QThread *QSqlDatabase::thread() const

返回指向相关QThread 实例的指针。

该函数在 Qt 6.8 中引入。

bool QSqlDatabase::transaction()

如果驱动程序支持事务，则在数据库上开始一个事务。如果操作成功，则返回true ；否则返回false 。

另请参阅 QSqlDriver::hasFeature()、commit() 和rollback()。

QString QSqlDatabase::userName() const

返回连接的用户名；该字段可能为空。

另请参阅 setUserName()。

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

将other 分配给此对象。