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