{"id":14969035,"url":"https://github.com/k1low/tbls","last_synced_at":"2026-04-08T08:01:02.841Z","repository":{"id":37246954,"uuid":"133827809","full_name":"k1LoW/tbls","owner":"k1LoW","description":"tbls is a CI-Friendly tool to document a database, written in Go.","archived":false,"fork":false,"pushed_at":"2026-04-03T04:29:42.000Z","size":131688,"stargazers_count":4169,"open_issues_count":55,"forks_count":197,"subscribers_count":22,"default_branch":"main","last_synced_at":"2026-04-03T04:54:35.613Z","etag":null,"topics":["bigquery","continuous-integration","database-document","database-schema","documentation-tool","dynamodb","er-diagram","excel","hacktoberfest","mariadb","markdown","mermaid","mysql","plantuml","postgresql","redshift","snowflake","spanner","sqlite","sqlserver"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/k1LoW.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null},"funding":{"github":"k1LoW","patreon":null,"open_collective":null,"ko_fi":null,"tidelift":null,"community_bridge":null,"liberapay":null,"issuehunt":null,"otechie":null,"custom":null}},"created_at":"2018-05-17T14:47:27.000Z","updated_at":"2026-04-03T04:29:25.000Z","dependencies_parsed_at":"2023-12-19T05:15:41.457Z","dependency_job_id":"eaee29b3-491c-4a06-932f-0b28ce9647d6","html_url":"https://github.com/k1LoW/tbls","commit_stats":{"total_commits":1539,"total_committers":65,"mean_commits":"23.676923076923078","dds":"0.23586744639376223","last_synced_commit":"a1cebf651e977b73043ea0eac242e469c8b1df2d"},"previous_names":[],"tags_count":234,"template":false,"template_full_name":null,"purl":"pkg:github/k1LoW/tbls","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/k1LoW%2Ftbls","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/k1LoW%2Ftbls/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/k1LoW%2Ftbls/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/k1LoW%2Ftbls/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/k1LoW","download_url":"https://codeload.github.com/k1LoW/tbls/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/k1LoW%2Ftbls/sbom","scorecard":{"id":546327,"data":{"date":"2025-08-11","repo":{"name":"github.com/k1LoW/tbls","commit":"174ce55ee29a0955e77071ddb076a050628b8b52"},"scorecard":{"version":"v5.2.1-40-gf6ed084d","commit":"f6ed084d17c9236477efd66e5b258b9d4cc7b389"},"score":4.3,"checks":[{"name":"Code-Review","score":3,"reason":"Found 3/9 approved changesets -- score normalized to 3","details":null,"documentation":{"short":"Determines if the project requires human code review before pull requests (aka merge requests) are merged.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#code-review"}},{"name":"Maintained","score":10,"reason":"30 commit(s) and 8 issue activity found in the last 90 days -- score normalized to 10","details":null,"documentation":{"short":"Determines if the project is \"actively maintained\".","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#maintained"}},{"name":"CII-Best-Practices","score":0,"reason":"no effort to earn an OpenSSF best practices badge detected","details":null,"documentation":{"short":"Determines if the project has an OpenSSF (formerly CII) Best Practices Badge.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#cii-best-practices"}},{"name":"Dangerous-Workflow","score":10,"reason":"no dangerous workflow patterns detected","details":null,"documentation":{"short":"Determines if the project's GitHub Action workflows avoid dangerous patterns.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#dangerous-workflow"}},{"name":"Token-Permissions","score":0,"reason":"detected GitHub workflow tokens with excessive permissions","details":["Warn: no topLevel permission defined: .github/workflows/ci.yml:1","Warn: no topLevel permission defined: .github/workflows/release-test.yml:1","Warn: no topLevel permission defined: .github/workflows/tagpr.yml:1","Info: no jobLevel write permissions found"],"documentation":{"short":"Determines if the project's workflows follow the principle of least privilege.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#token-permissions"}},{"name":"Binary-Artifacts","score":10,"reason":"no binaries found in the repo","details":null,"documentation":{"short":"Determines if the project has generated executable (binary) artifacts in the source repository.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#binary-artifacts"}},{"name":"License","score":10,"reason":"license file detected","details":["Info: project has a license file: LICENSE:0","Info: FSF or OSI recognized license: MIT License: LICENSE:0"],"documentation":{"short":"Determines if the project has defined a license.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#license"}},{"name":"Fuzzing","score":0,"reason":"project is not fuzzed","details":["Warn: no fuzzer integrations found"],"documentation":{"short":"Determines if the project uses fuzzing.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#fuzzing"}},{"name":"Security-Policy","score":0,"reason":"security policy file not detected","details":["Warn: no security policy file detected","Warn: no security file to analyze","Warn: no security file to analyze","Warn: no security file to analyze"],"documentation":{"short":"Determines if the project has published a security policy.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#security-policy"}},{"name":"Branch-Protection","score":0,"reason":"branch protection not enabled on development/release branches","details":["Warn: branch protection not enabled for branch 'main'"],"documentation":{"short":"Determines if the default and release branches are protected with GitHub's branch protection settings.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#branch-protection"}},{"name":"Signed-Releases","score":0,"reason":"Project has not signed or included provenance with any releases.","details":["Warn: release artifact v1.87.0 not signed: https://api.github.com/repos/k1LoW/tbls/releases/237043901","Warn: release artifact v1.86.1 not signed: https://api.github.com/repos/k1LoW/tbls/releases/229168454","Warn: release artifact v1.85.5 not signed: https://api.github.com/repos/k1LoW/tbls/releases/225661896","Warn: release artifact v1.85.4 not signed: https://api.github.com/repos/k1LoW/tbls/releases/219532866","Warn: release artifact v1.85.3 not signed: https://api.github.com/repos/k1LoW/tbls/releases/219328436","Warn: release artifact v1.87.0 does not have provenance: https://api.github.com/repos/k1LoW/tbls/releases/237043901","Warn: release artifact v1.86.1 does not have provenance: https://api.github.com/repos/k1LoW/tbls/releases/229168454","Warn: release artifact v1.85.5 does not have provenance: https://api.github.com/repos/k1LoW/tbls/releases/225661896","Warn: release artifact v1.85.4 does not have provenance: https://api.github.com/repos/k1LoW/tbls/releases/219532866","Warn: release artifact v1.85.3 does not have provenance: https://api.github.com/repos/k1LoW/tbls/releases/219328436"],"documentation":{"short":"Determines if the project cryptographically signs release artifacts.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#signed-releases"}},{"name":"Pinned-Dependencies","score":0,"reason":"dependency not pinned by hash detected -- score normalized to 0","details":["Warn: third-party GitHubAction not pinned by hash: .github/workflows/ci.yml:25: update your workflow using https://app.stepsecurity.io/secureworkflow/k1LoW/tbls/ci.yml/main?enable=pin","Warn: third-party GitHubAction not pinned by hash: .github/workflows/ci.yml:36: update your workflow using https://app.stepsecurity.io/secureworkflow/k1LoW/tbls/ci.yml/main?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/ci.yml:39: update your workflow using https://app.stepsecurity.io/secureworkflow/k1LoW/tbls/ci.yml/main?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/ci.yml:42: update your workflow using https://app.stepsecurity.io/secureworkflow/k1LoW/tbls/ci.yml/main?enable=pin","Warn: third-party GitHubAction not pinned by hash: .github/workflows/ci.yml:59: update your workflow using https://app.stepsecurity.io/secureworkflow/k1LoW/tbls/ci.yml/main?enable=pin","Warn: third-party GitHubAction not pinned by hash: .github/workflows/ci.yml:77: update your workflow using https://app.stepsecurity.io/secureworkflow/k1LoW/tbls/ci.yml/main?enable=pin","Warn: third-party GitHubAction not pinned by hash: .github/workflows/ci.yml:82: update your workflow using https://app.stepsecurity.io/secureworkflow/k1LoW/tbls/ci.yml/main?enable=pin","Warn: third-party GitHubAction not pinned by hash: .github/workflows/ci.yml:102: update your workflow using https://app.stepsecurity.io/secureworkflow/k1LoW/tbls/ci.yml/main?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/ci.yml:105: update your workflow using https://app.stepsecurity.io/secureworkflow/k1LoW/tbls/ci.yml/main?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/ci.yml:108: update your workflow using https://app.stepsecurity.io/secureworkflow/k1LoW/tbls/ci.yml/main?enable=pin","Warn: third-party GitHubAction not pinned by hash: .github/workflows/release-test.yml:55: update your workflow using https://app.stepsecurity.io/secureworkflow/k1LoW/tbls/release-test.yml/main?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/release-test.yml:58: update your workflow using https://app.stepsecurity.io/secureworkflow/k1LoW/tbls/release-test.yml/main?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/release-test.yml:63: update your workflow using https://app.stepsecurity.io/secureworkflow/k1LoW/tbls/release-test.yml/main?enable=pin","Warn: third-party GitHubAction not pinned by hash: .github/workflows/release-test.yml:73: update your workflow using https://app.stepsecurity.io/secureworkflow/k1LoW/tbls/release-test.yml/main?enable=pin","Warn: third-party GitHubAction not pinned by hash: .github/workflows/release-test.yml:97: update your workflow using https://app.stepsecurity.io/secureworkflow/k1LoW/tbls/release-test.yml/main?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/release-test.yml:100: update your workflow using https://app.stepsecurity.io/secureworkflow/k1LoW/tbls/release-test.yml/main?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/release-test.yml:105: update your workflow using https://app.stepsecurity.io/secureworkflow/k1LoW/tbls/release-test.yml/main?enable=pin","Warn: third-party GitHubAction not pinned by hash: .github/workflows/release-test.yml:115: update your workflow using https://app.stepsecurity.io/secureworkflow/k1LoW/tbls/release-test.yml/main?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/release-test.yml:129: update your workflow using https://app.stepsecurity.io/secureworkflow/k1LoW/tbls/release-test.yml/main?enable=pin","Warn: third-party GitHubAction not pinned by hash: .github/workflows/release-test.yml:141: update your workflow using https://app.stepsecurity.io/secureworkflow/k1LoW/tbls/release-test.yml/main?enable=pin","Warn: third-party GitHubAction not pinned by hash: .github/workflows/release-test.yml:144: update your workflow using https://app.stepsecurity.io/secureworkflow/k1LoW/tbls/release-test.yml/main?enable=pin","Warn: third-party GitHubAction not pinned by hash: .github/workflows/release-test.yml:147: update your workflow using https://app.stepsecurity.io/secureworkflow/k1LoW/tbls/release-test.yml/main?enable=pin","Warn: third-party GitHubAction not pinned by hash: .github/workflows/release-test.yml:153: update your workflow using https://app.stepsecurity.io/secureworkflow/k1LoW/tbls/release-test.yml/main?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/release-test.yml:19: update your workflow using https://app.stepsecurity.io/secureworkflow/k1LoW/tbls/release-test.yml/main?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/release-test.yml:24: update your workflow using https://app.stepsecurity.io/secureworkflow/k1LoW/tbls/release-test.yml/main?enable=pin","Warn: third-party GitHubAction not pinned by hash: .github/workflows/release-test.yml:38: update your workflow using https://app.stepsecurity.io/secureworkflow/k1LoW/tbls/release-test.yml/main?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/tagpr.yml:16: update your workflow using https://app.stepsecurity.io/secureworkflow/k1LoW/tbls/tagpr.yml/main?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/tagpr.yml:19: update your workflow using https://app.stepsecurity.io/secureworkflow/k1LoW/tbls/tagpr.yml/main?enable=pin","Warn: third-party GitHubAction not pinned by hash: .github/workflows/tagpr.yml:25: update your workflow using https://app.stepsecurity.io/secureworkflow/k1LoW/tbls/tagpr.yml/main?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/tagpr.yml:35: update your workflow using https://app.stepsecurity.io/secureworkflow/k1LoW/tbls/tagpr.yml/main?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/tagpr.yml:40: update your workflow using https://app.stepsecurity.io/secureworkflow/k1LoW/tbls/tagpr.yml/main?enable=pin","Warn: third-party GitHubAction not pinned by hash: .github/workflows/tagpr.yml:49: update your workflow using https://app.stepsecurity.io/secureworkflow/k1LoW/tbls/tagpr.yml/main?enable=pin","Warn: third-party GitHubAction not pinned by hash: .github/workflows/tagpr.yml:74: update your workflow using https://app.stepsecurity.io/secureworkflow/k1LoW/tbls/tagpr.yml/main?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/tagpr.yml:77: update your workflow using https://app.stepsecurity.io/secureworkflow/k1LoW/tbls/tagpr.yml/main?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/tagpr.yml:82: update your workflow using https://app.stepsecurity.io/secureworkflow/k1LoW/tbls/tagpr.yml/main?enable=pin","Warn: third-party GitHubAction not pinned by hash: .github/workflows/tagpr.yml:92: update your workflow using https://app.stepsecurity.io/secureworkflow/k1LoW/tbls/tagpr.yml/main?enable=pin","Warn: third-party GitHubAction not pinned by hash: .github/workflows/tagpr.yml:126: update your workflow using https://app.stepsecurity.io/secureworkflow/k1LoW/tbls/tagpr.yml/main?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/tagpr.yml:129: update your workflow using https://app.stepsecurity.io/secureworkflow/k1LoW/tbls/tagpr.yml/main?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/tagpr.yml:134: update your workflow using https://app.stepsecurity.io/secureworkflow/k1LoW/tbls/tagpr.yml/main?enable=pin","Warn: third-party GitHubAction not pinned by hash: .github/workflows/tagpr.yml:143: update your workflow using https://app.stepsecurity.io/secureworkflow/k1LoW/tbls/tagpr.yml/main?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/tagpr.yml:165: update your workflow using https://app.stepsecurity.io/secureworkflow/k1LoW/tbls/tagpr.yml/main?enable=pin","Warn: third-party GitHubAction not pinned by hash: .github/workflows/tagpr.yml:177: update your workflow using https://app.stepsecurity.io/secureworkflow/k1LoW/tbls/tagpr.yml/main?enable=pin","Warn: third-party GitHubAction not pinned by hash: .github/workflows/tagpr.yml:180: update your workflow using https://app.stepsecurity.io/secureworkflow/k1LoW/tbls/tagpr.yml/main?enable=pin","Warn: third-party GitHubAction not pinned by hash: .github/workflows/tagpr.yml:183: update your workflow using https://app.stepsecurity.io/secureworkflow/k1LoW/tbls/tagpr.yml/main?enable=pin","Warn: third-party GitHubAction not pinned by hash: .github/workflows/tagpr.yml:189: update your workflow using https://app.stepsecurity.io/secureworkflow/k1LoW/tbls/tagpr.yml/main?enable=pin","Warn: third-party GitHubAction not pinned by hash: .github/workflows/tagpr.yml:196: update your workflow using https://app.stepsecurity.io/secureworkflow/k1LoW/tbls/tagpr.yml/main?enable=pin","Warn: containerImage not pinned by hash: Dockerfile:1","Warn: containerImage not pinned by hash: Dockerfile:12: pin your Docker image by updating debian:bookworm-slim to debian:bookworm-slim@sha256:b1a741487078b369e78119849663d7f1a5341ef2768798f7b7406c4240f86aef","Warn: chocoCommand not pinned by hash: .github/workflows/ci.yml:99","Warn: goCommand not pinned by hash: .github/workflows/release-test.yml:34","Warn: goCommand not pinned by hash: .github/workflows/release-test.yml:69","Info:   0 out of  20 GitHub-owned GitHubAction dependencies pinned","Info:   0 out of  26 third-party GitHubAction dependencies pinned","Info:   0 out of   2 containerImage dependencies pinned","Info:   0 out of   1 chocoCommand dependencies pinned","Info:   0 out of   2 goCommand dependencies pinned"],"documentation":{"short":"Determines if the project has declared and pinned the dependencies of its build process.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#pinned-dependencies"}},{"name":"Packaging","score":10,"reason":"packaging workflow detected","details":["Info: Project packages its releases by way of GitHub Actions.: .github/workflows/release-test.yml:13"],"documentation":{"short":"Determines if the project is published as a package that others can easily download, install, easily update, and uninstall.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#packaging"}},{"name":"SAST","score":0,"reason":"SAST tool is not run on all commits -- score normalized to 0","details":["Warn: 0 commits out of 27 are checked with a SAST tool"],"documentation":{"short":"Determines if the project uses static code analysis.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#sast"}},{"name":"Vulnerabilities","score":7,"reason":"3 existing vulnerabilities detected","details":["Warn: Project is vulnerable to: GO-2022-0635","Warn: Project is vulnerable to: GO-2022-0646","Warn: Project is vulnerable to: GHSA-q7pp-wcgr-pffx"],"documentation":{"short":"Determines if the project has open, known unfixed vulnerabilities.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#vulnerabilities"}}]},"last_synced_at":"2025-08-20T09:37:01.371Z","repository_id":37246954,"created_at":"2025-08-20T09:37:01.371Z","updated_at":"2025-08-20T09:37:01.371Z"},"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31545906,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-07T16:28:08.000Z","status":"online","status_checked_at":"2026-04-08T02:00:06.127Z","response_time":54,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["bigquery","continuous-integration","database-document","database-schema","documentation-tool","dynamodb","er-diagram","excel","hacktoberfest","mariadb","markdown","mermaid","mysql","plantuml","postgresql","redshift","snowflake","spanner","sqlite","sqlserver"],"created_at":"2024-09-24T13:40:59.642Z","updated_at":"2026-04-08T08:01:02.818Z","avatar_url":"https://github.com/k1LoW.png","language":"Go","funding_links":["https://github.com/sponsors/k1LoW"],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n\u003cbr\u003e\n\u003cimg src=\"https://github.com/k1LoW/tbls/raw/main/img/logo.png\" width=\"200\" alt=\"tbls\"\u003e\n\u003cbr\u003e\u003cbr\u003e\n\u003c/p\u003e\n\n[![Build Status](https://github.com/k1LoW/tbls/workflows/build/badge.svg)](https://github.com/k1LoW/tbls/actions) [![GitHub release](https://img.shields.io/github/release/k1LoW/tbls.svg)](https://github.com/k1LoW/tbls/releases) [![Go Report Card](https://goreportcard.com/badge/github.com/k1LoW/tbls)](https://goreportcard.com/report/github.com/k1LoW/tbls) ![Coverage](https://raw.githubusercontent.com/k1LoW/octocovs/main/badges/k1LoW/tbls/coverage.svg) ![Code to Test Ratio](https://raw.githubusercontent.com/k1LoW/octocovs/main/badges/k1LoW/tbls/ratio.svg) ![Test Execution Time](https://raw.githubusercontent.com/k1LoW/octocovs/main/badges/k1LoW/tbls/time.svg)\n\n`tbls` (pronounced /ˈteɪbl̩z/) is a CI-Friendly tool to document a database, written in Go.\n\nKey features of `tbls` are:\n\n- **Document a database automatically in [GFM](https://github.github.com/gfm/) format. Output database schema [in many formats](#output-formats).**\n- **Single binary = CI-Friendly.**\n- **[Support many databases](#support-datasource).**\n- **Work as linter for database**\n\n### Table of Contents\n\n  - [Quick Start](#quick-start)\n  - [Install](#install)\n  - [Getting Started](#getting-started)\n    - [Document a database](#document-a-database)\n    - [Diff database and (document or database)](#diff-database-and-document-or-database)\n    - [Lint a database](#lint-a-database)\n    - [Measure document coverage](#measure-document-coverage)\n    - [Continuous Integration](#continuous-integration)\n  - [Configuration](#configuration)\n    - [Name](#name)\n    - [Description](#description)\n    - [Labels](#labels)\n    - [DSN](#dsn)\n      - [Support Datasource](#support-datasource)\n    - [Document path](#document-path)\n    - [Document format](#document-format)\n    - [ER diagram](#er-diagram)\n    - [Filter tables](#filter-tables)\n    - [Lint](#lint)\n    - [Comments](#comments)\n    - [Relations](#relations)\n    - [Viewpoints](#viewpoints)\n    - [Dictionary](#dictionary)\n    - [Personalized Templates](#personalized-templates)\n    - [Required Version](#required-version)\n  - [Expand environment variables](#expand-environment-variables)\n  - [Output formats](#output-formats)\n  - [Command arguments](#command-arguments)\n  - [Environment variables](#environment-variables)\n\n\u003cbr\u003e\n\n## Quick Start\n\nDocument a database with one command.\n\n```console\n$ tbls doc postgres://dbuser:dbpass@hostname:5432/dbname\n```\n\nUsing docker image.\n\n```console\n$ docker run --rm -v $PWD:/work -w /work ghcr.io/k1low/tbls doc postgres://dbuser:dbpass@hostname:5432/dbname\n```\n\n## Install\n\n**deb:**\n\n```console\n$ export TBLS_VERSION=X.X.X\n$ curl -o tbls.deb -L https://github.com/k1LoW/tbls/releases/download/v$TBLS_VERSION/tbls_$TBLS_VERSION-1_amd64.deb\n$ dpkg -i tbls.deb\n```\n\n**RPM:**\n\n```console\n$ export TBLS_VERSION=X.X.X\n$ yum install https://github.com/k1LoW/tbls/releases/download/v$TBLS_VERSION/tbls_$TBLS_VERSION-1_amd64.rpm\n```\n\n**Homebrew:**\n\n```console\n$ brew install tbls\n```\n\n**MacPorts:**\n\n```console\n$ sudo port install tbls\n```\n\n**[aqua](https://aquaproj.github.io/):**\n\n```console\n$ aqua g -i k1LoW/tbls\n```\n\n**Manually:**\n\nDownload binary from [releases page](https://github.com/k1LoW/tbls/releases)\n\n**go install:**\n\n```console\n$ go install github.com/k1LoW/tbls@latest\n```\n\n**Docker:**\n\n```console\n$ docker pull ghcr.io/k1low/tbls:latest\n```\n\n**On GitHub Actions:**\n\n```yml\n# .github/workflows/doc.yml\nname: Document\n\non:\n  push:\n    branches:\n      - main\n\njobs:\n  doc:\n    runs-on: ubuntu-latest\n    steps:\n      -\n        name: Checkout .tbls.yml\n        uses: actions/checkout@v3\n      -\n        uses: k1low/setup-tbls@v1\n      -\n        name: Run tbls for generate database document\n        run: tbls doc\n```\n\n**:octocat: A GitHub Action for tbls is [here](https://github.com/k1LoW/setup-tbls).**\n\n**Temporary:**\n\n```console\n$ source \u003c(curl https://raw.githubusercontent.com/k1LoW/tbls/main/use)\n```\n\n```console\n$ curl -sL https://raw.githubusercontent.com/k1LoW/tbls/main/use \u003e /tmp/use-tbls.tmp \u0026\u0026 . /tmp/use-tbls.tmp\n```\n\n## Getting Started\n\n### Document a database\n\nAdd `.tbls.yml` (or `tbls.yml`) file to your repository.\n\n```yaml\n# .tbls.yml\n\n# DSN (Database Source Name) to connect database\ndsn: postgres://dbuser:dbpass@localhost:5432/dbname\n\n# Path to generate document\n# Default is `dbdoc`\ndocPath: doc/schema\n```\n\n\u003e **Notice:** If you are using a symbol such as `#` `\u003c` in database password, URL-encode the password\n\nRun `tbls doc` to analyzes the database and generate document in GitHub Friendly Markdown format.\n\n```console\n$ tbls doc\n```\n\nCommit `.tbls.yml` and the document.\n\n```console\n$ git add .tbls.yml doc/schema\n$ git commit -m 'Add database document'\n$ git push origin main\n```\n\nView the document on GitHub.\n\n[Sample document](sample/postgres/README.md)\n\n![sample](img/doc.png)\n\n### Diff database and (document or database)\n\nUpdate database schema.\n\n```console\n$ psql -U dbuser -d dbname -h hostname -p 5432 -c 'ALTER TABLE users ADD COLUMN phone_number varchar(15);'\nPassword for user dbuser:\nALTER TABLE\n```\n\n`tbls diff` shows the difference between database schema and generated document.\n\n```diff\n$ tbls diff\ndiff postgres://dbuser:*****@hostname:5432/dbname doc/schema/README.md\n--- postgres://dbuser:*****@hostname:5432/dbname\n+++ doc/schema/README.md\n@@ -4,7 +4,7 @@\n\n | Name | Columns | Comment | Type |\n | ---- | ------- | ------- | ---- |\n-| [users](users.md) | 7 | Users table | BASE TABLE |\n+| [users](users.md) | 6 | Users table | BASE TABLE |\n | [user_options](user_options.md) | 4 | User options table | BASE TABLE |\n | [posts](posts.md) | 8 | Posts table | BASE TABLE |\n | [comments](comments.md) | 6 | Comments\u003cbr /\u003eMulti-line\u003cbr /\u003etable\u003cbr /\u003ecomment | BASE TABLE |\ndiff postgres://dbuser:*****@hostname:5432/dbname doc/schema/users.md\n--- postgres://dbuser:*****@hostname:5432/dbname\n+++ doc/schema/users.md\n@@ -14,7 +14,6 @@\n | email | varchar(355) |  | false |  |  | ex. user@example.com |\n | created | timestamp without time zone |  | false |  |  |  |\n | updated | timestamp without time zone |  | true |  |  |  |\n-| phone_number | varchar(15) |  | true |  |  |  |\n\n ## Constraints\n\n```\n\nAnd, `tbls diff` support for diff checking between database and other database\n\n```console\n$ tbls diff postgres://dbuser:*****@local:5432/dbname postgres://dbuser:*****@production:5432/dbname\n```\n\n\u003e **Notice:** `tbls diff` shows the difference Markdown documents only.\n\n### Re-generating database documentation\n\nExisting documentation can re-generated using either `--force` or `--rm-dist` flag.\n\n`--force` forces overwrite of the existing documents. It does not, however, remove files of removed tables.\n\n```console\n$ tbls doc --force\n```\n\n`--rm-dist` removes files in docPath before generating the documents.\n\n```console\n$ tbls doc --rm-dist\n```\n\n### Lint a database\n\nAdd linting rule to `.tbls.yml` following\n\n```yaml\n# .tbls.yml\nlint:\n  requireColumnComment:\n    enabled: true\n    exclude:\n      - id\n      - created\n      - updated\n  columnCount:\n    enabled: true\n    max: 10\n```\n\nRun `tbls lint` to check the database according to `lint:` rules\n\n```console\n$ tbls lint\nusers.username: column comment required.\nusers.password: column comment required.\nusers.phone_number: column comment required.\nposts.user_id: column comment required.\nposts.title: column comment required.\nposts.labels: column comment required.\ncomments.post_id: column comment required.\ncomment_stars.user_id: column comment required.\npost_comments.comment: column comment required.\nposts: too many columns. [12/10]\ncomments: too many columns. [11/10]\n\n11 detected\n```\n\n### Measure document coverage\n\n`tbls coverage` measure and show document coverage (description, comments).\n\n```console\n$ tbls coverage\nTable                       Coverage\nAll tables                  16.1%\n public.users               20%\n public.user_options        37.5%\n public.posts               35.3%\n public.comments            14.3%\n public.comment_stars       0%\n public.logs                12.5%\n public.post_comments       87.5%\n public.post_comment_stars  0%\n public.CamelizeTable       0%\n public.hyphen-table        0%\n administrator.blogs        0%\n backup.blogs               0%\n backup.blog_options        0%\n time.bar                   0%\n time.hyphenated-table      0%\n time.referencing           0%\n```\n\n### Continuous Integration\n\nContinuous integration using tbls.\n\n1. Commit the document using `tbls doc`.\n2. Update the database schema in the development cycle.\n3. Check for document updates by running `tbls diff` or `tbls lint` in CI.\n4. Return to **1**.\n\n**Example: Travis CI**\n\n```yaml\n# .travis.yml\nlanguage: go\n\ninstall:\n  - source \u003c(curl -sL https://raw.githubusercontent.com/k1LoW/tbls/main/use)\nscript:\n  - tbls diff\n  - tbls lint\n```\n\n\u003e **Tips:** If your CI based on Debian/Ubuntu (`/bin/sh -\u003e dash`), you can use the following install command `curl -sL https://raw.githubusercontent.com/k1LoW/tbls/main/use \u003e use-tbls.tmp \u0026\u0026 . ./use-tbls.tmp \u0026\u0026 rm ./use-tbls.tmp`\n\n\u003e **Tips:** If the order of the columns does not match, you can use the `--sort` option.\n\n## Configuration\n\n### Name\n\n`name:` is used to specify the database name of the document.\n\n```yaml\n# .tbls.yml\nname: mydatabase\n```\n\n### Description\n\n`desc:` is used to specify the database description.\n\n```yaml\n# .tbls.yml\ndesc: This is My Database\n```\n\n### Labels\n\n`labels:` is used to label the database or tables.\n\n**label database:**\n\n```yaml\n# .tbls.yml\nlabels:\n  - cmdb\n  - analytics\n```\n\n**label tables:**\n\n```yaml\n# .tbls.yml\ncomments:\n  -\n    table: users\n    labels:\n      - user\n      - privacy data\n```\n\n**label columns:**\n\n```yaml\n# .tbls.yml\ncomments:\n  -\n    table: users\n    columnLabels:\n      email:\n        - secure\n        - encrypted\n```\n\n### DSN\n\n`dsn:` (Data Source Name) is used to connect to database.\n\n```yaml\n# .tbls.yml\ndsn: my://dbuser:dbpass@hostname:3306/dbname\n```\n\n#### Support Datasource\n\ntbls supports the following databases/datasources.\n\n**PostgreSQL:**\n\n```yaml\n# .tbls.yml\ndsn: postgres://dbuser:dbpass@hostname:5432/dbname\n```\n\n```yaml\n# .tbls.yml\ndsn: pg://dbuser:dbpass@hostname:5432/dbname\n```\n\nWhen you want to disable SSL mode, add \"?sslmode=disable\"\nFor example:\n```yaml\ndsn: pg://dbuser:dbpass@hostname:5432/dbname?sslmode=disable\n```\n\n**MySQL:**\n\n```yaml\n# .tbls.yml\ndsn: mysql://dbuser:dbpass@hostname:3306/dbname\n```\n\n```yaml\n# .tbls.yml\ndsn: my://dbuser:dbpass@hostname:3306/dbname\n```\n\nWhen you want to hide AUTO_INCREMENT clause on the table definitions,\nadd \"?hide_auto_increment\".\nFor example:\n```yaml\ndsn: my://dbuser:dbpass@hostname:3306/dbname?hide_auto_increment\n```\n\n**MariaDB:**\n\n```yaml\n# .tbls.yml\ndsn: mariadb://dbuser:dbpass@hostname:3306/dbname\n```\n\n```yaml\n# .tbls.yml\ndsn: maria://dbuser:dbpass@hostname:3306/dbname\n```\n\n**SQLite:**\n\n```yaml\n# .tbls.yml\ndsn: sqlite:///path/to/dbname.db\n```\n\n```yaml\n# .tbls.yml\ndsn: sq:///path/to/dbname.db\n```\n\n**BigQuery:**\n\n```yaml\n# .tbls.yml\ndsn: bigquery://project-id/dataset-id?creds=/path/to/google_application_credentials.json\n```\n\n```yaml\n# .tbls.yml\ndsn: bq://project-id/dataset-id?creds=/path/to/google_application_credentials.json\n```\n\nTo set `GOOGLE_APPLICATION_CREDENTIALS` environment variable, you can use\n\n1. `export GOOGLE_APPLICATION_CREDENTIALS` or `export GOOGLE_APPLICATION_CREDENTIALS_JSON`\n2. Add query to DSN\n    - `?google_application_credentials=/path/to/client_secrets.json`\n    - `?credentials=/path/to/client_secrets.json`\n    - `?creds=/path/to/client_secrets.json`\n\nRequired permissions: `bigquery.datasets.get` `bigquery.tables.get` `bigquery.tables.list`\n\nAlso, you can use impersonate service account using environment variables below.\n\n- `GOOGLE_IMPERSONATE_SERVICE_ACCOUNT`: Email of service account\n- `GOOGLE_IMPERSONATE_SERVICE_ACCOUNT_LIFETIME`: You can use impersonate service account within this lifetime. This value must be readable from https://github.com/k1LoW/duration .\n\n\n**Cloud Spanner:**\n\n```yaml\n# .tbls.yml\ndsn: spanner://project-id/instance-id/dbname?creds=/path/to/google_application_credentials.json\n```\n\nTo set `GOOGLE_APPLICATION_CREDENTIALS` environment variable, you can use\n\n1. `export GOOGLE_APPLICATION_CREDENTIALS` or `export GOOGLE_APPLICATION_CREDENTIALS_JSON`\n2. Add query to DSN\n    - `?google_application_credentials=/path/to/client_secrets.json`\n    - `?credentials=/path/to/client_secrets.json`\n    - `?creds=/path/to/client_secrets.json`\n\nAlso, you can use impersonate service account using environment variables below.\n\n- `GOOGLE_IMPERSONATE_SERVICE_ACCOUNT`: Email of service account\n- `GOOGLE_IMPERSONATE_SERVICE_ACCOUNT_LIFETIME`: You can use impersonate service account within this lifetime. This value must be readable from https://github.com/k1LoW/duration .\n\n**Amazon Redshift:**\n\n```yaml\n# .tbls.yml\ndsn: redshift://dbuser:dbpass@hostname:5432/dbname\n```\n\n```yaml\n# .tbls.yml\ndsn: rs://dbuser:dbpass@hostname:5432/dbname\n```\n\n**Microsoft SQL Server:**\n\n```yaml\n# .tbls.yml\ndsn: mssql://DbUser:SQLServer-DbPassw0rd@hostname:1433/testdb\n```\n\n```yaml\n# .tbls.yml\ndsn: sqlserver://DbUser:SQLServer-DbPassw0rd@hostname:1433/testdb\n```\n\n```yaml\n# .tbls.yml\ndsn: ms://DbUser:SQLServer-DbPassw0rd@localhost:1433/testdb\n```\n\n**Amazon DynamoDB:**\n\n```yaml\n# .tbls.yml\ndsn: dynamodb://us-west-2\n```\n\n```yaml\n# .tbls.yml\ndsn: dynamo://ap-northeast-1?aws_access_key_id=XXXXXxxxxxxxXXXXXXX\u0026aws_secret_access_key=XXXXXxxxxxxxXXXXXXX\n```\n\nTo set AWS credentials, you can use\n\n1. [Use default credential provider chain of AWS SDK for Go](https://docs.aws.amazon.com/sdk-for-go/v1/developer-guide/configuring-sdk.html#specifying-credentials)\n2. Add query to DSN\n    - `?aws_access_key_id=XXXXXxxxxxxxXXXXXXX\u0026aws_secret_access_key=XXXXXxxxxxxxXXXXXXX`\n\n**Snowflake (Experimental):**\n\n```yaml\n---\n# .tbls.yml\ndsn: snowflake://user:password@myaccount/mydb/myschema\n```\n\nSee also: https://pkg.go.dev/github.com/snowflakedb/gosnowflake\n\n**MongoDB:**\n\n```yaml\n# .tbls.yml\ndsn: mongodb://mongoadmin:secret@localhost:27017/test\n```\n\n```yaml\n# .tbls.yml\ndsn: mongodb://mongoadmin:secret@localhost:27017/test?sampleSize=20\n```\n\nIf a field has multiple types, the `multipleFieldType` query can be used to list all the types.\n\n```yaml\n# .tbls.yml\ndsn: mongodb://mongoadmin:secret@localhost:27017/test?sampleSize=20\u0026multipleFieldType=true\n```\n\n**ClickHouse:**\n\n```yaml\n# .tbls.yml\ndsn: clickhouse://dbuser:dbpass@hostname:9000/dbname\n```\n\nSee also: https://pkg.go.dev/github.com/ClickHouse/clickhouse-go\n\n**Databricks (Experimental):**\n\nPersonal Access Token (PAT) Authentication:\n```yaml\n# .tbls.yml\ndsn: databricks://your_databricks_workspace_id.cloud.databricks.com:443/sql/1.0/warehouses/your_warehouse_id?catalog=your_catalog\u0026schema=your_schema\u0026token=your_token\n```\n\nOAuth Client Credentials Authentication:\n```yaml\n# .tbls.yml\ndsn: databricks://your_databricks_workspace_id.cloud.databricks.com:443/sql/1.0/warehouses/your_warehouse_id?catalog=your_catalog\u0026schema=your_schema\u0026client_id=your_client_id\u0026client_secret=your_client_secret\n```\n\nRequired parameters:\n- `your_databricks_workspace_id`: databricks workspace ID\n- `your_warehouse_id`: databricks sql warehouse ID\n- `your_catalog`: Unity Catalog name\n\noptional parameters:\n- `your_schema`: Schema/database name within the catalog. If not specified all tables in the catalogue will be documented and generated table references will include schema name.\n\nAuthentication (choose one):\n- PAT Authentication: `token` - Personal access token for authentication\n- OAuth Authentication: `client_id` and `client_secret` - OAuth M2M client credentials\n\nSee also: https://pkg.go.dev/github.com/databricks/databricks-sql-go\n\n**JSON:**\n\nThe JSON file output by the `tbls out -t json` command can be read as a datasource (JSON Schema is [here](spec/tbls.schema.json_schema.json)).\n\n```yaml\n---\n# .tbls.yml\ndsn: json://path/to/testdb.json\n```\n\n**HTTP:**\n\n```yaml\n---\n# .tbls.yml\ndsn: https://hostname/path/to/testdb.json\n```\n\n```yaml\n---\n# .tbls.yml\ndsn:\n  url: https://hostname/path/to/testdb.json\n  headers:\n    Authorization: token GITHUB_OAUTH_TOKEN\n```\n\n**GitHub:**\n\n```yaml\n---\n# .tbls.yml\ndsn: github://k1LoW/tbls/sample/mysql/schema.json\n```\n\n### External database driver\n\ntbls can integrate with external database drivers. If an executable with the pattern `tbls-driver-*` is on the PATH, tbls will recognize the corresponding scheme.\n\nFor example, if you have an executable named `tbls-driver-foodb`, tbls will recognize the `foodb://` scheme.\n\n`tbls-driver-foodb` receives the DSN at runtime via the environment variable `TBLS_DSN`. By outputting [schema.json](spec/tbls.schema.json_schema.json) via STDOUT, tbls will work with it.\n\n### Document path\n\n`tbls doc` generates document in the directory specified by `docPath:`.\n\n```yaml\n# .tbls.yml\n# Default is `dbdoc`\ndocPath: doc/schema\n```\n\n### Document format\n\n`format:` is used to change the document format.\n\n```yaml\n# .tbls.yml\nformat:\n  # Adjust the column width of Markdown format table\n  # Default is false\n  adjust: true\n  # Sort the order of table list and columns\n  # Default is false\n  sort: false\n  # Display sequential numbers in table rows\n  # Default is false\n  number: false\n  # The comments for each table in the Tables section of the index page will display the text up to the first double newline (first paragraph).\n  # Default is false\n  showOnlyFirstParagraph: true\n  # Hide table columns without values\n  # Default is false\n  hideColumnsWithoutValues: true\n  # It can be boolean or array\n  # hideColumnsWithoutValues: [\"Parents\", \"Children\"]\n```\n\n### ER diagram\n\n`tbls doc` generate ER diagram images at the same time.\n\n```yaml\n# .tbls.yml\ner:\n  # Skip generation of ER diagram\n  # Default is false\n  skip: false\n  # ER diagram image format (`png`, `jpg`, `svg`, `mermaid`)\n  # Default is `svg`\n  format: svg\n  # Add table/column comment to ER diagram\n  # Default is false\n  comment: true\n  # Hide relation definition from ER diagram\n  # Default is false\n  hideDef: true\n  # Show column settings in ER diagram. If this section is not set, all columns will be displayed (default).\n  showColumnTypes:\n    # Show related columns\n    related: true\n    # Show primary key columns\n    primary: true\n  # Distance between tables that display relations in the ER\n  # Default is 1\n  distance: 2\n  # ER diagram (png/jpg) font (font name, font file, font path or keyword)\n  # Default is \"\" (system default)\n  font: M+\n```\n\nIt is also possible to personalize the output by providing your own templates.\nSee the [Personalized Templates](#personalized-templates) section below.\n\n### Lint\n\n`tbls lint` work as linter for database.\n\n```yaml\n# .tbls.yml\nlint:\n  # require table comment\n  requireTableComment:\n    enabled: true\n    # all commented, or all uncommented.\n    allOrNothing: false\n  # require column comment\n  requireColumnComment:\n    enabled: true\n    # all commented, or all uncommented.\n    allOrNothing: true\n    # exclude columns from warnings\n    exclude:\n      - id\n      - created_at\n      - updated_at\n    # exclude tables from warnings\n    excludeTables:\n      - logs\n      - comment_stars\n  # require index comment\n  requireIndexComment:\n    enabled: true\n    # all commented, or all uncommented.\n    allOrNothing: false\n    # exclude indexes from warnings\n    exclude:\n      - user_id_idx\n    # exclude tables from warnings\n    excludeTables:\n      - logs\n      - comment_stars\n  # require constraint comment\n  requireConstraintComment:\n    enabled: true\n    # all commented, or all uncommented.\n    allOrNothing: false\n    # exclude constrains from warnings\n    exclude:\n      - unique_user_name\n    # exclude tables from warnings\n    excludeTables:\n      - logs\n      - comment_stars\n  # require trigger comment\n  requireTriggerComment:\n    enabled: true\n    # all commented, or all uncommented.\n    allOrNothing: false\n    # exclude triggers from warnings\n    exclude:\n      - update_count\n    # exclude tables from warnings\n    excludeTables:\n      - logs\n      - comment_stars\n  # require table labels\n  requireTableLabels:\n    enabled: true\n    # all commented, or all uncommented.\n    allOrNothing: false\n    # exclude tables from warnings\n    exclude:\n      - logs\n  # find a table that has no relation\n  unrelatedTable:\n    enabled: true\n    # all related, or all unrelated.\n    allOrNothing: true\n    # exclude tables from warnings\n    exclude:\n      - logs\n  # check max column count\n  columnCount:\n    enabled: true\n    max: 10\n    # exclude tables from warnings\n    exclude:\n      - user_options\n  # require columns\n  requireColumns:\n    enabled: true\n    columns:\n      -\n        name: created\n      -\n        name: updated\n        exclude:\n          - logs\n          - CamelizeTable\n  # check duplicate relations\n  duplicateRelations:\n    enabled: true\n  # check if the foreign key columns have an index\n  requireForeignKeyIndex:\n    enabled: true\n    exclude:\n      - comments.user_id\n  # checks if labels are in BigQuery style (https://cloud.google.com/resource-manager/docs/creating-managing-labels#requirements)\n  labelStyleBigQuery:\n    enabled: true\n    exclude:\n      - schema_migrations\n  # checks if tables are included in at least one viewpoint\n  requireViewpoints: \n    enabled: true\n    exclude:\n      - schema_migrations\n```\n\n### Filter tables\n\n![filter tables](img/filter-tables.png)\n\n`include:` and `exclude:` are used to filter target tables from `tbls *`.\n\n```yaml\n# .tbls.yml\ninclude:\n  - some_prefix_*\nexclude:\n  - some_prefix_logs\n  - CamelizeTable\n```\n\n`lintExclude:` is used to exclude tables from `tbls lint`.\n\n```yaml\n# .tbls.yml\nlintExclude:\n  - CamelizeTable\n```\n\n#### Filter logic\n\n1. Add tables/functions from include\n2. Remove tables/functions from exclude\n    - Check for include/exclude overlaps\n    - If include is more specific than exclude (i.e. `schema.MyTable` \u003e `schema.*` or `schema.MyT*` \u003e `schema.*`), include the table(s)/function(s). If include is equally or less specific than exclude, exclude wins.\n3. Result\n\n### Comments\n\n`comments:` is used to add table/column comment to database document without `ALTER TABLE`.\n\nFor example, you can add comment about VIEW TABLE or SQLite tables/columns.\n\n\u003e **Notice:** Comments defined in `.tbls.yml` will override existing comments in the schema.\n\n```yaml\n# .tbls.yml\ncomments:\n  -\n    table: users\n    # table comment\n    tableComment: Users table\n    # column comments\n    columnComments:\n      email: Email address as login id. ex. user@example.com\n    # labels for tables\n    labels:\n      - privary data\n      - backup:true\n  -\n    table: post_comments\n    tableComment: post and comments View table\n    columnComments:\n      id: comments.id\n      title: posts.title\n      post_user: posts.users.username\n      comment_user: comments.users.username\n      created: comments.created\n      updated: comments.updated\n  -\n    table: posts\n    # index comments\n    indexComments:\n      posts_user_id_idx: user.id index\n    # constraints comments\n    constraintComments:\n      posts_id_pk: PRIMARY KEY\n    # triggers comments\n    triggerComments:\n      update_posts_updated: Update updated when posts update\n```\n\n### Relations\n\n`relations:` is used to add or override table relation to database document without `FOREIGN KEY`.\n\nYou can create ER diagrams with relations without having foreign key constraints.\n\n```yaml\nrelations:\n  -\n    table: logs\n    columns:\n      - user_id\n    parentTable: users\n    parentColumns:\n      - id\n    # Relation definition\n    # Default is `Additional Relation`\n    def: logs-\u003eusers\n  -\n    table: logs\n    columns:\n      - post_id\n    parentTable: posts\n    parentColumns:\n      - id\n  -\n    table: logs\n    columns:\n      - comment_id\n    parentTable: comments\n    parentColumns:\n      - id\n  -\n    table: logs\n    columns:\n      - comment_star_id\n    parentTable: comment_stars\n    parentColumns:\n      - id\n```\n\n![img](sample/mysql/logs.svg)\n\n\n#### Override relations\n\nIf you want to override an existing relation, set the `override:` to `true`.\n\n```yaml\nrelations:\n  -\n    table: posts\n    columns:\n      - user_id\n    cardinality: zero or one\n    parentTable: users\n    parentColumns:\n      - id\n    parentCardinality: one or more\n    override: true\n    def: posts-\u003eusers\n```\n\n#### Automatically detect relations\n\n`detectVirtualRelations:` if enabled, automatically detect relations from table and column names.\n\n```yaml\ndetectVirtualRelations:\n  enabled: true\n  strategy: default\n```\n\n##### Supported strategies\n\n| strategy name                | relation from        | relation to     |\n| :--                          | :--                  | :--             |\n| `default`                    | `some_table.user_id` | `users.id`      |\n| `singularTableName`          | `some_table.user_id` | `user.id`       |\n| `identical`                  | `some_table.user_id` | `users.user_id` |\n| `identicalSingularTableName` | `some_table.user_id` | `user.user_id`  |\n| `invertedSingularTableName`  | `some_table.id_user` | `user.id`       |\n\n\n### Dictionary\n\n`dict:` is used to replace title/table header of database document\n\n```yaml\n# .tbls.yml\n---\ndict:\n  Tables: テーブル一覧\n  Description: 概要\n  Columns: カラム一覧\n  Indexes: INDEX一覧\n  Constraints: 制約一覧\n  Triggers: トリガー\n  Relations: ER図\n  Name: 名前\n  Comment: コメント\n  Type: タイプ\n  Default: デフォルト値\n  Children: 子テーブル\n  Parents: 親テーブル\n  Definition: 定義\n  Table Definition: テーブル定義\n```\n\n### Personalized Templates\n\nIt is possible to provide your own templates to personalize the documentation generated by `tbls` by adding a `templates:` section to your configuration.\nFor example:\n\n```yaml\ntemplates:\n  dot:\n    schema: 'templates/schema.dot.tmpl'\n    table: 'templates/table.dot.tmpl'\n  puml:\n    schema: 'templates/schema.puml.tmpl'\n    table: 'templates/table.puml.tmpl'\n  md:\n    index: 'templates/index.md.tmpl'\n    table: 'templates/table.md.tmpl'\n```\n\nA good starting point to design your own template is to modify a copy the default ones for [Dot](output/dot/templates), [PlantUML](output/plantuml/templates) and [markdown](output/md/templates).\n\n### Required Version\n\nThe `requiredVersion` setting defines a version constraint string. This defines which version of tbls can be used in the configuration.\n\n```yaml\nrequiredVersion: '\u003e= 1.42, \u003c 2'\n```\n\n## Expand environment variables\n\nAll configuration values can be set by expanding the environment variables.\n\n```yaml\n# .tbls.yml\ndsn: my://${MYSQL_USER}:${MYSQL_PASSWORD}@hostname:3306/${MYSQL_DATABASE}\n```\n\n### Viewpoints\nViewpoints of your database schema based on concerns of your domain and add description to them.\nYou can also define groups of tables within viewpoints.\n\n```yaml\n# .tbls.yml\n\nviewpoints:\n  -\n    name: comments on post\n    desc: Users can comment on each post multiple times and put a star on each comment.\n    tables:\n      - users\n      - posts\n      - comments\n      - comment_stars\n      - post_comments\n      - post_comment_stars\n    groups:\n      -\n        name: Comments\n        desc: Tables about comments\n        tables:\n          - posts\n          - comments\n          - post_comments\n      -\n        name: Stars\n        desc: Tables about stars\n        tables:\n          - comment_stars\n          - post_comment_stars\n\n```\n\n## Output formats\n\n`tbls out` output in various formats.\n\n**Markdown:**\n\n```console\n$ tbls out -t md -o schema.md\n```\n\n**DOT:**\n\n```console\n$ tbls out -t dot -o schema.dot\n```\n\n**PlantUML:**\n\n```console\n$ tbls out -t plantuml -o schema.puml\n```\n\n**Mermaid:**\n\n```console\n$ tbls out -t mermaid -o schema.mmd\n```\n\n**Image (svg, png, jpg):**\n\n```console\n$ tbls out -t svg --table users --distance 2 -o users.svg\n```\n\n**JSON:**\n\n```console\n$ tbls out -t json -o schema.json\n```\n\n\u003e **Tips:** `tbls doc` can load `schema.json` as DSN.\n\u003e\n\u003e ```console\n\u003e $ tbls doc json:///path/to/schema.json\n\u003e ```\n\n**YAML:**\n\n```console\n$ tbls out -t yaml -o schema.yaml\n```\n\n**Excel:**\n\n```console\n$ tbls out -t xlsx -o schema.xlsx\n```\n\n**.tbls.yml:**\n\n```console\n$ tbls out -t config -o .tbls.new.yml\n```\n\n## Command arguments\n\ntbls subcommands (`doc`,`diff`, etc) accepts arguments and options\n\n```console\n$ tbls doc my://root:mypass@localhost:3306/testdb doc/schema\n```\n\nYou can check available arguments and options using `tbls help [COMMAND]`.\n\n```console\n$ tbls help doc\n'tbls doc' analyzes a database and generate document in GitHub Friendly Markdown format.\n\nUsage:\n  tbls doc [DSN] [DOC_PATH] [flags]\n\nFlags:\n  -j, --adjust-table       adjust column width of table\n  -b, --base-url string    base url for links\n  -c, --config string      config file path\n  -t, --er-format string   ER diagrams output format (png, svg, jpg, mermaid). default: svg\n  -f, --force              force\n  -h, --help               help for doc\n      --rm-dist            remove files in docPath before generating documents\n      --sort               sort\n      --when string        command execute condition\n      --without-er         no generate ER diagrams\n```\n\n## Output Schema data\n\n`tbls doc` also output schema data (`schema.json`) to same directory as the generated schema document.\n\nTo disable output of schema data, set `disableOutputSchema:` to `true` in `.tbls.yml` file.\n\n## Environment variables\n\ntbls accepts environment variables `TBLS_DSN` and `TBLS_DOC_PATH`\n\n```console\n$ env TBLS_DSN=my://root:mypass@localhost:3306/testdb TBLS_DOC_PATH=doc/schema tbls doc\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fk1low%2Ftbls","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fk1low%2Ftbls","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fk1low%2Ftbls/lists"}