Skip to main content

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/.

PyPI version Python versions Downloads License CI Docs

📖 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.uri)            # gizmosql://127.0.0.1:42173?transport=tcp
    print(srv.username, srv.password)
    # ... point any GizmoSQL driver (ADBC, JDBC, ...) at srv.uri ...

srv.uri is the gizmosql:// connection URI that GizmoSQL drivers understand (gizmosql:// is TLS by default; ?transport=tcp marks the plaintext loopback endpoint this wrapper starts). For a generic Flight SQL client that only knows the gRPC schemes (e.g. pyarrow.flight), use srv.url instead: grpc+tcp://127.0.0.1:42173.

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

# Try the edge channel (GizmoSQL v1.41.0+): the next DuckDB major, pre-release
# (today DuckDB 2.0). EXPERIMENTAL — not for production workloads; database
# files it creates can't be opened by the stable or LTS channels.
gizmosql.Server(password="tiger", channel="edge")

# 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.uri (or srv.url, for a raw Flight SQL client) to whatever
    # client you're testing.
    my_client.connect(gizmosql_server.uri, "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

Variable Purpose
GIZMOSQL_CACHE_DIR Override the binary cache root (default: ~/.cache/gizmosql/ on POSIX, %LOCALAPPDATA%\gizmosql\Cache on Windows).
GIZMOSQL_VERSION Default server version when Server(version=...) is unset.
GIZMOSQL_RELEASE_REPO GitHub repo to download releases from (default gizmodata/gizmosql).
GIZMOSQL_RELEASE_BASE_URL Full base URL override; for testing against a staging release page.

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. The macOS binaries of GizmoSQL v1.41.0+ require macOS 15 (Sequoia) or later.

License

Apache-2.0, matching the main GizmoSQL project.

Metadata

Release files for gizmosql 1.42.2

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for gizmosql 1.42.2
File Size Uploaded Provenance Actions
gizmosql-1.42.2.tar.gz 17.8 kB With provenance Details for gizmosql-1.42.2.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for gizmosql 1.42.2
File Interpreter ABI Platform Actions
gizmosql-1.42.2-py3-none-any.whl Python 3 none any Details for gizmosql-1.42.2-py3-none-any.whl

Total release size: 33.6 kB

Release files / gizmosql-1.42.2.tar.gz

Download URL gizmosql-1.42.2.tar.gz
Size 17.8 kB
Tags Source
SHA-256 checksum
How to use checksums
d8b0333127d9072336dbd35d3a8a994f3efb40c721182699e1ea35dd1ce1a86d
BLAKE2b-256 checksum
How to use checksums
13ae73e9cd8eaf86a8d34050d43326dab57959f846b465bbcef62367ac1d3dd1
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 27, 2026.

Transparency log

Release files / gizmosql-1.42.2-py3-none-any.whl

Download URL gizmosql-1.42.2-py3-none-any.whl
Size 15.8 kB
Tags Python 3
SHA-256 checksum
How to use checksums
b0bf8e496e99b7bd9267d1300c38a0b71ed535eade20f8630950951d940b744c
BLAKE2b-256 checksum
How to use checksums
861ab028ed41fe460eb550c63e0ed7ac5c7aad589eff47feb40f9ccf7b7b0e3f
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 27, 2026.

Transparency log

Security for gizmosql 1.42.2

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for gizmosql-1.42.2.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 27, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

1.42.2 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page