{"id":14063316,"url":"https://github.com/cavo789/db_documentor","last_synced_at":"2026-04-29T03:31:59.949Z","repository":{"id":101354580,"uuid":"171243366","full_name":"cavo789/db_documentor","owner":"cavo789","description":"This script will establish a connection to a MySQL database, retrieve all tables and document them by creating `.csv`, `.md` and `.sql` files. If you're using [Marknotes](https://github.com/cavo789/marknotes), it'll also create the full documentation folder for Marknotes.","archived":false,"fork":false,"pushed_at":"2021-11-01T21:30:19.000Z","size":645,"stargazers_count":3,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-12-31T21:44:11.243Z","etag":null,"topics":["documentation-generator","markdown","marknotes","mysqli","wiki"],"latest_commit_sha":null,"homepage":null,"language":"PHP","has_issues":false,"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/cavo789.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,"governance":null,"roadmap":null,"authors":null,"dei":null}},"created_at":"2019-02-18T08:24:24.000Z","updated_at":"2025-10-06T09:26:54.000Z","dependencies_parsed_at":"2023-03-12T11:30:47.529Z","dependency_job_id":null,"html_url":"https://github.com/cavo789/db_documentor","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/cavo789/db_documentor","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cavo789%2Fdb_documentor","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cavo789%2Fdb_documentor/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cavo789%2Fdb_documentor/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cavo789%2Fdb_documentor/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/cavo789","download_url":"https://codeload.github.com/cavo789/db_documentor/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cavo789%2Fdb_documentor/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32409086,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-29T02:37:21.628Z","status":"ssl_error","status_checked_at":"2026-04-29T02:36:50.947Z","response_time":110,"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":["documentation-generator","markdown","marknotes","mysqli","wiki"],"created_at":"2024-08-13T07:03:16.137Z","updated_at":"2026-04-29T03:31:59.922Z","avatar_url":"https://github.com/cavo789.png","language":"PHP","funding_links":[],"categories":["PHP"],"sub_categories":[],"readme":"# DB Documentor\n\n![Banner](imag.es/banner.svg)\n\n\u003e This script will establish a connection to a MySQL database, retrieve all tables and document them by creating `.csv`, `.md` and `.sql` files. If you're using [Marknotes](https://github.com/cavo789/marknotes), it'll also create the full documentation folder for Marknotes.\n\n- [Description](#description)\n- [Install](#install)\n- [Configuration](#configuration)\n- [Usage](#usage)\n- [Hints](#hints)\n  - [Marknotes](#marknotes)\n  - [Laravel](#laravel)\n- [Author](#author)\n- [License](#license)\n\n## Description\n\nTable by table documentation will be generated:\n\n- a .csv file with the first xxx records of the table\n- a .sql file with a simple SELECT statement on that table\n- a \\_connection.md file with the info needed for establishing a connection\n  on the database\n- a \\_description.md file with the description of the table\n- a \\_structure.md file with a markdown table and will display the structure of the table (fieldname, type and comments if any)\n\nIf create_marknotes setting is set to True, additional .md files will be created:\n\n- a .md file for the documentation of the database itself\n- one .md file by table.\n\nThese two additional files will use a template defined in the settings.json file, under\nmarknotes-\u003etemplates. Please refers to the marknotes documentation to learn more on that tool.\n\n@see https://github.com/cavo789/marknotes\n\n## Install\n\n1. Get a copy of `DB_Documentor.php` (or download/clone the repository) and store the script on your localhost website;\n2. Copy the `settings.json.dist` and name the name file `settings.json`;\n3. Edit `settings.json` and edit the file (DB name, host, user, ...) so the setting fit your needs;\n\n## Configuration\n\nAll the configuration is done in a file called `settings.json`. If the file isn't present, please copy `settings.json.dist` and name the new file `settings.json`.\n\nThen edit the file so you can customize how the script works.\n\nBelow the content of the file:\n\n````json\n{\n  \"databases\": [\n    {\n      \"host\": \"localhost\",\n      \"name\": \"your-db-name\",\n      \"user\": \"root\",\n      \"password\": \"\",\n      \"prefix\": \"\",\n      \"type\": \"mysqli\",\n      \"output\": {\n        \"folder\": \"C:\\\\temp\\\\db-documentation\",\n        \"url\": \"\"\n      }\n    }\n  ],\n  \"config\": {\n    \"create_csv\": 1,\n    \"create_marknotes\": 1,\n    \"create_md\": 1,\n    \"create_sql\": 1,\n    \"csv_separator\": \";\",\n    \"get_credentials\": 1,\n    \"get_detail\": 1,\n    \"maxrows\": 5,\n    \"timeformat\": \"d/m/Y H:i:s\",\n    \"timezone\": \"Europe/Brussels\"\n  },\n  \"marknotes\": {\n    \"templates\": {\n      \"database\": [\n        \"# Database @@DB_NAME@@\",\n        \"\",\n        \"%TOC_6%\",\n        \"\",\n        \"## Connection information\",\n        \"\",\n        \"%INCLUDE tables/.files/@@DB_NAME@@_connection.md%\",\n        \"\",\n        \"## Summary of tables\",\n        \"\",\n        \"%CSV tables/.files/@@DB_NAME@@_tables.csv%\",\n        \"\",\n        \"## List of tables\",\n        \"\",\n        \"%INCLUDE tables/*.md%\"\n      ],\n      \"table\": [\n        \"# @@TABLE_NAME@@\",\n        \"\",\n        \"%INCLUDE .files/@@TABLE_NAME@@_description.md%\",\n        \"\",\n        \"%INCLUDE .files/@@TABLE_NAME@@_custom.md%\",\n        \"\",\n        \"## SQL\",\n        \"\",\n        \"```sql\",\n        \"%INCLUDE .files/@@TABLE_NAME@@.sql%\",\n        \"```\",\n        \"\",\n        \"## Fields\",\n        \"\",\n        \"%INCLUDE .files/@@TABLE_NAME@@_structure.md%\",\n        \"\",\n        \"## Samples\",\n        \"\",\n        \"%CSV .files/@@TABLE_NAME@@.csv%\"\n      ]\n    }\n  }\n}\n````\n\n### databases\n\nThis is where you'll define the databases that you want to document, you can have more than one f.i.\n\n```json\n\"databases\": [\n        {\n            \"name\": \"DB1\",\n            ...\n        },\n        {\n            \"name\": \"DB2\",\n            ...\n        },\n        {\n            \"name\": \"DB3\",\n            ...\n        }\n    ]\n}\n```\n\n_(simplified example)_\n\nA database should contain at least the following information:\n\n- `host`: the name of the database server (`localhost` the most of time);\n- `name`: name of the database. That name will appear in the interface;\n- `user`: the name of the user to use to get access to the database (`root` the most of time on a local webserver);\n- `password`: password for that user;\n- `prefix`: if your tables have a prefix, please specify the prefix here;\n- `type`: the database type (`mysqli` the most of time);\n\nThen you'll have an `output` entry with two items:\n\n- `add_custom_files`: 0 or 1 - create a `xxx_custom.md` (where `xxx` is a table name) file for each table with an empty content. That file will be created **only** if the file isn't yet present so the documentation maintainer can add extra comments in that custom file and generate again and again new documentation; the `xxx_custom.md` won't never be modified by code; just created if missing;\n- `folder`: the full name to the folder where to store files generated by the script;\n- `url`: when the output has been successfully done, DB Documentor can display a link `Click here to see the documentation online`. If you want this, just specifiy your documentation URL here f.i. `http://localhost:8080/yourdoc/index.html` (very useful when using Marknotes).\n\n```json\n{\n  \"host\": \"localhost\",\n  \"name\": \"your-db-name\",\n  \"user\": \"root\",\n  \"password\": \"\",\n  \"prefix\": \"\",\n  \"type\": \"mysqli\",\n  \"output\": {\n    \"add_custom_files\": 1,\n    \"folder\": \"C:\\\\temp\\\\db-documentation\",\n    \"url\": \"\"\n  }\n}\n```\n\n### config\n\nConfiguration options:\n\n- `create_csv`: 0 or 1 - Does this script should generate .csv files?;\n- `create_marknotes`: 0 or 1 - Does this script should generate files for marknotes?;\n- `create_md`: 0 or 1 - Does this script should generate .md files?;\n- `create_sql`: 0 or 1 - Does this script should generate .sql files?;\n- `csv_separator`: Define the separator to use for CSV files, Default is \";\";\n- `get_credentials`: 0 or 1 - Does the documentation should include the credentials of the database?;\n- `get_detail`: 0 or 1 - Does the documentation should include one documentation by table?;\n- `maxrows`: Number of rows to show in the table samples;\n- `timeformat`: Format for displaying date/time, Default; if not specified, will be Y-m-d h:i:s a;\n- `timezone`: Needed to correctly display date/time, Default will be retrieved from the server's default.\n\n```json\n\"config\": {\n    \"create_csv\": 1,\n    \"create_marknotes\": 1,\n    \"create_md\": 1,\n    \"create_sql\": 1,\n    \"csv_separator\": \";\",\n    \"get_credentials\": 1,\n    \"get_detail\": 1,\n    \"maxrows\": 5,\n    \"timeformat\": \"d/m/Y H:i:s\",\n    \"timezone\": \"Europe/Brussels\"\n}\n```\n\n### marknotes\n\nWhen the `create_marknotes` option is set to `1` in the `config` node, generated files will be create in such way that [Marknotes](https://github.com/cavo789/marknotes) will display them easily.\n\nMarknotes documentation will be:\n\n- One markdown file (`.md` extension) with the documentation of the database and\n- One markdown file for each table in the database.\n\nBoth these files will be created by using a template. The `marknotes` node in the `settings.json` file deserves that purpose.\n\n````json\n\"marknotes\": {\n    \"templates\": {\n        \"database\": [\n            \"# Database @@DB_NAME@@\",\n            \"\",\n            \"%TOC_6%\",\n            \"\",\n            \"## Connection information\",\n            \"\",\n            \"%INCLUDE tables/.files/@@DB_NAME@@_connection.md%\",\n            \"\",\n            \"## Summary of tables\",\n            \"\",\n            \"%CSV tables/.files/@@DB_NAME@@_tables.csv%\",\n            \"\",\n            \"## List of tables\",\n            \"\",\n            \"%INCLUDE tables/*.md%\"\n        ],\n        \"table\": [\n            \"# @@TABLE_NAME@@\",\n            \"\",\n            \"%INCLUDE .files/@@TABLE_NAME@@_description.md%\",\n            \"\",\n            \"%INCLUDE .files/@@TABLE_NAME@@_custom.md%\",\n            \"\",\n            \"## SQL\",\n            \"\",\n            \"```sql\",\n            \"%INCLUDE .files/@@TABLE_NAME@@.sql%\",\n            \"```\",\n            \"\",\n            \"## Fields\",\n            \"\",\n            \"%INCLUDE .files/@@TABLE_NAME@@_structure.md%\",\n            \"\",\n            \"## Samples\",\n            \"\",\n            \"%CSV .files/@@TABLE_NAME@@.csv%\"\n        ]\n    }\n}\n````\n\n## Usage\n\nOnce your changes have been made in the `settings.json` file, just go to your web interface (f.i. `http://localhost/doc/DB_Documentor.php`) and run it.\n\nYou'll get a form with a selection box: the list of databases will be displayed and simply select the database for which you want to generate the documentation.\n\nAs soon as a database name is selected, the program will start and after a few seconds, files will be created on your disk. Where? Please see the `output` folder in your `settings.json` file.\n\nYou can define one `output` folder by databases.\n\n## Hints\n\n### Marknotes\n\nBy using [Marknotes](https://github.com/cavo789/marknotes), documentation has never be so simple: just install Marknotes (see [Marknotes_Install](https://github.com/cavo789/marknotes_install)) and once done, specify the location of the `doc` folder of your current Marknotes installation in the `output` folder of your `settings.json` file.\n\nBy refreshing the documentation, files will be immediately store in your Marknotes installation and immediately available for your documentation.\n\nMarknotes has a lot of plugins and can easily convert documentation to Word documents (`.docx`) or Markdown files (`.md`).\n\n### Laravel\n\nIf you're working with Laravel, it's easy to add comments to tables and fields by using a migration script.\n\nWhen you create your own table in Laravel, as you know, you get a `.php` file in the `/database/migrations` folder. This is the file where you specify your fields.\n\nTake a look on the `up` function here below to learn how to add comments for fields and for the table:\n\n```php\npublic function up()\n{\n    Schema::create('test', function (Blueprint $table) {\n        $table-\u003estring('id', 100)-\u003eprimary();\n        $table-\u003einteger('user_id');\n        $table-\u003eboolean('enabled')-\u003ecomment = 'When set to false, the record should be considered as deleted (soft delete)';\n    });\n\n    DB::statement(\"ALTER TABLE `test` comment 'This table is used for ... and also for ...'\");\n}\n```\n\nLaravel expose a `comment` attribute for fields but no for the table. That's why we recommend to use a `DB::statement` command for running a DDL `ALTER TABLE`.\n\nBoth table and field's comment will be retrieved by this `DB_Documentor` tool.\n\n## Author\n\nChristophe Avonture\n\n## License\n\n[MIT](LICENSE)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcavo789%2Fdb_documentor","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcavo789%2Fdb_documentor","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcavo789%2Fdb_documentor/lists"}