gizmosql

Run a GizmoSQL Flight SQL server as a managed subprocess from Python — no compile toolchain required, no ahead-of-time install step. The matching gizmosql_server binary is downloaded from GitHub Releases on first use and cached under ~/.cache/gizmosql/.

📖 Full reference: docs.gizmosql.com/#/python_library — covers all Server() parameters, the pytest fixture pattern, the multi-agent pattern, environment variables, and limitations. This README is a quick tour; the docs page is the authoritative reference.

Why?

GizmoSQL is a network endpoint — Apache Arrow Flight SQL on top of DuckDB. The point of running it from Python isn't to talk to it from the same process (the duckdb package is better at that), it's to expose a SQL endpoint to other things:

• pytest fixtures that exercise a real Flight SQL server in CI
• Multi-tool / multi-agent workflows where the Python process is the orchestrator and other tools (a JDBC driver, Power BI, AI agents, a separate worker) all connect to the same server
• Notebook demos that need a live server while showing client-side code
• "Expose this DuckDB file to the network" — three lines of Python and any Flight SQL client can query it

Install

pip install gizmosql
# or, with the optional ADBC client for Server.connect():
pip install 'gizmosql[adbc]'

The package itself has zero runtime dependencies. The gizmosql_server binary is fetched on first use (~10 MB compressed); subsequent starts use the cached copy.

Quick start

import gizmosql

with gizmosql.Server(password="tiger") as srv:
    print(srv.url)            # grpc+tcp://127.0.0.1:42173
    print(srv.username, srv.password)
    # ... point any Flight SQL client at srv.url ...

The context manager:

1. Downloads the matching server binary on first use.
2. Picks a free TCP port (so multiple parallel test workers don't collide).
3. Starts the subprocess and blocks until it's accepting connections.
4. SIGTERMs it on exit, escalating to SIGKILL if it doesn't respond.

From the same Python process (optional)

With the adbc extra, you can also query the server from the same Python that started it:

import gizmosql

with gizmosql.Server(password="tiger") as srv:
    with srv.connect() as conn, conn.cursor() as cur:
        cur.execute("SELECT GIZMOSQL_VERSION(), GIZMOSQL_EDITION()")
        print(cur.fetchall())

ADBC connectivity is provided by adbc-driver-gizmosql 2.0, powered by the new native Go GizmoSQL ADBC driver. Same API as before, with DDL/DML immediate execution, RETURNING support, gizmosql:// URIs, and OAuth/SSO provided by the shared Go driver library.

Common configurations

# Persistent on-disk database with the TPC-H sample loaded at startup.
gizmosql.Server(
    password="tiger",
    database_filename="warehouse.duckdb",
    init_sql_commands="CALL dbgen(sf=1);",  # ~1 GB on disk
)

# Pin the LTS channel (DuckDB LTS release).
gizmosql.Server(password="tiger", channel="lts")

# Pin a specific version (overrides the package's default version).
gizmosql.Server(password="tiger", version="v1.25.1")

# Listen on all interfaces (default is loopback only).
gizmosql.Server(password="tiger", host="0.0.0.0")

# Forward arbitrary CLI flags to gizmosql_server.
gizmosql.Server(
    password="tiger",
    extra_args=["--print-queries", "--query-log-level", "debug"],
)

See gizmosql_server --help (in the cached binary) for the full set of CLI flags — anything passed via extra_args is forwarded verbatim.

Versioning

gizmosql==X.Y.Z ships in lock-step with the matching GizmoSQL server tag vX.Y.Z — that's the version it'll download and run unless you override with version="...". Python-only patches (rare) use PEP 440 .postN suffixes, e.g. 1.25.1.post1.

pytest fixture pattern

# conftest.py
import pytest
import gizmosql

@pytest.fixture(scope="session")
def gizmosql_server(tmp_path_factory):
    db = tmp_path_factory.mktemp("gizmosql") / "test.duckdb"
    with gizmosql.Server(password="testpw", database_filename=str(db)) as srv:
        yield srv

# test_my_app.py
def test_my_jdbc_client_can_query(gizmosql_server):
    # Hand srv.url to whatever client you're testing.
    my_client.connect(gizmosql_server.url, "gizmosql", "testpw")
    ...

The session scope reuses the server across the whole run; ports are auto-picked, so parallel pytest-xdist workers don't collide.

Environment variables

Limitations

• Subprocess only (no in-process / FFI mode in v1). The server runs in its own process and clients (including Server.connect()) talk to it over the loopback Flight SQL endpoint. This is the right architecture for the intended use cases — see Why? above.
• Pre-built binaries exist for: macOS arm64, Linux amd64, Linux arm64, Windows amd64, Windows arm64. Other platforms aren't supported.

Links

• 📖 Python Library reference — full API + patterns
• 🌐 Product page
• 📦 Install picker (CLI, Homebrew, Docker, Python)
• 🚀 Quick Start guide
• 📚 GizmoSQL documentation
• 🦆 LTS Channel guide
• 🐛 Issues / requests

License

Apache-2.0, matching the main GizmoSQL project.