PySide6.QtSql.QSqlDatabase

class QSqlDatabase

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

概要

属性

方法

静态函数

注意

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

详细描述

警告

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

QSqlDatabase 类提供了一个通过连接访问数据库的接口。QSqlDatabase 的实例表示该连接。该连接通过一个从 QSqlDriver 派生的 支持的数据库驱动程序 提供对数据库的访问。或者，您可以从 QSqlDriver 子类化您自己的数据库驱动程序。有关更多信息，请参阅 如何编写您自己的数据库驱动程序。QSqlDatabase 实例只能由创建它的线程访问。因此，您必须确保在正确的上下文中创建它们。或者，您可以使用 moveToThread() 更改上下文。

通过调用静态函数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 模块

注意

当使用from __feature__ import true_property时，属性可以直接使用，否则通过访问器函数使用。

property numericalPrecisionPolicyᅟ: QSql.NumericalPrecisionPolicy

此属性保存了在此数据库连接上创建的查询所使用的默认数值精度策略。

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

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

Access functions:
PySide6.QtSql.QSqlDatabase.defaultConnection
__init__()

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

__init__(driver)
Parameters:

driver – QSqlDriver

这是一个重载函数。

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

__init__(other)
Parameters:

其他 – QSqlDatabase

创建 other 的副本。

__init__(type)
Parameters:

类型 – 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 或更高版本

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

static addDatabase(driver[, connectionName=QLatin1StringView(QSqlDatabase.defaultConnection)])
Parameters:
Return type:

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 环境, SQLHANDLE 连接

qsql_odbc.cpp

QDB2

QDB2

SQLHANDLE 环境, SQLHANDLE 连接

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()

static addDatabase(type[, connectionName=QLatin1StringView(QSqlDatabase.defaultConnection)])
Parameters:

  • type – str

  • connectionName – str

Return type:

QSqlDatabase

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

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

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

如果未指定connectionName，则新连接将成为应用程序的默认连接，并且后续调用database()时如果没有连接名称参数，将返回默认连接。如果在此处提供了connectionName，则使用database(connectionName)来检索连接。

警告

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

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

另请参阅

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

static cloneDatabase(other, connectionName)
Parameters:
Return type:

QSqlDatabase

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

注意

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

static cloneDatabase(other, connectionName)
Parameters:

  • 其他 – str

  • connectionName – str

Return type:

QSqlDatabase

这是一个重载函数。

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

注意

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

当在另一个线程中克隆数据库时，这个重载非常有用，该线程与由other表示的数据库所使用的线程不同。

close()

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

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

另请参阅

removeDatabase()

commit()
Return type:

布尔

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

注意

对于某些数据库，如果有一个active query正在使用数据库进行SELECT操作，提交将会失败并返回false。在执行提交之前，请将查询设置为inactive。

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

connectOptions()
Return type:

字符串

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

另请参阅

setConnectOptions()

connectionName()
Return type:

字符串

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

注意

连接名称不是database name。

另请参阅

addDatabase()

static connectionNames()
Return type:

字符串列表

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

另请参阅

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

static contains([connectionName=QLatin1StringView(QSqlDatabase.defaultConnection)])
Parameters:

connectionName – str

Return type:

布尔

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

另请参阅

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

static database([connectionName=QLatin1StringView(QSqlDatabase.defaultConnection)[, open=true]])
Parameters:

  • connectionName – str

  • open – 布尔值

Return type:

QSqlDatabase

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

另请参阅

isOpen() 线程 和 SQL 模块

databaseName()
Return type:

字符串

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

注意

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

另请参阅

setDatabaseName()

driver()
Return type:

QSqlDriver

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

另请参阅

addDatabase() drivers()

driverName()
Return type:

字符串

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

另请参阅

addDatabase() driver()

static drivers()
Return type:

字符串列表

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

另请参阅

registerSqlDriver()

exec([query=""])
Parameters:

query – str

Return type:

QSqlQuery

注意

此函数已弃用。

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

请使用exec()代替。

另请参阅

QSqlQuery lastError()

exec_([query=""])
Parameters:

query – str

Return type:

QSqlQuery

hostName()
Return type:

字符串

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

另请参阅

setHostName()

static isDriverAvailable(name)
Parameters:

name – str

Return type:

布尔

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

另请参阅

drivers()

isOpen()
Return type:

布尔

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

isOpenError()
Return type:

布尔

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

isValid()
Return type:

布尔

警告

本节包含从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()
Return type:

QSqlError

返回有关数据库上发生的最后一个错误的信息。

与单个查询同时发生的故障由lastError()报告。

另请参阅

QSqlError lastError()

moveToThread(targetThread)
Parameters:

targetThread – QThread

Return type:

布尔

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

在此操作期间，您必须确保没有QSqlQuery绑定到此实例，否则QSqlDatabase将不会移动到给定线程，并且函数将返回false。

由于关联的驱动程序是从QObject派生的，所有将QObject移动到另一个线程的限制也适用于此函数。

另请参阅

moveToThread()线程 和 SQL 模块

numericalPrecisionPolicy()
Return type:

NumericalPrecisionPolicy

返回数值精度策略。

属性 numericalPrecisionPolicyᅟ 的获取器。

open()
Return type:

布尔

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

open(user, password)
Parameters:

  • user – str

  • password – str

Return type:

布尔

这是一个重载函数。

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

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

另请参阅

lastError()

password()
Return type:

字符串

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

另请参阅

setPassword()

port()
Return type:

整数

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

另请参阅

setPort()

primaryIndex(tablename)
Parameters:

tablename – str

Return type:

QSqlIndex

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

注意

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

另请参阅

tables() record()

record(tablename)
Parameters:

tablename – str

Return type:

QSqlRecord

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

注意

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

static registerSqlDriver(name, creator)
Parameters:

警告

本节包含从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)
Parameters:

connectionName – str

警告

本节包含从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()
Return type:

布尔

如果驱动程序支持事务并且已经开始了transaction()，则在数据库上回滚事务。如果操作成功，则返回true。否则返回false。

注意

对于某些数据库，如果有一个active query正在使用数据库进行SELECT操作，回滚将失败并返回false。在执行回滚之前，请将查询inactive。

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

setConnectOptions([options=""])
Parameters:

options – 字符串

警告

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

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

options 字符串的格式是一个以分号分隔的选项名称或选项=值对的列表。这些选项取决于所使用的数据库客户端，并在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
    # ...

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

另请参阅

connectOptions()

setDatabaseName(name)
Parameters:

name – str

警告

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

将连接的数据库名称设置为name。为了使设置生效，数据库名称必须在连接opened之前设置。或者，您可以close()连接，设置数据库名称，然后再次调用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)
Parameters:

host – str

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

没有默认值。

setNumericalPrecisionPolicy(precisionPolicy)
Parameters:

precisionPolicy – NumericalPrecisionPolicy

将numericalPrecisionPolicy设置为precisionPolicy。

属性 numericalPrecisionPolicyᅟ 的设置器。

setPassword(password)
Parameters:

password – str

将连接的密码设置为password。为了使密码生效，必须在连接opened之前设置密码。或者，您可以close()连接，设置密码，然后再次调用open()。

没有默认值。

警告

此函数以明文形式在Qt中存储密码。使用接受密码作为参数的open()调用来避免此行为。

另请参阅

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

setPort(p)
Parameters:

p – 整数

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

没有默认值。

setUserName(name)
Parameters:

name – str

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

没有默认值。

tables([type=QSql.Tables])
Parameters:

类型 – TableType

Return type:

字符串列表

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

另请参阅

primaryIndex() record()

thread()
Return type:

QThread

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

transaction()
Return type:

布尔

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

userName()
Return type:

字符串

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

另请参阅

setUserName()