Setting up SQL database documentation

Applies to
ApexSQL Doc

Summary
This article explains how to set up the SQL database documentation process using ApexSQL Doc, a SQL Server documentation tool.

Description

Connecting to server

To set up the SQL database documentation process, the user needs to connect to SQL server first. After the application is started there are several ways to connect to SQL server instance:

Connecting to SQL Server instance to set up the SQL database documentation process

Clicking any of the option selected above, the Add SQL Server dialog will appear.

Quick tip icon

Quick tip:

Documenting SQL database from a remote server with slow connection can be improved by increasing the Connection timeout value and the Execution timeout value

The default values can be increased in the Connection options dialog as shown below:

Starting the Connection options dialog

Quick tip icon

Quick tip:

Documenting large SQL databases, or multiple databases from multiple SQL servers at once is recommended with the increased values for the Connection timeout, and Execution timeout

Selecting the databases

The list of connected SQL Servers will be shown in the SQL Servers section, and the list of the databases for the selected SQL servers will be shown in the Databases section to the right.

Selecting the SQL databases for documenting

Quick tip icon

Quick tip:

At least one database must be selected in order to proceed with setting up the documentation process

SQL Server documentation settings

The documentation about SQL server can be included, and its objects can be filtered in the same way as the database objects using the Object filter option. For the selected combination of server objects included those filtered, the Bitwise set combination will be generated, and it can be used to include the same combination using the Command Line Interface (CLI):

Specifying documenting options for SQL Server

Clicking the Database options tab from the Datasources and objects pane to the left, will open the additional documentation settings at the database level. Using these options, the user can include/exclude system objects or highlight SQL code in the documentation. The Table of contents section can be formatted by grouping the database objects or including the objects by owner/schema section. The extended properties can be included in the documentation checking the Include extended properties option:

Quick tip icon

Quick tip:

The options with clock displayed in the tooltip icon means that this is a performance intensive option, and if enabled, it can slow down the documenting process

For more detailed documentation, there are additional options that allow adding system objects, including graphical dependencies, syntax highlighting for SQL code in the generated documentation. Depending on the number of options enabled, and number of database objects included, it can slow down the SQL database documenting process:

Database options tab in ApexSQL Doc

Adding database objects

Clicking the Database objects option to the left opens a list of all database object types. The user needs just to select the checkbox by the objects that needs to be included in the SQL database documentation. As for the server objects, the database objects can be filtered in the same way, enabling the Filter option. For the selected database object, its attributes will be shown in the Object options section to the right, and the user can include/exclude any of the object option selecting the appropriate checkbox as shown below:

Adding database objects using ApexSQL Doc

After adding database and server objects, and setting up the documenting options, the user can choose the output format, and modify the output style. All of this can be set up from the Output options pane:

Selecting the format of a documentation file in ApexSQL Doc

Quick tip icon

Quick tip:

It is strongly recommended not to use doc/docx output format for large databases, or when documenting multiple databases at once

After all options are set, the database documenting process can be started by clicking the Generate button from the Home tab as shown below:

After the documenting process is complete, the result of the documentation looks like this: