mysqlSchemaToMarkdown

Translate a MySQL DB Schema to Markdown (GHC), with a lot of configurability along the way. The reason why I chose to make a generator then use the ones that are out in the wild is because I needed the following functionality:

• Make it so this script can be be automated, with a CI hook or git hook if need be
• Make it so that I can remove the columns that I don't think that are important to the documentation (example: Collation or Privileges)
• Add additional documentation that can be added before/after a table.

How to Run

To run, call the following:

node index.js --config <config>

Configuration File

A sample config file is located here. Field description is as follows

• dbConfig [Required]
  • host [Required] String - Where the host will connect. In most cases, localhost is the direction you want to go
  • port [Optional] Number - Defaults to 3306
  • user [Required] String - In the case of localhost, this is typically root
  • database [Required] String - The database we will be reading table data from
  • password [Optional] String - The password to the database
• outputMarkdown [Required] String - Where you want the markdown outputted. Example here.
• globalSettings [Optional]
  • documentName [Optional] String - What you want the title of the document to be
  • before [Optional] String - The file path of a markdown document that you want to be prepended to the document before the tables are listed. Example here.
  • after [Optional] String - The file path of a markdown document that you want to be appended to the document after the tables are listed. Example here
  • shownColumns [Optional] Array - If you want only to show some of the columns, list them out here. Order does not matter in this case. If the field is not defined, defaults to:

    • "shownColumns": [
        "Field",
        "Comment",
        "Type",
        "Collation",
        "Null",
        "Key",
        "Default",
        "Extra",
        "Privileges"
      ]

  • tables [Required] Object - The list of tables that you want outputted. Format is that the key is the table name, while the properties are for the markdown. Example:

    "tables": {
      "house": { 
        "before": "sample/sampleStubMarkdown/houseBefore.md"    
      },
      "pet": {
        "before": "sample/sampleStubMarkdown/petBefore.md",
        "after": "sample/sampleStubMarkdown/petAfter.md"
      }
    }

  • before [Optional] String - The file path of a markdown document that you want to be prepended to the section before this table's data is listed. Example here.
  • after [Optional] String - The file path of a markdown document that you want to be appended to the section after this table's data is listed. Example here

Additional Info

Usage: index [options]

  Translate your database schema into markdown files


  Options:

    -V, --version              output the version number
    -c, --config <configFile>  Sample config file
    -h, --help                 output usage information

Try Me

Example of what will be outputted here.

I wrote up a quick and dirty script to show off the functionality this piece of software. Disclaimer, you need the following:

• Linux/OSX (or something that can run a bash script)
• A locally running instance of MySQL and that can handle the following settings

• "host": "localhost",
  "port": 5984,
  "user": "root",
  "password": null

  • Note: if you have your local instance under different settings, feel free to update sample/sample_config.json to the settings that work for you
• Be ok if the script adds a database mysqlSchemaToMarkDown_SampleData to your local instance. After the demonstration, feel free to drop the tables and/or database.

If you are good with all of that, go to the root directory of this project and run:

./sample/generateSampleMarkdown.sh

This will generate a markdown file output.md to the project root directory for your review.

If you want to clean up the sample data, simply run

./sample/cleanUpSampleSQLData.sh