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
- Yarn
- pnpm
npm install -g dbdocs
yarn global add dbdocs
pnpm add -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.12.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 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.
OTP email screenshot
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!