{"id":13466833,"url":"https://github.com/k1LoW/tbls","last_synced_at":"2025-03-26T00:31:34.310Z","repository":{"id":37246954,"uuid":"133827809","full_name":"k1LoW/tbls","owner":"k1LoW","description":"tbls is a CI-Friendly tool for document a database, written in Go.","archived":false,"fork":false,"pushed_at":"2024-10-25T13:56:57.000Z","size":130632,"stargazers_count":3472,"open_issues_count":30,"forks_count":167,"subscribers_count":23,"default_branch":"main","last_synced_at":"2024-10-29T14:51:34.707Z","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},"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":"2024-10-29T12:32:42.000Z","dependencies_parsed_at":"2023-12-19T05:15:41.457Z","dependency_job_id":"0ee32dbf-7654-4287-8cec-2cba8c07d9e3","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":201,"template":false,"template_full_name":null,"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","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":245543426,"owners_count":20632648,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","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-07-31T15:00:50.568Z","updated_at":"2025-03-26T00:31:34.297Z","avatar_url":"https://github.com/k1LoW.png","language":"Go","funding_links":["https://github.com/sponsors/k1LoW"],"categories":["Go","开源类库","Database","Open source library","continuous-integration","sqlite","The AWESOME list","Schema"],"sub_categories":["持续集成/部署","Continuous Integration/Delivery","Database","Documentations"],"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 k1LoW/tap/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**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 from include\n2. Remove tables 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). 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\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"}