数据库文档模板生成器

数据库文档模板

1. 数据库概览

• 数据库名称：<数据库名>
• 数据库类型和版本：PostgreSQL <版本号>（例如：14/15）
• 字符集和排序规则：
  • server_encoding：<UTF8 等>
  • LC_COLLATE（排序规则）：<示例：en_US.UTF-8>
  • LC_CTYPE（字符分类）：<示例：en_US.UTF-8>
• 创建时间和最后修改时间：<创建时间> / <最后修改时间>
• 实例/集群信息（可选）：
  • 逻辑集群/数据库实例标识：<cluster/db 标识>
  • 所有者（Owner）：<角色名>
  • 表空间（Tablespace）：<默认/自定义表空间>
• Schema 概览：
  • Schema 列表与用途：<schema1：用途说明>；<schema2：用途说明> …
• 扩展（Extensions）清单与用途（例如 PostGIS、pg_trgm、uuid-ossp 等）：<扩展名：用途说明>

2. 架构设计

• 设计理念和原则：
  • 数据建模原则（范式/反范式折中、主外键策略、业务键与代理键使用说明）
  • 命名规范（库、schema、表、列、索引、约束、函数/过程、序列的命名规则）
  • 可扩展性与兼容性考虑（分区策略、历史数据留存策略、审计字段）
• 主要功能模块划分：
  • 模块/域划分与对应的 Schema/表列表：<模块A：schema/表>；<模块B：schema/表> …
• 数据流向说明：
  • 上游来源（系统/接口/批处理）、入库方式（ETL/CDC/消息）
  • 下游消费者（报表/API/数据服务）
  • 关键数据流转节点与质量控制点（去重、校验、审计）
  • 参考图件（ER 图、数据流图）位置：<链接/文件名>

3. 表结构说明

为每张表重复以下小节结构。

3.1 .<表名>

• 表说明：<表的用途和业务含义>
• 基本信息：
  • 业务域/模块：<域/模块名>
  • 数据量级（行数级别、增长速率）：<例如：千万级，日增百万>
  • 生命周期与归档策略：<保留周期、归档落地位置>
  • 分区策略（如适用）：<范围/列表/哈希，分区键，分区命名规则>
  • 继承关系（如适用）：<父表/子表>
  • 表空间与存储参数（如适用）：<tablespace，fillfactor 等>
• 字段列表： | 字段名 | 数据类型 | 长度 | 是否为空 | 默认值 | 字段说明 | |--------|----------|------|----------|--------|----------| | <列名> | <如: bigint/varchar/timestamp> | <适用于可变长类型> | <YES/NO> | <表达式/常量> | <含义/取值约束> |
• 字段补充信息（如适用）：
  • 主键列：<列名列表>
  • 业务唯一键：<列名列表>
  • 外键列及引用对象：<列名> → <schema.表(列)>
  • 序列/自增策略：<GENERATED {ALWAYS|BY DEFAULT} AS IDENTITY 或 序列名>
  • 列级排序规则（如有）：<列名：collation>
• 触发器与规则（如适用）：
  • 触发器列表：<触发器名：时机(INSERT/UPDATE/DELETE/TRUNCATE)、时序(BEFORE/AFTER)、作用列、函数>
  • 规则（Rules）：<规则名：重写逻辑简述>
• 备注：<其他说明>

（按需继续添加 3.2、3.3 … 对应其他表）

4. 索引配置

说明：为每类索引列出清单，补充索引方法（btree/gin/gist/brin）、包含列（INCLUDE）、部分索引条件（WHERE）、存储参数（如 fillfactor）。

• 主键索引（PRIMARY KEY） | 索引名 | 表名 | 列 | 索引方法 | 说明 | |--------|------|----|----------|------| | <idx_pk> | <schema.表> | <列列表> | btree | <说明> |

• 唯一索引（UNIQUE） | 索引名 | 表名 | 列 | 索引方法 | 条件(可选) | 说明 | |--------|------|----|----------|------------|------| | <idx_uq> | <schema.表> | <列列表> | btree | <WHERE 条件> | <说明> |

• 普通索引（非唯一） | 索引名 | 表名 | 列 | 索引方法 | INCLUDE(可选) | 条件(可选) | 说明 | |--------|------|----|----------|----------------|------------|------| | | <schema.表> | <列/表达式> | <btree/gin/gist/brin> | <列列表> | <WHERE 条件> | <说明> |

• 复合索引（多列/表达式） | 索引名 | 表名 | 列顺序 | 索引方法 | 用途场景 | 说明 | |--------|------|--------|----------|----------|------| | <idx_cmp> | <schema.表> | <col1, col2, …> | <方法> | <典型查询> | <说明> |

5. 约束关系

• 主键约束（PRIMARY KEY） | 约束名 | 表名 | 列 | 是否可延迟 | |--------|------|----|------------| | <pk_name> | <schema.表> | <列列表> | <DEFERRABLE/NOT DEFERRABLE> |

• 外键约束（FOREIGN KEY） | 约束名 | 源表(列) | 目标表(列) | ON UPDATE | ON DELETE | 是否可延迟 | 说明 | |--------|----------|------------|-----------|-----------|------------|------| | <fk_name> | <schema.表(列)> | <schema.表(列)> | <NO ACTION/…> | <NO ACTION/…> | <DEFERRABLE/…> | <说明> |

• 唯一约束（UNIQUE） | 约束名 | 表名 | 列 | 是否可延迟 | 说明 | |--------|------|----|------------|------| | <uq_name> | <schema.表> | <列列表> | <DEFERRABLE/…> | <说明> |

• 检查约束（CHECK） | 约束名 | 表名 | 条件表达式 | 说明 | |--------|------|------------|------| | <ck_name> | <schema.表> | <表达式> | <说明> |

• 关系说明与ER参考

  • 关键关系文字说明：<一对多/多对多/继承等关系说明>
  • ER 图链接/文件：<链接/文件名>

6. 视图和存储过程

• 视图定义和用途 | 名称 | 类型 | Schema | 依赖对象 | 主要逻辑/过滤说明 | 备注 | |------|------|--------|----------|-------------------|------| | <view_name> | 视图/物化视图 | | <表/视图列表> | <汇总/筛选逻辑概要> | <刷新策略等> |

  • 物化视图（如适用）：刷新策略（按需/定时/依赖变更）、刷新并发性、索引说明

• 存储过程功能说明（或函数） | 名称 | 类型 | Schema | 输入参数 | 返回类型 | 语言 | 安全上下文 | 说明 | |------|------|--------|----------|----------|------|------------|------| | <proc_or_func> | PROCEDURE/FUNCTION | | <参数签名> | <RETURNS …> | <plpgsql/sql/…> | <SECURITY INVOKER/DEFINER> | <用途说明> |

• 触发器函数（如适用） | 函数名 | 触发时机 | 作用表 | 触发行 | 说明 | |--------|----------|--------|--------|------| | <trg_func> | BEFORE/AFTER INSERT/UPDATE/DELETE/TRUNCATE | <schema.表> | <列/行> | <说明> |

7. 权限管理

• 用户角色定义 | 角色名 | 角色类型 | 继承自 | 用途 | 备注 | |--------|----------|--------|------|------| | <role_name> | 登录角色/组角色 | <父角色> | <用途说明> | <备注> |

• 数据访问权限

  • 所有权（Owner）分配：<对象范围 → 所有者角色>
  • 授权矩阵（GRANT） | 对象类型 | 对象名 | 授权给 | 权限 | 说明 | |----------|--------|--------|------|------| | TABLE | <schema.表> | <角色> | SELECT/INSERT/UPDATE/DELETE | <说明> | | SCHEMA | | <角色> | USAGE/CREATE | <说明> | | FUNCTION | <schema.函数> | <角色> | EXECUTE | <说明> |
  • 行级安全（RLS）策略（如启用） | 表名 | 策略名 | 作用 | 使用者 | 策略表达式 | 备注 | |------|--------|------|--------|------------|------| | <schema.表> | | SELECT/INSERT/… | <角色/用户> | <表达式> | <说明> |

8. 维护计划

• 备份策略
  • 备份类型与范围：<逻辑/物理；全量/增量；对象范围>
  • 计划与保留：<频率、保留周期、RPO/RTO 目标>
  • 归档与加密：<归档位置、加密方式、访问控制>
  • 恢复演练与验证：<周期、验证要点、演练记录位置>
  • 依赖与前置条件：<窗口期、资源需求、协调方>
• 性能优化建议
  • 统计信息与Autovacuum：<更新频率、关键表策略、监控指标记录位置>
  • 索引维护：<重建/重组计划、热点索引清单、部分索引评估点>
  • 分区与冷热数据：<分区维护周期、历史分区处置策略>
  • 并发与锁：<高并发热点表/语句清单、超时阈值、退避策略说明>
  • 资源与配置记录：<连接池/并行度/内存/存储参数的记录位置与变更流程>
  • 查询基线与回归：<关键SQL基线集合、变更前后对比方法、存档位置>

数据库文档模板

1. 数据库概览

• 数据库名称：<MongoDB逻辑库名称>
• 数据库类型和版本：MongoDB <版本号>（示例：6.0）
• 字符集和排序规则：
  • 字符集：UTF-8（固定）
  • 默认排序规则（Collation）：<库/集合级默认，例如：zh@collation 或 simple>
• 创建时间和最后修改时间： /
• 部署类型：<Standalone | Replica Set | Sharded Cluster>
• 存储引擎：WiredTiger（默认，如有特殊配置请说明）
• 认证方式：<SCRAM-SHA-256 等>（不填真实凭据）
• 读写参数：<readConcern / writeConcern / readPreference 概要>
• 连接信息标识：<逻辑名称或连接别名，不含真实地址和账号>

注：以上为基础元数据记录项，仅填写必要信息，避免真实敏感配置或凭据。

2. 架构设计

• 设计理念和原则：
  • 文档模型约定：<内嵌（Embedded）/ 引用（Reference）适用场景说明>
  • 模式管理：<是否使用Schema Validation（JSON Schema）>
  • 命名规范：<集合命名、字段命名、时间字段、主引用字段等规范>
• 主要功能模块划分：
  • <模块A>：<业务简述>，涉及集合：<集合1, 集合2>
  • <模块B>：<业务简述>，涉及集合：<集合3, 集合4>
• 数据流向说明：
  • 写入来源：<API/ETL/消息队列等>
  • 消费与下游：<离线分析/报表/协同系统>
  • 跨集合关系：<内嵌/引用/聚合视图说明>
  • 分片策略（如适用）：<分片键、路由原则、预期访问模式>

3. 表结构说明

说明：MongoDB中“表”对应“集合（Collection）”。为每个集合复制本节，补充字段与说明。

3.1 集合名：<集合名称>

• 表说明：<集合用途与业务含义，包含关键文档结构要点>

• 文档示例（可选，脱敏）：<简化示例JSON，避免真实数据>

• 字段列表（说明：“数据类型”为BSON类型；“长度”为适用时填写，如字符串最大长度；“是否为空”指字段可缺省/可为null）： | 字段名 | 数据类型 | 长度 | 是否为空 | 默认值 | 字段说明 | |--------|----------|------|----------|--------|----------| | _id | ObjectId | - | 否 | 自动生成 | 主键索引字段 | | | <String/Int/Date/...> | <如适用> | <是/否> | <值/无> | <业务含义与取值规则> | | | <...> | <...> | <...> | <...> | <...> |

• 校验规则（如启用Schema Validation）：

  • 规则类型：<JSON Schema / validator 表达式>
  • 严格级别：<error / warn>
  • 规则摘要：<关键字段必填/类型/枚举范围>

• 集合属性（如适用）：

  • 是否为上限集合（Capped Collection）：<是/否>，大小/文档数：<数值>
  • 是否为时序集合（Time Series）：<是/否>，时间字段/分组字段：<字段名>
  • 默认排序规则（Collation）：<如与库默认不同请填写>

（将3.1复制为3.2、3.3…覆盖所有集合）

4. 索引配置

说明：统一记录索引定义与用途。可按集合归类。

• 主键索引（_id 自动创建）

  • 集合：<集合名>
  • 说明：_id 单字段索引，类型：<ObjectId/自定义>，是否覆盖业务主键：<是/否>

• 唯一索引 | 索引名 | 集合 | 键（含顺序） | 选项 | 用途说明 | |--------|------|--------------|------|----------| | <idx_unique_x> | <集合名> | { : 1 } | unique: true | <唯一约束目的> |

• 普通索引（单字段） | 索引名 | 集合 | 键（含顺序） | 选项（稀疏/部分等） | 用途说明 | |--------|------|--------------|---------------------|----------| | <idx_field_x> | <集合名> | { : 1 } | sparse: <true/false> | <查询加速场景> |

• 复合索引（多字段） | 索引名 | 集合 | 键（含顺序） | 选项 | 用途说明 | |--------|------|--------------|------|----------| | <idx_comp_xy> | <集合名> | { : 1, : -1 } | <partialFilterExpression等> | <常见查询条件/排序匹配> |

• 其他索引（如需要，放入对应类别或在用途中注明）

  • TTL（过期）、文本（text）、地理（2dsphere/2d）、哈希（hashed）、通配（wildcard）

索引维护说明（简要）：

• 建立/移除窗口：<业务低峰时段>
• 变更评估：<涉及查询、写入开销评估要点>

5. 约束关系

• 主键约束：

  • 字段：_id
  • 规则：全局唯一，类型与生成方式说明：<ObjectId/自定义策略>

• 外键约束（逻辑层面，MongoDB无内置外键）： | 来源集合.字段 | 目标集合.字段 | 关系类型 | 约束与一致性策略 | |---------------|---------------|----------|------------------| | <A.refUserId> | <users._id> | 1:N | <应用层校验/聚合校验/删除级联策略说明> |

• 唯一约束：

  • 载体：唯一索引
  • 说明：<哪些字段组合必须唯一及业务原因>

• 检查约束（Validation）：

  • 载体：Schema Validation / validator
  • 说明：<范围、枚举、格式、数值上下限等>

6. 视图和存储过程

• 视图定义和用途： | 视图名 | 基础集合 | 定义方式 | 主要用途 | |--------|----------|----------|----------| | <v_xxx> | <集合1,集合2> | 聚合管道（pipeline 摘要） | <报表/脱敏/简化查询> |

• 存储过程功能说明：

  • 说明：MongoDB无原生存储过程；如采用服务器端脚本或函数，请在此记录 | 名称 | 类型 | 位置 | 功能摘要 | 风险与限制 | |------|------|------|----------|------------| | <fn_xxx> | 服务器端脚本/函数 | <库/命名空间> | <功能> | <兼容性/安全提示> |

7. 权限管理

• 用户角色定义（基于RBAC：基于角色的访问控制） | 角色名 | 作用域（db/collection） | 权限（读/写/管理） | 继承角色 | 说明 | |--------|-------------------------|--------------------|----------|------| | | <dbX/> | read | <内置read> | 应用只读 | | | <dbX/> | readWrite | <内置readWrite> | 应用读写 | | | <admin/*> | 管理（仅必要项） | <dbAdmin等> | 运维维护 |

• 数据访问权限（避免填写真实账号） | 用户标识 | 绑定角色 | 认证方式 | 可访问资源 | 说明 | |----------|----------|----------|------------|------| | <svc_app> | | | <dbX 指定集合> | 服务账户 | | | | | <dbX 只读> | 分析账户 |

• 审计与最小权限：

  • 原则：最小权限、分离职责、审计关键操作
  • 审计项：<用户创建/角色变更/DDL/高危命令>

8. 维护计划

• 备份策略（不含真实路径与密钥）

  • 备份方式：<mongodump/快照/云备份>
  • 频率与保留：<全量/增量，保留周期>
  • 覆盖范围：<单库/分片集群/配置服务器/仲裁节点说明>
  • 恢复演练：<频率与验证项，例如一致性校验、视图与索引重建验证>

• 运维与健康检查

  • 例行项：<副本集状态/复制延迟/磁盘与WiredTiger缓存/连接数/慢查询>
  • 日志与告警：<慢查询阈值/磁盘水位/复制滞后/分片均衡器状态>
  • 数据校验：<validate 命令计划（仅低峰使用）>

• 性能优化建议（填写项，避免敏感数据）

  • 查询与索引：<高频查询、覆盖索引、排序与投影匹配>
  • 模式与文档：<内嵌vs引用取舍、热点字段、文档体积＞
  • 分片与路由（如适用）：<分片键匹配访问路径、均衡与分块监控>
  • 读写参数：<readConcern/writeConcern/readPreference 策略说明>

—— 使用说明（操作手册风格简要提示）：

• 填写占位符时仅记录逻辑信息，严禁使用真实地址、账号、密钥等敏感数据。
• 字段类型请使用BSON基本类型（如 String、Int32、Int64、Double、Decimal128、Date、ObjectId、Boolean、Array、Document 等）。
• 当“长度”不适用时可填“-”；当字段可能“缺省”与“为null”含义不同，请在“字段说明”中明确。
• 所有变更（索引、验证规则、权限）需在本模板同步记录“原因、影响范围、回滚方案”（如有）。