🚀 GizmoSQL — High-Performance SQL Server for the Cloud

🌟 What is GizmoSQL?

GizmoSQL is a lightweight, high-performance SQL server built on:

🦆 DuckDB or 🗃️ SQLite for query execution
🚀 Apache Arrow Flight SQL for fast, modern connectivity
🔒 Middleware-based auth with optional TLS & JWT

Originally forked from sqlflite — and now enhanced into a more extensible, production-ready platform under the Apache 2.0 license.

📦 Editions

GizmoSQL is available in two editions:

| Feature | Core | Enterprise | |---------|:----:|:----------:| | DuckDB & SQLite backends | ✅ | ✅ | | Arrow Flight SQL protocol | ✅ | ✅ | | TLS & mTLS authentication | ✅ | ✅ | | JWT token authentication | ✅ | ✅ | | Query timeout | ✅ | ✅ | | Session Instrumentation | ❌ | ✅ | | Kill Session | ❌ | ✅ | | Per-Catalog Permissions | ❌ | ✅ | | SSO/OIDC Authentication (JWKS) | ❌ | ✅ | | Authorized Email Filtering | ❌ | ✅ |

GizmoSQL Core is free and open source under the Apache 2.0 license.

GizmoSQL Enterprise requires a commercial license. Contact sales@gizmodata.com for licensing information.

For more details, see the Editions documentation.

🧠 Why GizmoSQL?

🛰️ Deploy Anywhere — Run as a container, native binary, or in Kubernetes
📦 Columnar Fast — Leverages Arrow columnar format for high-speed transfers
⚙️ Dual Backends — Switch between DuckDB and SQLite at runtime
🔐 Built-in TLS + Auth — Password-based login + signed JWT tokens
📈 Super Cheap Analytics — TPC-H SF 1000 in 161s for ~$0.17 on Azure
🧪 CLI, Python, JDBC, SQLAlchemy, Ibis, WebSocket — Pick your interface

📦 Component Versions

| Component | Version | |----------------------------------------------------------------------------------|---------| | DuckDB | v1.5.1 | | SQLite | 3.52.0 | | Apache Arrow (Flight SQL) | 23.0.1 | | jwt-cpp | v0.7.2 | | OpenTelemetry C++ | v1.25.0 | | nlohmann/json | v3.12.0 |

📚 Documentation

For detailed instructions and configuration information, see our full documentation:

GizmoSQL Documentation

🚀 Quick Start

Default credentials: The server's default username is gizmosql_user (override with --username or GIZMOSQL_USERNAME). A password is always required via --password or GIZMOSQL_PASSWORD.

Option 1: Run from Docker

# Username defaults to "gizmosql_user" when GIZMOSQL_USERNAME is not set
docker run --name gizmosql \
           --detach \
           --rm \
           --tty \
           --init \
           --publish 31337:31337 \
           --env TLS_ENABLED="1" \
           --env GIZMOSQL_PASSWORD="gizmosql_password" \
           --env PRINT_QUERIES="1" \
           --pull always \
           gizmodata/gizmosql:latest

Option 2: Mount Your Own DuckDB database file

duckdb ./tpch_sf1.duckdb << EOF
INSTALL tpch; LOAD tpch; CALL dbgen(sf=1);
EOF

docker run --name gizmosql \
           --detach \
           --rm \
           --tty \
           --init \
           --publish 31337:31337 \
           --env TLS_ENABLED="1" \
           --env GIZMOSQL_PASSWORD="gizmosql_password" \
           --pull always \
           --mount type=bind,source=$(pwd),target=/opt/gizmosql/data \
           --env DATABASE_FILENAME="data/tpch_sf1.duckdb" \
           gizmodata/gizmosql:latest

Option 3: Install via Homebrew (macOS & Linux)

brew tap gizmodata/tap
brew install gizmosql

Supported platforms:

macOS (Apple Silicon / ARM64)
Linux (x86-64 / AMD64)
Linux (ARM64)

Then run the server (username defaults to gizmosql_user):

GIZMOSQL_PASSWORD="gizmosql_password" gizmosql_server --database-filename your.duckdb --print-queries

Option 4: Windows Installer (MSI)

Download the latest MSI installer from the GitHub Releases page. The installer adds gizmosql_server.exe and gizmosql_client.exe to C:\Program Files\GizmoSQL and updates the system PATH.

Then run the server from PowerShell or Command Prompt:

$env:GIZMOSQL_PASSWORD="gizmosql_password"
gizmosql_server --database-filename your.duckdb --print-queries

🧰 Clients and Tools

🔗 JDBC

Use with DBeaver or other JDBC clients:

jdbc:gizmosql://localhost:31337?useEncryption=true&user=gizmosql_user&password=gizmosql_password&disableCertificateVerification=true

More info: Setup guide

🐍 Python (ADBC)

Prerequisite: Python 3.10+ and the GizmoSQL ADBC driver:

pip install adbc-driver-gizmosql

The driver also supports OAuth/SSO authentication for GizmoSQL Enterprise users.

from adbc_driver_gizmosql import dbapi as gizmosql

with gizmosql.connect(
    "grpc+tls://localhost:31337",
    username="gizmosql_user",
    password="gizmosql_password",
    tls_skip_verify=True,  # Not needed if you use a trusted CA-signed TLS cert
) as conn:
    with conn.cursor() as cur:
        cur.execute(
            "SELECT n_nationkey, n_name FROM nation WHERE n_nationkey = ?",
            parameters=[24],
        )
        x = cur.fetch_arrow_table()

🔑 Token authentication

See: https://github.com/gizmodata/generate-gizmosql-token for an example of how to generate a token and use it with GizmoSQL.

💻 CLI Client

GizmoSQL ships with an interactive SQL shell inspired by psql and the DuckDB CLI:

# Interactive session
GIZMOSQL_PASSWORD="gizmosql_password" gizmosql_client --host localhost --username gizmosql_user --tls --tls-skip-verify

Run a single query with --command:

GIZMOSQL_PASSWORD="gizmosql_password" gizmosql_client \
  --host localhost --username gizmosql_user --tls --tls-skip-verify \
  --command "SELECT version()"

Pipe SQL from a heredoc:

GIZMOSQL_PASSWORD="gizmosql_password" gizmosql_client \
  --host localhost --username gizmosql_user --tls --tls-skip-verify --quiet <<'EOF'
SELECT n_nationkey, n_name
FROM nation
WHERE n_nationkey = 24;
EOF

More info: Client Shell documentation

🏗️ Build from Source (Optional)

git clone https://github.com/gizmodata/gizmosql --recurse-submodules
cd gizmosql
cmake -S . -B build -G Ninja -DCMAKE_INSTALL_PREFIX=/usr/local
cmake --build build --target install

Then run:

GIZMOSQL_PASSWORD="..." gizmosql_server --database-filename ./data/your.db --print-queries

🧪 Advanced Features

✅ DuckDB + SQLite backend support
✅ TLS & optional mTLS
✅ JWT-based auth (automatically issued, signed server-side)
✅ Server initialization via INIT_SQL_COMMANDS or INIT_SQL_COMMANDS_FILE
✅ Slim Docker image for minimal runtime

🛠 Backend Selection

# DuckDB (default)
gizmosql_server -B duckdb --database-filename data/foo.duckdb

# SQLite
gizmosql_server -B sqlite --database-filename data/foo.sqlite

[!TIP] You can now use the: --query-timeout argument to set a maximum query timeout in seconds for the server. Queries running longer than the timeout will be killed. The default value of: 0 means "unlimited". Example: gizmosql_server (other args...) --query-timeout 10 will set a timeout of 10 seconds for all queries.

[!TIP] The health check query can be customized using --health-check-query or the GIZMOSQL_HEALTH_CHECK_QUERY environment variable. The default is SELECT 1. This is useful when you need a more specific health check for your deployment. Example: gizmosql_server (other args...) --health-check-query "SELECT 1 FROM my_table LIMIT 1"

🧩 Extensions & Integrations

💻 GizmoSQL UI 🚀 NEW!
🔌 SQLAlchemy dialect
💿 Apache Superset compatible SQLAlchemy driver
🔌 [Ibis adapter](https://github.c

Gizmosql

Install / Use

README