gizmodata/gizmosql repository overview

⁠🚀 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:

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

GizmoSQL Enterprise requires a commercial license. Contact [email protected]⁠ 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

⁠📚 Documentation

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

GizmoSQL Documentation⁠

⁠🚀 Quick Start

⁠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 — GizmoSQL-amd64.msi for x64 machines, or GizmoSQL-arm64.msi for Windows on Arm (e.g. Snapdragon X-class devices). 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

⁠Option 5: iOS App (iPhone & iPad) 📱

GizmoSQL is available as a native iOS app on the Apple App Store — run a full GizmoSQL server right on your iPhone or iPad.

The iOS edition bundles the DuckDB engine and the Arrow Flight SQL server, so any GizmoSQL client (JDBC, ADBC, CLI, UI, etc.) can connect to it over your local network.

⁠🧰 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

⁠🧩 Extensions & Integrations

• 💻 GizmoSQL UI⁠ 🚀 NEW!
• 🔌 SQLAlchemy dialect⁠
• 💿 Apache Superset compatible SQLAlchemy driver⁠
• 🔌 Ibis adapter⁠
• 🌐 Flight SQL over WebSocket Proxy⁠
• 📈 Metabase driver⁠
• ⚙️ dbt Adapter⁠
• 🥅 SQLMesh Adapter⁠ 🚀 NEW!
• ✨ PySpark SQLFrame adapter⁠ 🚀 NEW!
• 🪩 ADBC Scanner by Query.Farm⁠ 🚀 NEW!
• ⚓️ Kubernetes Operator⁠ 🚀 NEW!
• 📺 GizmoSQLLine JDBC CLI Client⁠ NEW!
• 🔥 Grafana Plugin⁠ NEW!
• 🕸️ JavaScript/TypeScript Client⁠ NEW!
• ☕️ JDBC Driver⁠ NEW!
• 🐍 Python ADBC Driver (with OAuth/SSO)⁠ NEW!
• 🔌 ODBC Driver⁠ NEW!
• 📊 Power BI Connector⁠ NEW!
• 🗺️ QGIS Plugin (qgizmosql)⁠ 🚀 NEW!

⁠📊 Performance

💡 On Azure VM Standard_E64pds_v6 (~$3.74/hr):

• TPC-H SF 1000 benchmark:
  ⏱️ 161.4 seconds
  💰 ~$0.17 USD total

⁠🔒 License

GizmoSQL Core is licensed under the Apache License, Version 2.0⁠.

Enterprise features (in src/enterprise/) are proprietary and require a commercial license from GizmoData LLC. See src/enterprise/LICENSE⁠ for details.

⁠📫 Contact

Questions or consulting needs?

📧 [email protected]⁠
🌐 https://gizmodata.com⁠