// the find
k1LoW/tbls
tbls is a CI-Friendly tool to document a database, written in Go.
tbls connects to your database and generates Markdown docs, ER diagrams, and a schema.json from the live schema. It also runs as a linter — you define rules like "all FK columns need an index" and it fails CI if they're violated. Aimed at teams who want database documentation that doesn't drift from the actual schema.
1. Genuinely wide datasource coverage: Postgres, MySQL, SQLite, BigQuery, Spanner, Redshift, DynamoDB, ClickHouse, MongoDB, Databricks, Snowflake — plus an external driver protocol so you can add your own via a PATH-resident binary. 2. The linter is the underrated half. `requireForeignKeyIndex`, `requireColumns`, `duplicateRelations`, `columnCount` — these are the rules that catch schema sloppiness that code review misses. Running `tbls diff` in CI to catch undocumented migrations is a good pattern. 3. Virtual relations in `.tbls.yml` let you draw ER diagrams for schemas that don't use FK constraints (which is most production schemas). 4. Single static binary, zero runtime deps — drops into any CI pipeline without a Docker layer or language runtime to manage.
1. ER diagram generation shells out to Graphviz (`dot`) for PNG/SVG. If Graphviz isn't installed, that silently falls back or errors — not obvious from the README, and Graphviz is not in most base CI images. 2. MongoDB support samples documents to infer schema, which means the docs are probabilistic on heterogeneous collections. The `sampleSize` default is undocumented in the README; on a 10M-row collection with polymorphic fields you'll get incomplete output. 3. Comments in `.tbls.yml` override database comments — easy to create a two-source-of-truth problem on teams where some add comments in migrations and others add them in the config file. There's no merge or conflict detection. 4. The `.tbls.yml` DSN stores credentials in plaintext in a committed config file by default; environment variable expansion is supported but not the default example, so the careless path leaks creds.