🚀 GizmoSQL — High-Performance SQL Server for the Cloud

[!IMPORTANT] GizmoSQL is in maintenance mode. Please use Hardcharger going forward. See the Hardcharger documentation to get started.

---

🌟 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	❌	✅
Prometheus Metrics Endpoint & SQL Metrics	❌	✅
Kill Session	❌	✅
Per-Catalog Permissions	❌	✅
SSO/OIDC Authentication (JWKS)	❌	✅
Authorized Email Filtering	❌	✅
Statement Queuing	❌	✅

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.

Runtime metrics require the metrics license feature and are disabled by default. See the monitoring guide for enablement, the configurable HTTP port/bind address, SQL access, and Prometheus/Grafana setup.

---

🧠 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, MCP — Pick your interface

---

📦 Component Versions

Component	Version
DuckDB	v1.5.6 (stable) · v1.4.5 (LTS) · v2.0.0 (edge — experimental, not for production)
SQLite	3.53.4
Apache Arrow (Flight SQL)	26.0.0
jwt-cpp	v0.7.2
OpenTelemetry C++	v1.29.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 trust gizmodata/tap
brew install gizmosql

Note: Homebrew 6.0 (June 2026) requires third-party taps to be explicitly trusted before formulae can be installed from them — hence the brew trust step. On older Homebrew versions the command doesn't exist; simply skip it. Alternatively, brew install gizmodata/tap/gizmosql installs with a one-off trust for just this formula.

Supported platforms:

• macOS 15 (Sequoia) or later (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.

[!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

As of v2.0, the driver is powered by the native Go GizmoSQL ADBC driver — same Python API, with DDL/DML immediate execution, RETURNING support, gizmosql:// URIs, and OAuth/SSO provided by a shared driver library that also serves Go, C/C++, R, and other ADBC languages. The driver supports OAuth/SSO authentication for GizmoSQL Enterprise users.

from adbc_driver_gizmosql import dbapi as gizmosql

with gizmosql.connect(
    "gizmosql://localhost:31337",  # TLS by default; legacy grpc+tls:// also works
    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!
• 🤖 MCP Server for AI agents (Claude Desktop, Claude Code, any MCP client) 🚀 NEW!
• 🔌 SQLAlchemy dialect
• 💿 Apache Superset compatible SQLAlchemy driver
• 🔌 Ibis adapter
• 🌐 Flight SQL over WebSocket Proxy
• 📈 Metabase driver 🚀 NEW!
• ⚙️ dbt Adapter
• 🥅 SQLMesh Adapter 🚀 NEW!
• ✨ PySpark SQLFrame adapter 🚀 NEW!
• 🪩 ADBC Scanner by Query.Farm 🚀 NEW!
• 🧲 ADBC extension for DuckDB by Columnar 🚀 NEW!
• ⚓️ Kubernetes Operator 🚀 NEW!
• 📺 GizmoSQLLine JDBC CLI Client

---

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

---

💬 Community

Want to contribute code? See CONTRIBUTING.md for setup, formatting, linting, clang-tidy, tests, and the checks required by CI.

Join the GizmoData Community Slack to ask questions, share what you're building, and get help from the team and other users:

👉 Join the GizmoData Community on Slack

---

📫 Contact

Questions or consulting needs?

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

---

Built with ❤️ by GizmoData™