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 流接口 处理程序（包装为 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()