🚀 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.4.4
SQLite	3.51.1
Apache Arrow (Flight SQL)	23.0.1
jwt-cpp	v0.7.1
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

---

🧰 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()
        print(x)

---

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

---

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