[dbdocs](https://dbdocs.io/) is a free service for creating and hosting database documentation and [[entity-relationship diagrams]]. Using [[database markup language]] (DBML) you can specify the design of the database in text. `dbdocs` generates the diagrams and documentation and hosts it for you. This approach has the benefit of [[diagrams and documentation as code]]. ## Installation You will need to install [[Node.js]] to access [[npm]]. ```bash npm install -g dbdocs ``` Install the DBML Language Support extension for [[VS Code]]. ## Getting Started A single `.dbml` file is all you need to use `dbdocs`. Store this file with other documentation in your project directory. (`dbdocs` recommends storing the file in the project's root directory; see this guide to [[project organization]]). 1. Create a new `.dbml` file in [[VS Code]] and define the database using [[database markup language|DBML]]. Use this template to begin. ```dbml Project <project_name> { database_type: 'PostgreSQL' Note: ''' **markdown content here** ''' } Table <table_name> { id int [pk] <attr1> varchar note: "<add note here>" } ``` > [!tip] > You can [convert your .sql file into .dbml](https://www.dbml.org/cli/#convert-a-sql-file-to-dbml) with a few command lines. 2. Login to `dbdocs` (you will create a login in this step if you do not already have one). Select the Email login method and supply your email address (or select the GitHub option and login through GitHub). You will receive an email with an OTP code (or it will be provided by a dialog box after logging in to GitHub), input that when prompted. ```bash dbdocs login ``` 3. Build the `dbdocs` project. ```bash dbdocs build <path to your dbml file>/database.dbml ``` 4. Review your documentation at the provided url. Link to this url in your project's [[README]] or other documentation where appropriate.