🚀 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.2
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

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.

Important

The iOS app is intended for development, learning, demos, and local prototyping — not production workloads. iOS enforces aggressive background execution limits, memory caps, and network/thermal throttling that make a phone or tablet unsuitable for hosting production SQL traffic. For production, run GizmoSQL via Docker, Kubernetes, Homebrew, or the native Linux/macOS/Windows binaries.

---

🧰 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
• 🌐 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!

---

📊 Performance

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

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

🏁 Speed for the win. Performance for pennies.

---

🔒 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?

📧 info@gizmodata.com
🌐 https://gizmodata.com

---

Built with ❤️ by GizmoData™