Одной из частых задач документирования является документирование баз данных. Это может быть документирование PostgreSQL, Clickhouse, MongoDB и других баз данных. Их все объединяет один простой факт — такую документацию сложно делать вручную. В этой статье я разберу, как создать описание базы данных PostgreSQL с помощью утилиты tbls.

Что войдет в документацию

Посмотреть пример документации можно по ссылке. Хоть генерацию документации можно настроить с помощью шаблонов, на самом деле, базовый шаблон покрывает всю основную информацию.

В базовом шаблоне создается общий файл README.md с названием всех таблиц и ER-диаграммой в формате SVG. А также к каждой таблице создается markdown-файл с более подробным описанием и SVG-файл с изображением таблицы и ее связей.

В описании таблицы можно найти:

• Viewpoints — предопределенный контекст для просмотра схемы данных.

• Contrains — ограничения, например, PRIMARY KEY.

• Indexes — индексы для оптимального поиска по базе данных.

• Relations — связи между таблицами в виде ER-диаграммы.

Шаг 1. Установить нужные утилиты

Чтобы создать тестовую базу данных на своем компьютере, установите psql и mock-data.
Чтобы сгенерировать документацию к базе данных, установите tbls.

Шаг 2. (опционально) Создать базу данных

Если у вас уже есть база данных, к которой вы хотите создать документацию, пропустите этот шаг.

При установке psql была создана база данных и пользователь по умолчанию, оба с именем postgres. Эту базу данных и суперпользователя мы будем использовать для документации.

После установки psql и mock-data:

1. Откройте командную строку.

2. Откройте терминал psql для работы с помощью команды psql -d postgres -U postgres или sudo -u postgres psql для MacOS и Linux.

3. Создайте в терминале psql две таблицы с помощью команды CREATE TABLE films (code char(5) CONSTRAINT firstkey PRIMARY KEY, title varchar(40) NOT NULL,mdid integer NOT NULL, date_prod date, kind varchar(10), len interval hour to minute); CREATE TABLE distributors (did integer PRIMARY KEY GENERATED BY DEFAULT AS IDENTITY, name varchar(40) NOT NULL CHECK (name <> ''));.

4. Закройте терминал psql с помощью \q.

5. Продолжайте работать в командной строке и заполните пустые таблицы данными с помощью команды mock d -c -f -d postgres -u postgres -p 5432 -a localhost -w <пароль_суперпользователя>. Пароль суперпользователя вы задавали во время установки psql.

Готово, вы создали базу данных с двумя таблицами данных.

Шаг 3. Сгенерировать документацию для базы данных

Введите в командной строке: tbls doc postgres://postgres:<пароль_суперпользователя>@localhost:5432/postgres. В команде используется ссылка на базу данных, которая была создана локально на прошлом шаге. Пароль суперпользователя вы задавали во время установки psql.

Если вы хотите сделать описание к другой базе данных, то ссылка обычно составляется по шаблону — postgres://<имя пользователя>:<пароль пользователя>@<имя хоста>:5432/<название базы данных>. Посмотреть ссылки для других типов баз данных можно в документации tbls.

Заключение

После выполнения команды вы получили папку с файлами Markdown и SVG с техническим описанием базы данных.

С помощью tbls мы быстро и удобно создали описание базы данных и связей между таблицами. Причем эту команду можно использовать не один раз, но и в рамках CI/CD, который будет автоматически запускаться при обновлении базы данных.

Конечно, созданная утилитой документация необязательно будет являться полным описанием, но вы можете использовать его и улучшать позже в тех аспектах, в которых нужно.