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.
- 🛰️ 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 | Version |
|---|---|
| DuckDB | v1.3.2 |
| SQLite | 3.50.2 |
| Apache Arrow (Flight SQL) | 20.0.0 |
| jwt-cpp | v0.7.1 |
For detailed instructions and configuration information, see our full documentation:
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 missing \
gizmodata/gizmosql:latestduckdb ./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 missing \
--mount type=bind,source=$(pwd),target=/opt/gizmosql/data \
--env DATABASE_FILENAME="data/tpch_sf1.duckdb" \
gizmodata/gizmosql:latestUse with DBeaver or other JDBC clients:
jdbc:arrow-flight-sql://localhost:31337?useEncryption=true&user=gizmosql_username&password=gizmosql_password&disableCertificateVerification=trueMore info: Setup guide
import os
from adbc_driver_flightsql import dbapi as gizmosql, DatabaseOptions
with gizmosql.connect(uri="grpc+tls://localhost:31337",
db_kwargs={"username": os.getenv("GIZMOSQL_USERNAME", "gizmosql_username"),
"password": os.getenv("GIZMOSQL_PASSWORD", "gizmosql_password"),
DatabaseOptions.TLS_SKIP_VERIFY.value: "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)gizmosql_client --command Execute --host localhost --port 31337 --username gizmosql_username --password gizmosql_password --query "SELECT version()" --use-tls --tls-skip-verifygit clone https://github.com/gizmodata/gizmosql --recurse-submodules
cmake -S . -B build -G Ninja -DCMAKE_INSTALL_PREFIX=/usr/local
cmake --build build --target installThen run:
GIZMOSQL_PASSWORD="..." gizmosql_server --database-filename ./data/your.db --print-queries- ✅ DuckDB + SQLite backend support
- ✅ TLS & optional mTLS
- ✅ JWT-based auth (automatically issued, signed server-side)
- ✅ Server initialization via
INIT_SQL_COMMANDSorINIT_SQL_COMMANDS_FILE - ✅ Slim Docker image for minimal runtime
# DuckDB (default)
gizmosql_server -B duckdb --database-filename data/foo.duckdb
# SQLite
gizmosql_server -B sqlite --database-filename data/foo.sqlite💡 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.
Apache License, Version 2.0
https://www.apache.org/licenses/LICENSE-2.0
Questions or consulting needs?
📧 info@gizmodata.com
🌐 https://gizmodata.com
Built with ❤️ by GizmoData™