Documenting MySQL Databases

The power of TechWriter comes from its ability to leverage information from your database. In this topic we will show you how to document MySQL Databases using the MySQL Workbench design tool to include comments directly within the database itself. Comments can include simple text descriptions or richly formatted content depending on the comment model you wish to use.

Documenting Tables

To create table comments using MySQL Workbench, right click on the table and select 'Alter Table' from the pop-up menu. This will display the Properties dialog similar to the following on the right side pane:

Table Properties

Creating table comments is as simple as entering text in the comments box.

Documenting Table Columns

To document columns using MySQL Workbench, right click on the table and select 'Alter Table' from the pop-up menu. Next, select Columns in the menu towards the bottom of the page. This will display all of the columns within the table.

Column Properties

Once you select the column you wish to document, enter the comment in the comments box on the right hand side of the window.

Documenting Functions and Stored Procedures

To document functions and stored procedures in MySQL you must use the COMMENT characteristic within the routine definition. Right click on the appropriate routine and select 'Alter Routine' from the pop-up menu.

Procedure Properties

The COMMENT characteristic may also be used for documenting query parameters using comment tags. The comment tags to use will depend on the comment model that was specified for your database in the Database Settings dialog. This dialog is displayed when you add or edit a database for the project.

Documenting Other Database Objects

MySQL does not currently provide a method for documenting the following database objects:

Views
Indexes
Foreign Key Relationships
Check Constraints
Databases

However, you can still document these types of database objects using TechWriter annotations.

Formatting Options

In some instances, you may want to format your comments with multiple paragraphs, lists, links and other formatting options that are available when using TechWriter's Annotation editor. While MySQL does not provide a WYSIWYG editor, you can still apply formatting to the text using the syntax defined by the comment model. TechWriter supports several different comment models, including HTML, that can be used with MySQL to format your comments. See Supported Comment Models for more information.