tbls

README

tbls

tbls is a CI-Friendly tool for document a database, written in Go.

The key of Features of tbls are:

• Single binary
• Document in GitHub Friendly Markdown format
• CI-Friendly

Usage | Sample | Integration with CI tools | Installation | Database Support

Usage

$ tbls
tbls is a tool for document a database, written in Go.

Usage:
  tbls [command]

Available Commands:
  diff        diff database and document
  doc         document a database
  dot         generate dot file
  help        Help about any command
  version     print tbls version

Flags:
  -h, --help   help for tbls

Use "tbls [command] --help" for more information about a command.

Document a database schema

tbls doc analyzes a database and generate document in GitHub Friendly Markdown format.

$ tbls doc postgres://user:pass@hostname:5432/dbname ./dbdoc

If you can use Graphviz dot command, tbls doc generate ER diagram images at the same time.

Sample document and schema.

Diff database schema and document

tbls diff shows the difference between database schema and generated document.

$ tbls diff postgres://user:pass@hostname:5432/dbname ./dbdoc

Notice: tbls diff shows the difference Markdown documents only.

Integration with CI tools

1. Commit document using tbls doc.
2. Check document updates using tbls diff

Set following code to your-ci-config.yml.

DIFF=`tbls diff postgres://user:pass@localhost:5432/testdb?sslmode=disable ./dbdoc` && if [ ! -z "$DIFF" ]; then echo "document does not match database." >&2 ; tbls diff postgres://user:pass@localhost:5432/testdb?sslmode=disable ./dbdoc; exit 1; fi

Makefile sample is following

doc: ## Document database schema
	tbls doc postgres://user:pass@localhost:5432/testdb?sslmode=disable ./dbdoc

testdoc: ## Test database schema document
	$(eval DIFF := $(shell tbls diff postgres://user:pass@localhost:5432/testdb?sslmode=disable ./dbdoc))
	@test -z "$(DIFF)" || (echo "document does not match database." && tbls diff postgres://user:pass@localhost:5432/testdb?sslmode=disable ./dbdoc && exit 1)

Tips: If the order of the columns does not match, you can use the --sort option.

Add additional data (relations, comments) to schema

To add additional data to the schema, specify the yaml file with the --add option as follows

$ tbls diff mysql://user:pass@hostname:3306/dbname --add path/to/additional_data.yml ./dbdoc

Installation

$ go get github.com/k1LoW/tbls

or

$ brew install k1LoW/tbls/tbls

Database Support

• PostgreSQL
• MySQL