dbdocs - dbdocs logo
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 setup 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.

1. Install dbdocs via terminal

Run the following command in the terminal:

npm install -g dbdocs

Or if you're using yarn

yarn global add dbdocs

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...


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

$ dbdocs
dbdocs ======

VERSION
  dbdocs/0.6.2 win32-x64 node-v12.16.1

USAGE
  $ dbdocs [COMMAND]
  
COMMANDS
  build     build docs
  help      display help for dbdocs
  login     login to dbdocs
  logout    logout
  ls        list projects
  password  set password for your project or remove password
  remove    remove project
  token     generate or revoke your authentication token
  validate  validate docs content

2. 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.

Suppose we create a file named database.dbml as below.

Project Ecommerce {
  database_type: 'PostgreSQL'
  Note: '''
    # Ecommerce Database
    **markdown content here**
  '''
}
Table users as U {
  id int [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']
}
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.

The Note in Project information supports markdown syntax, so you can write note in markdown for a better description. It should be like:

Project first_project {
  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 first_project. Otherwise, you will be asked for your project name in step 5.

3. Login to dbdocs

Before generating dbdocs view, you need to login by executing the following command (login via email)

$ dbdocs login
? Choose a login method: Email
? Your email: <your email address>
āœ” Request email authentication
? Please input OTP code sent to the email:

By entering correctly the OTP code in the email, you will be able to access the dbdocs.

4. Generate 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...
Done. Visit: https://dbdocs.io/khanh-tran-quoc/Ecommerce

5. 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.

Remove your project

You can simply remove your project by remove command

$ dbdocs remove <project name>
āœ” Removed successfully

Conclusion

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