built by

dbdocs.io Quickstart Guide

Introduction

dbdocs.io is a free, simple tool to create web-based documentation for your database. This guide will help you set up and start using dbdocs in less than 5 minutes.

Installation

Prerequisite

Make sure NodeJS and NPM have been installed on your computer before the installation.

Installation steps

1. Install dbdocs via terminal

Run the following command in the terminal:

$ npm install -g dbdocs
dbdocs install...

Note that in some cases, you need to add sudo to your command so npm can install dbdocs globally.

$ sudo npm install -g dbdocs
dbdocs install...
2. Verify that dbdocs has been successfully installed

Execute dbdocs command to check that it has already been installed and preview some commands.

$ dbdocs
dbdocs ======

VERSION
dbdocs/0.1.0 linux-x64 node-v13.12.0

USAGE
$ dbdocs [COMMAND]

COMMANDS
build    builds docs
help     display help for dbdocs
login    login to dbdocs
logout   logout
remove   remove docs
3. Define your database with DBML

To work with dbdocs, define your database schema using DBML - a simple and open-source DSL language. We recommend you use Visual Studio Code as you can install DBML Language Support package that comes with it, but any other editors will work just as fine.

Project Ecommerce {
database_type: 'PostgreSQL'
note: '''
# Ecommerce Database
**markdown content here**
'''
}

Table users as U {
id varchar [pk, increment]
full_name varchar
created_at timestamp
country_code int

note: "table 'users' contains user information"
}

Table merchants {
id int [pk]
merchant_name varchar
country_code int [note: "country of merchant"]
admin_id int [ref: > U.id]
created_at datetime [default: `now()`, note: "created time"]

note: "table 'merchants' contains merchant information"
}

Table countries {
code int [pk]
name varchar
continent_name varchar
}

Table order_items {
order_id int [ref: > orders.id]
product_id int
quantity int [default: 1]

note: 'items in an order'
}

Table orders {
id int [pk]
user_id int [not null, unique]
status varchar
created_at varchar [note: 'When order created']

note: 'items in an order'
}

Enum products_status {
out_of_stock
in_stock
running_low [note: 'less than 20']
}

Table products {
id int [pk]
name varchar
merchant_id int [not null]
price int
status products_status
created_at datetime [default: `now()`]

Indexes {
(merchant_id, status) [name: 'product_status']
id [unique]
}
}

Ref: U.country_code > countries.code
Ref: merchants.country_code > countries.code
Ref: order_items.product_id > products.id
Ref: products.merchant_id > merchants.id
Quick tip: you can convert your .sql file into .dbml with a few command lines.

Note:

  • The Note in Project information supports markdown syntax, so you can write note in markdown for a better description. It should be like:
    Project Ecommerce {
    database_type: 'PostgreSQL'
    note: '''
    # Ecommerce Database
    **markdown content here**
    '''
    }
  • Your document will have the same name as your project name. In this example, your document name will be Ecommerce. If you have not included a name for your project, you will be asked for it in step 5.
4. Login to dbdocs via Github

Before generating dbdocs view, you need to login by executing the following command

$ dbdocs login
? Please input your authentication token:

A login page will appear in your browser. It requires you to login with your GitHub account, click Continue with GitHub, then copy and paste your token to the terminal where it asks "Please input your authentication token".

5. Generate a dbdocs view

Open the folder which contains your dbml file in terminal, then generate dbdocs view by the following command.

$ dbdocs build <path to your dbml file>/database.dbml
Pushing new database schema to project your_project...
Password is not set for 'Ecommerce'

You will receive a warning that password is not set for your project, read the privacy instruction below to know how to protect your project.

6. Check your database documentation!

The last step provides you with a link to visit your database documentation. In our example, visit: https://dbdocs.io/khanh-tran-quoc/Ecommerce to take a look.

7. Privacy

Your dbdocs project is set to be public by default. However, you can follow the following command to protect it with a password.

$ dbdocs password --set <password> --project <project name>
Password is set for <project name>

Or

$ dbdocs password --project <project name>
? Enter password: [hidden]
? Re-enter password: [hidden]
Password is set for <project name>

Or you can build your project with password by using build command with --password

$ dbdocs build <path to your dbml file>/database.dbml --password <password>
Pushing new database schema to project your_project...
Password is set for 'Ecommerce'

Now your project is protected, only the one who have your password can access your project.

Remove password from your project to make it public

$ dbdocs password --remove --project <project name>
Password is removed from 'Ecommerce'
8. Integrate with CI

You can use your unique access token to update projects with continuous integration (CI) systems:
First, generate your access token on local after logged in.

$ dbdocs token -g
Verify your identity
Your access token is: eyJhbGciOi...
Warning: Please save this token. You cannot see it again.

Then add DBDOCS_TOKEN as a new environment variable in your CI machine.

DBDOCS_TOKEN=eyJhbGciOi...

It's done! Now you can run dbdocs build command on your CI without login actions.

$ dbdocs build <path to your dbml file>/Ecommerce.dbml

You can try it out with our GitHub's Actions quick setup

name: CI

on:
push:
branches: [ main ]
pull_request:
branches: [ main ]

jobs:
build:
runs-on: ubuntu-latest

steps:
- uses: actions/checkout@v2

- name: Install dbdocs
run: sudo npm install -g dbdocs

- name: Check dbdocs
run: dbdocs

- name: Update dbdocs project
env:
DBDOCS_TOKEN: eyJhbGciOi...
run: dbdocs build ./ecommerce.dbml

Remove your existing token with this command

$ dbdocs token -r
Verify your identity
Your access token has been revoked
9. Remove your project

You can simply remove your project by remove command

$ dbdocs remove <project name>
Removed successfully

By now, you've successfully set up dbdocs.io . A few things we'd suggest you do as the next steps: