数据库维护工具 (scripts/utils)¶

scripts/utils/ 目录提供了一套完整的 SQLite 数据库维护工具，包括备份、收缩、完整性检查、孤儿记录清理等功能。

目录结构¶

scripts/utils/
├── __init__.py      # 公共模块：路径工具函数
├── db_maintain.py   # 主维护工具（备份/收缩/统计/完整性检查/自增ID重置）
├── db_cleanup.py    # 孤儿记录清理
├── db_backup.py     # 快速备份快捷脚本
└── db_vacuum.py     # 快速收缩快捷脚本

公共模块 (`init.py`)¶

提供项目路径相关工具函数，供其他脚本引用：

函数	说明	返回值
`get_project_root()`	获取项目根目录	`Path`
`get_default_db_path()`	获取默认数据库路径	`Path` → `database/certflow.db`
`get_backup_dir()`	获取备份目录（不存在则创建）	`Path` → `database/backups/`
`get_logs_dir()`	获取日志目录（不存在则创建）	`Path` → `logs/`

1. 主维护工具 (`db_maintain.py`)¶

功能最全面的数据库维护入口，支持多种操作组合使用。

快速开始¶

# 查看帮助
uv run python scripts/utils/db_maintain.py --help

# 显示数据库基本信息
uv run python scripts/utils/db_maintain.py --info

# 显示所有表记录数统计
uv run python scripts/utils/db_maintain.py --stats

# 检查完整性（数据库结构 + 外键约束）
uv run python scripts/utils/db_maintain.py --check

# 备份数据库
uv run python scripts/utils/db_maintain.py --backup

# 收缩数据库（VACUUM + ANALYZE）
uv run python scripts/utils/db_maintain.py --vacuum --analyze

# 组合使用
uv run python scripts/utils/db_maintain.py --info --stats --check --vacuum

参数说明¶

参数	简写	说明
`--db PATH`	`-d`	指定数据库文件路径（默认：`database/certflow.db`）
`--info`	`-i`	显示数据库详细信息（文件大小、页面信息、SQLite版本等）
`--stats`	`-s`	显示所有表的记录数统计和自增值
`--check`	`-c`	检查数据库完整性（结构完整性 + 外键约束）
`--vacuum`	`-v`	执行 VACUUM 收缩数据库文件
`--analyze`	`-a`	执行 ANALYZE 更新查询优化统计信息
`--backup`	`-b`	备份数据库到 `database/backups/`
`--reset-auto`	—	重置自增ID
`--table NAME`	`-t`	指定表名（配合 `--reset-auto` 使用，默认 `sale_plans`）
`--execute`	`-e`	执行修改操作（`--reset-auto` 默认为试运行）

功能详解¶

`--info` 显示数据库信息¶

数据库信息: D:/project/database/certflow.db
============================================================

文件大小: 42.50 MB
修改时间: 2025-06-08 14:30:00
页面大小: 4096 bytes
页面数量: 10880
空闲页面: 256
浪费空间: 1.00 MB (建议执行 --vacuum)
SQLite 版本: 3.45.1

`--stats` 显示表统计¶

表统计信息: D:/project/database/certflow.db
============================================================

表名                                   记录数       自增值
-------------------------------------------------------------
certificates                           1,234       1,235
sale_plans                             5,678       5,800
users                                     12          13
-------------------------------------------------------------
总计                                   6,924

`--check` 完整性检查¶

执行 PRAGMA integrity_check 检查数据库结构是否损坏
执行 PRAGMA foreign_key_check 检查是否存在外键约束违反

`--vacuum` 数据库收缩¶

执行 VACUUM 回收空闲空间，减小数据库文件大小
配合 --analyze 会额外执行 ANALYZE 更新查询优化统计
显示优化前后的文件大小对比

`--backup` 数据库备份¶

使用 SQLite 原生 backup() API 进行在线热备份
备份文件命名：{数据库名}_backup_{时间戳}.db
备份目录：database/backups/

`--reset-auto` 重置自增ID¶

将指定表的自增ID重置为 MAX(id) + 1
默认为试运行模式，需添加 --execute 才实际修改
配合 --table 指定目标表

指定其他数据库¶

# 对备份数据库执行操作
uv run python scripts/utils/db_maintain.py --db database/backups/certflow02+网络.db --info

# 使用相对路径
uv run python scripts/utils/db_maintain.py -d data/archive.db --stats

2. 孤儿记录清理 (`db_cleanup.py`)¶

扫描数据库中所有外键关系，找出引用了不存在父记录的"孤儿"子记录并清理。

使用方法¶

# 试运行（只查看，不清理）
uv run python scripts/utils/db_cleanup.py

# 正式清理
uv run python scripts/utils/db_cleanup.py --execute

# 指定数据库文件
uv run python scripts/utils/db_cleanup.py --db data/other.db --execute

参数介绍¶

参数	简写	说明
`--db PATH`	`-d`	指定数据库文件路径
`--execute`	`-e`	执行清理（默认试运行，只显示不操作）

工作原理¶

通过 PRAGMA foreign_key_list 获取所有外键关系
对每个外键关系执行 LEFT JOIN ... WHERE IS NULL 查找孤儿记录
试运行模式仅列出孤儿记录数量和涉及的列
执行模式会 DELETE 所有孤儿记录并提交

输出示例¶

============================================================
清理孤儿记录: D:/project/database/certflow.db
============================================================

发现孤儿记录:
  certificates.sale_plan_id -> sale_plans.id: 3 条

正在清理...
  已清理 certificates: 3 条
[OK] 清理完成

3. 快速备份 (`db_backup.py`)¶

一键备份当前默认数据库的快捷脚本。

uv run python scripts/utils/db_backup.py

输出示例：

正在备份数据库: D:/project/database/certflow.db

数据库备份完成: D:/project/database/backups/certflow_backup_20250608_143000.db

实际上是调用 db_maintain.py 中的 backup_database() 函数。

4. 快速收缩 (`db_vacuum.py`)¶

一键收缩当前默认数据库的快捷脚本（执行 VACUUM + ANALYZE）。

uv run python scripts/utils/db_vacuum.py

输出示例：

正在收缩数据库: D:/project/database/certflow.db

数据库收缩完成!

实际上是调用 db_maintain.py 中的 vacuum_database() 函数，默认附带 ANALYZE。

典型使用场景¶

场景一：日常维护巡检¶

# 一次性查看所有状态
uv run python scripts/utils/db_maintain.py --info --stats --check

场景二：定期备份 + 优化¶

# 先备份，再收缩
uv run python scripts/utils/db_maintain.py --backup --vacuum --analyze

场景三：数据清理后重置自增ID¶

# 试运行确认
uv run python scripts/utils/db_maintain.py --reset-auto --table sale_plans

# 正式执行
uv run python scripts/utils/db_maintain.py --reset-auto --table sale_plans --execute

场景四：数据导入后清理孤儿记录¶

# 试运行
uv run python scripts/utils/db_cleanup.py

# 确认无误后正式清理
uv run python scripts/utils/db_cleanup.py --execute

安全说明¶

备份操作 (--backup, db_backup.py)：使用 SQLite 原生 backup() API，在线热备份，不影响正常读写
只读操作 (--info, --stats, --check)：不对数据库做任何修改
修改操作 (--vacuum, --reset-auto, --execute)：建议先在备份数据库上测试
孤儿清理 (db_cleanup.py)：默认试运行，需显式添加 --execute 才会执行删除

建议：在执行任何修改操作前，先运行 --backup 创建备份。