https://github.com/gizmodata/gizmosql

🚀 GizmoSQL — High-Performance SQL Server
https://github.com/gizmodata/gizmosql

adbc apache-arrow apache-arrow-flight apache-arrow-flight-sql database databases duckdb gizmodata gizmosql ibis jdbc jwt-authentication pyarrow sql sqlalchemy sqlite sqlite3 tls

Last synced: 15 days ago
JSON representation

🚀 GizmoSQL — High-Performance SQL Server

Host: GitHub
URL: https://github.com/gizmodata/gizmosql
Owner: gizmodata
License: other
Created: 2024-09-17T21:41:49.000Z (over 1 year ago)
Default Branch: main
Last Pushed: 2026-03-31T15:02:00.000Z (about 1 month ago)
Last Synced: 2026-03-31T15:09:32.321Z (about 1 month ago)
Topics: adbc, apache-arrow, apache-arrow-flight, apache-arrow-flight-sql, database, databases, duckdb, gizmodata, gizmosql, ibis, jdbc, jwt-authentication, pyarrow, sql, sqlalchemy, sqlite, sqlite3, tls
Language: C++
Homepage: https://gizmodata.com/gizmosql
Size: 2.55 MB
Stars: 300
Watchers: 5
Forks: 33
Open Issues: 9
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- Funding: .github/FUNDING.yml
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
- Notice: NOTICE

Awesome Lists containing this project

awesome-sqlite - GizmoSQL - Arrow Flight SQL server with TLS/auth that can run on top of SQLite (or DuckDB), exposing JDBC/ADBC access via Docker or binary. (Tools)
awesome-duckdb - GizmoSQL - Arrow Flight SQL Server - A C++ implementation of the [Arrow Flight SQL protocol](https://arrow.apache.org/docs/format/FlightSql.html) that runs in a client-server setup with DuckDB or SQLite as backends. (Client-Server Setups / Web Clients (WebAssembly))

README

          # 🚀 GizmoSQL — High-Performance SQL Server for the Cloud

[![DockerHub](https://img.shields.io/badge/dockerhub-image-green.svg?logo=Docker)](https://hub.docker.com/r/gizmodata/gizmosql)

[![GitHub Container](https://img.shields.io/badge/github--package-container--image-green.svg?logo=Docker)](https://github.com/gizmodata/gizmosql/pkgs/container/gizmosql)

[![Documentation](https://img.shields.io/badge/Documentation-dev-yellow.svg)](https://arrow.apache.org/docs/format/FlightSql.html)

[![GitHub](https://img.shields.io/badge/GitHub-gizmodata%2Fgizmosql-blue.svg?logo=Github)](https://github.com/gizmodata/gizmosql)

[![JDBC Driver](https://img.shields.io/badge/GizmoSQL%20JDBC%20Driver-download%20artifact-red?logo=Apache%20Maven)](https://github.com/gizmodata/gizmosql-jdbc-driver/releases/latest/download/gizmosql-jdbc-driver.jar)

[![ADBC PyPI](https://img.shields.io/badge/PyPI-GizmoSQL%20ADBC%20Driver-blue?logo=PyPI)](https://pypi.org/project/adbc-driver-gizmosql/)

[![SQLAlchemy Dialect](https://img.shields.io/badge/PyPI-GizmoSQL%20SQLAlchemy%20Dialect-blue?logo=PyPI)](https://pypi.org/project/sqlalchemy-gizmosql-adbc-dialect/)

[![Ibis Backend](https://img.shields.io/badge/PyPI-GizmoSQL%20Ibis%20Backend-blue?logo=PyPI)](https://pypi.org/project/ibis-gizmosql/)

[![App Store](https://img.shields.io/badge/App%20Store-GizmoSQL%20for%20iOS-black?logo=apple)](https://apps.apple.com/us/app/gizmosql/id6761951280)

---

## 🌟 What is GizmoSQL?

**GizmoSQL** is a lightweight, high-performance SQL server built on:

- 🦆 [DuckDB](https://duckdb.org) or 🗃️ [SQLite](https://sqlite.org) for query execution

- 🚀 [Apache Arrow Flight SQL](https://arrow.apache.org/docs/format/FlightSql.html) for fast, modern connectivity

- 🔒 Middleware-based auth with optional TLS & JWT

Originally forked from [`sqlflite`](https://github.com/voltrondata/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](mailto:sales@gizmodata.com) for licensing information.

For more details, see the [Editions documentation](https://docs.gizmosql.com/#/editions).

---

## 🧠 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](https://duckdb.org)                                                     | v1.5.2  |

| [SQLite](https://sqlite.org)                                                     | 3.52.0  |

| [Apache Arrow (Flight SQL)](https://arrow.apache.org/docs/format/FlightSql.html) | 23.0.1  |

| [jwt-cpp](https://thalhammer.github.io/jwt-cpp/)                                 | v0.7.2  |

| [OpenTelemetry C++](https://opentelemetry.io/docs/languages/cpp/)                | v1.25.0 |

| [nlohmann/json](https://json.nlohmann.me)                                        | v3.12.0 |

## 📚 Documentation

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

[GizmoSQL Documentation](https://docs.gizmosql.com)

---

## 🚀 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

```bash

# 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

```bash

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)

```bash

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`):

```bash

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](https://github.com/gizmodata/gizmosql/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:

```powershell

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

[](https://apps.apple.com/us/app/gizmosql/id6761951280)

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:

```text

jdbc:gizmosql://localhost:31337?useEncryption=true&user=gizmosql_user&password=gizmosql_password&disableCertificateVerification=true

```

More info: [Setup guide](https://github.com/gizmodata/setup-gizmosql-jdbc-driver-in-dbeaver)

---

### 🐍 Python (ADBC)

**Prerequisite:** Python 3.10+ and the [GizmoSQL ADBC driver](https://pypi.org/project/adbc-driver-gizmosql/):

```bash

pip install adbc-driver-gizmosql

```

The driver also supports OAuth/SSO authentication for GizmoSQL Enterprise users.

```python

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:

```bash

# Interactive session

GIZMOSQL_PASSWORD="gizmosql_password" gizmosql_client --host localhost --username gizmosql_user --tls --tls-skip-verify

```

Run a single query with `--command`:

```bash

GIZMOSQL_PASSWORD="gizmosql_password" gizmosql_client \

  --host localhost --username gizmosql_user --tls --tls-skip-verify \

  --command "SELECT version()"

```

Pipe SQL from a heredoc:

```bash

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](https://docs.gizmosql.com/#/client)

---

## 🏗️ Build from Source (Optional)

```bash

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:

```bash

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

```bash

# 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](https://github.com/gizmodata/gizmosql-ui) 🚀 **NEW!**

- 🔌 [SQLAlchemy dialect](https://github.com/gizmodata/sqlalchemy-gizmosql-adbc-dialect)

- 💿 [Apache Superset compatible SQLAlchemy driver](https://github.com/gizmodata/superset-sqlalchemy-gizmosql-adbc-dialect)

- 🔌 [Ibis adapter](https://github.com/gizmodata/ibis-gizmosql)

- 🌐 [Flight SQL over WebSocket Proxy](https://github.com/gizmodata/flight-sql-websocket-proxy)

- 📈 [Metabase driver](https://github.com/J0hnG4lt/metabase-flightsql-driver)

- ⚙️ [dbt Adapter](https://github.com/gizmodata/dbt-gizmosql)

- 🥅 [SQLMesh Adapter](https://github.com/gizmodata/sqlmesh-gizmosql) 🚀 **NEW!**

- ✨ [PySpark SQLFrame adapter](https://github.com/gizmodata/sqlframe-gizmosql) 🚀 **NEW!**

- 🪩 [ADBC Scanner by Query.Farm](docs/adbc_scanner_duckdb.md) 🚀 **NEW!**

- ⚓️ [Kubernetes Operator](https://github.com/gizmodata/gizmosql-operator) 🚀 **NEW!**

- 📺 [GizmoSQLLine JDBC CLI Client](https://github.com/gizmodata/gizmosqlline) **NEW!**

- 🔥 [Grafana Plugin](https://grafana.com/grafana/plugins/gizmodata-gizmosql-datasource/) **NEW!**

- 🕸️ [JavaScript/TypeScript Client](https://github.com/gizmodata/gizmosql-client-js) **NEW!**

- ☕️ [JDBC Driver](https://github.com/gizmodata/gizmosql-jdbc-driver/releases/latest/download/gizmosql-jdbc-driver.jar) **NEW!**

- 🐍 [Python ADBC Driver (with OAuth/SSO)](https://github.com/gizmodata/adbc-driver-gizmosql) **NEW!**

- 🔌 [ODBC Driver](https://github.com/gizmodata/gizmosql-odbc-driver) **NEW!**

- 📊 [Power BI Connector](https://github.com/gizmodata/gizmosql-powerbi-connector) **NEW!**

- 🗺️ [QGIS Plugin (qgizmosql)](https://github.com/gizmodata/qgizmosql) 🚀 **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](https://www.apache.org/licenses/LICENSE-2.0).

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

---

## 📫 Contact

Questions or consulting needs?

📧 info@gizmodata.com  

🌐 [https://gizmodata.com](https://gizmodata.com)

---

> Built with ❤️ by [GizmoData™](https://gizmodata.com)

ecosyste.ms

Data

Tools

Indexes

Applications

Experiments

Awesome

https://github.com/gizmodata/gizmosql

Awesome Lists containing this project

README