简介

此 API 的定义旨在鼓励用于访问数据库的 Python 模块之间的一致性。通过这样做，我们希望实现一致性，从而导致更易于理解的模块、跨数据库更具可移植性的代码以及更广泛的 Python 数据库连接范围。

此接口规范包含以下几个方面

• 模块接口
• 连接对象
• 游标对象
• DBI 辅助对象

有关此规范的评论和问题，可以发送到 Python 表格数据库 SIG (https://pythonlang.cn/sigs/db-sig)。

此规范文档最后更新日期：1996 年 4 月 9 日。它将被称为此规范的 1.0 版。

模块接口

数据库接口模块通常应该使用以 db 结尾的名称命名。现有的例子包括：oracledb、informixdb 和 pg95db。这些模块应该导出以下几个名称

modulename(connection_string)

用于创建与数据库连接的构造函数。返回一个连接对象。

error

数据库模块错误引发的异常。

连接对象

连接对象应该响应以下方法

close()

立即关闭连接（而不是在 __del__ 被调用时关闭）。从这一点开始，连接将不可用；如果尝试使用连接执行任何操作，将引发异常。

commit()

将任何挂起的交易提交到数据库。

rollback()

将数据库回滚到任何挂起交易的开始。

cursor()

返回一个新的游标对象。如果数据库不支持游标概念，可能会抛出异常。

callproc([params])

(注意：此方法尚未定义好。) 使用给定的（可选）参数调用存储的数据库过程。返回存储过程的结果。

(所有游标对象属性和方法)

对于没有游标的数据库以及不需要游标复杂性的简单应用程序，连接对象应该响应游标对象的每个属性和方法。具有游标的数据库可以通过使用隐式、内部游标来实现这一点。

游标对象

这些对象表示一个数据库游标，用于管理提取操作的上下文。

游标对象应该响应以下方法和属性

arraysize

此读写属性指定使用 fetchmany() 一次提取的行数。此值在一次插入多行时也会使用（将元组/列表的元组/列表作为参数值传递给 execute()）。此属性默认值为单行。

请注意，arraysize 是可选的，仅用于提高数据库交互的性能。实现应该在 fetchmany() 方法中观察它，但可以自由地一次与数据库交互一行。

description

此只读属性是一个包含 7 个元组的元组。每个 7 个元组包含描述每个结果列的信息：(name, type_code, display_size, internal_size, precision, scale, null_ok)。如果操作不返回行或游标尚未通过 execute() 方法调用过操作，则此属性将为 None。

‘type_code’ 是下面部分指定的 ‘dbi’ 值之一。

注意：这有点变化。通常，7 个元组的前两个项目将始终存在；其他的可能是数据库特定的。

close()

立即关闭游标（而不是在 __del__ 被调用时关闭）。从这一点开始，游标将不可用；如果尝试使用游标执行任何操作，将引发异常。

execute(operation [,params])

执行（准备）数据库操作（查询或命令）。可以提供参数（作为序列（例如元组/列表）），并将绑定到操作中的变量。变量在基于数据库的特定符号中指定，该符号基于参数元组中的索引（基于位置而不是基于名称）。

参数也可以指定为序列的序列（例如元组列表），以在一个操作中插入多行。

游标将保留对操作的引用。如果再次传递相同的操作对象，则游标可以优化其行为。这对于使用相同操作但将其绑定到不同参数（多次）的算法最有效。

为了在重用操作时获得最大效率，最好使用 setinputsizes() 方法提前指定参数类型和大小。参数不匹配预定义信息是合法的；实现应该进行补偿，可能会降低效率。

使用 SQL 术语，这些是 execute() 方法的可能结果值

• 如果语句是 DDL（例如 CREATE TABLE），则返回 1。
• 如果语句是 DML（例如 UPDATE 或 INSERT），则返回受影响的行数（0 或正整数）。
• 如果语句是 DQL（例如 SELECT），则返回 None，表示语句尚未完成，直到使用其中一种 ‘fetch’ 方法。

fetchone()

提取查询结果的下一行，返回单个元组。

fetchmany([size])

提取查询结果的下一组行，返回一个元组列表。当没有更多行可用时，返回一个空列表。要提取的行数由参数指定。如果它为 None，则游标的 arraysize 决定要提取的行数。

请注意，size 参数涉及性能考虑。为了获得最佳性能，通常最好使用 arraysize 属性。如果使用 size 参数，那么最好让它从一次 fetchmany() 调用到下一次调用保持相同的值。

fetchall()

提取查询结果的所有行，返回一个元组列表。请注意，游标的 arraysize 属性会影响此操作的性能。

setinputsizes(sizes)

(注意：此方法尚未定义好。) 这可以在调用 execute() 之前使用，以预定义操作参数的内存区域。sizes 指定为元组——每个输入参数一个项目。该项目应该是与将使用的输入相对应的 Type 对象，或者它应该是指定字符串参数最大长度的整数。如果该项目为 None，则不会为该列预留预定义的内存区域（这对于避免为大型输入预留预定义区域很有用）。

此方法将在调用 execute() 方法之前使用。

请注意，此方法是可选的，仅用于提高数据库交互的性能。实现可以自由地不做任何事情，用户也可以自由地不使用它。

setoutputsize(size [,col])

(注意：此方法尚未定义好。)

为提取大型列（例如 LONG）设置列缓冲区大小。列指定为结果元组中的索引。使用值为 None 的列将设置游标中所有大型列的默认大小。

此方法将在调用 execute() 方法之前使用。

请注意，此方法是可选的，仅用于提高数据库交互的性能。实现可以自由地不做任何事情，用户也可以自由地不使用它。

DBI 辅助对象

许多数据库需要以特定格式输入才能绑定到操作的输入参数。例如，如果输入的目标是 DATE 列，那么它必须以特定的字符串格式绑定到数据库。类似的问题存在于 “行 ID” 列或大型二进制项（例如 blob 或 RAW 列）。这给 Python 带来了问题，因为 execute() 方法的参数是无类型的。当数据库模块看到一个 Python 字符串对象时，它不知道它应该绑定为简单的 CHAR 列、原始二进制项还是 DATE。

为了克服这个问题，创建了 ‘dbi’ 模块。此模块指定了一些用于处理数据库的基本数据库接口类型。有两个类：‘dbiDate’ 和 ‘dbiRaw’。这些是简单的容器类，封装了一个值。当传递给数据库模块时，模块可以检测到输入参数是作为 DATE 还是 RAW。为了对称性，数据库模块将返回 DATE 和 RAW 列作为这些类的实例。

游标对象的 ‘description’ 属性返回有关查询的每个结果列的信息。‘type_code’ 被定义为此模块导出的五种类型之一：STRING、RAW、NUMBER、DATE 或 ROWID。

该模块导出以下名称

dbiDate(value)

此函数构造一个 ‘dbiDate’ 实例，该实例保存日期值。该值应指定为自 “纪元” 以来（例如 time.time()）的秒数。

dbiRaw(value)

此函数构造一个 ‘dbiRaw’ 实例，该实例保存原始（二进制）值。该值应指定为 Python 字符串。

STRING

此对象用于描述数据库中基于字符串的列（例如 CHAR）。

RAW

此对象用于描述数据库中（大型）二进制列（例如 LONG RAW、blob）。

NUMBER

此对象用于描述数据库中的数字列。

DATE

此对象用于描述数据库中的日期列。

ROWID

此对象用于描述数据库中的 “行 ID” 列。

鸣谢

非常感谢 Andrew Kuchling，他在 2001 年将 Python 数据库 API 规范 1.0 从原始 HTML 格式转换为 PEP 格式。

Greg Stein 是 Python 数据库 API 规范 1.0 的最初作者。Marc-André 后来作为编辑继续维护该 API。

版权

本文件已置于公有领域。