Grainlift ADBC Gateway

Serve your database over the network. Keep the standard ADBC API.

Grainlift makes server-installed database drivers available to remote applications through Apache Arrow ADBC. Keep native drivers and database credentials on the server while clients use ordinary ADBC connections, SQL, transactions, and Arrow results.

grainlift-adbc-gateway packages the Rust gateway executable and installs Apache's SQLite ADBC driver as a dependency. Python launches the server; query execution runs in Rust and the downstream driver. Supported platform wheels need no Rust toolchain. Python 3.13 or newer is required.

• Start with SQLite: serve a local database with one command.
• Keep Arrow results: clients pull record batches from server-side cursors.
• Control access centrally: configure authentication, target permissions, credentials, and resource limits at the gateway.
• Use other ADBC databases: install their drivers on the server and define targets in a configuration file. Capabilities depend on the downstream driver.

Start a gateway

With uv, serve an existing SQLite database:

uvx grainlift-adbc-gateway serve sqlite ./database.sqlite

To create a new database, add --create:

uvx grainlift-adbc-gateway serve sqlite ./database.sqlite --create

The gateway listens on 127.0.0.1:8080, exposes target sqlite, and creates a random bearer token in .grainlift-token in the current directory. Later starts reuse that token file. The token is never printed; keep it private and out of source control. On Windows, restrict the directory's ACL to the service account. Database and token parent directories must already exist.

For a persistent command, install with uv tool install grainlift-adbc-gateway or pip install grainlift-adbc-gateway, then run grainlift-adbc-gateway directly.

Query from Python

In your client environment, install the Grainlift ADBC client and PyArrow:

pip install adbc-driver-grainlift pyarrow

With the gateway running, execute this from its working directory so the example can read .grainlift-token:

from pathlib import Path

import adbc_driver_grainlift.dbapi as adbc

with adbc.connect(
    db_kwargs={
        "grainlift.uri": "grainlift+http://127.0.0.1:8080",
        "grainlift.target": "sqlite",
        "grainlift.auth.bearer_token": Path(".grainlift-token").read_text().strip(),
    },
    autocommit=True,
) as connection:
    with connection.cursor() as cursor:
        cursor.execute("SELECT 42 AS answer")
        print(cursor.fetch_arrow_table())

Other ADBC applications can load the native Grainlift client driver directly. See the Python client guide and the DuckDB example.

Configure a deployment

The SQLite shorthand uses loopback HTTP. For remote access, multiple databases, or transport and authentication settings, use a configuration file:

grainlift-adbc-gateway check --config grainlift.toml
grainlift-adbc-gateway serve --config grainlift.toml

Start with the example configuration. check validates configuration and policy without loading drivers or connecting to databases. Configured deployments support HTTP(S), loopback TCP, mTLS TCP, and authenticated Iroh QUIC, with server-controlled database options and quotas.

Grant access only to callers trusted to use the configured database: the gateway is not a SQL or filesystem sandbox. Sessions, transactions, and live result cursors belong to one server process, so replicated deployments require session affinity. A server restart invalidates its sessions.

Read the security guide and process isolation guidance before deploying. Downstream drivers determine supported operations; see the known limitations for cancellation and native-driver caveats.

Choose the right package

Documentation and support

• CLI reference: token files, listener options, Iroh identities, and source builds.
• Project overview: architecture and use cases.
• Source code and issue tracker.

An open source Query Farm project, licensed under Apache 2.0.