duckdb 默认使用 wal（write-ahead logging）模式提升写入性能，但 flask 进程异常终止或未显式触发检查点（checkpoint）时，wal 中的未同步变更会丢失，导致看似成功提交的数据在重启后消失。
duckdb 默认使用 wal（write-ahead logging）模式提升写入性能，但 flask 进程异常终止或未显式触发检查点（checkpoint）时，wal 中的未同步变更会丢失，导致看似成功提交的数据在重启后消失。
DuckDB 与传统数据库（如 PostgreSQL 或 SQLite 的默认配置）不同：它默认启用 WAL 模式以优化并发写入性能，但这也带来一个关键行为——事务提交（COMMIT）仅将变更写入 WAL 日志，并不立即同步到主数据库文件。只有当 WAL 被定期 checkpoint（检查点）时，这些变更才会被合并并持久化到 .db 文件中。而 Flask 开发服务器在 Ctrl+C 退出时，若未主动触发 CHECKPOINT，WAL 中尚未刷盘的记录（如最后几条 INSERT 或 UPDATE）就会丢失，造成“数据已提交却消失”的错觉。
该问题在你的代码中尤为典型：尽管多次调用 db.session.commit() 并最终 db.session.close()，但 SQLAlchemy 的 commit() 对 DuckDB 仅等价于 WAL 写入，无法替代物理同步。重启后出现的外键错误（Violates foreign key constraint because key "auditid: ..." does not exist）正是因引用表（如 AuditHistory）的主键记录仅存在于 WAL 中、未落盘，导致被引用方（如 AuditLog）在重放 WAL 时找不到父记录。
✅ 正确做法是：在应用优雅退出前，显式执行 CHECKPOINT 命令强制同步 WAL 到主数据库文件。DuckDB 官方文档明确指出：“The CHECKPOINT command forces all changes in the WAL to be written to the main database file.”
以下是推荐的 Flask 优雅退出处理方案（兼容 SQLAlchemy）：
import signal
import sys
from datetime import datetime
def graceful_shutdown(signal_received, frame):
print(f'\n[{datetime.now().isoformat()}] SIGINT received. Initiating graceful shutdown...')
with app.app_context():
# 1. 确保所有待提交变更已提交（虽非充分，但为最佳实践）
try:
db.session.commit()
except Exception as e:
print(f"Warning: Failed to commit pending session: {e}")
db.session.rollback()
# 2. 关键步骤：强制 DuckDB 执行 CHECKPOINT 同步 WAL
try:
db.engine.execute("CHECKPOINT;")
print("✓ DuckDB CHECKPOINT completed — all WAL changes persisted.")
except Exception as e:
print(f"✗ Failed to execute CHECKPOINT: {e}")
# 3. 清理会话资源
db.session.close()
print("Shutting down Flask server...")
sys.exit(0)
# 注册信号处理器（适用于开发服务器及 gunicorn/uwsgi 等）
signal.signal(signal.SIGINT, graceful_shutdown)
signal.signal(signal.SIGTERM, graceful_shutdown)
⚠️ 注意事项：
- CHECKPOINT 是 DuckDB 特有命令，不可用于其他数据库（如 PostgreSQL），因此建议通过 db.engine.dialect.name == 'duckdb' 做运行时判断，确保多数据库兼容性；
- 不要在每次 commit() 后都调用 CHECKPOINT——它会阻塞并显著降低写入吞吐量，仅应在进程退出、服务重启或关键一致性保障场景下使用；
- 若使用 duckdb.connect(..., read_only=False) 直连（非 SQLAlchemy），可直接调用 conn.execute("CHECKPOINT")；
- 开发阶段建议在 app.run() 前添加此处理器；生产部署时（如用 Gunicorn），需配合 --preload 或 on_worker_shutdown 钩子实现类似逻辑。
总结：DuckDB 的 WAL 模式是性能利器，但不是“零配置”持久化方案。理解其同步机制，并在生命周期终点主动 CHECKPOINT，是保障数据不丢的核心前提。
