voltrondata/sqlflite

SQLFlite

基于DuckDB或SQLite后端的Apache Arrow Flight SQL服务器

![Documentation-dev]([] ![Arrow JDBC Driver-download artifact]([] ![PyPI-Arrow ADBC Flight SQL driver]([] ![PyPI-SQLFlite Ibis Backend]([] ![PyPI-SQLFlite SQLAlchemy Dialect]([***]

镜像概述

SQLFlite是一个基于Apache Arrow Flight SQL协议的服务器实现，使用DuckDB或SQLite作为后端数据库执行引擎。该镜像支持通过中间件进行身份验证，并可通过TLS实现加密数据库连接，提供高效的列式数据传输能力。

核心功能和特性

• 双后端支持：默认使用DuckDB，也可切换为SQLite作为数据库引擎
• 安全连接：支持TLS加密传输，可选mTLS客户端认证
• 灵活认证：通过密码验证机制控制客户端访问
• 初始化配置：支持启动时执行SQL命令或SQL文件进行数据库初始化
• 多客户端支持：兼容JDBC、ADBC、Ibis、SQLAlchemy等多种连接方式
• 查询监控：可配置打印客户端执行的SQL查询

使用场景

• 轻量级列式数据库服务部署
• 开发/测试环境中的SQL兼容数据服务
• 需要高效列式数据传输的应用集成
• 基于DuckDB/SQLite的数据分析服务

使用方法

选项1：使用已发布的Docker镜像运行

打开终端，拉取并运行已配置好的Docker镜像：

bash
docker run --name sqlflite \
           --detach \
           --rm \
           --tty \
           --init \
           --publish 31337:31337 \
           --env TLS_ENABLED="1" \
           --env SQLFLITE_PASSWORD="sqlflite_password" \
           --env PRINT_QUERIES="1" \
           --pull missing \
           voltrondata/sqlflite:latest

上述命令会自动挂载一个小型TPC-H DuckDB数据库文件。

注意：可通过设置环境变量TLS_ENABLED="0"禁用TLS（默认启用）。除非在Kubernetes等环境中使用mTLS sidecar，否则不建议禁用TLS，因为这会导致连接不安全。

挂载自定义数据库文件

运行Docker镜像时，可挂载自定义DuckDB数据库文件（数据库必须使用DuckDB 1.1.1版本构建）：

前提条件：安装DuckDB CLI 1.1.1版本并确保可执行文件在PATH中。

平台下载链接：

• https://github.com/duckdb/duckdb/releases/download/v1.1.1/duckdb_cli-linux-amd64.zip
• https://github.com/duckdb/duckdb/releases/download/v1.1.1/duckdb_cli-linux-aarch64.zip
• https://github.com/duckdb/duckdb/releases/download/v1.1.1/duckdb_cli-osx-universal.zip

生成TPC-H Scale Factor 1 (1GB)数据库文件并挂载运行：

bash
# 在主机的/tmp目录生成TPC-H数据库
pushd /tmp

duckdb ./tpch_sf1.duckdb << EOF
.bail on
.echo on
SELECT VERSION();
INSTALL tpch;
LOAD tpch;
CALL dbgen(sf=1);
EOF

# 运行sqlflite容器并挂载主机数据库文件
docker run --name sqlflite \
           --detach \
           --rm \
           --tty \
           --init \
           --publish 31337:31337 \
           --env TLS_ENABLED="1" \
           --env SQLFLITE_PASSWORD="sqlflite_password" \
           --pull missing \
           --mount type=bind,source=$(pwd),target=/opt/sqlflite/data \
           --env DATABASE_FILENAME="data/tpch_sf1.duckdb" \
           voltrondata/sqlflite:latest

运行初始化SQL命令

可通过设置INIT_SQL_COMMANDS环境变量指定启动时执行的SQL命令（用分号分隔）：

bash
docker run --name sqlflite \
           --detach \
           --rm \
           --tty \
           --init \
           --publish 31337:31337 \
           --env TLS_ENABLED="1" \
           --env SQLFLITE_PASSWORD="sqlflite_password" \
           --env PRINT_QUERIES="1" \
           --env INIT_SQL_COMMANDS="SET threads = 1; SET memory_limit = '1GB';" \
           --pull missing \
           voltrondata/sqlflite:latest

也可通过INIT_SQL_COMMANDS_FILE环境变量指定包含SQL命令的文件路径（文件需挂载到容器内）。

注意：对于DuckDB后端，会自动执行以下初始化命令：SET autoinstall_known_extensions = true; SET autoload_known_extensions = true;

注意：返回结果的SELECT语句不会显示结果；执行失败的初始化命令会导致服务器中止并退出非零代码。

客户端连接方式

通过JDBC连接

下载Apache Arrow Flight SQL JDBC驱动，使用以下JDBC连接字符串：

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

注意：若重启容器后使用相同密码连接JDBC可能出现"Invalid bearer token provided"错误，需修改SQLFLITE_PASSWORD环境变量并使用新密码连接。

通过ADBC Python Flight SQL驱动连接

ADBC提供比JDBC更好的性能，减少序列化/反序列化，保持数据列格式。

安装依赖：

bash
# 创建Python虚拟环境
python3 -m venv .venv

# 激活虚拟环境
. .venv/bin/activate

# 安装依赖
pip install --upgrade pip
pip install pandas pyarrow adbc_driver_flightsql

# 启动Python交互shell
python

在Python shell中执行：

python
import os
from adbc_driver_flightsql import dbapi as sqlflite, DatabaseOptions


with sqlflite.connect(uri="grpc+tls://localhost:31337",
                        db_kwargs={"username": os.getenv("SQLFLITE_USERNAME", "sqlflite_username"),
                                   "password": os.getenv("SQLFLITE_PASSWORD", "sqlflite_password"),
                                   DatabaseOptions.TLS_SKIP_VERIFY.value: "true"  # 使用可信CA签名证书时不需要
                                   }
                        ) 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)

预期结果：

text
pyarrow.Table
n_nationkey: int32
n_name: string
----
n_nationkey: [[24]]
n_name: [["UNITED STATES"]]

通过sqlflite_client CLI工具连接

sqlflite_client CLI工具已内置于Docker镜像，也可作为独立可执行文件下载：

bash
sqlflite_client \
  --command Execute \
  --host "localhost" \
  --port 31337 \
  --username "sqlflite_username" \
  --password "sqlflite_password" \
  --query "SELECT version()" \
  --use-tls \
  --tls-skip-verify

预期结果：

text
Results from endpoint 1 of 1
Schema:
version(): string

Results:
version():   [
    "v1.1.1"
  ]

Total: 1

通过Ibis连接

详见：https://github.com/ibis-project/ibis-sqlflite

通过SQLAlchemy连接

详见：https://github.com/prmoore77/sqlalchemy-sqlflite-adbc-dialect

停止容器

bash
docker stop sqlflite

选项2：下载并运行sqlflite CLI可执行文件

下载最新版本的sqlflite_server CLI可执行文件：

• https://github.com/voltrondata/sqlflite/releases/latest/download/sqlflite_cli_linux_amd64.zip
• https://github.com/voltrondata/sqlflite/releases/latest/download/sqlflite_cli_linux_arm64.zip
• https://github.com/voltrondata/sqlflite/releases/latest/download/sqlflite_cli_macos_amd64.zip
• https://github.com/voltrondata/sqlflite/releases/latest/download/sqlflite_cli_macos_arm64.zip

运行命令：

bash
SQLFLITE_PASSWORD="sqlflite_password" sqlflite_server --database-filename data/some_db.duckdb --print-queries

查看所有选项：

bash
sqlflite_server --help

选项3：手动构建解决方案

1. 克隆仓库并构建静态库和可执行文件

bash
git clone https://github.com/voltrondata/sqlflite --recurse-submodules
cd sqlflite

# 构建并安装静态库和可执行文件
cmake -S . -B build -G Ninja -DCMAKE_INSTALL_PREFIX=/usr/local
cmake --build build --target install

2. 安装ADBC客户端交互的Python依赖（需Python 3.9+）

bash
python3 -m venv .venv
. .venv/bin/activate
pip install --upgrade pip setuptools wheel
pip install --requirement ./requirements.txt

3. 获取SQLite3示例数据

bash
wget https://github.com/lovasoa/TPCH-sqlite/releases/download/v1.0/TPC-H-small.db -O ./data/TPC-H-small.sqlite

4. 创建DuckDB数据库

bash
python "scripts/create_duckdb_database_file.py" \
       --file-name="TPC-H-small.duckdb" \
       --file-path="data" \
       --overwrite-file=true \
       --scale-factor=0.01

5. 生成TLS证书（可选）

bash
pushd tls
./gen-certs.sh
popd

6. 启动Flight SQL服务器

bash
SQLFLITE_PASSWORD="sqlflite_password" sqlflite_server --database-filename data/TPC-H-small.duckdb --print-queries

选择不同后端

默认使用DuckDB后端，可通过--backend或-B参数切换：

使用DuckDB后端（默认）

bash
SQLFLITE_PASSWORD="sqlflite_password" sqlflite_server --database-filename data/TPC-H-small.duckdb

或

bash
SQLFLITE_PASSWORD="sqlflite_password" sqlflite_server -B duckdb -D data/TPC-H-small.duckdb

使用SQLite后端

bash
SQLFLITE_PASSWORD="sqlflite_password" sqlflite_server -B sqlite -D data/TPC-H-small.sqlite

或

bash
SQLFLITE_PASSWORD="sqlflite_password" sqlflite_server --backend sqlite --database-filename data/TPC-H-small.sqlite

命令行帮助

运行sqlflite_server --help查看所有可用选项：

bash
sqlflite_server --help
Allowed options:
  --help                              显示帮助信息
  --version                           打印版本信息并退出
  -B [ --backend ] arg (=duckdb)      指定数据库后端，允许选项：duckdb, sqlite
  -H [ --hostname ] arg               指定服务器监听主机名，未设置则使用环境变量SQLFLITE_HOSTNAME，默认0.0.0.0
  -R [ --port ] arg (=31337)          指定服务器监听端口
  -D [ --database-filename ] arg      指定数据库文件路径（绝对路径或相对当前工作目录）
  -U [ --username ] arg               指定允许连接的用户名，未设置则使用环境变量SQLFLITE_USERNAME，默认sqlflite_username
  -P [ --password ] arg               指定连接密码，未设置则使用环境变量SQLFLITE_PASSWORD，未设置时服务器将启动失败
  -S [ --secret-key ] arg             指定用于签名JWT的密钥，未设置则使用环境变量SECRET_KEY，未设置时生成随机密钥
  -T [ --tls ] arg                    指定TLS证书和密钥文件路径
  -I [ --init-sql-commands ] arg      指定启动时执行的SQL命令，未设置则使用环境变量INIT_SQL_COMMANDS
  -F [ --init-sql-commands-file ] arg 指定包含启动SQL命令的文件路径，未设置则使用环境变量INIT_SQL_COMMANDS_FILE
  -M [ --mtls-ca-cert-filename ] arg  指定用于验证客户端的mTLS CA证书路径（PEM格式）
  -Q [ --print-queries ]              将客户端执行的查询打印到标准输出

Slim Docker镜像

提供不包含Python、TLS证书生成和示例数据库的精简镜像。必须提供以下环境变量：

• DATABASE_FILENAME - 数据库文件路径
• SQLFLITE_PASSWORD - 服务器密码

可选环境变量：

• TLS_ENABLED - 设置为"1"启用TLS（默认"0"禁用）
• TLS_CERT - 启用TLS时，TLS证书文件路径（需挂载到容器）
• TLS_KEY - 启用TLS时，TLS密钥文件路径（需挂载到容器）

运行命令：

bash
docker run --name sqlflite-slim \
           --detach \
           --rm \
           --tty \
           --init \
           --publish 31337:31337 \
           --env DATABASE_FILENAME="data/some_database.duckdb" \
           --env TLS_ENABLED="0" \
           --env SQLFLITE_PASSWORD="sqlflite_password" \
           --env PRINT_QUERIES="1" \
           --pull missing \
           voltrondata/sqlflite:latest-slim

详见容器入口脚本start_sqlflite_slim.sh。