Skip to main content

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

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

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

$ dbdocs
VERSION
  dbdocs/0.14.0 darwin-arm64 node-v20.13.1

USAGE
  $ dbdocs [COMMAND]

COMMANDS
  build     build docs
  db2dbml   Generate DBML directly from a database
  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
  rename    change your username
  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.

database.dbml
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 generate .dbml from your database or 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 4.

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.

OTP email screenshot

Login to dbdocs via OTP

4. Generate dbdocs project​

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

$ dbdocs build <path to your dbml file>/database.dbml --project Ecommerce
Pushing new database schema to project Ecommerce...
✔ Done. Visit: https://dbdocs.io/khanh-tran-quoc/Ecommerce

Notes:

  • You can use the --project <username>/<project_name> flag to publish to other users' projects where you already have edit authority.

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: