class QSqlDatabase#

QSqlDatabase 类处理数据库连接。 更多…

摘要#

方法#

静态函数#

注意

本文档可能包含自动从C++翻译到Python的代码段。我们始终欢迎对代码段的翻译做出贡献。如果您发现翻译存在问题，也可以通过在https:/bugreports.qt.io/projects/PYSIDE上创建工单的方式告诉我们。

详细描述#

警告

本节包含自动从C++翻译到Python的代码段，可能包含错误。

QSqlDatabase 类提供了一个通过连接访问数据库的接口。一个 QSqlDatabase 的实例表示连接。连接通过支持的一种数据库驱动程序提供对数据库的访问，这些驱动程序是从 QSqlDriver 派生的。或者，您也可以从 QSqlDriver 派生您自己的数据库驱动程序。有关更多信息，请参阅如何编写自己的数据库驱动程序。

通过调用静态函数addDatabase() 之一创建一个连接（即 QSqlDatabase 的实例），其中指定所需的驱动程序或驱动程序类型（根据数据库类型而定）以及连接名称。连接以其自己的名称而闻名，而非与之连接的数据库的名称。您可以对一个数据库拥有多个连接。 QSqlDatabase 还支持 默认 连接的概念，即无名称的连接。要创建默认连接，在调用 addDatabase() 时不要传递连接名称参数。之后，如果调用任何不指定连接名称的静态成员函数，则假定默认连接。以下示例代码展示了如何创建并打开到 PostgreSQL 数据库的默认连接

db = QSqlDatabase.addDatabase("QPSQL")
db.setHostName("acidalia")
db.setDatabaseName("customdb")
db.setUserName("mojito")
db.setPassword("J0a1m8")
ok = db.open()

创建 QSqlDatabase 对象之后，使用 setDatabaseName()、 setUserName()、 setPassword()、 setHostName()、 setPort() 和 setConnectOptions() 设置连接参数。然后调用 open() 来激活到数据库的物理连接。在打开之前，该连接是不可用的。

上述定义的连接将是 默认 连接，因为我们没有给 addDatabase() 提供连接名称。之后，您可以通过调用 database() 而不带连接名称参数来获取默认连接

db = QSqlDatabase.database()

QSqlDatabase 是一个值类。通过一个 QSqlDatabase 实例对数据库连接所做的更改，将影响表示相同连接的其他 QSqlDatabase 实例。使用 cloneDatabase() 可根据现有的连接创建一个独立的数据库连接。

警告

强建议您不要将 QSqlDatabase 作为类的成员保留副本，因为这将阻止在关闭时正确清理实例。如果您需要访问现有的 QSqlDatabase ，请使用 database() 方法进行访问。如果您选择有一个 QSqlDatabase 成员变量，则在删除 QCoreApplication 实例之前必须将其删除，否则可能导致未定义的行为。

如果您创建了多个数据库连接，请在调用 addDatabase() 时为每个连接指定一个唯一的连接名称。使用带有连接名称的 database() 获取该连接。使用带有连接名称的 removeDatabase() 移除一个连接。如果尝试移除由其他 QSqlDatabase 对象引用的连接，QSqlDatabase 会输出警告。使用 contains() 查看给定的连接名称是否在连接列表中。

一些实用方法

tables()

返回表列表

primaryIndex()

返回表的主索引

record()

返回关于表字段的元信息

transaction()

开始一个事务

commit()

保存并完成事务

rollback()

取消事务

hasFeature()

检查驱动程序是否支持事务

lastError()

返回有关上次错误的信息

drivers()

返回可用的 SQL 驱动程序名称

isDriverAvailable()

检查特定驱动程序是否可用

registerSqlDriver()

注册自定义驱动程序

注意

在创建查询之前，必须开始事务。

参考

QSqlDriver QSqlQuery Qt SQL 线程 和 SQL 模块

PySide6.QtSql.QSqlDatabase.defaultConnection#
__init__(driver)#
参数：

driver – QSqlDriver

这是一个重载函数。

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

__init__()

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

__init__(type)
参数：

类型 – str

这是一个重载函数。

创建一个使用由 type 指定的驱动器的 QSqlDatabase 连接。如果无法识别 type，则数据库连接将没有任何功能。

当前可用的驱动类型包括

驱动程序类型

描述

QDB2

IBM DB2

QIBASE

Borland InterBase 驱动程序

QMYSQL

MySQL 驱动程序

QOCI

Oracle 调用接口驱动程序

QODBC

ODBC 驱动程序（包括 Microsoft SQL Server）

QPSQL

PostgreSQL 驱动程序

QSQLITE

SQLite 3 或以上版本

QMIMER

Mimer SQL 11 或以上版本

可以动态加载额外的第三方驱动程序，包括您自己的自定义驱动程序。

__init__(other)
参数：

其他 – QSqlDatabase

创建一个other的副本。

静态addDatabase(driver[, connectionName=QLatin1StringView(QSqlDatabase.defaultConnection)])#
参数：

  • driver – QSqlDriver

  • connectionName – 字符串

返回类型：

QSqlDatabase

警告

本节包含自动从C++翻译到Python的代码段，可能包含错误。

此重载在有需要使用您自己实例化的driver创建数据库连接时非常有用。这可能是一个您自己的数据库驱动程序，或者您可能只需要实例化一个Qt驱动程序。如果这样做，建议将驱动程序代码包含到您应用程序中。例如，您可以使用自己的QPSQL驱动程序创建PostgreSQL连接，如下所示

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

上述代码设置PostgreSQL连接并实例化一个QPSQLDriver对象。接下来，调用addDatabase() 增加连接到已知连接中，以便它可以使用Qt SQL类。当使用连接句柄（或句柄集）实例化驱动程序时，Qt假设您已经打开了数据库连接。

注意

我们假设qtdir是Qt的安装目录。这将包含使用PostgreSQL客户端库和实例化QPSQLDriver对象所需的代码，假设您在包含搜索路径中有PostgreSQL头文件。

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

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

描述的该方法适用于所有提供的驱动程序。唯一的区别将在于驱动程序构造函数参数。以下是Qt包含的驱动程序及其源代码文件和构造函数参数的表

驱动程序

类名

构造函数参数

包含的文件

QPSQL

QPSQLDriver

PGconn *connection

qsql_psql.cpp

QMYSQL

QMYSQLDriver

MYSQL *connection

qsql_mysql.cpp

QOCI

QOCIDriver

OCIEnv *environment, OCISvcCtx *serviceContext

qsql_oci.cpp

QODBC

QODBCDriver

SQLHANDLE environment, SQLHANDLE connection

qsql_odbc.cpp

QDB2

QDB2

SQLHANDLE environment, SQLHANDLE connection

qsql_db2.cpp

QSQLITE

QSQLiteDriver

sqlite *connection

qsql_sqlite.cpp

QMIMER

QMimerSQLDriver

MimerSession *connection

qsql_mimer.cpp

QIBASE

QIBaseDriver

isc_db_handle connection

qsql_ibase.cpp

警告

使用与现有连接相同的连接名称添加数据库连接，会替换现有连接。

警告

SQL框架将拥有对driver的所有权。它不得被删除。要删除连接，请使用removeDatabase()。

参考

drivers()

静态addDatabase(type[, connectionName=QLatin1StringView(QSqlDatabase.defaultConnection)])
参数：

  • 类型 – str

  • connectionName – 字符串

返回类型：

QSqlDatabase

使用驱动类型 type 和连接名称 connectionName 将数据库添加到数据库连接列表中。如果已存在名为 connectionName 的数据库连接，则该连接将被移除。

数据库连接通过 connectionName 来引用。返回刚添加的数据库连接。

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

如果未指定 connectionName，新连接将成为应用程序的默认连接。后续调用 database() 而不提供连接名称参数时，将返回默认连接。如果在这里提供了 connectionName，则使用 database(connectionName) 来获取连接。

警告

如果您添加了一个与现有连接同名的连接，新连接将替换旧连接。如果您在未指定 connectionName 的情况下多次调用此函数，则默认连接将被替换。

在使用连接之前，必须对其进行初始化。例如，调用以下方法之一或所有：setDatabaseName()、setUserName()、setPassword()、setHostName()、setPort()、setConnectOptions()，最后调用 open()。

参考

database() removeDatabase() 多线程 和 SQL 模块

staticcloneDatabase(other, connectionName)#
参数：
返回类型：

QSqlDatabase

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

注意

新的连接尚未打开。在使用新连接之前，必须调用open() 。

static cloneDatabase(other, connectionName)
参数：

  • other – str

  • connectionName – 字符串

返回类型：

QSqlDatabase

这是一个重载函数。

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

注意

新的连接尚未打开。在使用新连接之前，必须调用open() 。

此重载在将数据库克隆到由other表示的数据库使用的线程时很有用。

close()#

关闭数据库连接，释放任何获取的资源，并使所有与数据库一起使用的现有QSqlQuery对象无效。

这也将影响此QSqlDatabase对象的副本。

commit()#
返回类型：

bool

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

注意

对于某些数据库，如果有使用数据库的 SELECT 的活动查询，提交将失败并返回 false。在进行提交之前，请使查询变为非活动状态。

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

connectOptions()#
返回类型：

str

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

connectionName()#
返回类型：

str

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

注意

连接名称不是数据库的 database name .

参考

addDatabase()

静态 connectionNames(#
返回类型：

字符串列表

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

参考

contains() database() 线程和SQL模块

静态 contains([connectionName=QLatin1StringView(QSqlDatabase.defaultConnection)])#
参数：

connectionName – 字符串

返回类型：

bool

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

参考

connectionNames() database() 线程和SQL模块

静态 database([connectionName=QLatin1StringView(QSqlDatabase.defaultConnection)[, open=true]])#
参数：

  • connectionName – 字符串

  • open – bool

返回类型：

QSqlDatabase

返回名为 connectionName 的数据库连接。必须已经使用 addDatabase() 添加数据库连接。如果 open 为 true（默认值）且数据库连接尚未打开，则立即打开它。如果未指定任何 connectionName，则使用默认连接。如果 connectionName 不在数据库列表中，则返回无效连接。

参考

isOpen() 线程 和 SQL 模块

databaseName()#
返回类型：

str

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

注意

数据库名称不是连接名称。

参考

setDatabaseName()

driver()#
返回类型：

QSqlDriver

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

driverName()#
返回类型：

str

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

静态 drivers()#
返回类型：

字符串列表

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

exec([query=""])#
参数：

query – str

返回类型：

QSqlQuery

注意

该函数已过时。

在数据库上执行SQL语句并返回一个QSqlQuery对象。请使用lastError()来检索错误信息。如果query为空，则返回一个空且无效的查询，且不会影响lastError()。

请使用exec()代替。

exec_([query=""])#
参数：

query – str

返回类型：

QSqlQuery

hostName()#
返回类型：

str

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

参考

setHostName()

静态 isDriverAvailable(name)#
参数：

name – 字符串

返回类型：

bool

如果存在名为 name 的驱动器，则返回 true；否则返回 false。

参考

drivers()

isOpen()#
返回类型：

bool

如果数据库连接当前是打开的，则返回 true；否则返回 false。

isOpenError()#
返回类型：

bool

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

isValid()#
返回类型：

bool

警告

本节包含自动从C++翻译到Python的代码段，可能包含错误。

如果 QSqlDatabase 有有效的驱动器，则返回 true。

示例

db = QSqlDatabase()
print(db.isValid() ) # Returns false
db = QSqlDatabase.database("sales")
print(db.isValid() # Returns \c true if "sales" connection exists)
QSqlDatabase.removeDatabase("sales")
print(db.isValid() ) # Returns false
lastError()#
返回类型：

QSqlError

返回数据库最后发生错误的详细信息。

与单个查询一起发生的失败将由 lastError() 报告。

numericalPrecisionPolicy()#
返回类型：

数值精度策略

返回数据库连接当前的默认精度策略。

open()#
返回类型：

bool

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

open(user, password)
参数：

  • user – str

  • password – str

返回类型：

bool

这是一个重载函数。

使用给定的用户名和密码打开数据库连接。成功时返回 true；否则返回 false。可以使用lastError()函数获取错误信息。

此函数不会存储给定的密码。相反，该密码将直接传递给驱动程序以打开连接，然后将其丢弃。

参考

lastError()

password()#
返回类型：

str

返回连接的密码。如果使用 setPassword() 设置了密码，则返回空字符串；如果调用 open() 时提供了密码，或者未使用密码。

参考

setPassword()

port()#
返回类型：

int

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

参考

setPort()

primaryIndex(tablename)#
参数：

tablename – str

返回类型：

QSqlIndex

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

注意

某些驱动程序，如 QPSQL 驱动程序，可能需要您以小写形式传递 tablename，如果创建表时未引号。有关更多信息，请参阅 Qt SQL驱动程序 文档。

参考

tables() record()

record(tablename)#
参数：

tablename – str

返回类型：

QSqlRecord

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

注意

某些驱动程序，如 QPSQL 驱动程序，可能需要您以小写形式传递 tablename，如果创建表时未引号。有关更多信息，请参阅 Qt SQL驱动程序 文档。

static registerSqlDriver(name, creator)#
参数：

警告

本节包含自动从C++翻译到Python的代码段，可能包含错误。

此函数在SQL框架内部注册名为name的新SQL驱动程序。如果您有一个自定义SQL驱动程序且不希望将其作为插件编译，这将很有用。

示例

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

QSqlDatabase 将拥有creator指针的所有权，因此您不能自己删除它。

参考

drivers()

static removeDatabase(connectionName)#
参数：

connectionName – 字符串

警告

本节包含自动从C++翻译到Python的代码段，可能包含错误。

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

警告

在调用此函数时应在数据库连接上没有打开的查询，否则会发生资源泄露。

示例

# WRONG
db = QSqlDatabase.database("sales")
query = QSqlQuery("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

正确的方法

    db = QSqlDatabase.database("sales")
    query = QSqlQuery("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模块

rollback()#
返回类型：

bool

如果驱动程序支持事务且已开始一次 transaction()，则将撤销数据库上的事务。如果操作成功，则返回 true，否则返回 false。

注意

对于某些数据库，如果在数据库上存在使用 SELECT 的 active query，则回滚操作可能会失败并返回 false。在进行回滚之前，请使查询 inactive。

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

setConnectOptions([options=""])#
参数：

options - str

警告

本节包含自动从C++翻译到Python的代码段，可能包含错误。

设置特定于数据库的 options。这必须在连接打开之前完成，否则它将不起作用。另一种可能是关闭连接，调用 QSqlDatabase::setConnectOptions()，然后再次 open() 连接。

选项字符串的格式是由分号分隔的选项名称或选项=value 对的列表。选项取决于所使用的数据库客户端，并在 SQL 数据库驱动程序 页面中为每个插件进行描述。

示例

db.setConnectOptions("SSL_KEY=client-key.pemSSL_CERT=client-cert.pem;SSL_CA=ca-cert.pem;CLIENT_IGNORE_SPACE=1"); # use an SSL connection to the server
if not db.open():
    db.setConnectOptions() # clears the connect option string
    # ...

# ...
# PostgreSQL connection
db.setConnectOptions("requiressl=1") # enable PostgreSQL SSL connections
if not db.open():
    db.setConnectOptions() # clear options
    # ...

# ...
# ODBC connection
db.setConnectOptions("SQL_ATTR_ACCESS_MODE=SQL_MODE_READ_ONLYSQL_ATTR_TRACE=SQL_OPT_TRACE_ON"); # set ODBC options
if not db.open():
    db.setConnectOptions() # don't try to set this option
    # ...

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

setDatabaseName(name)#
参数：

name – 字符串

警告

本节包含自动从C++翻译到Python的代码段，可能包含错误。

将连接的数据库名称设置为 name。为了生效，数据库名称必须在连接 打开 之前设置。或者，您也可以先 关闭 连接，设置数据库名称，然后再次调用 open()。

注意

数据库名称不是连接名称。连接名称必须在创建连接对象时传递到 addDatabase()。

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

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

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

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

例如，Microsoft Access 用户可以使用以下连接字符串直接打开一个 .mdb 文件，而不必在 ODBC 管理器中创建 DSN 条目

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

# ...

没有默认值。

setHostName(host)#
参数：

host – str

将连接的主机名设置为host。要生效，必须在连接被打开之前设置主机名。或者，您也可以通过close()关闭连接，设置主机名，然后再次调用open()。

没有默认值。

setNumericalPrecisionPolicy(precisionPolicy)#
参数：

precisionPolicy – NumericalPrecisionPolicy

将在此数据库连接上创建的查询使用的默认数值精度策略设置为precisionPolicy。

注意：不支持以低精度获取数值的驱动程序将忽略精度策略。您可以使用hasFeature()来确定是否支持此功能。

注意：将默认精度策略设置为precisionPolicy不会影响任何当前处于活动状态的查询。

setPassword(password)#
参数：

password – str

将连接的密码设置为password。为了生效，必须在连接 打开 之前设置密码。或者，您可以 关闭 连接，设置密码，然后再次调用 打开 方法。

没有默认值。

警告

这个函数将在 Qt 中以明文形式存储密码。为了避免这种行为，请使用带密码参数的 open() 调用。

参考

password() setUserName() setDatabaseName() setHostName() setPort() setConnectOptions() open()

setPort(p)#
参数：

p – int

将连接的端口号设置为 port。为了生效，必须在连接 打开 之前设置端口号。或者，您可以 关闭 连接，设置端口号，然后再次调用 打开 方法。

没有默认值。

setUserName(name)#
参数：

name – 字符串

将该连接的用户名设置为 name。为使生效，用户名必须在连接被打开之前设置。或者，您可以先调用close()关闭连接，设置用户名，然后再调用open()。

没有默认值。

tables([type=QSql.Tables])#
参数：

type – TableType

返回类型：

字符串列表

返回数据库的表格（系统表格和视图），由参数 type 指定。

transaction()#
返回类型：

bool

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

userName()#
返回类型：

str

返回连接的用户名；它可能为空。

参考

setUserName()