📚 课程目录第2章环境搭建与快速上手

2. 环境搭建与快速上手

在正式进入金融数据分析之前，先把“工具链”搭好，是后续所有章节能否顺畅推进的前提。DuckDB 的定位是“进程内分析型数据库”，它不像 MySQL、PostgreSQL 那样需要独立启动服务进程，而是以库的形式嵌入到你的 Python、R 或命令行环境中。理解这一点，才能理解它为什么在本地金融数据研究里如此高效。

一、核心原理：为什么金融研究适合用 DuckDB

金融数据研究有几个典型特征：数据量中等偏大（单表几百万到上亿行很常见）、以列式读取为主（如收益率、成交量、因子值）、查询模式偏聚合与窗口计算、且经常需要与 pandas、R data.frame 互操作。DuckDB 的列式存储与向量化执行引擎，恰好匹配这些特征。

更关键的是它的“零服务”架构：数据库文件就是一个普通文件，可以随项目一起拷贝、版本管理、放进 Git LFS。对于需要复现研究结果的量化场景，这一点比传统数据库友好得多。

二、安装与三种接入方式

DuckDB 的安装非常轻量。CLI 版本可以直接下载单文件可执行程序；Python 与 R 则通过包管理器安装。下面给出三种方式的最小可用命令。

# 方式一：CLI（以 macOS/Linux 为例，下载后赋予执行权限）
curl -LO https://github.com/duckdb/duckdb/releases/latest/download/duckdb_cli-osx-universal.zip
unzip duckdb_cli-osx-universal.zip
chmod +x duckdb
./duckdb finance.db

# 方式二：Python
pip install duckdb pandas

# 方式三：R
install.packages(c("duckdb", "DBI", "dplyr"))

安装完成后，建议先做一次“连通性验证”，确认版本与基本查询可用：

-- CLI 中执行
SELECT version();
SELECT 42 AS answer;

# Python 中执行
import duckdb
print(duckdb.__version__)
duckdb.sql("SELECT 42 AS answer").show()

建议在项目根目录固定 DuckDB 版本，例如在 requirements.txt 中写 duckdb==1.1.3，避免不同机器上因版本差异导致 SQL 行为不一致。

三、内存数据库与持久化数据库的选择

DuckDB 支持两种数据库形态：内存数据库（:memory:）和持久化文件数据库（如 finance.db）。二者在 SQL 语法上完全一致，差别只在生命周期与共享方式。

对比维度	内存数据库 :memory:	持久化文件 finance.db
生命周期	会话结束即释放	文件长期保留
适用场景	临时探索、单元测试、一次性计算	因子库、行情库、可复现研究
并发访问	单进程内	支持多进程只读，写入需注意锁
迁移与备份	需导出为 Parquet/CSV	直接拷贝文件即可
典型命令	`duckdb` 或 `duckdb.connect()`	`duckdb finance.db` 或 `duckdb.connect("finance.db")`

持久化数据库在写入时会加文件锁。若同时用 CLI 和 Python 打开同一个 .db 文件并尝试写入，可能报 “database is locked”。研究阶段建议“一个写入进程 + 多个只读进程”的模式。

四、首个金融数据查询示例

下面用一个贴近真实场景的例子：假设我们有一份日频行情数据 prices.csv，字段为 trade_date, symbol, close, volume。我们先用 DuckDB 直接读取 CSV，再计算每只股票最近 5 日的成交量均值。

import duckdb

con = duckdb.connect("finance.db")

# 1. 直接从 CSV 建表（DuckDB 可自动推断类型）
con.execute("""
CREATE OR REPLACE TABLE prices AS
SELECT * FROM read_csv_auto('prices.csv');
""")

# 2. 查看表结构
con.sql("DESCRIBE prices").show()

# 3. 计算每只股票最近 5 日成交量均值
con.sql("""
SELECT
    symbol,
    trade_date,
    close,
    AVG(volume) OVER (
        PARTITION BY symbol
        ORDER BY trade_date
        ROWS BETWEEN 4 PRECEDING AND CURRENT ROW
    ) AS vol_ma5
FROM prices
ORDER BY symbol, trade_date;
""").show()

如果使用 CLI，同样的逻辑可以写成：

duckdb finance.db
D CREATE OR REPLACE TABLE prices AS SELECT * FROM read_csv_auto('prices.csv');
D SELECT symbol, trade_date, close,
         AVG(volume) OVER (PARTITION BY symbol ORDER BY trade_date
                           ROWS BETWEEN 4 PRECEDING AND CURRENT ROW) AS vol_ma5
  FROM prices ORDER BY symbol, trade_date LIMIT 20;

在 R 中，则可以通过 DBI 与 dplyr 组合完成：

library(DBI)
library(duckdb)
library(dplyr)

con <- dbConnect(duckdb(), dbdir = "finance.db")
prices <- tbl(con, "prices")

prices %>%
  group_by(symbol) %>%
  arrange(trade_date) %>%
  mutate(vol_ma5 = zoo::rollmean(volume, 5, fill = NA, align = "right")) %>%
  collect()

dbDisconnect(con, shutdown = TRUE)

五、常见误区与复盘

误区一：把 DuckDB 当 MySQL 用。DuckDB 是分析型数据库，不适合高频小事务写入。金融研究中应尽量“批量导入 + 批量查询”。
误区二：忽略文件锁。多个进程同时写同一个 .db 文件会失败。建议写入集中在单一进程，其他进程只读。
误区三：直接对超大 CSV 反复扫描。首次导入后应转为 DuckDB 原生表或 Parquet，后续查询速度会显著提升。
误区四：在 Python 中混用 pandas 与 DuckDB 的连接。推荐用 duckdb.sql(...).df() 或 .fetchdf() 显式转换，避免隐式类型问题。