tblsrun
Generate database documentation from migration files. Uses tbls internally to generate the docs. Useful for reviewing database schema change in your team.
How it works?
It works by spawning a database, then it will run the migrations files, and run the tbls
to generate the db doc.
Currently it only support postgres
for the DB & golang-migrate for migration files format
Example Database
Here is the example database documentation link
Snippets
Installation
go install github.com/fahmifan/tblsrun/cmd/tblsrun@latest
How To Use
- Set env variables, you can use
.env.example
as a reference. - Create tbls config (see
example.tbls.yml
) - Then run
tbslrun
, e.g.:tblsrun postgres docker
- Currently it only support
postgres
with 2 modesembedded
ordocker
embedded
will run postgres binary as child processdocker
will spawn a postgres docker container, you need docker installed to use this
- When running, it will install the latest
tbls
automatically if not exists in the$PATH
- Currently it only support
Environtment Variables
TBLS_DATABASE_NAME
- your database name, it will be use in the generated doc
TBLS_DATABASE_SCHEMA
- your database schema, it will be use in the generated doc
TBLS_DATABASE_PORT
- override the default database port (e.g. postgres: 5432)
TBLS_MIGRATION_DIR
- the directory where your migration files are located
- currently only support
golang-migrate
format
TBLS_CONFIG_FILE
- the path to your
tbls
config file
- the path to your
Multiple migrations folder & schemas
One use case for this is when you have multiple schemas in your database with separate migrations folder, and you want to generate the doc for each schema.
To enable this, you need to set the TBLS_DATABASE_SCHEMA
to schema_1,schema_2,schema_n
, and the TBLS_MIGRATION_DIR
to dir_1,dir_2,dir_n
.
If we want to generate it into different folder, we need to have multiple .tbls.yml
& .env
files, example to configure this:
# schema_1.tbls.yml
docPath: example/dbdoc/bar
# schema_2.tbls.yml
docPath: example/dbdoc/foo
Check example for more details.
Available Commands
Generate database documentation from migration files
Usage:
tblsrun [command]
Available Commands:
help Help about any command
postgres Run tbls with postgres
Flags:
--env-file string --env-file="custom.env" (default ".env")
-h, --help help for tblsrun
Testing
To do manual test we can run make dbdoc
and check there should be 2 output