Generate Database Documentation Using Monstarillo

In this tutorial we will generate database documentation using Monstarillo. We will create a create and run a template that will generate simple database documentation for a Postgres database will will spin up in Docker. The documentation will include basic information about the table’s columns and foreign key information.

To follow along with this tutorial you will need Docker or access to a Postgres database. The completed code for this can be found in github.

The first step is to install Monstarillo. Verify that Monstarillo is installed correctly by executing the command monstarillo from your command line.

monstarillo

How Monstarillo WOrks

Monstarillo is a template based code generator. Monstarillo runs Go Templates and uses a json file to tell Monstarillo how to run the templates and what to name the output of the templates. Next we will be creating this json file.

Create your first template

Create a folder and two text files in the folder named templates.json and tables.tmpl. Tables.tmpl is the template we will be running. I created the folder /home/patrick/tutorial.

Add the following code to the templates.json.

{
    "templates": [
      {
        "templateFile": "{{getTag .Tags \"TemplateRoot\"}}/table.tmpl",
        "generatedFileName": "{{ .CurrentTable.GetCamelCaseTableName}}.md",
        "generatedFolderName": "tables",
        "minimumGeneratedFileLength": 0,
        "outputPath": "{{getTag .Tags \"OutputPath\"}}/",
        "overwriteFile": true
      }
    ],
    "tags": [
      {
        "tagName": "TemplateRoot",
        "value": "/home/patrick/tutorial"
      },
      {
        "tagName": "OutputPath",
        "value": "/home/patrick/tutorial/output"
      }
    ]
  }

The templates array in the json file is the list of templates that we want Monstarillo to process. The tags array is a list of tags that we can use in our template definitions. In this case we are defining two tags. The first tag “TemplateRoot” should point to the folder containing the templates we want to run. table.tmpl is the template we will be running so the value of “TemplateRoot” should be the location of the folder you created in the previous step. The value of the second tag “OutputPath” should point to the folder you want the files that Monstarillo creates to be created in. In my case I want the generated files to be in a output folder that resides in the folder I created in the previous step.

Make sure you update the values of the two tags, and templateFile to match the folder and files you created.

Template Definition

• templateFile – The location of the template we want Monstarillo to run. In this case “{{getTag .Tags \”TemplateRoot\”}} returns the value we set for the tag TemplateRoot “/home/patrick/tutorial”
• generatedFileName – The name of the file that Monstarillo will generate. Monstarillo will execute each template once for each table in your database. {{ .CurrentTable.GetCamelCaseTableName}} will return the name of the table being processed in Camel Case.
• generatedFolderName – (optional) the name of the folder you would like to have the output generated in. In this case we are putting the files in a folder called tables. This folder will be created in the folder set in the template’s outputPath.
• minimumGeneratedFileLength – (optional) If set Monstarillo will only create a file if the length of the output is greater than this number.
• outputPath – The folder that Monstarillo will create the generated files in. {{getTag .Tags \”OutputPath\”}} returns the value of the tag OutputPath
• overwriteFile – If true Monstarillo will overwrite a generated file if it already exists.

Set up our database

Next we will set up our database. To begin clone the repo https://github.com/monstarillo/monstarillo-templates. Open a command prompt and cd to the chinhook-db folder in the reop you just cloned. Create the docker image for our database with the command:

docker build -t monstarillo-postgres .

Create the container by running the following command replacing <Your Password> with the password of your choice:

docker run --name monstarillo-postgres -e POSTGRES_PASSWORD=<Your Password> -p 5432:5432 -d monstarillo-postgres

Test our JSON file

Next we will run Monstarillo against our database to test the json file. Since we don’t have any code in our template Monstarillo should generate a tables folder with a markdown file for each table in our database.

Execute Monstarillo against the chinhook database we just stood up with the command

monstarillo postgres --t /home/patrick/tutorial/templates.json --u postgres --p <Your Password> --db "chinhook-db" --host "localhost" --schema "public"

In the command postgres tells Monstarillo to run against a postgres database. –t points to the json file that tells Monstarillo which templates to run and how to run them. –u is the database username postgres in our example. –p is the database password. –db is the name of the database we want Monstarillo to run against. –host is the hostname for the database we want Monstarillo to run against. –schema is the name of the schema we want Monstarillo to run against.

Your output should be similar to the image below. If you see errors it is likely because you have made an error with one or more of the file locations in the json file or in the call to monstarillo.

You should also have some files created my monstarillo. You should have a tables folder with a markdown file for each table in the database.

Print Table Names

Next we will modify the template to print out the table name in the markdown file we generate. Add the following to the table.tmpl

# {{.CurrentTable.GetPascalCaseTableName}}

.CurrentTable is the table object that Monstarillo uses to generate code. All of the properties of a Monstarillo table can be found in the documentation https://monstarillo.com/docs/api/table/. The GetPascalCaseTableName property will return the table’s name in pascal case. Running Monstarillo again will generate the files again with the table name.

Print COlumn Information

Next we will add some column information to the generated markdown files we create. Add the following to the table.tmpl

## Columns
|ColumnName|DB Data Type| Java DataType| C# DataType| Go Data Type|Is Primary Key|Is Nullable|Is Auto Increment|
| ---- | ----- | ----- | ----- | ----- | ----- | ----- | ----- |{{range .CurrentTable.Columns}}
|{{.GetCamelCaseColumnName}}|{{.DataType}}|{{.GetJavaDataType}}|{{.GetCSharpDataType}}|{{.GetGoDataType}}|{{.IsPrimaryKey}} |{{.IsNullable}} |{{.IsAutoIncrement}}|{{end}}

|ColumnName|DB Data Type| Java DataType| C# DataType| Go Data Type|Is Primary Key|Is Nullable|Is Auto Increment|
| ---- | ----- | ----- | ----- | ----- | ----- | ----- | ----- |

Adds a header

{{range .CurrentTable.Columns}}

{{end}}

This loops through all of the columns for the table.

|{{.GetCamelCaseColumnName}}|{{.DataType}}|{{.GetJavaDataType}}|{{.GetCSharpDataType}}|{{.GetGoDataType}}|{{.IsPrimaryKey}} |{{.IsNullable}} |{{.IsAutoIncrement}}|

The code inside of the loop prints out information about the column being processed in the loop. All of the properties of a Monstarillo column can be found in the documentation at https://monstarillo.com/docs/api/column/

Executing the monstarillo command again now will generate the markdown files again including the column information.

Add Foreign Key Information

Next we will add information about the tables foreign keys to the markdown files. Add the following to the table.tmpl file

## Foreign Keys{{if gt ( len .CurrentTable.ForeignKeys) 0 }}
| Constraint Name | Foreign Key Table Name | Foreign Key Column Name | Primary Key Table Name | Primary Key Column Name|
| ---- | ---- | ---- | ----  | --- |{{else}}
None {{end}} {{range .CurrentTable.ForeignKeys}}
|{{.ConstraintName}}|{{.FkTableName}}|{{.FkColumnName}}|{{.PkTableName}}|{{.PkColumnName}}|{{end}}


## Referenced Foreign Keys{{if gt ( len .CurrentTable.ReferencedForeignKeys) 0 }}
| Constraint Name | Foreign Key Table Name | Foreign Key Column Name | Primary Key Table Name | Primary Key Column Name|
| ---- | ---- | ---- | ----  | --- |{{else}}
None {{end}}{{range .CurrentTable.ReferencedForeignKeys}}
|{{.ConstraintName}}|{{.FkTableName}}|{{.FkColumnName}}|{{.PkTableName}}|{{.PkColumnName}}|{{end}}

{{if gt ( len .CurrentTable.ForeignKeys) 0 }}
{{end}}

This executes the code between the if and the end only if the table has more than 0 foreign keys. The .CurrentTable has a collection of ForeignKeys and ReferencedForeignKeys. The properties of the ForeignKeys and ReferencedForeignKeys can be found in the documentation at https://monstarillo.com/docs/api/foreign-key/

Run Monstarillo

The template is now complete. Execute Monstarillo again to generate the markdown files.

monstarillo postgres --t /home/patrick//tutorial/templates.json --u postgres --p <Your Password> --db "chinhook-db" --host "localhost" --schema "public"

All of the tables do not have foreign key information. The invoice table does.

You have generated database documentation using Monstarillo. Next you could try to generate database documentation for a MySql or Oracle database. Or you could Generate a Rest API Using Go for a MySql Database or Generate a REST API Using Java for a MYSQL database.