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:
- Check out our dbdocs Quick tour docs to get familiar with the platform components
- Check out our diagram tool dbdiagram.io which is a great complement to dbdocs.io š„
- Contact us at [email protected] if you need any help!