文档化 MS SQL Server 数据库

引言

所有公司都会积累各种数据，这些数据最终不可避免地会存储在数据库中。如今，几乎任何你能想到的应用程序都将包含一个数据库。这就是为什么对数据库对象描述有相当高的需求。

实现此过程主要有两种方法——你可以使用对象的扩展属性或各种第三方工具。

在本文中，我们将回顾一些使用扩展属性和第三方工具对 SQL Server 数据库进行文档编制的示例。

如何使用文档工具记录 SQL Server 数据库

你可以使用 `sp_addextendedproperty` 系统存储过程添加扩展属性。其文档位于此处。

以下是此存储过程的一些用法示例

1. 为 `dbo.GetPlansObject` 函数的 `@ObjectID` 参数添加描述

   SELECT emp.[EmployeeID]
      ,emp.[LastName]
      ,emp.[FirstName]
      ,s.[SkillName]
      ,DATEDIFF(DAY, jh.[StartDate], _
       jh.[FinishDate]) / (DATEDIFF(YEAR, jh.[StartDate], _
       jh.[FinishDate]) + 1) AS [PeriodDay]
      ,CASE
   WHEN ((2017 >= year(jh.[StartDate])) AND
   (2018 > year(jh.[FinishDate]))) THEN 2017
   WHEN ((2018 >= year(jh.[StartDate])) AND
   (2019 > year(jh.[FinishDate]))) THEN 2018
   WHEN ((2019 >= year(jh.[StartDate])) AND
   (2020 > COALESCE(year(jh.[FinishDate]), year(GetDate())))) THEN 2019
   END AS [Year]
   FROM [Employee] AS emp
   INNER JOIN [JobHistory] AS jh
   ON emp.[EmployeeID] = jh.[EmployeeID]
   INNER JOIN [Project] AS p
   ON p.[ProjectID] = jh.[ProjectID]
   INNER JOIN [ProjectSkill] AS ps
   ON p.[ProjectID] = ps.[ProjectID]
   INNER JOIN [Skill] AS s
   ON s.[SkillID] = ps.[SkillID]
   WHERE (jh.[FinishDate] >= DATEADD(YEAR, -3, GetDate())
   OR (jh.[FinishDate] IS NULL));

   同样，你可以为存储过程参数添加描述。

2. 为 `dbo.GetPlansObject` 函数添加描述

   EXEC sys.sp_addextendedproperty @name=N'MS_Description',
   
   @value=N'Returns all plans for the specified object',
   @level0type=N'SCHEMA',
   @level0name=N'dbo',
   @level1type=N'FUNCTION',
   @level1name=N'GetPlansObject';

   你可以用类似的方式为存储过程和触发器添加描述。

3. 为 `inf.vColumnTableDescription` 视图添加描述

   EXEC sys.sp_addextendedproperty @name=N'MS_Description',
   
   @value=N'Description of table columns',
   @level0type=N'SCHEMA',
   @level0name=N'inf',
   @level1type=N'VIEW',
   @level1name=N'vColumnTableDescription';

   你也可以为表添加描述。

4. 为 `dbo.TABLE` 表的 `TEST_GUID` 列添加描述

   EXEC sys.sp_addextendedproperty @name=N'MS_Description',
   
   @value=N'Record ID (global)',
   @level0type=N'SCHEMA',
   @level0name=N'dbo',
   @level1type=N'TABLE',
   @level1name=N'TEST',
   @level2type=N'COLUMN',
   @level2name=N'TEST_GUID';

   也可以为表列添加描述。

5. 为 `rep` 方案添加描述

   EXEC sys.sp_addextendedproperty @name=N'MS_Description',
   
   @value=N'The rep schema objects contain information for reports' ,
   @level0type=N'SCHEMA',
   @level0name=N'rep';

6. 添加数据库描述

   EXEC sys.sp_addextendedproperty @name=N'MS_Description',
   
   @value=N'Administration Database
   Version for MS SQL Server 2016-2017 
   (MS SQL Server 2012-2014 is also fully or partially supported).
   Support for all versions up to MS SQL Server 2012 
   may not be at a sufficient level for use in a production environment';

7. 为数据库索引添加描述

   EXEC sys.sp_addextendedproperty @name=N'MS_Description',
   								@value=N'cluster index' ,
   								@level0type=N'SCHEMA',
   								@level0name=N'srv',
   								@level1type=N'TABLE',
   								@level1name=N'Recipient',
   								@level2type=N'INDEX',
   	 @level2name=N'indInsertUTCDate';

   同样，你可以为视图索引添加描述。

   要更改或删除描述，你只需要分别使用 `sp_updateextendedproperty` 和 `sp_dropextendedproperty` 存储过程。你可以在文档中阅读有关这些存储过程的更多信息

   • sp_updateextendedproperty
   • sp_dropextendedproperty

现在，我们将分析获取对象描述信息的方法

1. 要获取数据库对象描述信息，你可以使用以下查询

   select
   
   SCHEMA_NAME(obj.[schema_id]) as SchemaName
   ,QUOTENAME(object_schema_name(obj.[object_id]))+'.'+quotename(obj.[name]) as ObjectName
   ,obj.[type] as [Type]
   ,obj.[type_desc] as [TypeDesc]
   ,ep.[value] as ObjectDescription
   from sys.objects as obj
   left outer join sys.extended_properties as ep on obj.[object_id]=ep.[major_id]
   											 and ep.[minor_id]=0
   											 and ep.[name]='MS_Description'
   where obj.[is_ms_shipped]=0
   and obj.[parent_object_id]=0

   这里使用以下系统视图

   1. `sys.objects` — 数据库对象。你可以在此处了解更多信息。
   2. `sys.extended_properties` — 当前数据库中的扩展属性。更多详细信息请见此处。

   此查询生成以下列

   1. `SchemaName` — 对象方案
   2. `ObjectName` — 对象的名称
   3. `Type` — 对象类型
   4. `TypeDesc` — 对象类型描述
   5. `ObjectDescription` — 自定义对象描述
2. 要获取具有父对象的对象的描述，你可以使用以下查询

   select
   
   SCHEMA_NAME(obj.[schema_id]) as SchemaName
   ,QUOTENAME(object_schema_name(obj.[parent_object_id]))+_
   '.'+quotename(object_name(obj.[parent_object_id])) as ParentObjectName
   ,QUOTENAME(object_schema_name(obj.[object_id]))+'.'+quotename(obj.[name]) as ObjectName
   ,obj.[type] as [Type]
   ,obj.[type_desc] as [TypeDesc]
   ,ep.[value] as ObjectDescription
   from sys.all_objects as obj
   left outer join sys.extended_properties as ep on obj.[parent_object_id]=ep.[major_id]
   											 and ep.[minor_id]=obj.[object_id]
   											 and ep.[name]='MS_Description'
   where obj.[is_ms_shipped]=0
   and obj.[parent_object_id]<>0

   此处显示与前一个查询相似的列，但添加了一个新列。`ParentObjectName` 是对象的父级（例如，表是列的父级）。

   此查询还使用 `sys.all_objects` 系统视图，该视图显示所有数据库对象。你可以在此处阅读有关此视图的更多信息。

3. 你可以通过执行以下查询获取参数描述

   select
   
   SCHEMA_NAME(obj.[schema_id]) as SchemaName
   ,QUOTENAME(object_schema_name(obj.[object_id]))+_
   '.'+quotename(object_name(obj.[object_id])) as ParentObjectName
   ,p.[name] as ParameterName
   ,obj.[type] as [Type]
   ,obj.[type_desc] as [TypeDesc]
   ,ep.[value] as ParameterDescription
   from sys.parameters as p
   inner join sys.objects as obj on p.[object_id]=obj.[object_id]
   left outer join sys.extended_properties as ep on obj.[object_id]=ep.[major_id]
   											 and ep.[minor_id]=p.[parameter_id]
   											 and ep.[name]='MS_Description'
   where obj.[is_ms_shipped]=0

   此处显示的字段与前一个查询中的字段相似。但是，有一些更改和添加

   1. `Type` 和 `TypeDesc` — 与父对象（存储过程或函数）相关
   2. `ParameterName` — 参数的名称

   此查询还使用 `sys.parameters` 系统视图，该视图显示数据库对象参数。有关更详细的描述，请参阅视图文档。

4. 可以通过以下查询获取表列的描述

   select
   
   SCHEMA_NAME(t.schema_id) as SchemaName
   ,QUOTENAME(object_schema_name(t.[object_id]))+'.'+quotename(t.[name]) as TableName
   ,c.[name] as ColumnName
   ,ep.[value] as ColumnDescription
   from sys.tables as t
   inner join sys.columns as c on c.[object_id]=t.[object_id]
   left outer join sys.extended_properties as ep on t.[object_id]=ep.[major_id]
   											 and ep.[minor_id]=c.[column_id]
   											 and ep.[name]='MS_Description'
   where t.[is_ms_shipped]=0;

   此处显示以下列

   1. `SchemaName` - 表方案的名称
   2. `TableName` - 表的名称
   3. `ColumnName` - 表列的名称
   4. `ColumnDescription` - 表列的描述

   此查询还使用以下系统视图

   1. `sys.tables` - 表。更多详细信息请见此处
   2. `sys.columns` – 列。更多信息请见此处
5. 可以通过以下查询检索视图列的描述

   select
   
   SCHEMA_NAME(t.schema_id) as SchemaName
   ,QUOTENAME(object_schema_name(t.[object_id]))+'.'+quotename(t.[name]) as ViewName
   ,c.[name] as ColumnName
   ,ep.[value] as ColumnDescription
   from sys.views as t
   inner join sys.columns as c on c.[object_id]=t.[object_id]
   left outer join sys.extended_properties as ep on t.[object_id]=ep.[major_id]
   											 and ep.[minor_id]=c.[column_id]
   											 and ep.[name]='MS_Description'
   where t.[is_ms_shipped]=0;

   此处显示以下列

   1. `SchemaName` - 呈现方案的名称
   2. `ViewName` — 视图的名称
   3. `ColumnName` — 视图列的名称
   4. `ColumnDescription` - 视图列的描述

   此请求还使用 `sys.views` 系统视图，该视图显示所有数据库视图。你可以在此处找到更多信息。

6. 你可以使用以下查询获取数据库架构描述

   select
   
   SCHEMA_NAME(t.schema_id) as SchemaName
   ,ep.[value] as SchemaDescription
   from sys.schemas as t
   left outer join sys.extended_properties as ep on t.[schema_id]=ep.[major_id]
   											 and ep.[minor_id]=0
   											 and ep.[name]='MS_Description'

   有两列，`SchemaName` 和 `SchemaDescription`，分别显示架构的名称和描述。

   此查询还使用 `sys.schemas` 系统视图，该视图显示所有数据库架构。更多详细信息。

7. 你可以使用以下查询获取整个数据库中所有索引的扩展属性

   SELECT SCHEMA_NAME(obj.[schema_id]) as [SchemaName],
   	   obj.[name] as [ObjectName],
   	   ind.[name] as [IndexName],
   	   EP.[name]  as [ExtendedPropertyName],
   	   EP.[value] as [ExtendedPropertyValue]
   FROM sys.extended_properties AS EP
   inner join sys.objects as obj on EP.[major_id]=obj.[object_id]
   inner join sys.indexes as ind on EP.[minor_id]=ind.[index_id]
   WHERE EP.class = 7

   此处显示以下列

   1. `SchemaName` — 对象架构的名称
   2. `ObjectName` — 对象的名称
   3. `IndexName` — 索引的名称
   4. `ExtendedPropertyName` - 扩展属性的名称
   5. `ExtendedPropertyValue` - 扩展属性的值

   此查询还使用 `sys.indexes` 系统视图，该视图显示数据库中的所有索引。你可以在此处找到更多详细信息。

接下来，我们将探讨如何通过使用 Devart 的专用工具以另一种方式处理数据库文档。

使用 dbForge Documenter for SQL Server 记录数据库

在 dbForge Studio for SQL Server 中，你可以创建数据库文档项目。此功能也在 dbForge Documenter for SQL Server 中实现。

在此示例中，我们将使用专为 MS SQL Server DBMS 维护而设计的 SRV 数据库。它可免费用于任何目的，因此你可以在此处下载其源文件：https://github.com/jobgemws/Projects-MS-SQL-Server-DBA/tree/master/SRV。

要创建数据库文档项目，打开 Studio 后，在“工具”菜单中单击“新建文档...”

接下来，选择你需要为其创建数据库文档的所需服务器。

之后，将出现以下文档主页。它可以以多种方式排列，包括以下方式

你可以不生成文档中的主页就开始。为此，只需取消选中窗口左上角的复选框。

请记住，只有启用复选框的元素才会被生成。

接下来，你需要配置所有选定服务器范围内的生成，以及每个特定服务器的生成

例如，让我们通过将所有选项切换到“关闭”来禁用此页面上的所有设置

接下来，选择“用户数据库”页面。此外，为了示例起见，让我们关闭“用户数据库”选项

接下来，选择 SRV 数据库

在这里，我们将输入数据库的描述并单击“保存”。

用户保存的所有描述更改也将保存到相应对象的高级属性中。

之后，我们将关闭“属性”、“选项”和“数据库文件”

其余设置应保持启用状态

现在让我们打开 SRV 数据库本身并选择“表”页面

此页面列出了表及其描述。

当你编辑描述时，会出现两个按钮

1. 保存 - 保存更改
2. 取消 - 取消更改

让我们通过单击选择 `dbo.AuditQuery` 表

此页面列出了表的列及其描述。

此外，你可以在此页面上看到显示的表索引。

当你编辑描述时，会出现两个按钮

1. 保存 - 保存更改
2. 取消 - 取消更改

此外，此页面还包含表定义代码、表描述、表属性等。

如有必要，你可以关闭任何单独的选项。

“视图”文件夹中的视图页面以及其他数据库对象的页面看起来相同

通过这种方式，你可以记录以下数据库对象

1. 表及其列和索引
2. 视图及其列和索引
3. 存储过程及其参数
4. 函数及其参数，包括表格和标量
5. DDL 触发器
6. 用户
7. 角色
8. 架构及其他

设置完文档后，你可以通过单击“保存”并选择适当的路径和文件来保存项目

生成数据库文档

现在，让我们仔细看看文档项目的顶部面板

这里有三个按钮

1. 添加连接 ... - 允许你为文档添加新服务器
2. 刷新 - 开始更新选定文档服务器信息的进程
3. 生成 ... - 打开文档生成设置窗口。

单击“生成 ...”按钮。将打开文档生成窗口本身

在这里，你可以选择许多不同的选项，但以下选项是必要的

1. 格式（通常，默认选择 HTML）
2. 文档将生成到的文件夹

此外，通过单击左下角的“保存命令行...”，可以将选定的设置生成为 `.bat` 文件。

接下来，你需要单击“生成”按钮以启动文档本身的生成过程。当此操作成功完成时，将出现以下窗口

之后，转到选定的文档目录并打开 `mail.html` 文件以打开生成的 SRV 数据库网页文档。

同样，可以将多个数据库收集在一个文档中，即使它们位于不同的服务器上。

结论

我们研究了如何通过高级属性和借助 dbForge Documenter for SQL Server 创建和查看对象描述。描述构成了数据库文档的大部分。此外，从本文所示的示例中，我们可以看到 `dbForge` Documenter for SQL Server 工具允许你快速创建和编辑特定对象和整个文档的描述。这既可以针对单个数据库也可以针对多个数据库完成——无论它们位于一个服务器上还是几个不同的服务器上。

历史

• 2019 年 7 月 9 日：初始版本