voltrondata/flight-sql

Arrow Flight SQL server - DuckDB / SQLite

重要提示：此镜像已弃用，请使用新的 https://hub.docker.com/repository/docker/voltrondata/sqlflite 镜像替代。

https://hub.docker.com/r/voltrondata/flight-sql []([] https://github.com/voltrondata/flight-sql-server-example []([] []([***]

镜像概述

本镜像展示了如何使用DuckDB或SQLite作为后端数据库构建Apache Arrow Flight SQL服务器实现。它通过中间件支持认证，并允许通过TLS建立加密的数据库连接。有关Apache Arrow Flight SQL的更多信息，请参见这篇文章。

核心功能和特性

• 多后端支持：兼容DuckDB（默认）和SQLite数据库后端
• 安全连接：支持TLS加密传输，可通过环境变量启用/禁用
• 认证机制：基于密码的认证，通过JWT令牌管理会话
• 初始化配置：支持启动时执行SQL命令或SQL文件，自定义数据库环境
• 客户端兼容性：支持JDBC驱动、ADBC Python驱动及专用CLI工具连接
• 灵活部署：提供标准Docker镜像和精简版Docker镜像（无Python及示例数据）

使用场景

• 开发环境中快速搭建Arrow Flight SQL服务
• 数据分析场景下通过Arrow协议高效访问DuckDB/SQLite数据库
• 测试Arrow Flight SQL客户端应用（如JDBC/ADBC驱动兼容性测试）
• 构建基于Arrow列存格式的轻量级数据服务

使用方法

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

打开终端，拉取并运行已配置好的Docker镜像（如需在屏幕上查看标准输出，可将"--detach"改为"--interactive"）：

bash
docker run --name flight-sql \
           --detach \
           --rm \
           --tty \
           --init \
           --publish 31337:31337 \
           --env TLS_ENABLED="1" \
           --env FLIGHT_PASSWORD="flight_password" \
           --env PRINT_QUERIES="1" \
           --pull missing \
           voltrondata/flight-sql:latest

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

注意：可通过将环境变量TLS_ENABLED设置为"0"禁用容器内的TLS（默认值为"1"，即启用）。除非在Kubernetes中使用mTLS sidecar等类似机制，否则不建议禁用TLS，因为这会导致不安全连接。

可选：使用自定义数据库文件

运行Docker镜像时，可以指定自己的DuckDB数据库文件（数据库必须使用DuckDB 1.0.0版本构建）。

前提条件：安装DuckDB CLI
安装https://github.com/duckdb/duckdb/releases/tag/v1.0.0%E7%9A%84DuckDB CLI，并确保可执行文件在PATH中。

平台下载链接：
https://github.com/duckdb/duckdb/releases/download/v1.0.0/duckdb_cli-linux-amd64.zip
https://github.com/duckdb/duckdb/releases/download/v1.0.0/duckdb_cli-linux-aarch64.zip
https://github.com/duckdb/duckdb/releases/download/v1.0.0/duckdb_cli-osx-universal.zip

以下示例生成一个新的TPC-H Scale Factor 1（1GB）数据库文件，并运行docker镜像挂载该文件：

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

# 运行flight-sql docker容器，并将主机上创建的DuckDB数据库文件挂载到容器内
docker run --name flight-sql \
           --detach \
           --rm \
           --tty \
           --init \
           --publish 31337:31337 \
           --env TLS_ENABLED="1" \
           --env FLIGHT_PASSWORD="flight_password" \
           --pull missing \
           --mount type=bind,source=$(pwd),target=/opt/flight_sql/data \
           --env DATABASE_FILENAME="data/tpch_sf1.duckdb" \
           voltrondata/flight-sql:latest

运行初始化SQL命令

可通过设置环境变量INIT_SQL_COMMANDS在容器启动时执行初始化命令，值为用分号分隔的SQL命令字符串。例如：SET threads = 1; SET memory_limit = '1GB';。

以下是运行带初始化SQL命令的Docker镜像完整示例：

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

也可通过设置环境变量INIT_SQL_COMMANDS_FILE指定包含初始化SQL命令的文件路径（例如/tmp/init.sql），该文件必须挂载到容器内。

注意：对于DuckDB后端，会自动运行以下初始化命令：SET autoinstall_known_extensions = true; SET autoload_known_extensions = true;
注意：返回数据的SELECT初始化命令不会显示结果（不支持）。
注意：失败的初始化SQL命令会导致Flight SQL服务器中止并以非零退出码退出。

通过JDBC连接服务器

下载Apache Arrow Flight SQL JDBC驱动

使用以下JDBC连接字符串从主机连接到本地运行的Docker Flight SQL服务器（如修改了FLIGHT_PASSWORD环境变量的值，请相应更改密码）：

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

有关在流行数据库IDE工具DBeaver Community Edition中设置JDBC驱动的说明，请参见此https://github.com/voltrondata/setup-arrow-jdbc-driver-in-dbeaver%E3%80%82

注意：如果停止/重启Flight SQL Docker容器，并尝试使用相同密码通过JDBC连接，可能会出现错误："Invalid bearer token provided. Detail: Unauthenticated"。这是因为客户端JDBC驱动缓存了使用前一实例RSA私钥签名的bearer令牌。只需通过更改"FLIGHT_PASSWORD"环境变量设置新容器的密码，然后使用新密码通过JDBC连接。

通过新的ADBC Python Flight SQL驱动连接服务器

可使用新的Apache Arrow Python ADBC Flight SQL驱动查询Flight SQL服务器。ADBC相比JDBC具有性能优势，因为它最大限度地减少了序列化/反序列化，数据在所有阶段都保持列存格式。

有关ADBC和Flight SQL的更多信息，请参见此处。

确保已安装Python 3.9+，然后打开终端运行：

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

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

# 安装依赖，包括新的Arrow ADBC Flight SQL驱动
pip install --upgrade pip
pip install pandas pyarrow adbc_driver_flightsql

# 启动Python交互式shell
python

在Python shell中运行：

python
from adbc_driver_flightsql import dbapi as flight_sql, DatabaseOptions

flight_password = "flight_password"  # 生产环境中建议使用环境变量！

with flight_sql.connect(uri="grpc+tls://localhost:31337",
                        db_kwargs={"username": "flight_username",
                                   "password": flight_password,
                                   DatabaseOptions.TLS_SKIP_VERIFY.value: "true"  # 如果使用受信任CA签名的TLS证书，则不需要此选项
                                   }
                        ) 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"]]

通过新的flight_sql_client CLI工具连接

也可使用新的flight_sql_client CLI工具连接Flight SQL服务器并运行命令。该工具内置在Docker镜像中，也可作为独立可执行文件用于Linux和MacOS。

示例（从主机终端运行）：

bash
flight_sql_client \
  --command Execute \
  --host "localhost" \
  --port 31337 \
  --username "flight_username" \
  --password "flight_password" \
  --query "SELECT version()" \
  --use-tls \
  --tls-skip-verify

应返回：

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

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

Total: 1

停止服务

使用以下命令停止docker镜像：

bash
docker stop flight-sql

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

从以下支持的平台下载（并解压缩）最新版本的flight_sql_server CLI可执行文件：
https://github.com/voltrondata/flight-sql-server-example/releases/latest/download/flight_sql_cli_linux_amd64.zip
https://github.com/voltrondata/flight-sql-server-example/releases/latest/download/flight_sql_cli_linux_arm64.zip
https://github.com/voltrondata/flight-sql-server-example/releases/latest/download/flight_sql_cli_macos_amd64.zip
https://github.com/voltrondata/flight-sql-server-example/releases/latest/download/flight_sql_cli_macos_arm64.zip

然后在终端中运行：

bash
FLIGHT_PASSWORD="flight_password" flight_sql_server --database-filename data/some_db.duckdb --print-queries

查看所有程序选项：

bash
flight_sql_server --help

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

要手动构建解决方案并运行SQLite和DuckDB Flight SQL服务器，需要在机器上设置Python 3.9+虚拟环境。按照以下步骤操作：

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

bash
git clone https://github.com/voltrondata/flight-sql-server-example --recurse-submodules
cd flight-sql-server-example

# 构建并安装静态库和可执行文件
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. （可选）生成用于加密Flight SQL服务器流量的TLS证书

bash
pushd tls
./gen-certs.sh
popd

6. 启动Flight SQL服务器（使用--print-queries选项在运行时打印客户端SQL命令）

bash
FLIGHT_PASSWORD="flight_password" flight_sql_server --database-filename data/TPC-H-small.duckdb --print-queries

选择不同的后端

此选项允许从两个后端中选择：SQLite和DuckDB，默认使用DuckDB。

bash
$ FLIGHT_PASSWORD="flight_password" flight_sql_server --database-filename data/TPC-H-small.duckdb
Apache Arrow version: 17.0.0
WARNING - TLS is disabled for the Flight SQL server - this is insecure.
DuckDB version: v1.0.0
Running Init SQL command: 
SET autoinstall_known_extensions = true;
Running Init SQL command: 
 SET autoload_known_extensions = true;
Using database file: "/opt/flight_sql/data/TPC-H-small.duckdb"
Print Queries option is set to: false
Apache Arrow Flight SQL server - with engine: DuckDB - will listen on grpc+tcp://0.0.0.0:31337
Flight SQL server - started

上述命令等效于运行flight_sql_server -B duckdb或flight_sql --backend duckdb。要选择SQLite，运行：

bash
FLIGHT_PASSWORD="flight_password" flight_sql_server -B sqlite -D data/TPC-H-small.sqlite 

或

bash
FLIGHT_PASSWORD="flight_password" flight_sql_server --backend sqlite --database-filename data/TPC-H-small.sqlite

运行结果如下：

bash
Apache Arrow version: 17.0.0
WARNING - TLS is disabled for the Flight SQL server - this is insecure.
SQLite version: 3.45.0
Using database file: "/opt/flight_sql/data/TPC-H-small.sqlite"
Print Queries option is set to: false
Apache Arrow Flight SQL server - with engine: SQLite - will listen on grpc+tcp://0.0.0.0:31337
Flight SQL server - started

查看帮助

要查看所有可用选项，运行flight_sql_server --help：

bash
flight_sql_server --help
Allowed options:
  --help                              显示帮助信息
  --version                           打印版本信息并退出
  -B [ --backend ] arg (=duckdb)      指定数据库后端，允许选项：duckdb、sqlite
  -H [ --hostname ] arg               指定Flight SQL服务器监听的主机名。未设置时使用环境变量'FLIGHT_HOSTNAME'；若也未设置，默认使用'0.0.0.0'
  -R [ --port ] arg (=31337)          指定Flight SQL服务器监听的端口
  -D [ --database-filename ] arg      指定数据库文件名（绝对路径或相对于当前工作目录的路径）
  -U [ --username ] arg               指定允许客户端连接的用户名。未设置时使用环境变量'FLIGHT_USERNAME'；若也未设置，默认使用'flight_username'
  -P [ --password ] arg               指定客户端连接服务器的密码。未设置时使用环境变量'FLIGHT_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命令的文件