{"id":22393637,"url":"https://github.com/gizmodata/gizmosql","last_synced_at":"2026-06-13T01:01:38.089Z","repository":{"id":298962503,"uuid":"858981627","full_name":"gizmodata/gizmosql","owner":"gizmodata","description":"🚀 GizmoSQL — High-Performance Database Server","archived":false,"fork":false,"pushed_at":"2026-06-12T18:04:33.000Z","size":3712,"stargazers_count":325,"open_issues_count":6,"forks_count":34,"subscribers_count":4,"default_branch":"main","last_synced_at":"2026-06-12T18:14:38.838Z","etag":null,"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"],"latest_commit_sha":null,"homepage":"https://gizmodata.com/gizmosql","language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/gizmodata.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"docs/security.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":"NOTICE","maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null},"funding":{"github":"gizmodata"}},"created_at":"2024-09-17T21:41:49.000Z","updated_at":"2026-06-11T17:46:29.000Z","dependencies_parsed_at":"2025-06-13T21:29:13.758Z","dependency_job_id":"583e979f-5f78-43d8-bd01-b10756084ec1","html_url":"https://github.com/gizmodata/gizmosql","commit_stats":null,"previous_names":["gizmodata/gizmosql"],"tags_count":228,"template":false,"template_full_name":null,"purl":"pkg:github/gizmodata/gizmosql","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gizmodata%2Fgizmosql","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gizmodata%2Fgizmosql/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gizmodata%2Fgizmosql/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gizmodata%2Fgizmosql/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/gizmodata","download_url":"https://codeload.github.com/gizmodata/gizmosql/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gizmodata%2Fgizmosql/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34268189,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-12T02:00:06.859Z","response_time":109,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["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"],"created_at":"2024-12-05T05:06:38.401Z","updated_at":"2026-06-13T01:01:38.057Z","avatar_url":"https://github.com/gizmodata.png","language":"C++","funding_links":["https://github.com/sponsors/gizmodata"],"categories":["Tools","Client-Server Setups","\u003ca name=\"C%2B%2B\"\u003e\u003c/a\u003eC++","C++"],"sub_categories":["Web Clients (WebAssembly)"],"readme":"# 🚀 GizmoSQL — High-Performance SQL Server for the Cloud\n\n[![DockerHub](https://img.shields.io/badge/dockerhub-image-green.svg?logo=Docker)](https://hub.docker.com/r/gizmodata/gizmosql)\n[![DockerHub LTS](https://img.shields.io/badge/dockerhub-LTS%20image-blue.svg?logo=Docker)](https://hub.docker.com/r/gizmodata/gizmosql-lts)\n[![LTS Channel](https://img.shields.io/badge/LTS-channel%20guide-orange.svg)](https://docs.gizmosql.com/lts_channel/)\n[![GitHub Container](https://img.shields.io/badge/github--package-container--image-green.svg?logo=Docker)](https://github.com/gizmodata/gizmosql/pkgs/container/gizmosql)\n[![Documentation](https://img.shields.io/badge/Documentation-dev-yellow.svg)](https://arrow.apache.org/docs/format/FlightSql.html)\n[![GitHub](https://img.shields.io/badge/GitHub-gizmodata%2Fgizmosql-blue.svg?logo=Github)](https://github.com/gizmodata/gizmosql)\n[![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)\n[![ADBC PyPI](https://img.shields.io/badge/PyPI-GizmoSQL%20ADBC%20Driver-blue?logo=PyPI)](https://pypi.org/project/adbc-driver-gizmosql/)\n[![SQLAlchemy Dialect](https://img.shields.io/badge/PyPI-GizmoSQL%20SQLAlchemy%20Dialect-blue?logo=PyPI)](https://pypi.org/project/sqlalchemy-gizmosql-adbc-dialect/)\n[![Ibis Backend](https://img.shields.io/badge/PyPI-GizmoSQL%20Ibis%20Backend-blue?logo=PyPI)](https://pypi.org/project/ibis-gizmosql/)\n[![App Store](https://img.shields.io/badge/App%20Store-GizmoSQL%20for%20iOS-black?logo=apple)](https://apps.apple.com/us/app/gizmosql/id6761951280)\n\n---\n\n## 🌟 What is GizmoSQL?\n\n**GizmoSQL** is a lightweight, high-performance SQL server built on:\n\n- 🦆 [DuckDB](https://duckdb.org) or 🗃️ [SQLite](https://sqlite.org) for query execution\n- 🚀 [Apache Arrow Flight SQL](https://arrow.apache.org/docs/format/FlightSql.html) for fast, modern connectivity\n- 🔒 Middleware-based auth with optional TLS \u0026 JWT\n\nOriginally forked from [`sqlflite`](https://github.com/voltrondata/sqlflite) — and now enhanced into a more extensible, production-ready platform under the Apache 2.0 license.\n\n---\n\n## 📦 Editions\n\nGizmoSQL is available in two editions:\n\n| Feature | Core | Enterprise |\n|---------|:----:|:----------:|\n| DuckDB \u0026 SQLite backends | ✅ | ✅ |\n| Arrow Flight SQL protocol | ✅ | ✅ |\n| TLS \u0026 mTLS authentication | ✅ | ✅ |\n| JWT token authentication | ✅ | ✅ |\n| Query timeout | ✅ | ✅ |\n| Session Instrumentation | ❌ | ✅ |\n| Kill Session | ❌ | ✅ |\n| Per-Catalog Permissions | ❌ | ✅ |\n| SSO/OIDC Authentication (JWKS) | ❌ | ✅ |\n| Authorized Email Filtering | ❌ | ✅ |\n| Statement Queuing | ❌ | ✅ |\n\n**GizmoSQL Core** is free and open source under the Apache 2.0 license.\n\n**GizmoSQL Enterprise** requires a commercial license. Contact [sales@gizmodata.com](mailto:sales@gizmodata.com) for licensing information.\n\nFor more details, see the [Editions documentation](https://docs.gizmosql.com/editions/).\n\n---\n\n## 🧠 Why GizmoSQL?\n\n- 🛰️ **Deploy Anywhere** — Run as a container, native binary, or in Kubernetes\n- 📦 **Columnar Fast** — Leverages Arrow columnar format for high-speed transfers\n- ⚙️ **Dual Backends** — Switch between DuckDB and SQLite at runtime\n- 🔐 **Built-in TLS + Auth** — Password-based login + signed JWT tokens\n- 📈 **Super Cheap Analytics** — TPC-H SF 1000 in 161s for ~$0.17 on Azure\n- 🧪 **CLI, Python, JDBC, SQLAlchemy, Ibis, WebSocket** — Pick your interface\n\n---\n\n## 📦 Component Versions\n\n| Component                                                                        | Version |\n|----------------------------------------------------------------------------------|---------|\n| [DuckDB](https://duckdb.org)                                                     | v1.5.3  |\n| [SQLite](https://sqlite.org)                                                     | 3.53.1  |\n| [Apache Arrow (Flight SQL)](https://arrow.apache.org/docs/format/FlightSql.html) | 23.0.1  |\n| [jwt-cpp](https://thalhammer.github.io/jwt-cpp/)                                 | v0.7.2  |\n| [OpenTelemetry C++](https://opentelemetry.io/docs/languages/cpp/)                | v1.25.0 |\n| [nlohmann/json](https://json.nlohmann.me)                                        | v3.12.0 |\n\n## 📚 Documentation\n\nFor detailed instructions and configuration information, see our full documentation:\n\n[GizmoSQL Documentation](https://docs.gizmosql.com)\n\n---\n\n## 🚀 Quick Start\n\n\u003e **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`.\n\n### Option 1: Run from Docker\n\n```bash\n# Username defaults to \"gizmosql_user\" when GIZMOSQL_USERNAME is not set\ndocker run --name gizmosql \\\n           --detach \\\n           --rm \\\n           --tty \\\n           --init \\\n           --publish 31337:31337 \\\n           --env TLS_ENABLED=\"1\" \\\n           --env GIZMOSQL_PASSWORD=\"gizmosql_password\" \\\n           --env PRINT_QUERIES=\"1\" \\\n           --pull always \\\n           gizmodata/gizmosql:latest\n```\n\n### Option 2: Mount Your Own DuckDB database file\n\n```bash\nduckdb ./tpch_sf1.duckdb \u003c\u003c EOF\nINSTALL tpch; LOAD tpch; CALL dbgen(sf=1);\nEOF\n\ndocker run --name gizmosql \\\n           --detach \\\n           --rm \\\n           --tty \\\n           --init \\\n           --publish 31337:31337 \\\n           --env TLS_ENABLED=\"1\" \\\n           --env GIZMOSQL_PASSWORD=\"gizmosql_password\" \\\n           --pull always \\\n           --mount type=bind,source=$(pwd),target=/opt/gizmosql/data \\\n           --env DATABASE_FILENAME=\"data/tpch_sf1.duckdb\" \\\n           gizmodata/gizmosql:latest\n```\n\n### Option 3: Install via Homebrew (macOS \u0026 Linux)\n\n```bash\nbrew tap gizmodata/tap\nbrew install gizmosql\n```\n\nSupported platforms:\n- macOS (Apple Silicon / ARM64)\n- Linux (x86-64 / AMD64)\n- Linux (ARM64)\n\nThen run the server (username defaults to `gizmosql_user`):\n\n```bash\nGIZMOSQL_PASSWORD=\"gizmosql_password\" gizmosql_server --database-filename your.duckdb --print-queries\n```\n\n### Option 4: Windows Installer (MSI)\n\nDownload the latest MSI installer from the [GitHub Releases](https://github.com/gizmodata/gizmosql/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.\n\nThen run the server from PowerShell or Command Prompt:\n\n```powershell\n$env:GIZMOSQL_PASSWORD=\"gizmosql_password\"\ngizmosql_server --database-filename your.duckdb --print-queries\n```\n\n### Option 5: iOS App (iPhone \u0026 iPad) 📱\n\nGizmoSQL is available as a native iOS app on the Apple App Store — run a full GizmoSQL server right on your iPhone or iPad.\n\n[\u003cimg src=\"docs/app-store-badge.png\" alt=\"Download GizmoSQL on the App Store\" height=\"60\"\u003e](https://apps.apple.com/us/app/gizmosql/id6761951280)\n\nThe 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.\n\n\u003e [!IMPORTANT]\n\u003e **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.\n\n---\n\n## 🧰 Clients and Tools\n\n### 🔗 JDBC\n\nUse with DBeaver or other JDBC clients:\n\n```text\njdbc:gizmosql://localhost:31337?useEncryption=true\u0026user=gizmosql_user\u0026password=gizmosql_password\u0026disableCertificateVerification=true\n```\n\nMore info: [Setup guide](https://github.com/gizmodata/setup-gizmosql-jdbc-driver-in-dbeaver)\n\n---\n\n### 🐍 Python (ADBC)\n\n**Prerequisite:** Python 3.10+ and the [GizmoSQL ADBC driver](https://pypi.org/project/adbc-driver-gizmosql/):\n\n```bash\npip install adbc-driver-gizmosql\n```\n\nThe driver also supports OAuth/SSO authentication for GizmoSQL Enterprise users.\n\n```python\nfrom adbc_driver_gizmosql import dbapi as gizmosql\n\nwith gizmosql.connect(\n    \"grpc+tls://localhost:31337\",\n    username=\"gizmosql_user\",\n    password=\"gizmosql_password\",\n    tls_skip_verify=True,  # Not needed if you use a trusted CA-signed TLS cert\n) as conn:\n    with conn.cursor() as cur:\n        cur.execute(\n            \"SELECT n_nationkey, n_name FROM nation WHERE n_nationkey = ?\",\n            parameters=[24],\n        )\n        x = cur.fetch_arrow_table()\n```\n\n---\n\n### 🔑 Token authentication\nSee: https://github.com/gizmodata/generate-gizmosql-token for an example of how to generate a token and use it with GizmoSQL.\n\n### 💻 CLI Client\n\nGizmoSQL ships with an interactive SQL shell inspired by `psql` and the DuckDB CLI:\n\n```bash\n# Interactive session\nGIZMOSQL_PASSWORD=\"gizmosql_password\" gizmosql_client --host localhost --username gizmosql_user --tls --tls-skip-verify\n```\n\nRun a single query with `--command`:\n\n```bash\nGIZMOSQL_PASSWORD=\"gizmosql_password\" gizmosql_client \\\n  --host localhost --username gizmosql_user --tls --tls-skip-verify \\\n  --command \"SELECT version()\"\n```\n\nPipe SQL from a heredoc:\n\n```bash\nGIZMOSQL_PASSWORD=\"gizmosql_password\" gizmosql_client \\\n  --host localhost --username gizmosql_user --tls --tls-skip-verify --quiet \u003c\u003c'EOF'\nSELECT n_nationkey, n_name\nFROM nation\nWHERE n_nationkey = 24;\nEOF\n```\n\nMore info: [Client Shell documentation](https://docs.gizmosql.com/client/)\n\n---\n\n## 🏗️ Build from Source (Optional)\n\n```bash\ngit clone https://github.com/gizmodata/gizmosql --recurse-submodules\ncd gizmosql\ncmake -S . -B build -G Ninja -DCMAKE_INSTALL_PREFIX=/usr/local\ncmake --build build --target install\n```\n\nThen run:\n\n```bash\nGIZMOSQL_PASSWORD=\"...\" gizmosql_server --database-filename ./data/your.db --print-queries\n```\n\n---\n\n## 🧪 Advanced Features\n\n- ✅ DuckDB + SQLite backend support\n- ✅ TLS \u0026 optional mTLS\n- ✅ JWT-based auth (automatically issued, signed server-side)\n- ✅ Server initialization via `INIT_SQL_COMMANDS` or `INIT_SQL_COMMANDS_FILE`\n- ✅ Slim Docker image for minimal runtime\n\n---\n\n## 🛠 Backend Selection\n\n```bash\n# DuckDB (default)\ngizmosql_server -B duckdb --database-filename data/foo.duckdb\n\n# SQLite\ngizmosql_server -B sqlite --database-filename data/foo.sqlite\n```\n\n\u003e [!TIP]\n\u003e 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\".\n\u003e Example: `gizmosql_server (other args...) --query-timeout 10`\n\u003e will set a timeout of 10 seconds for all queries.\n\n\u003e [!TIP]\n\u003e The health check query can be customized using `--health-check-query` or the `GIZMOSQL_HEALTH_CHECK_QUERY` environment variable.\n\u003e The default is `SELECT 1`. This is useful when you need a more specific health check for your deployment.\n\u003e Example: `gizmosql_server (other args...) --health-check-query \"SELECT 1 FROM my_table LIMIT 1\"`\n\n---\n\n\n## 🧩 Extensions \u0026 Integrations\n\n- 💻 [GizmoSQL UI](https://github.com/gizmodata/gizmosql-ui) 🚀 **NEW!**\n- 🔌 [SQLAlchemy dialect](https://github.com/gizmodata/sqlalchemy-gizmosql-adbc-dialect)\n- 💿 [Apache Superset compatible SQLAlchemy driver](https://github.com/gizmodata/superset-sqlalchemy-gizmosql-adbc-dialect)\n- 🔌 [Ibis adapter](https://github.com/gizmodata/ibis-gizmosql)\n- 🌐 [Flight SQL over WebSocket Proxy](https://github.com/gizmodata/flight-sql-websocket-proxy)\n- 📈 [Metabase driver](https://github.com/J0hnG4lt/metabase-flightsql-driver)\n- ⚙️ [dbt Adapter](https://github.com/gizmodata/dbt-gizmosql)\n- 🥅 [SQLMesh Adapter](https://github.com/gizmodata/sqlmesh-gizmosql) 🚀 **NEW!**\n- ✨ [PySpark SQLFrame adapter](https://github.com/gizmodata/sqlframe-gizmosql) 🚀 **NEW!**\n- 🪩 [ADBC Scanner by Query.Farm](docs/adbc_scanner_duckdb.md) 🚀 **NEW!**\n- ⚓️ [Kubernetes Operator](https://github.com/gizmodata/gizmosql-operator) 🚀 **NEW!**\n- 📺 [GizmoSQLLine JDBC CLI Client](https://github.com/gizmodata/gizmosqlline) **NEW!**\n- 🔥 [Grafana Plugin](https://grafana.com/grafana/plugins/gizmodata-gizmosql-datasource/) **NEW!**\n- 🕸️ [JavaScript/TypeScript Client](https://github.com/gizmodata/gizmosql-client-js) **NEW!**\n- ☕️ [JDBC Driver](https://github.com/gizmodata/gizmosql-jdbc-driver/releases/latest/download/gizmosql-jdbc-driver.jar) **NEW!**\n- 🐍 [Python ADBC Driver (with OAuth/SSO)](https://github.com/gizmodata/adbc-driver-gizmosql) **NEW!**\n- 🔌 [ODBC Driver](https://github.com/gizmodata/gizmosql-odbc-driver) **NEW!**\n- 📊 [Power BI Connector](https://github.com/gizmodata/gizmosql-powerbi-connector) **NEW!**\n- 🗺️ [QGIS Plugin (qgizmosql)](https://plugins.qgis.org/plugins/qgizmosql) 🚀 **NEW!**\n---\n\n## 📊 Performance\n\n💡 On Azure VM `Standard_E64pds_v6` (~$3.74/hr):\n\n- TPC-H SF 1000 benchmark:  \n  ⏱️ 161.4 seconds  \n  💰 ~$0.17 USD total\n\n\u003e 🏁 Speed for the win. Performance for pennies.\n\n---\n\n## 🔒 License\n\n**GizmoSQL Core** is licensed under the [Apache License, Version 2.0](https://www.apache.org/licenses/LICENSE-2.0).\n\n**Enterprise features** (in `src/enterprise/`) are proprietary and require a commercial license from GizmoData LLC. See [src/enterprise/LICENSE](src/enterprise/LICENSE) for details.\n\n---\n\n## 📫 Contact\n\nQuestions or consulting needs?\n\n📧 info@gizmodata.com  \n🌐 [https://gizmodata.com](https://gizmodata.com)\n\n---\n\n\u003e Built with ❤️ by [GizmoData™](https://gizmodata.com)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgizmodata%2Fgizmosql","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgizmodata%2Fgizmosql","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgizmodata%2Fgizmosql/lists"}