DuckDB 默认使用 WAL（Write-Ahead Logging）模式提升写性能，但 Flask 进程意外终止时，WAL 中未同步到主数据库文件的变更会丢失；必须显式执行 CHECKPOINT 才能强制将 WAL 日志刷入磁盘，确保数据持久化。
duckdb 默认使用 wal（write-ahead logging）模式提升写性能，但 flask 进程意外终止时，wal 中未同步到主数据库文件的变更会丢失；必须显式执行 `checkpoint` 才能强制将 wal 日志刷入磁盘，确保数据持久化。
在将 Flask 应用从 PostgreSQL 迁移到 DuckDB 的过程中，开发者常遇到一个隐蔽却关键的问题：看似成功提交的数据库变更，在应用重启后凭空消失。这并非事务失败或代码逻辑错误，而是 DuckDB 特有的持久化机制所致。
DuckDB 为兼顾写入性能，默认启用 WAL 模式——所有修改首先写入内存中的 WAL 日志，再异步刷盘至主数据库文件（.db）。这意味着：
- .commit() 仅保证变更已写入 WAL，不保证已落盘；
- .close() 或进程退出（如 Ctrl+C）若未触发 WAL 同步，未刷盘的 WAL 条目将被丢弃；
- 重启后，DuckDB 尝试回放 WAL 时因引用缺失（如外键指向的 auditid 在主库中不存在），抛出 Violates foreign key constraint 错误，正是这一现象的典型表现。
✅ 正确解决方案是：在应用优雅退出前，显式执行 CHECKPOINT 命令。该命令强制 DuckDB 将 WAL 中所有待同步变更合并并写入主数据库文件，完成真正的持久化。
由于 SQLAlchemy 官方 API 未封装 CHECKPOINT，需通过原生 SQL 执行：
from sqlalchemy import text
def graceful_shutdown():
try:
# 确保所有待提交事务完成
db.session.commit()
# 强制同步 WAL 到磁盘
db.engine.execute(text("CHECKPOINT;"))
print("✅ DuckDB CHECKPOINT completed: all changes persisted.")
except Exception as e:
print(f"⚠️ CHECKPOINT failed: {e}")
finally:
db.session.close()
并在 Flask 启动时注册信号处理器（推荐使用 signal 模块捕获 SIGINT）：
import signal
import sys
def signal_handler(sig, frame):
print("\n? Received SIGINT. Initiating graceful shutdown...")
with app.app_context():
graceful_shutdown()
sys.exit(0)
signal.signal(signal.SIGINT, signal_handler)
⚠️ 注意事项：
- 不要依赖 db.session.close() 或 db.engine.dispose() 触发自动 checkpoint —— DuckDB 不提供此行为；
- 避免在每次 .commit() 后都调用 CHECKPOINT —— 频繁 checkpoint 会显著降低写入性能，仅应在进程退出前调用一次；
- 若使用内存数据库（:memory:），CHECKPOINT 无效且无持久化意义，请确保连接字符串指向磁盘文件（如 duckdb:///app.db）；
- 生产环境建议结合 atexit 注册兜底清理，并在 app.teardown_appcontext 中补充日志审计。
总结：DuckDB 的 WAL 是性能利器，但也是“隐形陷阱”。理解其持久化语义，并在生命周期终点主动 CHECKPOINT，是保障数据不丢失的关键一步——这不是 bug，而是设计使然。
