ExArrow.ADBC.ConnectionPool (ex_arrow v0.4.0)

View Source

NimblePool-backed ADBC connection pool for ExArrow.

Opens a pool of ExArrow.ADBC.Connection handles against a single ExArrow.ADBC.Database, recycling them across callers. This is the recommended approach for applications that issue many concurrent or frequent ADBC queries.

Usage

Add the pool to your supervision tree:

children = [
  # 1. Open the database (once)
  {ExArrow.ADBC.DatabaseServer, name: :mydb, driver_path: "/path/to/libadbc_driver_duckdb.so"},
  # 2. Start a pool of connections against it
  {ExArrow.ADBC.ConnectionPool, name: :mypool, database: :mydb, pool_size: 4}
]
Supervisor.start_link(children, strategy: :one_for_one)

Then call the pool:

{:ok, stream} = ExArrow.ADBC.ConnectionPool.query(:mypool, "SELECT 1 AS n")

Ad-hoc pool

{:ok, db}   = ExArrow.ADBC.Database.open(driver_path: "/path/to/driver.so")
{:ok, pool} = ExArrow.ADBC.ConnectionPool.start_link(database: db, pool_size: 4)

{:ok, stream} = ExArrow.ADBC.ConnectionPool.query(pool, "SELECT 42 AS answer")

Options

  • :database — ExArrow.ADBC.Database.t() or a registered name (atom). Required.
  • :pool_size — number of connections to keep open (default: System.schedulers_online()).
  • :name — optional GenServer-style name for the pool process.
  • :lazy — if true, connections are opened on first checkout rather than at pool start (default: false).

Checkout options (passed as the final keyword list to query/3)

  • :pool_timeout — milliseconds to wait for an available connection (default: 5_000).
  • :timeout — milliseconds for the SQL statement to execute (default: 15_000).

Summary

Functions

query(pool, sql, opts \\ [])

Executes sql using a checked-out connection from pool.

start_link(opts)

Starts a connection pool linked to the current process.

with_connection(pool, fun, opts \\ [])

Runs fun.(conn) with a checked-out ExArrow.ADBC.Connection.t().

Functions

query(pool, sql, opts \\ [])

@spec query(term(), String.t(), keyword()) ::
  {:ok, ExArrow.Stream.t()} | {:error, term()}

Executes sql using a checked-out connection from pool.

Returns {:ok, ExArrow.Stream.t()} where the stream has already been fully collected into memory so the connection can be returned to the pool immediately. Use ExArrow.Stream.to_list/1 to decode the batches.

Options

  • :pool_timeout — ms to wait for a connection (default 5_000).
  • :timeout — ms allowed for statement execution (default 15_000).

start_link(opts)

@spec start_link(keyword()) :: {:ok, pid()} | {:error, term()}

Starts a connection pool linked to the current process.

See the module doc for accepted options.

with_connection(pool, fun, opts \\ [])

@spec with_connection(
  term(),
  (ExArrow.ADBC.Connection.t() -> {term(), :ok | {:remove, term()}}),
  keyword()
) :: term()

Runs fun.(conn) with a checked-out ExArrow.ADBC.Connection.t().

Use this for multi-statement operations or metadata calls that do not fit the single-SQL query/3 API. fun must return {result, checkin_tag} where checkin_tag is :ok (reuse the connection) or {:remove, reason} (discard and replace it).

Example

ExArrow.ADBC.ConnectionPool.with_connection(pool, fn conn ->
  {:ok, stmt} = ExArrow.ADBC.Statement.new(conn)
  ExArrow.ADBC.Statement.set_sql(stmt, "SELECT 1")
  {ExArrow.ADBC.Statement.execute(stmt), :ok}
end)