{"id":37064129,"url":"https://github.com/foliant-docs/foliantcontrib.dbdoc","last_synced_at":"2026-01-14T07:29:40.359Z","repository":{"id":92058814,"uuid":"268745086","full_name":"foliant-docs/foliantcontrib.dbdoc","owner":"foliant-docs","description":"Database documentation generator for Foliant","archived":false,"fork":false,"pushed_at":"2025-09-29T11:33:21.000Z","size":384,"stargazers_count":7,"open_issues_count":1,"forks_count":2,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-09-29T13:25:34.974Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","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/foliant-docs.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}},"created_at":"2020-06-02T08:31:55.000Z","updated_at":"2025-09-18T08:33:43.000Z","dependencies_parsed_at":null,"dependency_job_id":"feffb0f2-1573-4083-b175-2057b660b2a8","html_url":"https://github.com/foliant-docs/foliantcontrib.dbdoc","commit_stats":null,"previous_names":[],"tags_count":9,"template":false,"template_full_name":null,"purl":"pkg:github/foliant-docs/foliantcontrib.dbdoc","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/foliant-docs%2Ffoliantcontrib.dbdoc","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/foliant-docs%2Ffoliantcontrib.dbdoc/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/foliant-docs%2Ffoliantcontrib.dbdoc/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/foliant-docs%2Ffoliantcontrib.dbdoc/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/foliant-docs","download_url":"https://codeload.github.com/foliant-docs/foliantcontrib.dbdoc/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/foliant-docs%2Ffoliantcontrib.dbdoc/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28413261,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-14T05:26:33.345Z","status":"ssl_error","status_checked_at":"2026-01-14T05:21:57.251Z","response_time":107,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"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":[],"created_at":"2026-01-14T07:29:39.811Z","updated_at":"2026-01-14T07:29:40.348Z","avatar_url":"https://github.com/foliant-docs.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"[![](https://img.shields.io/pypi/v/foliantcontrib.dbdoc.svg)](https://pypi.org/project/foliantcontrib.dbdoc/)  [![](https://img.shields.io/github/v/tag/foliant-docs/foliantcontrib.dbdoc.svg?label=GitHub)](https://github.com/foliant-docs/foliantcontrib.dbdoc)\n\n# Database Documentation Generator for Foliant\n\n![](https://raw.githubusercontent.com/foliant-docs/foliantcontrib.dbdoc/master/img/dbdoc.png)\n\n*Static site on the picture was built with [Slate](https://foliant-docs.github.io/docs/backends/slate/) backend together with DBDoc preprocessor*\n\nThis preprocessor generates simple documentation based on the structure of the database. It uses [Jinja2](http://jinja.pocoo.org/) templating engine for customizing the layout and [PlantUML](http://plantuml.com/) for drawing the database scheme.\n\nCurrently supported databases:\n\n* **PostgreSQL**,\n* **Oracle**,\n* **Microsoft SQL Server**,\n* **MySQL**.\n\n\u003e **Important Notice**: We, here at Foliant, don't work with *all* of the databases mentioned above. That's why we cannot thoroughly test the preprocessor's work with all of them. That's where we need your help: If you encounter *any* errors during build; if you are not getting enough information for your document in the template; if you can't make the filters work; or if you see any other anomaly, please [send us an issue](https://github.com/foliant-docs/foliantcontrib.dbdoc/issues) in GitHub. We will try to fix it as fast as we can. Thanks!\n\n## Installation\n\n### Prerequisites\n\nDBDoc generates documentation by querying database structure. That's why you will need client libraries and their Python connectors installed on your computer before running the preprocessor.\n\n**PostgreSQL**\n\nTo install PostgreSQL simply run\n\n```bash\n$ pip3 install psycopg2-binary\n```\n\n**Oracle**\n\nOracle libraries are proprietary, so we cannot include them even in our [Docker distribution](https://hub.docker.com/r/foliant/foliant/tags). So if you are planning on using DBDoc to document Oracle databases, first install the [Instant Client](https://www.oracle.com/database/technologies/instant-client.html).\n\n\u003e If you search the web, you can find ways to install Oracle Instant Client inside your Docker image, just saying.\n\nNext install the Python connector for Oracle database\n\n```bash\n$ pip3 install cx_Oracle\n```\n\n**Microsoft SQL Server**\n\nOn Windows you will need to install MS SQL Server.\n\nOn Unix you will first need to install [unixODBC](http://www.unixodbc.org/), and then — the ODBC driver. Microsoft has a detailed instructions on how to install the driver [on Linux](https://docs.microsoft.com/en-us/sql/connect/odbc/linux-mac/installing-the-microsoft-odbc-driver-for-sql-server) and [on Mac](https://docs.microsoft.com/en-us/sql/connect/odbc/linux-mac/install-microsoft-odbc-driver-sql-server-macos).\n\nInstall the Python connector for Microsoft SQL Server database\n\n```bash\n$ pip3 install pyodbc\n```\n\n**MySQL**\n\nOn Mac you can simply run\n\n```bash\n$ brew install mysql\n```\n\nOn Linux you will have to install server and client packages, for example, with apt-get\n\n```bash\nsudo apt-get update\nsudo apt-get install -y mysql-server libmysqlclient-dev\n```\n\nFinally, install the Python connector for Microsoft SQL Server database\n\n```bash\n$ pip3 install mysqlclient\n```\n\n### Preprocessor\n\n```bash\n$ pip install foliantcontrib.dbdoc\n```\n\n## Config\n\nTo enable the preprocessor, add `dbdoc` to `preprocessors` section in the project config:\n\n```yaml\npreprocessors:\n    - dbdoc\n```\n\nThe preprocessor has a number of options:\n\n```yaml\npreprocessors:\n    - dbdoc:\n        dbms: pgsql\n        host: localhost\n        port: 5432\n        dbname: postgres\n        user: postgres\n        password: !env DBDOC_PASS\n        doc: True\n        scheme: True\n        strict: False\n        trusted_connection: False\n        filters:\n            ...\n        doc_template: dbdoc.j2\n        scheme_template: scheme.j2\n        components:\n          - tables\n          - functions\n          - triggers\n        driver: '{ODBC Driver 17 for SQL Server}'\n```\n\n`dbms`\n:   Name of the DBMS. Should be one of: `pgsql`, `oracle`, `sqlserver`, `mysql`. Only needed if you are using `\u003cdbdoc\u003e` tag. If you are using explicit tags (`\u003coracle\u003e`, `\u003cpgsql\u003e`), this parameter is ignored.\n\n`host`\n:   Database host address. Default: `localhost`\n\n`port`\n:   Database port. Default: `5432` for pgsql, `1521` for Oracle, `1433` for MS SQL, `3306` for MySQL.\n\n`dbname`\n:   Database name. Default: `postgres` for pgsql, `orcl` for oracle, `mssql` for MS SQL, `mysql` for MySQL.\n\n`user`\n:   Database user name. Default: `postgres` for pgsql, `hr` for oracle, `SA` for MS SQL, `root` for MySQL.\n\n`password`\n:   Database user password. Default: `postgres` for pgsql, `oracle` for oracle, `\u003cYourStrong@Passw0rd\u003e` for MS SQL, `passwd` for MySQL.\n\n\u003e It is not secure to store plain text passwords in your config files. We recommend to use [environment variables](https://foliant-docs.github.io/docs/config/#env) to supply passwords\n\n`doc`\n:   If `true` — documentation will be generated. Set to `false` if you only want to draw a scheme of the database. Default: `true`\n\n`scheme`\n:   If `true` — the platuml code for database scheme will be generated. Default: `true`\n\n`strict`\n:   If `true` — the build will fail if connection to database cannot be established. If `false` — the preprocessor will skip the tag with warning. Default: `false`\n\n`trusted_connection`\n:   Specific option for MS SQL Server. If true - will use Windows Authentication (Trusted Connection) instead of username/password. Default: false. Requires proper ODBC driver configuration.\n\n`filters`\n:   SQL-like operators for filtering the results. More info in the **Filters** section.\n\n`doc_template`\n:   Path to jinja-template for documentation. Path is relative to the project directory. If not supplied — default template would be used.\n\n`scheme_template`\n:   Path to jinja-template for scheme. Path is relative to the project directory. If not supplied — default template would be used.\n\n`components`\n:   List of components to be added to documentation. If not supplied — everything will be added. Use to exclude some parts of documentation. Available components: `'tables'`, `'views'`, `'functions'`, `'triggers'`.\n\n`driver`\n:   Specific option for MS SQL Server database. Defines the driver connection string. Default: `{ODBC Driver 17 for SQL Server}`.\n\n## Usage\n\nDBDoc currently supports four database engines: Oracle, PostgreSQL, MySQL and Microsoft SQL Server. To generate Oracle database documentation, add an `\u003coracle\u003e\u003c/oracle\u003e` tag to a desired place of your chapter.\n\n\n```html\n# Introduction\n\nThis document contains the most awesome automatically generated documentation of our marvellous Oracle database.\n\n\u003coracle\u003e\u003c/oracle\u003e\n```\n\nTo generate PostgreSQL database documentation, add a `\u003cpgsql\u003e\u003c/pgsql\u003e` tag to a desired place of your chapter.\n\n\n```html\n# Introduction\n\nThis document contains the most awesome automatically generated documentation of our marvellous Oracle database.\n\n\u003cpgsql\u003e\u003c/pgsql\u003e\n```\n\nTo generate MySQL database documentation, add a `\u003cmysql\u003e\u003c/mysql\u003e` tag to a desired place of your chapter.\n\n\n```html\n# Introduction\n\nThis document contains the most awesome automatically generated documentation of our marvellous SQL Server database.\n\n\u003cmysql\u003e\u003c/mysql\u003e\n```\n\nTo generate SQL Server database documentation, add a `\u003csqlserver\u003e\u003c/sqlserver\u003e` tag to a desired place of your chapter.\n\n\n```html\n# Introduction\n\nThis document contains the most awesome automatically generated documentation of our marvellous SQL Server database.\n\n\u003csqlserver\u003e\u003c/sqlserver\u003e\n```\n\nEach time the preprocessor encounters one of the mentioned tags, it inserts the whole generated documentation text instead of it. The connection parameters are taken from the config-file.\n\nYou can also specify some parameters (or all of them) in the tag options:\n\n```html\n# Introduction\n\nIntroduction text for database documentation.\n\n\u003coracle scheme=\"true\"\n        doc=\"false\"\n        host=\"11.51.126.8\"\n        port=\"1521\"\n        dbname=\"mydb\"\n        user=\"scott\"\n        password=\"tiger\"\u003e\n\u003c/oracle\u003e\n```\n\nTag parameters have the highest priority.\n\nThis way you can have documentation for several different databases in one foliant project (even in one md-file if you like it so). It also allows you to put documentation and scheme for you database separately by switching on/off `doc` and `scheme` params in tags.\n\n## Filters\n\nYou can add filters to exclude some tables from the documentation. dbdocs supports several SQL-like filtering operators and a determined list of filtering fields.\n\nYou can switch on filters either in foliant.yml file like this:\n\n```yaml\npreprocessors:\n  - dbdoc:\n    filters:\n      eq:\n        schema: public\n      regex:\n        table_name: 'main_.+'\n```\n\nor in tag options using the same yaml-syntax:\n\n```html\n\n\u003cpgsql filters=\"\n  eq:\n    schema: public\n  regex:\n    table_name: 'main_.+'\"\u003e\n\u003c/pgsql\u003e\n\n```\n\nList of currently supported operators:\n\noperator | SQL equivalent | description | value\n-------- | -------------- | ----------- | -----\n`eq` | `=` | equals | literal\n`not_eq` | `!=` | does not equal | literal\n`in` | `IN` | contains | list\n`not_in` | `NOT IN` | does not contain | list\n`regex` | `~`, `REGEX_LIKE` | matches regular expression | literal\n`not_regex` | `!~`, `NOT REGEX_LIKE` | does not match regular expression | literal\n\n\u003e Note: `regex` and `not_regex` are not supported with Microsoft SQL Server DBMS.\n\nList of currently supported filtering fields:\n\nfield | description\n----- | -----------\nschema | filter by database schema\ntable_name | filter by database table names\n\nThe syntax for using filters in configuration files is following:\n\n```yaml\nfilters:\n  \u003coperator\u003e:\n    \u003cfield\u003e: value\n```\n\nIf `value` should be list like for `in` operator, use YAML-lists instead:\n\n```yaml\nfilters:\n  in:\n    schema:\n      - public\n      - corp\n```\n\n## About Templates\n\nThe structure of generated documentation is defined by jinja-templates. You can choose what elements will appear in the documentation, change their positions, add constant text, change layouts and more. Check the [Jinja documentation](http://jinja.pocoo.org/docs/2.10/templates/) for info on all cool things you can do with templates.\n\nIf you don't specify path to templates in the config-file and tag-options dbdoc will use default templates.\n\nIf you wish to create your own template, the default ones may be a good starting point.\n\n* [Default **Oracle doc** template.](https://github.com/foliant-docs/foliantcontrib.dbdoc/blob/master/foliant/preprocessors/dbdoc/oracle/templates/doc.j2)\n* [Default **Oracle scheme** template.](https://github.com/foliant-docs/foliantcontrib.dbdoc/blob/master/foliant/preprocessors/dbdoc/oracle/templates/scheme.j2)\n* [Default **PostgreSQL doc** template.](https://github.com/foliant-docs/foliantcontrib.dbdoc/blob/master/foliant/preprocessors/dbdoc/pgsql/templates/doc.j2)\n* [Default **PostgreSQL scheme** template.](https://github.com/foliant-docs/foliantcontrib.dbdoc/blob/master/foliant/preprocessors/dbdoc/pgsql/templates/doc.j2)\n* [Default **MySQL doc** template.](https://github.com/foliant-docs/foliantcontrib.dbdoc/blob/master/foliant/preprocessors/dbdoc/mysql/templates/doc.j2)\n* [Default **MySQL scheme** template.](https://github.com/foliant-docs/foliantcontrib.dbdoc/blob/master/foliant/preprocessors/dbdoc/mysql/templates/doc.j2)\n* [Default **SQL Server doc** template.](https://github.com/foliant-docs/foliantcontrib.dbdoc/blob/master/foliant/preprocessors/dbdoc/mssql/templates/doc.j2)\n* [Default **SQL Server scheme** template.](https://github.com/foliant-docs/foliantcontrib.dbdoc/blob/master/foliant/preprocessors/dbdoc/mssql/templates/doc.j2)\n\n## Tests\n\nFor run tests, use:\n```bash\n./test_in_docker.sh --python-version \"3.9\" --db-type \"mysql\"\n```\n\n**Options:**\n`--python-version \u003cpython-version\u003e` – Specifies Python version for test environment. Available_: 3.8, 3.9, 3.10 etc.\n\n`--db-type \u003cdb-type\u003e` – Chooses database type for testing. Available_: mysql, pgsql.\n\n**Usage Examples**\n\n```bash\n# Basic usage with defaults\n./test_in_docker.sh\n\n# Specific Python and database\n./test_in_docker.sh --python-version \"3.10\" --db-type \"pgsql\"\n\n# Only change database type\n./test_in_docker.sh --db-type \"mysql\"\n\n# Only change Python version\n./test_in_docker.sh --python-version \"3.9\"\n```\n\n**What It Does:**\n1. Starts Docker container with specified Python version.\n2. Initializes chosen database type with test data.\n3. Runs test suite.\n4. Cleans up resources after completion.\n5. Returns exit code based on test results.\n\n**Notes**\n- Requires Docker installed;\n- Test data is automatically loaded from `test_data/` directory;\n- Results are displayed in console with color formatting;\n- Exit code 0 = success, 1 = test failures.\n\n## Troubleshooting\n\nIf you get errors during build, especially errors concerning connection to the database, you have to make sure that you are supplying the right parameters.\n\nThere may be a lot of possible causes for errors. For example, MS SQL Server may fail to connect to local database if you specify host as `localhost`, you have to explicitly write `0.0.0.0` or `127.0.0.1`.\n\nSo your first action to root the source of your errors should be running a python console and trying to connect to your database manually.\n\nHere are sample snippets on how to connect to different databases.\n\n**PostgreSQL**\n\n[psycopg2](https://pypi.org/project/psycopg2/) library is required.\n\n```python\nimport psycopg2\n\ncon = psycopg2.connect(\n      \"host=localhost \"\n      \"port=5432 \"\n      \"dbname=MyDatabase \"\n      \"user=postgres\"\n      \"password=postgres\"\n)\n```\n\n**Oracle**\n\n[cx_Oracle](https://oracle.github.io/python-cx_Oracle/) library is required.\n\n```python\nimport cx_Oracle\n\ncon = cx_Oracle.connect(\n    \"Scott/Tiger@localhost:1521/MyDatabase\"\n    encoding='UTF-8',\n    nencoding='UTF-8'\n)\n```\n\n**MySQL**\n\n[mysqlclient](https://pypi.org/project/mysqlclient/) library is required.\n\n```python\nfrom MySQLdb import _mysql\n\ncon = _mysql.connect(\n        host='localhost',\n        port=3306,\n        user='root',\n        passwd='password',\n        db='MyDatabase'\n    )\n```\n\n**Microsoft SQL Server**\n\n[pyodbc](https://pypi.org/project/pyodbc/) library is required.\n\n```python\nimport pyodbc\n\ncon = pyodbc.connect(\n    \"DRIVER={ODBC Driver 17 for SQL Server};\"\n    \"SERVER=0.0.0.0,1433;\"\n    \"DATABASE=MyDatabase;\"\n    \"UID=Usernam;PWD=Password_0\"\n)\n```\n\n**Microsoft SQL Server Authentication Issues**\n\nWhen using MS SQL Server, you have two authentication options:\n\n1. SQL Server Authentication (username/password):\n\n    ```yaml\n    trusted_connection: false\n    user: your_username\n    password: your_password\n    ```\n\n2. Windows Authentication (Trusted Connection):\n\n    ```yaml\n    trusted_connection: true\n    # no user/password needed\n    ```\n\nFor Windows Authentication to work:\n\n- Make sure your ODBC driver supports Trusted Connections.\n- The account running Foliant must have proper database permissions.\n- On Linux/Mac, you may need to configure Kerberos for cross-platform authentication.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffoliant-docs%2Ffoliantcontrib.dbdoc","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffoliant-docs%2Ffoliantcontrib.dbdoc","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffoliant-docs%2Ffoliantcontrib.dbdoc/lists"}