DuckDB 1.5 + Quack 协议深度实战：当嵌入式分析数据库学会"说话"——从 VARIANT 类型到内置 GEOMETRY、从 PEG 解析器到 HTTP 原生客户端-服务器协议的生产级完全指南（2026）

引言：一只学会说话的鸭子

如果你在过去几年里从事数据分析相关工作，几乎不可能没听过 DuckDB。这个自称为"分析领域的 SQLite"的嵌入式列式数据库，凭借零配置、进程内运行、直接查询 Parquet/CSV 的能力，迅速成为数据科学家和工程师的标配工具。但一直以来，它有一个明显的短板：它不能"说话"——多个进程无法同时读写同一个 DuckDB 数据库文件。

2026 年，DuckDB 团队一口气放出了两个重磅更新：3 月发布的 DuckDB 1.5.0（Variegata） 和 5 月发布的 Quack 远程协议。前者带来了 VARIANT 类型、内置 GEOMETRY、PEG 解析器、全新 CLI 等重要特性；后者则彻底解决了多进程并发访问的问题——DuckDB 终于可以作为一个真正的客户端-服务器数据库运行了。

本文将从架构设计、核心特性、代码实战、性能优化四个维度，深度剖析这两大更新，帮你理解 DuckDB 正在从"单进程分析工具"进化为"通用数据处理基础设施"的技术路径。

一、DuckDB 1.5.0 核心特性全解析

1.1 VARIANT 类型：当 SQL 遇到半结构化数据

在数据分析的实际场景中，我们经常遇到 schema 不固定的数据：API 返回的 JSON 响应、日志中的嵌套字段、不同版本的事件数据。传统关系型数据库处理这类数据的方式是使用 JSON 类型，然后通过各种提取函数来访问嵌套字段。

DuckDB 1.5 引入了 VARIANT 类型，这是从 Snowflake 借鉴的概念，但在嵌入式数据库中实现尚属首次。VARIANT 的核心思想是：值可以拥有自己的类型，而不必在列级别统一。

-- 创建包含 VARIANT 列的表
CREATE TABLE events (
    id INTEGER,
    payload VARIANT
);

-- 插入不同结构的 JSON 数据
INSERT INTO events VALUES
    (1, {'type': 'click', 'x': 100, 'y': 200}),
    (2, {'type': 'purchase', 'item': 'laptop', 'price': 9999.99}),
    (3, {'type': 'login', 'device': 'iPhone', 'os_version': '18.0'});

-- 查询时按类型过滤
SELECT 
    id,
    payload.type AS event_type,
    payload.x,
    payload.price
FROM events
WHERE payload.type = 'click';

-- 结果:
-- id | event_type | x   | price
-- 1  | click      | 100 | NULL

VARIANT 与 JSON 类型的关键区别在于存储和查询效率：

-- JSON 类型：每次查询都需要重新解析字符串
SELECT json_extract(raw_json, '$.price')::DOUBLE AS price
FROM json_events;

-- VARIANT 类型：类型信息已存储，直接读取
SELECT payload.price::DOUBLE AS price
FROM events;

VARIANT 内部使用了 DuckDB 的 tagged union 表示，每个值存储时附带类型标签。这意味着查询时不需要重新解析，访问嵌套字段的性能比 JSON 类型提升 3-5 倍（官方基准测试数据）。

实战：处理动态 schema 的 API 响应

import duckdb

conn = duckdb.connect()

# 创建表
conn.execute("""
    CREATE TABLE api_responses (
        request_id VARCHAR,
        response VARIANT,
        timestamp TIMESTAMP
    )
""")

# 模拟不同版本的 API 响应
conn.execute("""
    INSERT INTO api_responses VALUES
        ('req_001', {'version': 1, 'user': {'name': 'Alice', 'age': 30}}, '2026-01-15 10:00:00'),
        ('req_002', {'version': 2, 'user': {'name': 'Bob', 'email': 'bob@test.com', 'preferences': {'theme': 'dark'}}, 'region': 'CN'}, '2026-03-20 14:30:00')
""")

# 跨版本查询：v2 新增了 email 字段，v1 没有
result = conn.execute("""
    SELECT 
        request_id,
        response.version AS api_version,
        response.user.name AS user_name,
        COALESCE(response.user.email, 'N/A') AS email,
        COALESCE(response.user.preferences.theme, 'default') AS theme
    FROM api_responses
    ORDER BY timestamp
""").fetchall()

for row in result:
    print(f"Request: {row[0]}, Version: {row[1]}, User: {row[2]}, Email: {row[3]}, Theme: {row[4]}")

# 输出:
# Request: req_001, Version: 1, User: Alice, Email: N/A, Theme: default
# Request: req_002, Version: 2, User: Bob, Email: bob@test.com, Theme: dark

1.2 内置 GEOMETRY 类型：空间分析无需扩展

在此之前，DuckDB 的空间分析需要加载 spatial 扩展。1.5 版本将 GEOMETRY 类型内置到核心引擎中，意味着开箱即用的空间数据处理能力。

-- 不再需要 INSTALL spatial; LOAD spatial;
-- 直接使用 GEOMETRY 类型
CREATE TABLE locations (
    id INTEGER,
    name VARCHAR,
    point GEOMETRY,
    area GEOMETRY
);

-- 创建点
INSERT INTO locations VALUES
    (1, 'Office', ST_Point2D(116.397, 39.908), NULL),
    (2, 'Warehouse', ST_Point2D(121.474, 31.230), NULL);

-- 计算两点间距离（米）
SELECT 
    a.name AS from_loc,
    b.name AS to_loc,
    ST_Distance(a.point, b.point) AS distance_degrees
FROM locations a, locations b
WHERE a.id = 1 AND b.id = 2;

-- 空间过滤：查找某区域内的点
SELECT name 
FROM locations 
WHERE ST_Within(point, ST_MakeEnvelope(116.0, 39.5, 117.0, 40.0));

内置化的好处不仅是省去了安装扩展的步骤，更重要的是 GEOMETRY 类型可以与 DuckDB 的向量化执行引擎深度集成：

-- 空间聚合：计算所有点的凸包
SELECT ST_ConvexHull(list(point)) AS hull
FROM locations;

-- 与 Parquet 数据源结合
SELECT count(*) AS points_in_region
FROM read_parquet('s3://my-bucket/geo-data/*.parquet')
WHERE ST_Within(geom, ST_Buffer(ST_Point2D(116.397, 39.908), 0.01));

1.3 PEG 解析器：SQL 解析的未来

DuckDB 1.5 引入了基于 PEG（Parser Expression Grammars）的实验性 SQL 解析器，替代了原有的递归下降解析器。这看似是一个内部实现细节，实际上影响深远。

传统递归下降解析器的局限：

• 错误信息不够友好（"syntax error at line 1"这类无用的报错）
• 不容易扩展语法（添加新语法结构需要手动编写解析代码）
• 自动补全支持有限

PEG 解析器的优势：

-- 启用 PEG 解析器
CALL enable_peg_parser();

-- 现在错误信息更加精准
SELECT FORM ducks;
-- 错误: Expected "FROM" but got "FORM" at position 7
-- 建议: Did you mean "FROM"?

-- Tab 补全也更智能
SELECT * FROM ducks WHERE habitat IS [TAB]
-- 自动建议: NOT NULL, NULL, 'wetland', 'grassland'

PEG 解析器的核心设计是语法规则可以被扩展插件修改。这意味着第三方扩展可以定义自己的 SQL 语法：

-- 假设某个扩展添加了 GRAPH QUERY 语法
-- PEG 解析器可以在运行时注册新的语法规则
CALL register_extension_grammar('graph');

-- 然后就可以直接使用扩展定义的语法
GRAPH QUERY 
  MATCH (n:Person)-[:KNOWS]->(m:Person)
  WHERE n.name = 'Alice'
  RETURN m.name;

虽然 PEG 解析器目前默认关闭，但它代表了 DuckDB SQL 引擎的未来方向。预计在 v2.0 中将默认启用。

1.4 全新 CLI：从终端工具到交互式体验

DuckDB 1.5 对 CLI 进行了全面重做，称之为 "Friendly CLI"。这不仅仅是界面美化，而是一整套交互体验的升级。

动态提示符

-- 旧版 CLI 的提示符始终是 "D "
D 

-- 新版 CLI 显示当前数据库和 schema
memory D 
-- ATTACH 后
my_database D 
-- USE schema 后
my_database.analytics D 

提示符支持自定义：

-- 使用括号代码自定义提示符
.prompt {database}.{schema} > 
-- 设置最大长度
.prompt {database:10} > 
-- 自定义颜色
.prompt {database:green} {schema:cyan} > 

语法高亮和分页器

-- 自动语法高亮（暗色/亮色模式）
SELECT name, count(*) AS cnt
FROM ducks
GROUP BY ALL
ORDER BY cnt DESC
LIMIT 10;

-- 结果超过 50 行自动启用分页器
FROM range(0, 1000);
-- 使用 Page Up/Down 导航，按 Q 退出

用 _ 访问上次查询结果

这是我最喜欢的新特性之一。在交互式分析中，经常需要对上一次查询的结果做进一步筛选：

-- 第一次查询
SELECT * FROM sales WHERE year = 2026;
-- 假设返回了 1000 行

-- 直接对结果进一步过滤，不需要重跑
SELECT * FROM _ WHERE region = 'CN';
-- 还可以继续链式操作
SELECT sum(amount) FROM _;

.tables 命令增强

my_database D .tables

 ────────────── my_database ───────────────
 ───────────────── main ──────────────────
┌─────────────────┐┌──────────────────────┐
│      orders     ││       customers      │
│                 ││                      │
│ id      integer ││ id           integer │
│ amount  double  ││ name         varchar │
│ date    date    ││ region       varchar │
│                 ││                      │
│    5000 rows    ││     1200 rows        │
└─────────────────┘└──────────────────────┘

1.5 其他重要更新

无损 CHECKPOINT

DuckDB 的 checkpoint 机制在 1.5 中得到了改进。之前的 checkpoint 会在 WAL 合并时锁住整个数据库，1.5 引入了增量 checkpoint，减少了写操作的阻塞时间。

-- 强制执行 checkpoint（不再阻塞读操作）
CHECKPOINT;

-- 查看当前 WAL 大小
SELECT 
    database_name,
    wal_size / 1024 / 1024 AS wal_mb
FROM duckdb_databases();

改进的 Parquet 读写

-- 写 Parquet 时支持列级别压缩设置
COPY (SELECT * FROM large_table) 
TO 'output.parquet' (FORMAT PARQUET, COMPRESSION 'ZSTD', COMPRESSION_LEVEL 9);

-- 读取 Parquet 时支持 row_group 级别的谓词下推
SELECT count(*) 
FROM read_parquet('s3://data/*.parquet', 
    filename=true, 
    file_row_number=true)
WHERE filename LIKE '%2026-06%';

二、Quack 协议：DuckDB 的客户端-服务器革命

2.1 为什么嵌入式数据库需要客户端-服务器模式？

DuckDB 一直是"进程内"数据库的代表——没有独立的服务进程，直接嵌入到宿主进程中运行。这种架构的优势很明显：零网络开销，API 调用直接操作内存数据结构，性能极高。

但这种架构有一个根本性限制：DuckDB 的单个数据库文件同一时刻只能被一个进程修改。这是因为 DuckDB 在内存中维护了大量的状态（缓冲区、索引、统计信息等），如果多个进程同时修改，需要一种机制来同步这些内存状态，而这在进程间共享内存的方案中极其复杂。

在实际业务中，这个限制导致了很多痛点：

1. 数据采集 + 实时分析：多个采集进程想写入同一个 DuckDB，同时分析进程需要读取最新数据
2. 微服务架构：多个服务实例需要共享同一个分析数据源
3. ETL 管道：不同阶段的处理进程需要读写同一组表
4. BI 看板：多个用户同时查询，偶尔还需要写入

社区提出了很多 workaround：用 Arrow Flight SQL 做协议层、用 MotherDuck 的私有协议、甚至把 DuckDB 嵌入 PostgreSQL 再用 pg 协议（所谓的 "EleDucken" 模式）。但这些方案要么复杂，要么依赖第三方，要么有性能损耗。

Quack 协议的出现，意味着 DuckDB 官方给出了一个优雅的解决方案。

2.2 Quack 协议架构设计

Quack 的设计哲学可以用一句话概括：用 HTTP 的简单性，逼近进程内调用的性能。

核心设计决策：

架构图（简化）：

┌─────────────────────┐         HTTP/2 + Arrow          ┌─────────────────────┐
│   DuckDB Client     │ ◄──────────────────────────────► │   DuckDB Server     │
│                     │                                  │                     │
│  ┌───────────────┐  │    ┌──────────────────────┐      │  ┌───────────────┐  │
│  │ Query Planner │  │    │  Connection Manager  │      │  │ Query Engine  │  │
│  └───────────────┘  │    └──────────────────────┘      │  └───────────────┘  │
│  ┌───────────────┐  │    ┌──────────────────────┐      │  ┌───────────────┐  │
│  │ Result Cache  │  │    │  Auth & TLS Layer    │      │  │ Storage Engine│  │
│  └───────────────┘  │    └──────────────────────┘      │  └───────────────┘  │
│  ┌───────────────┐  │    ┌──────────────────────┐      │  ┌───────────────┐  │
│  │ Local Buffer  │  │    │  Arrow Serialization │      │  │ WAL Manager   │  │
│  └───────────────┘  │    └──────────────────────┘      │  └───────────────┘  │
└─────────────────────┘                                  └─────────────────────┘

2.3 Quack 快速上手

服务器端

-- 安装 Quack 扩展
INSTALL quack FROM core_nightly;
LOAD quack;

-- 启动服务器
CALL quack_serve(
    'quack:localhost:5433',
    token = 'my_secret_token_2026'
);

-- 也可以绑定所有网络接口
CALL quack_serve(
    'quack:0.0.0.0:5433',
    token = 'my_secret_token_2026'
);

-- 创建一些测试数据
CREATE TABLE sales AS
    SELECT 
        range AS id,
        'product_' || (range % 100) AS product,
        (random() * 1000)::INTEGER AS amount,
        '2026-06-' || (range % 30 + 1) AS sale_date
    FROM range(1000000);

-- 服务器保持运行，等待客户端连接

客户端

-- 同样需要安装 Quack 扩展
INSTALL quack FROM core_nightly;
LOAD quack;

-- 配置认证
CREATE SECRET (
    TYPE quack,
    TOKEN 'my_secret_token_2026'
);

-- 连接到远程 DuckDB 实例
ATTACH 'quack:localhost:5433' AS remote_db;

-- 查询远程数据
SELECT product, sum(amount) AS total
FROM remote_db.sales
GROUP BY product
ORDER BY total DESC
LIMIT 5;

-- 在远程数据库创建表
CREATE TABLE remote_db.metrics (
    metric_name VARCHAR,
    value DOUBLE,
    recorded_at TIMESTAMP DEFAULT current_timestamp
);

-- 向远程表写入数据
INSERT INTO remote_db.metrics VALUES
    ('cpu_usage', 45.2, '2026-06-22 08:00:00'),
    ('memory_usage', 78.5, '2026-06-22 08:00:00');

2.4 Quack 的查询执行模型

Quack 支持两种查询执行模式，根据查询的复杂度自动选择：

模式一：查询下推（Query Pushdown）

对于简单的单表查询，Quack 会将整个查询下推到服务器端执行，只返回结果集：

-- 客户端发出的查询会被完整地下推到服务器
SELECT count(*) FROM remote_db.sales WHERE amount > 500;
-- 执行流程: Client → 发送 SQL → Server 执行 → 返回 Arrow 批次 → Client 接收

模式二：SQL 直传（Verbatim Query）

对于复杂查询（多表 JOIN、子查询、窗口函数等），可以使用 query 函数显式地将查询发送到服务器端执行：

-- 将复杂查询直接在服务器端执行
SELECT * FROM quack_query(
    'remote_db',
    'SELECT product, sum(amount) as total, 
            avg(amount) as avg_amount,
            count(*) as cnt
     FROM sales 
     WHERE sale_date >= ''2026-06-01''
     GROUP BY GROUPING SETS (product, ())
     ORDER BY total DESC'
);

这种设计的好处是：简单查询享受自动优化的便利，复杂查询可以用直传模式避免客户端的查询计划不优问题。

2.5 数据传输优化

Quack 在数据传输上做了大量优化，使其性能接近进程内调用：

列式 Arrow 传输

DuckDB 内部使用列式向量化执行引擎，数据天然就是按列组织的。Quack 直接使用 Apache Arrow 格式传输数据，这意味着：

• 数据不需要从列式转换为行式再转回列式
• Arrow 的零拷贝特性减少了内存分配和拷贝
• 客户端接收 Arrow 批次后可以直接用于计算，无需反序列化

import duckdb

# 客户端 Python 代码
client = duckdb.connect()
client.execute("INSTALL quack FROM core_nightly")
client.execute("LOAD quack")
client.execute("CREATE SECRET (TYPE quack, TOKEN 'my_secret_token_2026')")
client.execute("ATTACH 'quack:localhost:5433' AS remote")

# 查询结果自动以 Arrow 格式传输
result = client.execute("""
    SELECT * FROM remote.sales 
    WHERE amount > 100
""").fetch_arrow_reader()

# 零拷贝转换为 pandas DataFrame
import pyarrow as pa
table = result.read_all()
df = table.to_pandas()
print(f"Fetched {len(df)} rows, columns: {list(df.columns)}")

流式结果传输

对于大结果集，Quack 支持流式传输，客户端可以在第一批数据到达时就开始处理：

# 流式读取远程查询结果
reader = client.execute("""
    SELECT * FROM remote.sales
""").fetch_arrow_reader()

total = 0
for batch in reader:
    # 每收到一个 Arrow 批次就处理
    total += len(batch)
    print(f"Processed {total} rows so far...")

print(f"Total: {total} rows")

2.6 并发写入

Quack 解决的另一个核心问题是并发写入。在进程内模式下，只有一个进程可以写入 DuckDB。通过 Quack，多个客户端可以同时向服务器端写入：

import duckdb
import threading
import time

def writer(writer_id, num_records):
    """模拟多个写入进程"""
    conn = duckdb.connect()
    conn.execute("INSTALL quack FROM core_nightly")
    conn.execute("LOAD quack")
    conn.execute("CREATE SECRET (TYPE quack, TOKEN 'my_secret_token_2026')")
    conn.execute("ATTACH 'quack:localhost:5433' AS remote")
    
    for i in range(num_records):
        conn.execute(f"""
            INSERT INTO remote.events VALUES
            ('writer_{writer_id}', 'event_{i}', current_timestamp, {i * 1.5})
        """)
        time.sleep(0.001)  # 模拟真实写入间隔
    
    conn.close()
    print(f"Writer {writer_id} done")

# 启动 5 个并发写入线程
threads = []
for i in range(5):
    t = threading.Thread(target=writer, args=(i, 200))
    threads.append(t)
    t.start()

for t in threads:
    t.join()

# 验证所有数据都已写入
conn = duckdb.connect()
conn.execute("INSTALL quack FROM core_nightly")
conn.execute("LOAD quack")
conn.execute("CREATE SECRET (TYPE quack, TOKEN 'my_secret_token_2026')")
conn.execute("ATTACH 'quack:localhost:5433' AS remote")
count = conn.execute("SELECT count(*) FROM remote.events").fetchone()[0]
print(f"Total records written: {count}")  # 应为 1000

服务器端通过事务隔离和行级锁来保证并发写入的正确性：

-- 服务器端监控
SELECT * FROM duckdb_settings() 
WHERE name LIKE '%quack%';

-- 查看活跃连接
CALL quack_connections();

-- 查看查询历史
SELECT query, query_type, 
       rows_returned, 
       execution_time_ms
FROM quack_query_log()
ORDER BY execution_time_ms DESC
LIMIT 10;

三、生产级实战场景

3.1 场景一：实时数据采集 + OLAP 分析

这是 Quack 最典型的使用场景。多个数据采集服务将数据写入同一个 DuckDB 实例，分析师通过客户端实时查询。

架构设计

┌──────────┐   ┌──────────┐   ┌──────────┐
│ Collector│   │ Collector│   │ Collector│
│ (Go)     │   │ (Python) │   │ (Rust)   │
└─────┬────┘   └─────┬────┘   └─────┬────┘
      │              │              │
      │   Quack Protocol (HTTP/2)  │
      └──────────────┼──────────────┘
                     │
              ┌──────▼──────┐
              │ DuckDB      │
              │ Server      │
              │ (Quack)     │
              └──────┬──────┘
                     │
      ┌──────────────┼──────────────┐
      │              │              │
┌─────▼────┐  ┌─────▼────┐  ┌─────▼────┐
│ Jupyter  │  │ Grafana  │  │ CLI      │
│ Notebook │  │ Plugin   │  │ Client   │
└──────────┘  └──────────┘  └──────────┘

服务器端配置

-- server_setup.sql
-- 加载扩展
INSTALL quack FROM core_nightly;
LOAD quack;

-- 创建数据表
CREATE TABLE IF NOT EXISTS telemetry (
    source VARCHAR,
    metric_name VARCHAR,
    value DOUBLE,
    tags MAP(VARCHAR, VARCHAR),
    ingested_at TIMESTAMP DEFAULT current_timestamp
);

-- 创建聚合物化视图（加速查询）
CREATE MATERIALIZED VIEW telemetry_hourly AS
SELECT 
    source,
    metric_name,
    date_trunc('hour', ingested_at) AS hour,
    avg(value) AS avg_value,
    min(value) AS min_value,
    max(value) AS max_value,
    count(*) AS sample_count
FROM telemetry
GROUP BY source, metric_name, date_trunc('hour', ingested_at);

-- 启动 Quack 服务器
CALL quack_serve(
    'quack:0.0.0.0:5433',
    token = 'prod_telemetry_token_2026'
);

Go 采集端

package main

import (
    "database/sql"
    "fmt"
    "log"
    "time"

    _ "github.com/marcboeker/go-duckdb"
)

func main() {
    db, err := sql.Open("duckdb", "")
    if err != nil {
        log.Fatal(err)
    }
    defer db.Close()

    // 安装和加载 Quack 扩展
    db.Exec("INSTALL quack FROM core_nightly")
    db.Exec("LOAD quack")
    db.Exec("CREATE SECRET (TYPE quack, TOKEN 'prod_telemetry_token_2026')")
    db.Exec("ATTACH 'quack:server:5433' AS remote")

    // 批量写入遥测数据
    for i := 0; i < 1000; i++ {
        _, err = db.Exec(`
            INSERT INTO remote.telemetry (source, metric_name, value, tags)
            VALUES (?, ?, ?, map(['host'], ['server-1']))
        `, "collector-go", "cpu_percent", float64(i%100), 
        )
        if err != nil {
            log.Printf("Insert failed: %v", err)
        }
        time.Sleep(100 * time.Millisecond)
    }
    fmt.Println("Done writing 1000 telemetry records")
}

Python 分析端

import duckdb

conn = duckdb.connect()
conn.execute("INSTALL quack FROM core_nightly")
conn.execute("LOAD quack")
conn.execute("CREATE SECRET (TYPE quack, TOKEN 'prod_telemetry_token_2026')")
conn.execute("ATTACH 'quack:server:5433' AS remote")

# 实时查询 - 直接查明细表
print("=== 最近 10 条遥测数据 ===")
result = conn.execute("""
    SELECT source, metric_name, value, ingested_at
    FROM remote.telemetry
    ORDER BY ingested_at DESC
    LIMIT 10
""").fetchdf()
print(result)

# 聚合查询 - 命中物化视图
print("\n=== 每小时聚合统计 ===")
result = conn.execute("""
    SELECT hour, source, avg_value, sample_count
    FROM remote.telemetry_hourly
    ORDER BY hour DESC
    LIMIT 24
""").fetchdf()
print(result)

3.2 场景二：跨数据库联邦查询

DuckDB 1.5 的 ATTACH 语句 + Quack 使得联邦查询变得异常简单：

-- 同时连接多个数据源
INSTALL postgres; LOAD postgres;
INSTALL quack FROM core_nightly; LOAD quack;

-- 连接 PostgreSQL（用户数据）
ATTACH 'host=localhost user=postgres dbname=users' AS pg_db (TYPE postgres);

-- 连接远程 DuckDB（订单数据）
CREATE SECRET (TYPE quack, TOKEN 'analytics_token');
ATTACH 'quack:analytics-server:5433' AS analytics_db;

-- 跨数据库联邦查询
SELECT 
    u.name,
    u.email,
    o.total_amount,
    o.order_count
FROM pg_db.users u
JOIN (
    SELECT user_id, sum(amount) AS total_amount, count(*) AS order_count
    FROM analytics_db.orders
    WHERE created_at >= '2026-06-01'
    GROUP BY user_id
) o ON u.id = o.user_id
ORDER BY o.total_amount DESC
LIMIT 20;

3.3 场景三：本地开发 + 远程生产的无缝切换

import duckdb
import os

class DataService:
    def __init__(self, mode='local'):
        self.conn = duckdb.connect()
        if mode == 'remote':
            self._setup_remote()
        else:
            self._setup_local()
    
    def _setup_local(self):
        """本地开发模式：直接操作本地文件"""
        self.conn.execute("""
            ATTACH 'dev.duckdb' AS db
        """)
    
    def _setup_remote(self):
        """远程生产模式：通过 Quack 连接"""
        self.conn.execute("INSTALL quack FROM core_nightly")
        self.conn.execute("LOAD quack")
        self.conn.execute(f"""
            CREATE SECRET (TYPE quack, TOKEN '{os.environ['QUACK_TOKEN']}')
        """)
        self.conn.execute(f"""
            ATTACH 'quack:{os.environ['QUACK_HOST']}:5433' AS db
        """)
    
    def get_daily_metrics(self, date):
        """查询逻辑完全一致，无需修改"""
        return self.conn.execute(f"""
            SELECT metric_name, avg(value) as avg_value
            FROM db.metrics
            WHERE date = '{date}'
            GROUP BY metric_name
        """).fetchdf()

# 开发环境
dev_service = DataService(mode='local')
df = dev_service.get_daily_metrics('2026-06-22')

# 生产环境（只需切换 mode）
prod_service = DataService(mode='remote')
df = prod_service.get_daily_metrics('2026-06-22')

四、性能优化实战

4.1 Quack 协议性能基准

DuckDB 官方发布的 Quack 基准测试结果（TPC-H SF10，约 10GB 数据）：

关键发现：

• 查询密集型负载：Quack 的开销非常小（4-15%），因为查询下推使得大部分计算在服务器端完成
• 数据传输密集型：跨网络时开销较大，但 Arrow 列式传输仍然比行式协议（如 PostgreSQL 的 libpq）快 3-5 倍
• 批量写入：本地震荡在 10% 以内，跨网络建议攒批后一次性写入

4.2 查询优化策略

策略一：利用查询下推

-- ❌ 低效：在客户端过滤大量数据
SELECT * FROM remote.sales;
-- 然后在应用层过滤

-- ✅ 高效：让 WHERE 子句下推到服务器执行
SELECT product, sum(amount) 
FROM remote.sales 
WHERE sale_date >= '2026-06-01'
GROUP BY product;

策略二：批量写入

import duckdb

conn = duckdb.connect()
conn.execute("INSTALL quack FROM core_nightly")
conn.execute("LOAD quack")
conn.execute("CREATE SECRET (TYPE quack, TOKEN 'my_token')")
conn.execute("ATTACH 'quack:server:5433' AS remote")

# ❌ 逐行写入：每行都是一次网络往返
for record in records:
    conn.execute(f"INSERT INTO remote.events VALUES (?, ?, ?)", record)

# ✅ 批量写入：一次性传输
conn.execute("""
    INSERT INTO remote.events
    SELECT * FROM (VALUES 
        ('event_1', 'click', 1.0),
        ('event_2', 'purchase', 99.9),
        ('event_3', 'login', 0.0),
        -- ... 更多行
    ) AS t(name, type, value)
""")

# ✅ 更好的方式：用 Appender API
import duckdb
conn_local = duckdb.connect()
# 先写入本地临时表
conn_local.execute("CREATE TEMP TABLE temp_events AS SELECT * FROM read_csv('events.csv')")
# 然后一次性推送到远程
conn_local.execute("""
    COPY (SELECT * FROM temp_events) TO 'quack:server:5433/remote.events'
""")

策略三：物化视图加速

-- 在服务器端创建物化视图
CREATE MATERIALIZED VIEW daily_summary AS
SELECT 
    date_trunc('day', created_at) AS day,
    category,
    count(*) AS event_count,
    avg(value) AS avg_value
FROM events
GROUP BY date_trunc('day', created_at), category;

-- 客户端查询物化视图，性能提升 10-50 倍
SELECT * FROM remote.daily_summary 
WHERE day >= '2026-06-01'
ORDER BY day;

4.3 网络优化

启用 TLS

-- 服务器端启用 TLS
CALL quack_serve(
    'quack:0.0.0.0:5433',
    token = 'my_secret_token',
    certificate = '/path/to/server.crt',
    key = '/path/to/server.key'
);

连接池管理

import duckdb
from contextlib import contextmanager

class QuackConnectionPool:
    def __init__(self, host, token, pool_size=5):
        self.host = host
        self.token = token
        self.pool_size = pool_size
        self._pool = []
        self._init_pool()
    
    def _create_connection(self):
        conn = duckdb.connect()
        conn.execute("INSTALL quack FROM core_nightly")
        conn.execute("LOAD quack")
        conn.execute(f"CREATE SECRET (TYPE quack, TOKEN '{self.token}')")
        conn.execute(f"ATTACH 'quack:{self.host}:5433' AS remote")
        return conn
    
    def _init_pool(self):
        for _ in range(self.pool_size):
            self._pool.append(self._create_connection())
    
    @contextmanager
    def get_connection(self):
        if not self._pool:
            self._pool.append(self._create_connection())
        conn = self._pool.pop()
        try:
            yield conn
        finally:
            self._pool.append(conn)

# 使用连接池
pool = QuackConnectionPool('analytics-server', 'my_token')

with pool.get_connection() as conn:
    result = conn.execute("""
        SELECT * FROM remote.daily_summary 
        WHERE day = current_date
    """).fetchdf()
    print(result)

4.4 内存管理

Quack 服务器端需要特别关注内存使用，因为多个客户端的查询可能同时消耗大量内存：

-- 设置内存限制（服务器端）
SET memory_limit = '4GB';

-- 设置最大并发查询数
CALL quack_set_setting('max_concurrent_queries', 10);

-- 设置每查询内存限制
SET max_memory_per_query = '1GB';

-- 监控内存使用
SELECT 
    database_name,
    memory_usage_bytes / 1024 / 1024 AS memory_mb
FROM duckdb_databases();

-- 查看临时目录使用情况
SELECT current_setting('temp_directory');

五、DuckDB v2.0 展望

根据官方路线图，计划于 2026 年 9 月发布的 DuckDB v2.0 将带来以下重大变更：

5.1 PEG 解析器默认启用

v2.0 将默认启用 PEG 解析器，这意味着：

• 所有错误信息将更友好
• 扩展可以自定义 SQL 语法
• 自动补全功能将更加强大

5.2 Quack 协议稳定化

Quack 将从 beta 阶段毕业，移入核心扩展仓库（从 core_nightly 迁移到 core），并可能带来：

• WebSocket 传输支持（更低的延迟）
• 更细粒度的权限控制
• 内置连接池和负载均衡

5.3 存储格式升级

v2.0 可能引入新的存储格式版本，提升：

• 列式编码效率（更好的压缩比）
• 增量 checkpoint 性能
• 并发 I/O 支持

5.4 LTS 策略

DuckDB 1.4（Andium）作为 LTS 版本将持续更新到 2026 年 9 月。如果你的生产环境需要稳定性，建议继续使用 1.4 LTS；如果需要新特性（VARIANT、Quack 等），则升级到 1.5。

六、总结

DuckDB 1.5 和 Quack 协议的发布，标志着 DuckDB 从一个"数据分析的瑞士军刀"进化为"通用数据处理基础设施"的关键一步。让我们回顾核心要点：

DuckDB 1.5 的关键收获：

1. VARIANT 类型让 SQL 处理半结构化数据不再痛苦，3-5 倍的查询性能提升是实打实的
2. 内置 GEOMETRY让空间分析开箱即用，不再需要额外加载扩展
3. PEG 解析器是 SQL 引擎的未来，虽然目前默认关闭，但值得提前体验
4. 全新 CLI大幅提升了交互式分析的体验，动态提示符和 _ 快捷方式是效率利器

Quack 协议的关键收获：

1. 多进程并发写入终于解决，且实现方式优雅——基于 HTTP/2 + Arrow，而不是另起炉灶
2. 查询下推机制让远程查询的性能开销控制在 4-15%（本地）和 12-80%（跨网络）
3. 零配置的服务器启动方式，两个 DuckDB 实例就能组成客户端-服务器架构
4. 与现有生态兼容，ATTACH 语法让本地/远程切换对应用透明

什么时候用 Quack，什么时候用进程内模式？

DuckDB 正在证明一件事：嵌入式和客户端-服务器不是非此即彼的选择。一个好的数据库应该根据使用场景灵活切换架构模式，而不是强制用户进入某一种范式。这大概就是 DuckDB 能在短短几年内从学术项目成长为数据基础设施标配的原因——它始终在解决真实问题，而不是贩卖架构信仰。

参考资料

• DuckDB 1.5.0 发布公告: https://duckdb.org/2026/03/09/announcing-duckdb-150
• Quack 远程协议公告: https://duckdb.org/2026/05/12/quack-remote-protocol
• DuckDB Quack 文档: https://duckdb.org/docs/current/quack/overview
• DuckDB 安装指南: https://duckdb.org/install/
• DuckDB v1.5.0 GitHub Release: https://github.com/duckdb/duckdb/releases/tag/v1.5.0
• DuckDB 设计手册: https://duckdb.org/design/manual/