完美数据库产品文档的要素解析

快速上手部分，是让用户在最短的时间内，体验产品功能，完成一个使用闭环。这其中需包括从部署安装、开发设计到应用开发等多个阶段。在体验场景设计上，可选择最小功能为设计原则，能快速完成即可。如可能涉及到多个组件，也尽量减少来回交互，尽量通过在单一产品完成操作。

安装部署，通常是了解使用数据库的第一步。与前面的快速上手不同，这一环节尽量做到详实、完整，个中细节需要描述到位。

1).安装部署

由于数据库，通常存在多种规格或部署模式，在描述安装之前应先说明下大体情况、适用场景等，然后再针对不同安装情况分别加以说明。如果数据库包含多种组件（特别是分布式数据库），这种情况很常见，可以说明下各组件功能，并描述独立安装过程，由用户选择是否安装。对于同时提供多种安装方式，如命令行、图形化、容器化安装方式的，也应分别说明。在具体安装过程中，可遵循硬件、系统、环境、用户、初始化、安装、启动、组件、检测等环节分别加以说明。

2).数据库卸载

卸载，往往是很多产品文档会忽略的一个环节。如何干净、彻底地删除数据库，是需要遵循一定步骤的。通常应包括备份（数据+配置）、停止实例、删除空间、删除用户、检查残留等。

3).数据库升级

数据库升级是不可避免的操作，特别是在产品不完善的情况下。而对于用户来说，升级往往是比较痛苦的，如何做到升级平滑是DBA非常关注的问题。特别是在分布式环境下，组件多、节点多，升级能力更为重要。在整体升级中，可包括升级检查、影响评估、升级准备、数据备份、配置备份、实例升级、组件升级、状态检查、应用验证、升级回退等环节进行说明。

4).数据库扩缩容

数据库扩缩容分为两种情况，一种是所谓Scale UP，一种是Scale Out。前者更多是单机或集中式架构的场景扩容策略，这种更多是硬件的升级，这里不再详述。后者则更多是分布式数据库的通常扩容策略，很多数据库都采用存算分离架构，支持对计算、存储或其他组件的扩容。这其中的核心问题一是是否支持在线扩容，二是是否需要移动数据。之前接触不少用户，针对这块还是比较慎重的，需要在扩容过程中重点说明对线上运行的影响及过程跟踪。缩容的过程跟扩容类似，但需关注存储空间、算力等的减少或降低对系统的影响。

5).云与容器化

很多数据库，也提供了云端产品。云作为一种新型资源供给方式，颠覆了传统使用行为，大大加速简化了基础设施的构建及使用。作为云产品，安装部署、管理维护、监控告警、备份优化等都可以依托于云平台去完成。在安装部署阶段，用户可以不再关心具体的安装配置过程，而需要更多关心云的一些特殊性。如选择数据库产品、高可用架构、部署区域、网络拓扑、存储介质等以及是否购买使用其他产品。此处文档中只需描述这些特殊点，解决用户选择困难即可。针对支持容器化管理的情况，也可以一并说明如何使用管理数据库。具体操作可以参见后面参考引用部分。

数据库管理，主要是面向DBA人群，重点说明数据库管理的相关内容。这部分的内容会比较庞杂，需要分解说明。

1).集群管理

这其中包括实例及相关组件的启动、停止、状态查看。其他如增加、删除组件及节点，可以参考之前的“数据库扩缩容”；数据库升降级可参考之前的“数据库升降级”。

2).租户管理

如数据库支持租户，可在此处说明下，主要包括租户创建、删除、资源配置等。有些产品租户能力较强，实现了较为完整的租户能力，包括资源、参数、备份、监控、诊断等，这种情况建议在将租户管理放在数据库管理章节最后，独立说明。

3).参数管理

一个数据库会保护很多参数，特别是分布式数据库，不同组件也会有各自的参数。此部分需要说明参数的大致分类、操作方式（查看、修改、重置）、持久化情况等信息。至于参数的明细，可以在参考引用部分重点说明，包括但不限于参数名称、参数含义、值域范围、作用域（实例级、组件级、会话级等）、生效方式（在线、离线）等。这里强调下，有些产品是基于开源数据库实现或兼容其他数据库产品，需重点说明下“其他数据库”参数在当前产品是否有变化，并给出具体描述，不能直接引用其他产品说明。

4).日志管理

数据库系统中会包含很多日志，如常见的运行日志、事务日志、告警日志、监听日志、慢日志等。在此部分需要说明日志文件分类、文件名称、内容格式、存储位置、配置方法、归档删除策略等。如日志内容需要单独工具解读，也可以一并在此说明。日志是用户观察数据库的一个窗口，特别在很多产品性能视图、事件等机制尚不完善的情况下，因此应更加重视日志的使用。

5).存储管理

存储管理部分，涉及数据库运行时所需空间的管理，这里需根据不同文件对于空间、IO能力等诉求的差异，在前期就做好规划。后续日常管理则包括空间的扩容、移动、监控、清理等。对于很多数据库，还支持数据副本的概念，即数据存储多份，针对这种情况也需在此说明，包括工作原理等；如能人为干预副本的分配、移动、分裂、合并等也一并说明。

6).备份恢复

备份恢复部分，包括物理与逻辑备份恢复两种。一般建议将逻辑的备份恢复，归为导入导出，放在后面的数据集成章节，这里重点谈物理备份恢复。在开始部分可先说明备份介质选择、各组件备份（如数据、日志、配置等）。在具体备份操作上，包括备份创建、备份删除、过程跟踪、备份限流、备份集管理等。在具体恢复操作上，包括完整恢复、基于时点恢复、部分恢复（如基于对象）等。

7).故障诊断

故障诊断部分，建议先说明下整体故障诊断的框架，即支持哪些故障诊断的方法及手段，然后再具体说明。常见的诊断如健康检查（如存储坏块等）、日常巡检（如工作负载、参数配置等）、DUMP文件（各类异常生成）、错误码等。此部分需说明上述各类操作方法，具体DUMP文件格式解读、错误码信息可以引导参考引用部分。

8).监控指标

监控是DBA观察数据库的主要窗口，这其中包括数据字典视图、动态性能视图以及系统可吐出的各种Metric。此部分建议先说明下监控体系、收集机制、查询方法、指标分类及解读等。具体的视图、Metric 说明可引导参数引用部分。

9).应急处理

应急处理，是指系统过载或出现异常时需要紧急采取的措施。应急处理的首要目的并不是排查根因，而是快速止血，先让数据库尽快恢复正常服务能力。这里可根据经验收集经验，按异常类别进行分类说明。如硬件故障、业务过载、组件异常等，然后整理对应应急处理措施。

高可用意味着两点，一是服务高可用，二是数据高可靠。前者是为了保障业务系统的可用性，后者为为了保护企业核心资产-数据不丢失。针对整体高可用，可以在前面先概述下整体高可用技术，包括各种高可用架构，后面再分类说明。

1).实例高可用

在实例内部，已经内置有多种高可用能力。例如针对应用连接，Oracle 数据库支持的TAF；针对存储异常，很多数据库提供的多存储副本机制；针对误操作等，数据库提供如数据闪回功能；针对组件级故障，数据库提供的自动切换等。上述这些均为高可用在实例内能够提供的技术能力，可在此说明。

2).集群高可用

高可用集群是指在实例高可用基础外，通过架构支持多种集群方式以满足更高的可用性。当实例或单点集群出现故障时，可以切换到高可用集群的其他部分来承载。这其中可以有多种模式，常见的如主备、分布式和共享三种。主备模式，是指将主库/主集群数据复制一份到备库/备集群，后者可承担异常时切换满足业务访问或者承担只读访问需求。类似于Oracle DataGuard、MySQL Replication 方式。分布式模式，是指数据库本身各组件节点采用分布式架构，当异常时可通过冗余节点来处理。例如在存算分离架构下，计算节点多采用多点冗余无状态设计，存储节点采用多数据副本的方式解决单点，管理节点也多采用主备或基于共识协议方式解决。类似于 Google Spanner、OceanBase、TiDB、TDSQL等产品。共享模式则是指多个数据库实例作为计算节点共享一份存储（或加缓存）的方式，上层计算实例出现问题，可自动切换，下层的共享存储则通过硬件或分布式存储来解决。类似于 Oracle RAC 的方案即如此，国内如DM DSC、华为开源的参天引擎等。

3).部署实践：同城与异地

针对各种高可用方案，用户很关心如何选择及部署。这里可根据最为常用的几个高可用场景说下上述架构的部署方式。这其中包括针对同城（同机房）、同城（跨机房）、异地多种场景进行说明。比较高效的方式是画下部署图，这样比较清晰。此外，针对各种异常情况，不同场景及架构下的系统可用性（例如RTO、RPO指标）情况，这样用户可以一目了然。

4).高可用管理

针对上述高可用能力的相关操作，包括各种架构的搭建、切换、同步、监控、排障等。

一个安全的数据库系统应该能够建立安全保护机制，保护计算机硬件、软件和数据不因偶然和恶意的原因而遭到破坏、更改和泄漏。对数据库的安全性要求通常会被划分为保密性、完整性、可用性三个要素。保密性是指数据不能泄露给非授权用户，通常通过数据加密、访问控制等方式实现。完整性是指数据在存储和传输过程中，数据不被破坏及丢失，通常通过访问控制、完整性校验来实现。可用性是指数据可被授权用户，在异常时可恢复使用，通常通过备份、冗余、防火墙等方式来实现。

1).传输加密

传输加密是指在应用与数据库之间或数据库各组件之间使用 SSL/TLS 的方式实现通信加密。使用加密传输可以减少数据库中敏感信息的泄露风险，有效保护数据的安全。有些数据库产品是兼容开源数据库协议的，这时就需要判断是否已支持开源数据库的传输加密。

2).鉴权认证

鉴权认证，是指对登录数据库访问数据的用户进行身份验证，确认该用户是否能够与某一个数据库用户进行关联，并根据关联的数据库用户的权限，对该用户在数据库中的数据访问活动进行安全控制。有些数据库产品还支持操作系统认证，即使用操作系统用户直接登录，也需一并说明。

3).访问控制（用户、角色、权限）

访问控制，是指数据库通过用户、角色、权限设计，做到对资源访问控制管理，不同用户或角色担负不同的责任。在权限设计上，一般分为系统权限、对象权限，并提供一组视图来查看权限信息。有些数据库产品还扩展支持了三权分立、行级权限、网络安全等能力。

4).数据加密

数据加密，狭义上指对数据库存储数据的加密，广义则还包括对日志、备份、过程定义等的加密。通过数据加密可以有效的保护，避免因数据外泄造成的损失。现在大部分数据库都实现了透明加密（即TDE），加密与解密的过程对使用者来说是完全透明的。但这里需要关注几点，一是国密算法、密钥轮转等是否支持；二是数据加密后备份恢复或上下游生态是否受到影响。

5).安全审计

安全审计，是指对具备相应权限用户执行操作的记录，进而防止用户登录信息泄露，或者访问权限被滥用。审计功能可以加强企业对数据安全、合规等方面的要求，是跟踪用户行为最主要的工具。此部分应包括审计开启、查看的方法，及开启审计对性能影响的说明。

6).防火墙

防火墙功能，更多是在事前或事中针对访问做的一种防御措施，用于检测和防御外部入侵风险，较为常见的如IP白名单等。

前面几个章节多为面向运维侧，后面几个章节更多是面对架构、研发侧，讲述如何基于这个数据库开发应用系统。

1).连接驱动

2).SQL元素

针对SQL语句使用的最基本要素的说明，包括字面值、标识符、双引号、对象及对象命令、伪列（如有）、等的说明。

3).数据类型

支持数据类型，包括类型、存储长度、值域、精度等信息，最好以一种表格的形式呈现。为了方便用户理解，也可以同步列出主流数据库类型的对应关系，这样方便用户参照转换。

4).字符集

系统支持字符集的情况，并说明字符集使用规范。

5).运算符

数据库支持的运算符，包括但不限于算术、比较、逻辑、连接、位、其他运算符。

6).函数

数据支持的函数说明，包括但不限于日期、字符、数学、转换、聚焦、窗口、特殊函数等。如果系统还支持自定义函数，可在下面的语句开发部分详细说明。

7).语句开发

语句开发部分，大体可分为两个部分：SQL语言和过程语言。这其中包含的内容有比较多，其中SQL语言就包括DDL\DML\DQL\TCL等，又可以进一步分解如DQL就可以细分为查询、过滤、关联、嵌套、层次等。过程化语言则包括语法结构、条件控制、数据操作、数据游标等。这部分只描述基本内容即可，具体写法可参考后面的参考引用。此外，还可包含如注释等写法。

8).结构设计

数据库支持很多种对象，包括常见的表、分区、分片、索引、视图、触发器、存储过程、序列等。在结构设计部分，需说明各对象的设计规范，包括基础命名规范、设计规范、最佳实践等。相较于之前传统数据库，如今数据库在开发设计上需关注侧重点有了明显的变化。如在分布式数据库中，数据分片尤为重要；数仓数据库中列存表的设计有其特有要求；多模数据库，对架构设计又有着自己的特殊性等等。这部分内容较为繁多，可以结合案例进行说明，方便用户理解。

9).对象管理

上面结构设计中的诸多对象，都需要一定管理操作，如创建、删除、查看、修改、截断、重建、分析、编译、执行等等，均在此说明。

10).事务&隔离级

这其中包括事务原理性说明、事务控制、异常事务处理、事务与并发、事务与隔离级等内容的说明。针对事务的一些小点，如空闲事务、悬挂事务处理、显性与隐性事务、大事务处理等，也可在此说明。在分布式数据库下，分布式事务也需要单独说明下。

11).锁与死锁

需要说明系统锁的类别、工作机制、颗粒度、互斥行为、死锁与死锁检测机制等。

当系统出现性能瓶颈时，性能调优就显得尤为重要。调优本身可以在多个层次进行，这里可按照自下而上或者说先局部后总体的方式进行说明，通常都按照语句级、对象级、实例级、系统级、架构级、应用层调优顺序来展开。最后在说明下调优相关工具的使用。

1).SQL 调优

SQL 语句的调优，首先要理解SQL执行过程，包括解析器、优化器、执行器的行为，包括缓存、执行计划等内容。在具体描述上也可遵循上面的 SQL 执行顺序进行说明，逐步展开。其中优化器部分，还会涉及到统计信息、参数化等问题。这部分内容相对庞杂，需要细致说明。

2).对象调优

对象的调优，更多是在对象设计阶段的一些最佳实践，例如是否需要做分片、分区？是否需创建索引？如何和使用自增效率高等等。这部分可按照对象分列说明。在说明过程中，最好等配合一些查询、监控手段，可以印证调优是否有效。

3).实例调优

实例调优，通常是指各种参数的优化配置。最好的方式是提前建立性能基线，再根据收集到的信息做调整。很多数据诊断优化工具提供的报告，可以帮助完成实例调优。

4).系统调优

系统调优，是指在操作系统或硬件层面可以考虑的一些优化手段。

5).架构调优

当在单一实例或集群无法满足优化结果，就要考虑在架构层面进行。例如使用读写分离技术，满足更高的查询请求；如使用分布式数据库提供更强的计算能力等。这部分相对代价比较大了，通常描述些方法论就可以。

6).应用调优

最后部分，就是不要把优化仅仅限于数据库层面，在应用层也可以做很多东西。例如通过引入缓存降低数据库压力；通过应用层处理重数据库负载的计算任务降低压力等。

7).调优工具

配合上面的调优工作，需要一组调优工具来辅助完成。这其中比较重要的如统计信息，包括收集查看操作；执行计划，包括查看、管理执行计划；性能视图，包括各粒度性能指标的查看；性能诊断工具，如Oracle AWR等工具可以完成系统诊断等。

数据库不是一个孤立的环境，需要与上下游生态打通，这就对数据库提供的集成能力提出一定的要求。

1).数据迁移

数据迁移是指从其他数据库将数据一次性迁移到当前数据库；或将当前数据库迁移到其他库。这包括结构迁移和数据迁移，其中数据迁移又可分解为全量迁移、增量迁移、数据对比等过程。很多产品都支持了多种迁移工具，可采用列表方式详细说明。

2).数据同步

数据同步是指两个数据库之间保持持续数据复制状态，两个库之间可以保持准实时的状态。在同构数据库下往往可通过物理或逻辑日志消费的方式进行，异构库间相对难度较大。很多第三方产品提供了异构库间数据同步的能力。

3).导入导出

除了前面提到的备份恢复外，异构数据库间进行数据交换一个便捷的方式就通过导入导出方式。通过将数据导出为格式化文件或 SQL 语句的文件，再向目标端导入或执行，可相对容易地实现异构库数据交换。数据库应提供上述导出为文件或语句脚本的能力。

4).CDC

CDC，是Change Data Capture的缩写，翻译过来是数据变化捕捉。这是一种数据集成的能力，通过将数据库的变更处理为消息，供下游生态系统消费访问，可以较为容易地实现数据变化的传播。这也成为数据库开发生态的一种规范。

参考引用，是个“大字典”，文档中涉及到速查类的信息都可以放在这里，方便用户快速查找。

1).SQL 参考

包括SQL语句的写法、注意事项、典型示例等。由于SQL写法比较复杂，可以采用铁路图等方式简化理解，方便用户使用。具体使用上可按用途分类，按字母排索引表，便于查找。

2).PL 参考

过程化语言参考，包括前面讲的如循环、条件判断、分支、赋值、游标等操作，都在此说明。

3).API 参考

用户通常与数据库是通过 SQL 语句打交道，但有时也会提供API的方式。例如很多管控类的操作会提供API供用户调用，包括在K8S环境里集成的Operator也类似。特别是云产品，为了方便用户集成进自己的运维系统，也会提供Open API。这里重点说明下API用法、参数、给出示例即可。

4).系统变量与参数

这里重点说明变量或参数的含义、值域、作用域、是否热加载等信息，给出一份详细列表。需注意的是，分布式数据库有很多组件，需要区分上述变量或参数是哪个组件，是否可以统一设置等。

5).错误码

包括错误码组成、错误码含义、错误码速查表。如提供了兼容模式，还需说明是否兼容原始数据库的错误码，如果兼容一并列出。

6).告警/等待事件

系统定义的事件，包括告警事件、等待事件或其他事件。通过这些事件可以有效分析系统运行状态。

7).性能视图/数据字典

如前面所谈，需要完整的数据字典和性能视图说明，方便用户查询。

8).驱动说明

不同开发语言数据库驱动说明，包括驱动支持的主要功能、数据类型、函数等。

9).保留关键字

系统内置保留的关键字。

10).术语表

文档中引用名词的描述。

11).工具说明

数据库产品周边生态工具的说明，一般数据库产品都会提供如备份恢复、导入导出、SQL 命令行等工具。这里需说明各工具功能、使用方法、参数说明等。

12).生态兼容

生态兼容是指与数据库上下游生态的兼容情况，例如从数据建模、数据开发、数据分析、数据挖掘、可视化展现、数据管理、ETL、数据库管理、备份恢复、数据库优化、大数据平台等等，这些上面的主流工具是否支持这一产品。对于前天就具备兼容性产品来说，是会较容易的支持，如从0到1完成的新产品会有一个过程。

可部分可参考“快速入门”部分，可独立成章，包含的测试内容更加详实。