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