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

由于 DB-API 规范 的这一部分，DBAPI 绑定会在执行前预处理所有语句。

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

但是，您可能希望自己预处理语句，主要是因为这可以为您提供参数的模式（如果服务器支持）。这可以通过 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()