duckdb 默认使用 wal（write-ahead logging）模式提升写性能，但未显式执行 checkpoint 时，wal 中的变更不会同步到主数据库文件，导致 flask 退出后数据丢失。本文详解如何通过手动触发 checkpoint 确保 duckdb 变更持久化。
duckdb 默认使用 wal（write-ahead logging）模式提升写性能，但未显式执行 checkpoint 时，wal 中的变更不会同步到主数据库文件，导致 flask 退出后数据丢失。本文详解如何通过手动触发 checkpoint 确保 duckdb 变更持久化。
在将 Flask 应用从 PostgreSQL 迁移到 DuckDB 的过程中，开发者常会遇到一个隐蔽却关键的问题：看似成功提交的数据库操作，在应用正常退出（如 Ctrl+C）后凭空消失。这并非事务失败或异常未捕获所致，而是 DuckDB 的 WAL 持久化机制与传统关系型数据库存在本质差异。
DuckDB 默认启用 WAL 模式以优化并发写入性能——所有变更首先写入内存中的 WAL 日志，而非立即刷盘到主 .db 文件。只有当 WAL 被显式“检查点”（CHECKPOINT）时，这些变更才会被合并并持久化到底层数据库文件。若应用未主动触发 CHECKPOINT 就终止（即使已调用 session.commit() 和 session.close()），WAL 中未同步的更改将永久丢失，重启后还会因外键引用缺失（如错误提示 Violates foreign key constraint because key "auditid: ..." does not exist）而引发一致性异常。
✅ 正确做法是：在应用优雅退出前，强制执行 CHECKPOINT SQL 命令。注意：SQLAlchemy 的 db.session.commit() 或 db.session.close() 均不等价于 DuckDB 的 CHECKPOINT；Python API 也未封装该功能，必须通过原生 SQL 执行：
from sqlalchemy import text
def graceful_shutdown(signal_received, frame):
print('SIGINT received. Initiating graceful shutdown...')
with app.app_context():
try:
# 1. 确保当前事务已提交
db.session.commit()
# 2. 强制同步 WAL 到主数据库文件（DuckDB 特有关键步骤）
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()
exit(0)
# 绑定信号处理器（适用于开发服务器）
import signal
signal.signal(signal.SIGINT, graceful_shutdown)? 重要注意事项：
- CHECKPOINT 是阻塞操作，会等待 WAL 完全写入磁盘，因此应仅在退出路径中调用，避免影响请求处理性能；
- 若使用多线程/多进程部署（如 Gunicorn），需确保 CHECKPOINT 在主进程退出时执行，并注意连接池管理；
- 开发阶段建议在 app.teardown_appcontext 中添加日志验证，确认每次请求结束时 WAL 状态（非必需，仅用于调试）；
- 不要依赖 PRAGMA wal_level = 'none' 关闭 WAL——这会牺牲并发安全性和性能，且不解决根本问题。
总结而言，DuckDB 的轻量级设计带来了卓越的嵌入式体验，但也要求开发者明确理解其持久化语义。COMMIT 保证事务原子性，CHECKPOINT 才真正保障持久性。将 CHECKPOINT 纳入 Flask 的优雅退出流程，是确保 DuckDB 在生产环境中可靠落地的必要实践。
