fgrehm/libduckdb

libduckdb Docker镜像文档

镜像概述

libduckdb是一个以Docker镜像形式分发DuckDB头文件和库文件的项目。该镜像主要为Ruby项目设计，旨在支持依赖https://github.com/suketa/ruby-duckdb%E7%9A%84%E5%BA%94%E7%94%A8%EF%BC%8C%E5%90%8C%E6%97%B6%E4%B9%9F%E9%80%82%E7%94%A8%E4%BA%8E%E5%85%B6%E4%BB%96%E9%9C%80%E8%A6%81%E4%BD%BF%E7%94%A8DuckDB%E7%9A%84%E5%B9%B3%E5%8F%B0%E3%80%82%E5%85%B6%E6%A0%B8%E5%BF%83%E4%BB%B7%E5%80%BC%E5%9C%A8%E4%BA%8E%E7%AE%80%E5%8C%96DuckDB%E5%9C%A8Docker%E7%8E%AF%E5%A2%83%E4%B8%AD%E7%9A%84%E9%83%A8%E7%BD%B2%EF%BC%8C%E5%B0%A4%E5%85%B6%E6%98%AF%E8%A7%A3%E5%86%B3%E4%BA%86Alpine%E7%AD%89%E7%B2%BE%E7%AE%80Linux%E5%8F%91%E8%A1%8C%E7%89%88%E4%B8%AD%E6%89%8B%E5%8A%A8%E7%BC%96%E8%AF%91DuckDB%E7%9A%84%E5%A4%8D%E6%9D%82%E9%97%AE%E9%A2%98%E3%80%82

核心功能和特性

• 预编译分发：提供预编译的DuckDB头文件（.h）和库文件（.so），避免手动编译的耗时过程（通常需要20-30分钟）。
• 跨发行版支持：支持多种Linux发行版，包括Alpine（基于musl libc）和Debian/Ubuntu（基于glibc）等。
• 简化依赖管理：通过Docker多阶段构建，可直接将预编译文件复制到目标镜像，无需手动下载和配置。

使用场景

• Ruby项目中需要使用suketa/ruby-duckdb gem时，作为DuckDB依赖的提供方。
• 在Docker环境中（尤其是使用Alpine或slim等精简基础镜像时）快速部署DuckDB。
• 避免因不同Linux发行版（如Alpine的musl libc与标准glibc差异）导致的DuckDB安装问题。

可用标签

所有可用标签请参见Docker Hub：https://hub.docker.com/r/fgrehm/libduckdb/tags

使用方法

基本用法

在Dockerfile中通过多阶段构建，从libduckdb镜像复制所需文件：

dockerfile
FROM fgrehm/libduckdb:<TAG> AS libduckdb

FROM some/base:image-tag

# 方式一：直接复制所有文件（信任镜像时使用）
COPY --from=libduckdb /libduckdb /

# 方式二：显式复制指定文件
COPY --from=libduckdb /libduckdb/usr/local/include/duckdb.h /usr/local/include
COPY --from=libduckdb /libduckdb/usr/local/lib/libduckdb.so /usr/local/lib

Alpine Linux示例

适用于基于Alpine的Ruby镜像：

dockerfile
FROM fgrehm/libduckdb:0.8.0-alpine3.18 AS libduckdb

FROM ruby:3.2-alpine3.18
RUN apk add --no-cache --update \
            make \
            g++

# 复制DuckDB文件
COPY --from=libduckdb /libduckdb /

# 实际项目中需添加Gemfile等步骤
RUN gem install duckdb

其他发行版示例（如Debian/Ubuntu）

适用于基于Debian的slim镜像：

dockerfile
FROM fgrehm/libduckdb:0.8.0 AS libduckdb

FROM ruby:3-slim

RUN apt-get update \
    && apt-get install -y --no-install-recommends make gcc \
    && rm -rf /var/lib/apt/lists/*

# 复制DuckDB文件
COPY --from=libduckdb /libduckdb /

# 实际项目中需添加Gemfile等步骤
RUN gem install duckdb

为什么需要此镜像

使用suketa/ruby-duckdb gem时，需要先安装DuckDB引擎，否则会出现类似以下错误：

=> gem install duckdb

...

**
duckdb >= 0.5.0 is not found. Install duckdb >= 0.5.0 library and header file.
**

在macOS上，可通过brew install duckdb轻松解决；但在Linux上，尤其是Alpine等精简发行版中，问题更为复杂：

• 标准Linux：需手动下载DuckDB的C++包并配置，但流程繁琐。
• Alpine Linux：由于基于musl libc，直接使用官方预编译包会因glibc依赖问题失败，需手动编译DuckDB（耗时20+分钟）。

本镜像通过提供预编译的DuckDB文件，解决了上述问题，可直接通过COPY命令在多阶段构建中集成，大幅简化部署流程。