DBAPI/驱动管理器示例

这些示例展示了 ADBC Python 库的通用功能，这些功能不一定特定于任何一个驱动。

直接使用底层绑定

示例源码: driver_manager_lowlevel.py

虽然推荐使用 DB-API 绑定进行通用使用，但也提供了底层绑定。 这些主要直接镜像 ADBC C API。 它们可以用于选择退出 DB-API 包装器的一些行为。

import pyarrow

import adbc_driver_manager
import adbc_driver_sqlite

驱动程序包仍然具有创建根 AdbcDatabase 对象的便利功能。

db: adbc_driver_manager.AdbcDatabase = adbc_driver_sqlite.connect()

然后必须将数据库包装在 AdbcConnection 中。 这在范围上类似于 DB-API Connection 类。

conn = adbc_driver_manager.AdbcConnection(db)

最后，我们可以将连接包装在 AdbcStatement 中，它大致对应于 DB-API Cursor 类。

stmt = adbc_driver_manager.AdbcStatement(conn)

现在我们可以直接设置查询。 与常规 DB-API 绑定不同，这不会准备语句。 （根据驱动程序的不同，这可能会或可能不会有所不同，尤其是在多次执行同一查询的情况下。）

stmt.set_sql_query("SELECT 1 AS THEANSWER")

当我们执行查询时，我们会得到一个 Arrow C Stream Interface 句柄（包装为 PyCapsule），我们需要使用像 PyArrow 这样的库导入它。

handle, rowcount = stmt.execute_query()

SQLite 驱动程序不知道结果集的前端行数（其他驱动程序，例如 PostgreSQL 驱动程序，可能知道）。

assert rowcount == -1

我们可以使用 PyArrow API 读取结果。

reader = pyarrow.RecordBatchReader.from_stream(handle)
assert reader.schema == pyarrow.schema([("THEANSWER", "int64")])

最后，我们必须清理所有对象。 （它们也支持上下文管理器协议。）

stmt.close()
conn.close()
db.close()

手动准备语句

示例源码: driver_manager_prepare.py

DBAPI 绑定在执行之前准备所有语句，因为这是 DB-API 规范 的一部分。

对操作的引用将由游标保留。 如果再次传入相同的操作对象，则游标可以优化其行为。

但是，您可能希望自己准备语句，主要是因为这将为您提供参数的模式（如果服务器支持）。 这可以使用 Cursor.adbc_prepare 完成。

我们将使用 SQLite 驱动程序演示这一点，尽管其他驱动程序也支持它。

import pyarrow

import adbc_driver_sqlite.dbapi

conn = adbc_driver_sqlite.dbapi.connect()

with conn.cursor() as cur:
    param_schema = cur.adbc_prepare("SELECT ? + 1")
    assert param_schema == pyarrow.schema([("0", "null")])

请注意，此处的参数类型为 NULL，因为驱动程序不知道确切的类型。

如果我们现在使用参数执行相同的查询，则不会再次准备语句。

    cur.execute("SELECT ? + 1", parameters=(1,))
    assert cur.fetchone() == (2,)

    cur.execute("SELECT ? + 1", parameters=(41,))
    assert cur.fetchone() == (42,)

conn.close()