{"id":13707082,"url":"https://github.com/pausan/syncdbdocs","last_synced_at":"2026-04-02T03:02:33.925Z","repository":{"id":57617235,"uuid":"382840967","full_name":"pausan/syncdbdocs","owner":"pausan","description":"syncdbdocs is a tool to help you keep your database documented with a single source of truth","archived":false,"fork":false,"pushed_at":"2022-03-19T07:50:48.000Z","size":136,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-08-12T08:16:40.356Z","etag":null,"topics":["database","documentation","markdown","mysql","postgresql","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":"gpl-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/pausan.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2021-07-04T12:01:15.000Z","updated_at":"2022-05-11T19:49:36.000Z","dependencies_parsed_at":"2022-08-29T05:31:59.935Z","dependency_job_id":null,"html_url":"https://github.com/pausan/syncdbdocs","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/pausan/syncdbdocs","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pausan%2Fsyncdbdocs","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pausan%2Fsyncdbdocs/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pausan%2Fsyncdbdocs/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pausan%2Fsyncdbdocs/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/pausan","download_url":"https://codeload.github.com/pausan/syncdbdocs/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pausan%2Fsyncdbdocs/sbom","scorecard":{"id":723851,"data":{"date":"2025-08-11","repo":{"name":"github.com/pausan/syncdbdocs","commit":"3cbb0bf4fbadc3cc8faf3d6eafbcd21427e75181"},"scorecard":{"version":"v5.2.1-40-gf6ed084d","commit":"f6ed084d17c9236477efd66e5b258b9d4cc7b389"},"score":3.9,"checks":[{"name":"Maintained","score":0,"reason":"0 commit(s) and 0 issue activity found in the last 90 days -- score normalized to 0","details":null,"documentation":{"short":"Determines if the project is \"actively maintained\".","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#maintained"}},{"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":"Code-Review","score":0,"reason":"Found 0/18 approved changesets -- score normalized to 0","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":"Token-Permissions","score":0,"reason":"detected GitHub workflow tokens with excessive permissions","details":["Info: jobLevel 'actions' permission set to 'read': .github/workflows/codeql-analysis.yml:28","Info: jobLevel 'contents' permission set to 'read': .github/workflows/codeql-analysis.yml:29","Warn: no topLevel permission defined: .github/workflows/codeql-analysis.yml:1","Warn: no topLevel permission defined: .github/workflows/run-tests.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":"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":"Packaging","score":-1,"reason":"packaging workflow not detected","details":["Warn: no GitHub/GitLab publishing workflow detected."],"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":10,"reason":"SAST tool detected: CodeQL","details":["Info: SAST configuration detected: CodeQL","Warn: no pull requests merged into dev branch"],"documentation":{"short":"Determines if the project uses static code analysis.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#sast"}},{"name":"Pinned-Dependencies","score":0,"reason":"dependency not pinned by hash detected -- score normalized to 0","details":["Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/codeql-analysis.yml:41: update your workflow using https://app.stepsecurity.io/secureworkflow/pausan/syncdbdocs/codeql-analysis.yml/master?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/codeql-analysis.yml:45: update your workflow using https://app.stepsecurity.io/secureworkflow/pausan/syncdbdocs/codeql-analysis.yml/master?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/codeql-analysis.yml:56: update your workflow using https://app.stepsecurity.io/secureworkflow/pausan/syncdbdocs/codeql-analysis.yml/master?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/codeql-analysis.yml:70: update your workflow using https://app.stepsecurity.io/secureworkflow/pausan/syncdbdocs/codeql-analysis.yml/master?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/run-tests.yml:41: update your workflow using https://app.stepsecurity.io/secureworkflow/pausan/syncdbdocs/run-tests.yml/master?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/run-tests.yml:64: update your workflow using https://app.stepsecurity.io/secureworkflow/pausan/syncdbdocs/run-tests.yml/master?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/run-tests.yml:81: update your workflow using https://app.stepsecurity.io/secureworkflow/pausan/syncdbdocs/run-tests.yml/master?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/run-tests.yml:18: update your workflow using https://app.stepsecurity.io/secureworkflow/pausan/syncdbdocs/run-tests.yml/master?enable=pin","Warn: containerImage not pinned by hash: Dockerfile:4","Warn: containerImage not pinned by hash: Dockerfile:19","Info:   0 out of   8 GitHub-owned GitHubAction dependencies pinned","Info:   0 out of   2 containerImage 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":"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":"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":"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":"License","score":10,"reason":"license file detected","details":["Info: project has a license file: LICENSE:0","Info: FSF or OSI recognized license: GNU General Public License v2.0: 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":"Signed-Releases","score":-1,"reason":"no releases found","details":null,"documentation":{"short":"Determines if the project cryptographically signs release artifacts.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#signed-releases"}},{"name":"Branch-Protection","score":0,"reason":"branch protection not enabled on development/release branches","details":["Warn: branch protection not enabled for branch 'master'"],"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":"Vulnerabilities","score":8,"reason":"2 existing vulnerabilities detected","details":["Warn: Project is vulnerable to: GO-2024-2605 / GHSA-m7wr-2xf7-cm9p","Warn: Project is vulnerable to: GO-2024-2606 / GHSA-mrww-27vc-gghv"],"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-22T12:10:20.558Z","repository_id":57617235,"created_at":"2025-08-22T12:10:20.558Z","updated_at":"2025-08-22T12:10:20.558Z"},"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31294826,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-02T01:43:37.129Z","status":"online","status_checked_at":"2026-04-02T02:00:08.535Z","response_time":89,"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":["database","documentation","markdown","mysql","postgresql","sqlite","sqlserver"],"created_at":"2024-08-02T22:01:18.205Z","updated_at":"2026-04-02T03:02:33.892Z","avatar_url":"https://github.com/pausan.png","language":"Go","funding_links":[],"categories":["Go"],"sub_categories":[],"readme":"# syncdbdocs\n\nsyncdbdocs is a tool to help you keep your database documented with a single\nsource of truth\n\n## Problem to solve\n\nWhile not in SQL standard, widely used databases have a way of commenting\ntables and fields, althought it is usually very limited and cumbersome.\n\nThis project aims to provide a simple command to generate a textual representation\n(in txt, markdown or dbml) of the database structure and be able to comment on it\nand keep the documentation updated easily.\n\nThe original intend was to be able to sync back the documentation onto the\ndatabase, and while still possible and probably not hard to do, I've decided\nthat synching comments back to the database is not worth it due to the \ndifferent constraints of some databases of limiting comment length and/or\ncomment availability altogether.\n\nIt is probably far more useful to preserve the documentation in textual form\nand have a simple way of updating the document to include the new fields being\nadded.\n\nField order and table order will be preserved if you decide to reuse an\nexisting text or markdown file. New columns, tables and schemas from the database\nwill be appended in alphabetical order. Items that no longer exist will be marked\nas deleted.\n\nIt is encouraged that you run this command automatically from your build after\nmigrating database schema and commit the resulting file.\n\n## Installation\n\n    $ go get github.com/pausan/syncdbdocs\n\nor use docker\n\n    $ docker pull pausan/syncdbdocs\n\n## How to use\n\n### Short version (TLDR)\n\nFirst generate a document from scratch like this:\n\n    $ syncdbdocs -t pg -h 127.0.0.1 -u user -d dbname -o pg_dbname.txt\n\nUpdate documentation comments as you wish and then update database schema by\nrunning the following command:\n\n    $ syncdbdocs -t pg -h 127.0.0.1 -u user -d dbname -io pg_dbname.txt\n\nYou won't lose the editions of any of the existing schemas/tables/fields, but\nif a schema/table/field is deleted from the database, it will be deleted from\nthe document (also renames).\n\nIt is encourage that you commit the documentation on your control version system\nof choice.\n\n### Docker Image\n\nA tiny docker image is available so you can use it if you won't want to install\nwith go or you don't have a go compiler available.\n\nYou can use it like this:\n\n    $ docker run pausan/syncdbdocs -t pg -h 127.0.0.1 -u user -d dbname -io pg_dbname.txt\n\n### Long version\n\nFor now only commands to sync from the database to the file are provided\nmarkdown and dbml documentation from those comments from the database\nin order to keep a local textual representation of the schema.\n\nRun the program once to generate the first version of the documentation, and,\nin case there are no documented columns or tables or schema in the database\na document with the structure will be generated.\n\nPlease set DB_PASSWORD environment variable before running the command, and\nselect the database type with -t (or don't and it will try all drivers).\n\nExample of initial import for all database types supported:\n\n    $ syncdbdocs -t pg     -h 127.0.0.1 -u user -d dbname -o pg_dbname.txt\n    $ syncdbdocs -t mysql  -h 127.0.0.1 -u user -d dbname -o mysql_dbname.txt\n    $ syncdbdocs -t mssql  -h 127.0.0.1 -u user -d dbname -o mssql_dbname.txt\n    $ syncdbdocs -t sqlite -h sqlite_file.db    -d dbname -o sqlite_dbname.txt\n\nThe command will write to stdout if no output file is provided.\n\nTo update the file after making some changes to the structure of the database\n(eg adding tables or removing or renaming columns):\n\n    $ syncdbdocs -t pg -h 127.0.0.1 -u user -d dbname -i pg_dbname.txt -o pg_dbname.txt\n\nor:\n\n    $ syncdbdocs -t pg -h 127.0.0.1 -u user -d dbname -io pg_dbname.txt\n\nIf you'd like to generate a markdown file or dbml instead use -format:\n\n    $ syncdbdocs -t pg -h 127.0.0.1 -u user -d dbname -format markdown -o pg_dbname.md\n    $ syncdbdocs -t pg -h 127.0.0.1 -u user -d dbname -format dbml -o pg_dbname.dbml\n\nIf you want to check out more parameters, just run with -h or -help.\n\n## Formats\n\nPlain **text** files, **markdown** and **dbml** are the supported formats.\n\nMarkdown and text files include all comments and some extra information (like data types),\nwhile dbml is only provided to have a quick glance at the structure of the data.\n\n## Databases\n\npostgres, mysql and mssql are supported. Right now only reading comments\nand updating text/md files from database definitions is supported.\n\nIt should be easy to extend to other databases.\n\n### PostgreSQL\n\n- Read db definitions\n- Update text/markdown from db\n- Keep non-empty comments in the file if db has empty comments\n- Tested with postgres 9.x, 10.x, 11.x and 12.x\n\n### MySQL\n\n- Read db definitions\n- Update text/markdown from db\n- Keep non-empty comments in the file if db has empty comments\n- Tested with mysql v8.x\n\nNote for the future: when updating db from text files, we should be careful\nsince MySQL requires us to modify the whole column definition just to add\na comment. We can screw up data. Probably best way to proceed to avoid errors\nis to create a temporary table, apply the definition there, and compare, if\nthings look the same, then we can safely apply the same alter table to the\noriginal definition. Better to stay on the cautious side.\nUse DESCRIBE, SHOW COLUMNS or SHOW CREATE TABLE.\n\n### MS SQL Server\n\n- Read db definitions\n- Update text/markdown from db\n- Keep non-empty comments in the file if db has empty comments\n- Tested with sql server 2017 and 2019\n\n### SQLite\n\nThis database does not support comments, but this tool supports pulling the\ndatabase structure from it to update a comment file.\n\n- Read db definitions\n- Update text/markdown from db\n- Tested with sqlite 3.x\n\n## Project Status\n\nFollowing there is a list of main features and whether or not they are supported.\n\nSupported features:\n\n- Support for postgres, mysql, mssql and sqlite\n- Generate/update markdown documentation\n- Generate/update text documentation\n- Generate DBMLish file (not standard, just to have a rough view of the structure)\n- Update text \u0026 markdown from database without changing tables or field order\n\nMissing features:\n\n- Update database back from file comments\n- Support for other databases: oracle, ...\n- Generate nicer HTML output (from text or database)\n- Detect primary keys, indexes, triggers or functions\n\n## License\n\nThis software uses GPL v2 license, you can read it fully in LICENSE file.\n\n    Copyright (C) 2021 Pau Sanchez\n\n    This program is free software; you can redistribute it and/or modify\n    it under the terms of the GNU General Public License as published by\n    the Free Software Foundation; either version 2 of the License, or\n    (at your option) any later version.\n\n    This program is distributed in the hope that it will be useful,\n    but WITHOUT ANY WARRANTY; without even the implied warranty of\n    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the\n    GNU General Public License for more details.\n\n    You should have received a copy of the GNU General Public License along\n    with this program; if not, write to the Free Software Foundation, Inc.,\n    51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpausan%2Fsyncdbdocs","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpausan%2Fsyncdbdocs","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpausan%2Fsyncdbdocs/lists"}