gizmodata/gizmosql

🚀 GizmoSQL — 云环境高性能 SQL 服务器

![Documentation]([] ![JDBC Driver]([] ![ADBC PyPI]([] ![SQLAlchemy Dialect]([] ![Ibis Backend]([***]

---

🌟 什么是 GizmoSQL？

GizmoSQL 是一款轻量级高性能 SQL 服务器，基于以下技术构建：

• 🦆 DuckDB 或 🗃️ SQLite 用于查询执行
• 🚀 Apache Arrow Flight SQL 提供快速现代连接能力
• 🔒 基于中间件的认证机制，支持可选 TLS 和 JWT

最初从 https://github.com/voltrondata/sqlflite 分叉而来，现已增强为更具可扩展性的生产就绪平台，采用 Apache 2.0 许可证。

---

🧠 为什么选择 GizmoSQL？

• 🛰️ 随处部署 — 可作为容器、原生二进制文件运行或部署在 Kubernetes 中
• 📦 列式高速 — 利用 Arrow 列式格式实现高速数据传输
• ⚙️ 双后端支持 — 运行时可在 DuckDB 和 SQLite 之间切换
• 🔐 内置 TLS + 认证 — 基于密码的登录及签名 JWT 令牌
• 📈 超低成本分析 — 在 Azure 上运行 TPC-H SF 1000 基准测试仅需 161 秒，成本约 0.17 ***
• 🧪 多接口支持 — CLI、Python、JDBC、SQLAlchemy、Ibis、WebSocket，任您选择

---

📦 组件版本

📚 文档

有关详细说明和配置信息，请参阅完整文档：

GizmoSQL 文档

---

🚀 快速开始

选项 1：通过 Docker 运行

bash
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

选项 2：挂载自定义 DuckDB 数据库文件

bash
# 首先创建 DuckDB 数据库文件
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

---

🧰 客户端与工具

🔗 JDBC

可与 DBeaver 或其他 JDBC 客户端配合使用：

bash
jdbc:arrow-flight-sql://localhost:31337?useEncryption=true&user=gizmosql_username&password=gizmosql_password&disableCertificateVerification=true

更多信息：https://github.com/gizmodata/setup-arrow-jdbc-driver-in-dbeaver

---

🐍 Python (ADBC)

python
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"  # 如果使用受信任CA签名的TLS证书，则不需要此行
                                 },
                      autocommit=True
                      ) 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 配合使用的示例，请参见：https://github.com/gizmodata/generate-gizmosql-token

💻 CLI 客户端

bash
gizmosql_client   --command Execute   --host localhost --port 31337   --username gizmosql_username   --password gizmosql_password   --query "SELECT version()"   --use-tls --tls-skip-verify

---

🏗️ 从源码构建（可选）

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

构建后运行：

bash
GIZMOSQL_PASSWORD="..." gizmosql_server --database-filename ./data/your.db --print-queries

---

🧪 高级特性

• ✅ 支持 DuckDB 和 SQLite 后端
• ✅ TLS 及可选 mTLS
• ✅ 基于 JWT 的认证（自动颁发，服务器端签名）
• ✅ 通过 INIT_SQL_COMMANDS 或 INIT_SQL_COMMANDS_FILE 进行服务器初始化
• ✅ 精简 Docker 镜像，最小化运行时资源占用

---

🛠 后端选择

bash
# 默认使用 DuckDB
gizmosql_server -B duckdb --database-filename data/foo.duckdb

# 使用 SQLite
gizmosql_server -B sqlite --database-filename data/foo.sqlite

[!提示] 您现在可以使用 --query-timeout 参数设置服务器的最大查询超时时间（秒）。运行时间超过超时时间的查询将被终止。默认值 0 表示“无限制”。
示例：gizmosql_server (其他参数...) --query-timeout 10
将所有查询的超时时间设置为 10 秒。

---

🧩 扩展与集成

• 🔌 https://github.com/gizmodata/sqlalchemy-gizmosql-adbc-dialect
• 💿 https://github.com/gizmodata/superset-sqlalchemy-gizmosql-adbc-dialect
• 🔌 https://github.com/gizmodata/ibis-gizmosql
• 🌐 https://github.com/gizmodata/flight-sql-websocket-proxy
• 📈 https://github.com/J0hnG4lt/metabase-flightsql-driver
• ⚙️ https://github.com/gizmodata/dbt-gizmosql 🚀 新增！

---

📊 性能表现

💡 在 Azure VM Standard_E64pds_v6（约 3.74 ***/小时）上：

• TPC-H SF 1000 基准测试：
  ⏱️ 161.4 秒
  💰 总成本约 0.17 ***

🏁 速度制胜，经济高效。

---

🔒 许可证

Apache License, Version 2.0
https://www.apache.org/licenses/LICENSE-2.0

---

📫 联系方式

有问题或咨询需求？

📧 ***
🌐 [***]

---

由 GizmoData™ 精心打造 ❤️