datacatering/duckdb

DuckDB Docker 镜像技术文档

1. 镜像概述与主要用途

DuckDB Docker镜像是DuckDB嵌入式分析数据库的容器化部署方案，构建自GitHub仓库 https://github.com/data-catering/duckdb-docker%E3%80%82%E8%AF%A5%E9%95%9C%E5%83%8F%E6%97%A8%E5%9C%A8%E7%AE%80%E5%8C%96DuckDB%E7%9A%84%E9%83%A8%E7%BD%B2%E6%B5%81%E7%A8%8B%EF%BC%8C%E6%8F%90%E4%BE%9B%E6%97%A0%E9%9C%80%E6%89%8B%E5%8A%A8%E9%85%8D%E7%BD%AE%E4%BE%9D%E8%B5%96%E5%8D%B3%E5%8F%AF%E5%BF%AB%E9%80%9F%E5%90%AF%E5%8A%A8%E7%9A%84%E8%BF%90%E8%A1%8C%E7%8E%AF%E5%A2%83%EF%BC%8C%E6%94%AF%E6%8C%81%E5%91%BD%E4%BB%A4%E8%A1%8C%E4%BA%A4%E4%BA%92%E4%B8%8EWeb UI访问，适用于本地开发、数据分析及快速功能验证场景。

2. 核心功能与特性

2.1 基础功能

• DuckDB内核支持：集成DuckDB核心功能，包括SQL标准支持、ACID事务、列式存储优化、内存计算等嵌入式分析数据库特性。
• 轻量级部署：基于Docker容器化，无需本地安装DuckDB依赖，一键启动数据库实例。

2.2 镜像增强特性

• 交互模式支持：通过终端交互模式（-it）直接执行SQL命令，便捷进行数据查询与分析。
• Web UI集成：支持通过-ui参数启动内置Web UI，提供可视化操作界面（访问端口4213）。
• 跨平台兼容：适配Docker支持的各类操作系统（Linux、macOS、Windows），需配合Docker引擎运行。

3. 使用场景与适用范围

3.1 主要适用场景

• 本地数据分析：快速启动DuckDB实例，进行本地数据文件（CSV、Parquet等）的查询与分析。
• 开发与测试：为SQL脚本开发、数据处理逻辑验证提供隔离的数据库环境。
• 教学与演示：简化DuckDB入门门槛，无需复杂配置即可演示数据库功能。

3.2 适用人群

• 数据分析师、数据工程师
• 数据库开发与测试人员
• 需要轻量级SQL环境的开发者

4. 使用方法与部署示例

4.1 基础命令行交互模式

通过Docker直接启动DuckDB交互终端：

shell
docker run -it datacatering/duckdb:v1.4.0

参数说明：

• -i：保持标准输入打开，支持交互
• -t：分配伪终端，模拟终端环境

4.2 启动Web UI界面

通过-ui参数启动内置Web UI，支持浏览器访问：

shell
docker run --rm --net host -it datacatering/duckdb:v1.4.0 -ui

操作步骤：

1. 执行上述命令启动容器
2. 打开浏览器访问 http://localhost:4213 进入Web UI
3. 在UI中执行SQL查询、管理数据

参数说明：

• --rm：容器停止后自动删除，避免残留资源
• --net host：使用主机网络模式，确保容器内Web服务端口（4213）直接映射到主机
• -ui：启动Web UI服务

4.3 通过insta-infra工具启动

借助https://github.com/data-catering/insta-infra/tree/main%E5%B7%A5%E5%85%B7%E9%93%BE%E5%BF%AB%E9%80%9F%E9%83%A8%E7%BD%B2%EF%BC%9A

shell
# 克隆insta-infra仓库并进入目录（假设已完成前置配置）
./run.sh duckdb

注：insta-infra为数据工具快速部署脚本集合，具体使用需参考其官方文档。

4.4 Docker Compose部署示例

创建docker-compose.yml文件，配置DuckDB服务：

yaml
version: '3.8'
services:
  duckdb:
    image: datacatering/duckdb:v1.4.0
    network_mode: "host"  # 启用主机网络以暴露UI端口
    tty: true             # 等效于`-t`参数
    stdin_open: true      # 等效于`-i`参数
    command: -ui          # 启动Web UI
    # 可选：挂载本地目录持久化数据（需创建./data目录）
    volumes:
      - ./data:/root/.duckdb

启动服务：

shell
docker-compose up

5. 配置参数说明

5.1 容器运行参数

5.2 镜像命令参数

6. 注意事项

1. Docker Desktop主机网络配置：
   在Docker Desktop（Windows/macOS）中使用--net host时，需确保已启用主机网络支持，具体配置参考Docker官方文档。

2. 端口冲突处理：
   Web UI默认使用4213端口，若主机该端口被占用，需修改网络配置或停止占用进程。

3. 数据持久化：
   默认情况下，容器内数据存储于临时文件系统，若需持久化，需通过-v参数挂载本地目录（如-v ./duckdb_data:/root/.duckdb）。

4. 版本兼容性：
   示例中使用标签v1.4.0，实际部署时需根据需求指定DuckDB版本，可通过https://hub.docker.com/r/datacatering/duckdb%E6%9F%A5%E7%9C%8B%E5%8F%AF%E7%94%A8%E6%A0%87%E7%AD%BE%E3%80%82

7. 参考链接

• 镜像源码仓库：https://github.com/data-catering/duckdb-docker
• DuckDB官方文档：duckdb.org/docs
• insta-infra工具：https://github.com/data-catering/insta-infra/tree/main