数据库管理 (db)

Headless 命令 — 不依赖桌面 GUI，直接使用核心包运行。适用于服务器、CI/CD、容器化等无桌面环境。

概述

db 命令用于管理 ChainlessChain 的本地 SQLite 数据库，提供初始化、信息查看、备份和恢复等功能。数据库支持 SQLCipher AES-256 全库加密，零配置即可使用，适合在服务器和 CI/CD 环境中自动化管理数据存储。

核心特性

• 🗄️ SQLite 存储: 轻量级嵌入式数据库，零配置
• 🔐 可选加密: 支持 SQLCipher AES-256 全库加密
• 💾 备份恢复: 一键备份和恢复完整数据库
• 📊 信息查看: 查看数据库驱动、表数、文件大小等元信息

系统架构

db 命令 → db.js (Commander) → @chainlesschain/core-db
                                      │
                     ┌────────────────┼────────────────┐
                     ▼                ▼                ▼
                  db init          db info          db backup/restore
                     │                │                │
                     ▼                ▼                ▼
              创建表和索引       查询元信息        文件复制
                     │
                     ▼
              SQLite 数据库 (~/.chainlesschain/data/)

命令参考

chainlesschain db init                  # 初始化数据库
chainlesschain db init --path ./my.db   # 指定数据库路径
chainlesschain db info                  # 查看数据库信息（驱动、表数、大小）
chainlesschain db info --json           # JSON格式输出
chainlesschain db backup [output]       # 创建备份
chainlesschain db restore <backup>      # 从备份恢复

子命令说明

init

初始化 SQLite 数据库，自动创建所有表和索引。

chainlesschain db init
chainlesschain db init --path ./custom.db

info

显示数据库基本信息，包括驱动类型、表数量、文件大小等。

chainlesschain db info
chainlesschain db info --json

backup / restore

创建数据库备份或从备份恢复。

chainlesschain db backup                    # 备份到默认位置
chainlesschain db backup ./my-backup.db     # 备份到指定路径
chainlesschain db restore ./my-backup.db    # 从备份恢复

配置参考

chainlesschain db init [--path <db-file>]
chainlesschain db info [--json]
chainlesschain db backup [output]
chainlesschain db restore <backup>

性能指标

操作	目标	实际	状态
db init（创建表 + 索引）	< 500ms	~ 200ms	✅
db info（元数据查询）	< 100ms	~ 30ms	✅
db backup（本地文件复制）	< 2s / 100MB	~ 1.2s	✅
db restore（覆盖恢复）	< 2s / 100MB	~ 1.5s	✅
JSON 输出序列化	< 50ms	~ 10ms	✅

测试覆盖率

✅ db.test.js  - 覆盖 CLI 主要路径
  ├── 参数解析
  ├── 正常路径
  ├── 错误处理
  └── JSON 输出

关键文件

• packages/cli/src/commands/db.js — 命令实现
• @chainlesschain/core-db — 数据库核心包（48 个测试）

安全考虑

• 数据库文件支持 SQLCipher AES-256 加密
• 备份文件包含完整数据，应妥善保管
• restore 操作会覆盖当前数据库，建议先备份

使用示例

场景 1：首次初始化数据库

chainlesschain db init
chainlesschain db info

初始化 SQLite 数据库并创建所有表和索引，随后查看数据库驱动、表数量和文件大小等信息。

场景 2：备份与恢复

chainlesschain db backup ./backup-20260312.db
chainlesschain db restore ./backup-20260312.db

在进行重大操作前创建数据库备份，出问题时可以从备份恢复。

场景 3：CI/CD 中自动初始化

chainlesschain db init --path ./test.db
chainlesschain db info --json

在测试流水线中使用指定路径初始化数据库，JSON 输出便于脚本解析验证。

故障排查

问题	解决方案
init 失败报权限错误	检查数据目录写入权限
info 显示 0 tables	数据库未初始化，运行 db init
restore 后数据不一致	确认备份文件未损坏，重新备份恢复

相关文档

• CLI 命令行工具 — 完整命令参考
• 文件加密 — 数据库加密管理
• 配置说明 — 数据库路径配置