gizmosql-adbc

gizmosql-adbc-ci Go Reference Go Version Supported Python Versions PyPI version PyPI Downloads License

Native ADBC driver for GizmoSQL, written in Go, with Python bindings — the successor to adbc-driver-gizmosql 1.x.

Status: released. adbc-driver-gizmosql 2.0 ships from this repo — pip install adbc-driver-gizmosql gets the Go-backed driver with the same API as 1.x (migration guide).

Why a Go driver?

The GizmoSQL-specific behavior that today lives in the 1.x Python package — DDL/DML auto-detection and immediate execution (GizmoSQL's lazy-execution model), RETURNING handling, and the OAuth/SSO browser flow — moves into a native Go ADBC driver built on apache/arrow-adbc's Flight SQL driver. Compiled to a C shared library, one implementation then serves every ADBC language: Python, Go, R, C/C++, C#, Rust, and JavaScript.

Layout

go/       Go driver (wraps arrow-adbc's flightsql driver) + cgo C exports
python/   Python bindings — ships libadbc_driver_gizmosql in its wheels,
          keeps the 1.x dbapi.connect() API byte-compatible (PyPI:
          adbc-driver-gizmosql 2.0)
docs/     Design plan and work plan

Features

  • gizmosql:// URI scheme — TLS by default, ?transport=tcp for plaintext
  • DDL/DML auto-detection → immediate server-side execution (DoPut) under GizmoSQL's lazy-execution model, with INSERT/UPDATE/DELETE ... RETURNING eagerly materialized on the query path
  • OAuth/SSO code-exchange flow (/oauth/initiate → browser → /oauth/token/{uuid}), including a headless mode — from any language via adbc.gizmosql.* options
  • Everything the upstream Flight SQL driver provides: TLS, cookies, timeouts, connection profiles, OpenTelemetry tracing and logging
  • Python bindings keeping the 1.x adbc-driver-gizmosql API byte-compatible — the verbatim 1.x test suite is this repo's release gate (migration guide)

See docs/plan.md for the design and docs/WORKPLAN.md for build-out progress.

Usage (Go)

Start a GizmoSQL server

Start a GizmoSQL server in Docker (mounts a small TPC-H database by default):

docker run --name gizmosql \
           --detach \
           --rm \
           --tty \
           --init \
           --publish 31337:31337 \
           --env TLS_ENABLED="1" \
           --env GIZMOSQL_USERNAME="gizmosql_user" \
           --env GIZMOSQL_PASSWORD="gizmosql_password" \
           --env PRINT_QUERIES="1" \
           --pull missing \
           gizmodata/gizmosql:latest

Install

go get github.com/gizmodata/gizmosql-adbc/go@latest

(The Go module is versioned by go/vX.Y.Z tags — its own line, independent of this repo's Python/release v* tags.)

Password authentication

package main

import (
	"context"
	"fmt"

	"github.com/apache/arrow-go/v18/arrow/memory"
	"github.com/gizmodata/gizmosql-adbc/go/gizmosql"
)

func main() {
	ctx := context.Background()

	drv := gizmosql.NewDriver(memory.DefaultAllocator)
	db, err := drv.NewDatabase(map[string]string{
		"uri":      "gizmosql://localhost:31337", // TLS by default
		"username": "gizmosql_user",
		"password": "gizmosql_password",
		// Development only — trust the demo server's self-signed cert:
		"adbc.flight.sql.client_option.tls_skip_verify": "true",
	})
	if err != nil {
		panic(err)
	}
	defer db.Close()

	cnxn, err := db.Open(ctx)
	if err != nil {
		panic(err)
	}
	defer cnxn.Close()

	stmt, err := cnxn.NewStatement()
	if err != nil {
		panic(err)
	}
	defer stmt.Close()

	if err := stmt.SetSqlQuery(
		"SELECT n_nationkey, n_name FROM nation ORDER BY n_nationkey LIMIT 5",
	); err != nil {
		panic(err)
	}
	reader, _, err := stmt.ExecuteQuery(ctx)
	if err != nil {
		panic(err)
	}
	defer reader.Release()

	for reader.Next() {
		fmt.Println(reader.Record())
	}
}

URI schemes

The preferred way to connect is the gizmosql:// URI scheme, which is secure by default (gRPC with TLS):

URI Meaning
gizmosql://host:31337 gRPC with TLS (default)
gizmosql://host:31337?transport=tls gRPC with TLS (explicit)
gizmosql://host:31337?transport=tcp gRPC plaintext (no TLS)
grpc+tls://host:31337 Legacy TLS spelling (still supported)
grpc+tcp://host:31337 / grpc://host:31337 Legacy plaintext spellings (still supported)
flightsql://host:31337 Upstream Flight SQL spelling (still supported)

Observability: OpenTelemetry tracing & logging

Inherited from the upstream Flight SQL driver — trace spans are emitted for Database.Open, Prepare, ExecuteQuery, and ExecuteUpdate:

Option key (database options) Description
adbc.telemetry.traces_exporter Exporter: none, otlp, console, or adbcfile
adbc.telemetry.traces_folder_path Output directory for the adbcfile exporter
adbc.telemetry.trace_parent W3C Trace Context traceparent — join an existing distributed trace

With the otlp exporter, the standard OTEL_EXPORTER_OTLP_* environment variables configure the collector endpoint. Structured driver logging is enabled via ADBC_DRIVER_FLIGHTSQL_LOG_LEVEL (debug/info/warn/error).

DDL/DML — auto-detected and executed immediately

GizmoSQL plans queries lazily: the Flight SQL GetFlightInfo RPC only plans, so DDL/DML submitted through the normal query path never executes unless the result is fetched. This driver detects DDL/DML statements (first keyword, comments stripped) and routes them through ExecuteUpdate (DoPut) for immediate server-side execution — no fetch required. INSERT/UPDATE/DELETE ... RETURNING takes the query path with the result eagerly materialized, so the DML fires even if you never read the returned reader — matching the 1.x Python driver and the GizmoSQL JDBC/ODBC drivers:

stmt.SetSqlQuery("CREATE TABLE t (id INT)")
_, _, _ = stmt.ExecuteQuery(ctx) // executes immediately via DoPut

stmt.SetSqlQuery("INSERT INTO t VALUES (1), (2)")
_, affected, _ := stmt.ExecuteQuery(ctx) // affected == 2, already executed

Routing applies to plain SQL only — statements with bound parameters (Bind/BindStream) or Substrait plans use standard prepared-statement semantics.

OAuth/SSO authentication

When your GizmoSQL server is configured with OAuth, set adbc.gizmosql.auth_type to external — the driver initiates the flow, opens your browser to the identity provider, polls for completion, and connects with the identity token via Basic Auth (username token):

db, err := drv.NewDatabase(map[string]string{
	"uri":                     "gizmosql://gizmosql.example.com:31337",
	"adbc.gizmosql.auth_type": "external",
})
Option key Default Description
adbc.gizmosql.auth_type password password or external (OAuth/SSO)
adbc.gizmosql.oauth.url (discovered) Explicit OAuth base URL; otherwise probed from the connection host (HTTPS, then HTTP)
adbc.gizmosql.oauth.port 31339 OAuth HTTP port used for discovery
adbc.gizmosql.oauth.timeout_seconds 300 Max seconds to wait for the user to complete auth
adbc.gizmosql.oauth.poll_interval_seconds 1 Delay between token polls
adbc.gizmosql.oauth.open_browser true false prints the auth URL to stderr instead (headless)
adbc.gizmosql.oauth.tls_skip_verify (follows Flight SQL setting) Skip TLS verification for the OAuth HTTP server

Go-native callers can also run the flow directly — including fully headless with a custom URL handler — via gizmosql.GetOAuthToken:

result, err := gizmosql.GetOAuthToken(ctx, gizmosql.OAuthConfig{
	Host:           "gizmosql.example.com",
	AuthURLHandler: func(u string) { fmt.Println("authenticate at:", u) },
})
// result.Token → use as password with username "token"

Usage (any language, via driver manifest)

Build (or download from a release) the shared library, then install a driver manifest so every ADBC driver manager can load the driver by name:

make -C go lib   # produces go/build/libadbc_driver_gizmosql.{so,dylib,dll}

Copy packaging/gizmosql.toml.in to a driver search path as gizmosql.toml (e.g. ~/.config/adbc/drivers/ on Linux, ~/Library/Application Support/ADBC/Drivers/ on macOS, or any directory in ADBC_DRIVER_PATH), filling in the library path. Then:

# Python — no GizmoSQL-specific package needed:
import adbc_driver_manager.dbapi as dbapi

with dbapi.connect(driver="gizmosql", db_kwargs={
    "uri": "gizmosql://localhost:31337",
    "username": "gizmosql_user",
    "password": "gizmosql_password",
}) as conn:
    ...

The same driver = "gizmosql" reference works everywhere the ADBC driver manager does — with DDL/DML immediacy, RETURNING handling, gizmosql:// URIs, and OAuth all provided by the shared library. Verified against the Columnar ADBC QuickStarts gizmosql examples (see docs/quickstarts-conformance.md):

// Go via the C driver manager (github.com/apache/arrow-adbc/go/adbc/drivermgr)
var drv drivermgr.Driver
db, err := drv.NewDatabase(map[string]string{
    "driver":   "gizmosql",
    "uri":      "gizmosql://localhost:31337",
    "username": "gizmosql_user",
    "password": "gizmosql_password",
})

# R
library(adbcdrivermanager)
db <- adbc_database_init(
  adbc_driver("gizmosql"),
  uri = "gizmosql://localhost:31337",
  username = "gizmosql_user",
  password = "gizmosql_password"
)

// C/C++ (adbc_driver_manager.h)
AdbcDatabaseSetOption(&database, "driver", "gizmosql", &error);
AdbcDatabaseSetOption(&database, "uri", "gizmosql://localhost:31337", &error);

Or reference it from a connection profile usable in every language:

profile_version = 1

[Options]
driver = "gizmosql"
uri = "gizmosql://gizmosql.example.com:31337"
username = "gizmosql_user"
password = "{{ env_var(GIZMOSQL_PASSWORD) }}"

Usage (Python)

Until 2.0 ships from this repo, use the 1.x driver: pip install adbc-driver-gizmosql — see its README for full usage (the 2.0 bindings will keep that API byte-compatible).

License

Apache License 2.0 — see LICENSE.

Project links

Data verified by PyPI on Jul 29, 2026
Data provided by the project maintainers, verified at the time the release was uploaded to PyPI.

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Newer release available (2.0.13)

Owner

PyPI data
Data sourced directly from PyPI's database.

Credits

Author: GizmoData

GitHub Statistics

Data verified by PyPI on Jul 29, 2026
The GitHub source repository was provided by the project maintainers and verified by PyPI at the time of upload. Stars, forks, and open issues/PRs are derived from that repository and have not been independently verified.

License expression

Apache-2.0
View SPDX License List

Requires

Python >=3.10

Provides Extra

test dev

Classifiers

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distributions

No source distribution files available for this release.See tutorial on generating distribution archives.

Built Distributions

If you're not sure about the file name format, learn more about wheel file names.

adbc_driver_gizmosql-2.0.1-py3-none-win_arm64.whl (13.5 MB view details)

Uploaded Python 3Windows ARM64

adbc_driver_gizmosql-2.0.1-py3-none-win_amd64.whl (14.9 MB view details)

Uploaded Python 3Windows x86-64

adbc_driver_gizmosql-2.0.1-py3-none-manylinux_2_34_x86_64.whl (15.1 MB view details)

Uploaded Python 3manylinux: glibc 2.34+ x86-64

adbc_driver_gizmosql-2.0.1-py3-none-manylinux_2_34_aarch64.whl (13.8 MB view details)

Uploaded Python 3manylinux: glibc 2.34+ ARM64

adbc_driver_gizmosql-2.0.1-py3-none-macosx_11_0_x86_64.whl (8.2 MB view details)

Uploaded Python 3macOS 11.0+ x86-64

adbc_driver_gizmosql-2.0.1-py3-none-macosx_11_0_universal2.whl (7.6 MB view details)

Uploaded Python 3macOS 11.0+ universal2 (ARM64, x86-64)

File details

Details for the file adbc_driver_gizmosql-2.0.1-py3-none-win_arm64.whl.

File metadata

File hashes

Hashes for adbc_driver_gizmosql-2.0.1-py3-none-win_arm64.whl
Algorithm Hash digest
SHA256 a779e5fab051d153e0ba10ff5783ce790357d5bab6d7037e2b99685fe3e28c39
MD5 776c67b01e88b55bca4dd186fff82b82
BLAKE2b-256 5589265c3997ea35bd75cec9f510515b8381b320dfabda78fb019f98f9659434

See more details on using hashes here.

Provenance

The following attestation bundles were made for adbc_driver_gizmosql-2.0.1-py3-none-win_arm64.whl:

Publisher: release.yml on gizmodata/gizmosql-adbc

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file adbc_driver_gizmosql-2.0.1-py3-none-win_amd64.whl.

File metadata

File hashes

Hashes for adbc_driver_gizmosql-2.0.1-py3-none-win_amd64.whl
Algorithm Hash digest
SHA256 cec1b40ba7bdf3caf8fad0843871e46283de35c17e7137a2343c09e940617241
MD5 00330fef2fc9a9a090ff1bea1beafa26
BLAKE2b-256 07e88c0c143821e14c51b58c8dc4f511a2df645be20ddc487118661afc2c4cc1

See more details on using hashes here.

Provenance

The following attestation bundles were made for adbc_driver_gizmosql-2.0.1-py3-none-win_amd64.whl:

Publisher: release.yml on gizmodata/gizmosql-adbc

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file adbc_driver_gizmosql-2.0.1-py3-none-manylinux_2_34_x86_64.whl.

File metadata

File hashes

Hashes for adbc_driver_gizmosql-2.0.1-py3-none-manylinux_2_34_x86_64.whl
Algorithm Hash digest
SHA256 7443416e8c35d8eda3b85d05686edbe42ba84c8ece90148d54edae3eb5e1eafa
MD5 5d77766a44effd0ef9b1ee1d4bb402ae
BLAKE2b-256 e3154c2c5085d9c3830da321deef3af1b779358790833b9c5ed360bd3cd54298

See more details on using hashes here.

Provenance

The following attestation bundles were made for adbc_driver_gizmosql-2.0.1-py3-none-manylinux_2_34_x86_64.whl:

Publisher: release.yml on gizmodata/gizmosql-adbc

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file adbc_driver_gizmosql-2.0.1-py3-none-manylinux_2_34_aarch64.whl.

File metadata

File hashes

Hashes for adbc_driver_gizmosql-2.0.1-py3-none-manylinux_2_34_aarch64.whl
Algorithm Hash digest
SHA256 b17a30c42e7aa2ec28080d94c4aeb9c590252734b97b17dfbfa749e5aee71949
MD5 d13eaea49d4ada9d939fbae4ae128b5c
BLAKE2b-256 120c38a48894884d3179f6090333ee5d36aab4adb342c104fc7b15c9d8d873f6

See more details on using hashes here.

Provenance

The following attestation bundles were made for adbc_driver_gizmosql-2.0.1-py3-none-manylinux_2_34_aarch64.whl:

Publisher: release.yml on gizmodata/gizmosql-adbc

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file adbc_driver_gizmosql-2.0.1-py3-none-macosx_11_0_x86_64.whl.

File metadata

File hashes

Hashes for adbc_driver_gizmosql-2.0.1-py3-none-macosx_11_0_x86_64.whl
Algorithm Hash digest
SHA256 e92777b4d15d6d9a305a13a8c7c7f56d61bcfab0635232e90bbab9f8607f90de
MD5 166e6ffdb714cb5a00aa13ad54a0becf
BLAKE2b-256 a395281c3fd32d382dbb9593c03086378e8c08d64065368688dee605a324baf6

See more details on using hashes here.

Provenance

The following attestation bundles were made for adbc_driver_gizmosql-2.0.1-py3-none-macosx_11_0_x86_64.whl:

Publisher: release.yml on gizmodata/gizmosql-adbc

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file adbc_driver_gizmosql-2.0.1-py3-none-macosx_11_0_universal2.whl.

File metadata

File hashes

Hashes for adbc_driver_gizmosql-2.0.1-py3-none-macosx_11_0_universal2.whl
Algorithm Hash digest
SHA256 7f69cbc86dd7e24baf10a21749e30be4da4614ee11b739b3c8277db6284e7ab2
MD5 9fa8b8bf4b1dd480bc1ba5fc175248ca
BLAKE2b-256 313a52dab957728379b16c0586e2361f88f74af7f44b849023a38f8966ab05b6

See more details on using hashes here.

Provenance

The following attestation bundles were made for adbc_driver_gizmosql-2.0.1-py3-none-macosx_11_0_universal2.whl:

Publisher: release.yml on gizmodata/gizmosql-adbc

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Release history Release notifications | RSS feed

2.0.13

6 files

2.0.12

6 files

2.0.11

6 files

2.0.10

6 files

2.0.9

6 files

2.0.8

6 files

2.0.7

6 files

2.0.6

6 files

2.0.5

6 files

2.0.4

6 files

2.0.3

6 files

2.0.2

6 files

This release

2.0.1 This release

6 files

2.0.0

6 files

1.3.0

2 files

1.2.0

2 files

1.1.7

2 files

1.1.6

2 files

1.1.5

2 files

1.1.4

2 files

1.1.3

2 files

1.1.2

2 files

1.1.1

2 files

1.1.0

2 files

1.0.5

2 files

1.0.4

2 files

1.0.3

2 files

1.0.2

2 files

1.0.1

2 files

1.0.0

2 files

0.1.1

2 files

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