part38-rus.md

Создание страницы документации и SQL дампа структуры БД из DBML

Оригинал

Привет, ребята, добро пожаловать на мастер-класс по бэкенду!

Если вы всё ещё помните на первой лекции курса мы узнали о dbdiagram.io, бесплатном сервисе, созданном Holistics, который помогает нам проектировать базу данных с использованием DBML или языка разметки базы данных, визуализировать диаграммы сущность-связь таблицы, а затем автоматически генерировать и экспортировать SQL коды её структуры.

Недавно я только что узнал, что Holistic создал еще один очень крутой сервис под названием dbdocs.

Создаём документацию к БД с помощью dbdocs

Этот сервис помогает нам создать красивую веб-документацию по базе данных, используя тот же файл DBML, который мы создали ранее. Хотя разобраться в нём просто, он настолько классный, что я хочу показать вам, как использовать сервис в нашем простом банковском приложении. Я уверен, что это сделает ваш процесс разработки более увлекательным и продуктивным.

Итак, на лекции мы узнаем как сгенерировать как страницу документации, так и SQL код структуры БД непосредственно из терминала, используя dbdocs и CLI инструмент DBML.

Во-первых, давайте откроем веб-сайт dbdocs.io и перейдем на страницу Get Started. Чтобы установить инструмент dbdocs, у нас должен стоять NodeJS и npm на нашей машине.

Поскольку я пользуюсь Mac OS, я установлю их с помощью Homebrew.

brew install node

После успешной установки мы можем запустить node -v и npm -v, чтобы увидеть их версии.

Хорошо, теперь мы можем установить dbdocs с помощью этой команды:

npm install -g dbdocs 

Затем давайте выполним команду dbdocs, чтобы проверить, правильно ли она установлена.

dbdocs

Здесь на рисунке мы также видим некоторые доступные команды, которые помогут нам в создании документации или управлять логином и паролем на странице документации.

Следующим шагом является определение структуры с помощью DBML, что мы уже сделали в первой лекции курса.

Поэтому я просто копирую DBML содержимое с сайта dbdiagram.io. Затем в репозитории нашего простого банковского приложения я создам новую папку с названием doc и новый файл db.dbml внутри этой папки. Затем давайте вставим DBML код структуры БД. Пока в редакторе у нас нет подсветки синтаксиса.

В Visual Studio Code мы можем поискать по ключевому слову dbml и установить это расширение vscode-dbml.

После его установки вернитесь к DBML файлу, и удостоверьтесь, что подсветка кода включена.

Мы также можем добавить дополнительные метаданные и описание проекта. Например, я изменю это название с Ecommerce Database на Simple Bank Database.

Project first_project {
  database_type: 'PostgreSQL'
  Note: '''
    # Simple Bank Database
    **markdown content here**
  '''
}

Вы также можете добавить более подробное описание здесь, используя язык Markdown, если хотите. Пока что я просто удалю его.

Project first_project {
  database_type: 'PostgreSQL'
  Note: '''
    # Simple Bank Database
  '''
}

Хорошо, теперь с помощью этого файла DBML мы можем создать страницу документации БД. Но сначала нам нужно залогиниться в dbdocs.

Для этого нам просто нужно выполнить команду dbdocs login в терминале и указать адрес электронной почты для аутентификации. Итак, давайте сделаем это!

dbdocs login
Choose a login method:
  1) Email
  2) Github
  Answer:

Мы можем залогиниться с помощью электронной почты или учетной записи GitHub. Я выберу аутентификацию, используя электронную почту.

Затем введу адрес электронной почты: [email protected].

Приложение выдало сообщение Request email authentication («Была запрошена аутентификация по электронной почте»), поэтому нам нужно проверить им электронное письмо и ввести здесь предоставленный OTP (одноразовый пароль).

Итак, я открою Gmail. Там будет письмо от dbdocs.io. Давайте скопируем OTP из него и вставим в терминал.

Затем вуаля, мы успешно вошли в учетную запись. Теперь мы можем сгенерировать страницу документации БД с помощью команды dbdocs build.

Ему нужен только один аргумент, которым является путь к DBML файлу: в нашем случае doc/db.dbml.

dbdocs build doc/db.dbml

Страница успешно создана. Однако, обнаружились две проблемы: во-первых, страница еще не защищена паролем, поэтому любой может получить к ней доступ. А во-вторых, у неё не очень удачное название: first_project.

Это потому, что я забыл изменить название проекта из примера.

Итак, вернемся к коду и изменим название проекта на simple_bank.

Project simple_bank {
  database_type: 'PostgreSQL'
  Note: '''
    # Simple Bank Database
  '''
}

Теперь, если мы снова запустим dbdocs build, будет создана новая страница с правильным названием: simple_bank, именно так, как мы хотели.

Мы можем получить к нему доступ по этой ссылке.

Как видите, на данный момент она не защищена паролем.

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

Более подробную информацию о каждой таблице мы можем увидеть, выбрав её в левом боковом меню.

Справа отображаются все поля этой таблицы вместе с их типами, настройками, связями, значениями по умолчанию и индексами. Мы также можем увидеть полностью ER-диаграмму для базы данных на этой вкладке Relationships.

Или мы можем скопировать эту ссылку, чтобы поделиться ею с другими членами команды.

Но, конечно же, мы не хотим, чтобы кто угодно в Интернете знал о нашей внутренней структуре БД, верно?

Итак, давайте узнаем, как установить пароль для защиты нашей страницы документации. Это на самом деле довольно просто.

Как видите, нам просто нужно использовать команду dbdocs password.

Итак, давайте скопируем её и вставим в терминал.

dbdocs password --set <password> --project <project name>

Я изменю значение пароля на "secret", а название проекта должно быть "simple_bank".

dbdocs password --set secret --project simple_bank
Password is set for 'simple_bank'

И, вуаля, пароль для нашего проекта назначен. Теперь, если мы снова откроем эту страницу, то увидим надпись "protected project" («защищенный проект») и нам нужно будет ввести правильный пароль для входа на страницу.

Выглядит круто и так легко настроить, не так ли?

На странице также есть кнопка, позволяющая нам войти в систему с помощью электронной почты или GitHub.

Сам процесс похож на те действия, которые мы делали раньше в терминале. Просто введите адрес электронной почты, нажмите Send. Затем откройте Gmail, чтобы получить OTP. Скопируйте OTP из этого письма и вставьте его в это поле.

После этого мы сможем успешно залогиниться.

Мы можем открыть это меню и выбрать эту ссылку, показанную на рисунке, чтобы просмотреть все наши проекты.

Как видите, на данный момент у нас два проекта: simple_bank и first_project, который я создал ранее по ошибке.

Я хочу удалить first_project, чтобы на странице не было лишней, устаревшей информации, поэтому я собираюсь запустить команду dbdocs remove в терминале и передать название этого проекта.

dbdocs remove first_project
Removed successfully

Итак, он был успешно удалён.

Теперь, если мы вернемся на страницу документации, то увидим только один проект simple_bank.

Так что всё сработало как надо! Превосходно!

Теперь вы знаете, как создать страницу документации БД из DBML. Теперь давайте узнаем, как генерировать SQL код непосредственно в терминале. Мы можем использовать его в скрипте миграции БД.

Если мы вернемся на сайт dbdiagram, в меню dbx, кроме dbdocs, есть еще ссылка на dbml страницу.

На этой странице давайте откроем инструмент командной строки (CLI), затем прокрутите немного вниз, там будет инструкция, как установить инструмент.

Всё, что нам нужно сделать, это запустить

npm install -g @dbml/cli

в терминале.

Итак, инструмент командной строки dbml успешно установлен.

Вот как мы можем использовать его для генерации SQL кодов: просто запустите dbml2sql и укажите движок базы данных, в нашем случае это Postgres. Затем ключ -o, за которым следует путь к файлу, куда будет записан результат выполнения команды, я здесь введу doc/schema.sql. И, наконец, путь к файлу dbml, то есть doc/db.dbml.

dbml2sql --postgres -o doc/schema.sql doc/db.dbml
Generated SQL dump file (PostgreSQL): schema.sql

Вот и все! Создан файл c SQL дампом. Мы можем проверить это в Visual Studio Code.

Вот он, файл schema.sql в папке doc. Так что команда отлично отработала!

Обновляем Makefile

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

db_docs:
	dbdocs build doc/db.dbml

А вторая — db_schema, которую следует использовать для создания Postgres SQL дампа структуры базы данных.

db_schema:
	dbml2sql --postgres -o doc/schema.sql doc/db.dbml

Я также добавлю db_docs и db_schema в список PHONY. Итак, теперь всякий раз, когда мы хотим изменить структуру БД, после обновления файла DBML нам просто нужно запустить

make db_docs

чтобы заново создать страницу документации и

make db_schema
dbml2sql --postgres -o doc/schema.sql doc/db.dbml
Generated SQL dump file (PostgreSQL): schema.sql

чтобы заново создать файл с SQL дампом.

Очень легко и удобно, не так ли?

И, кстати, в Makefile я заметил, что несколько раз дублируется URL-адрес базы данных.

Мы можем уменьшить число дублирующегося кода, заменив его переменной. Давайте назовем её DB_URL.

migrateup:
	migrate -path db/migration -database "$(DB_URL)" -verbose up

migrateup1:
	migrate -path db/migration -database "$(DB_URL)" -verbose up 1

migratedown:
	migrate -path db/migration -database "$(DB_URL)" -verbose down

migratedown1:
	migrate -path db/migration -database "$(DB_URL)" -verbose down 1

Обратите внимание, что здесь я использую символ $ и пару круглых скобок, чтобы получить значение переменной. Теперь мы можем определить эту переменную в верхней части Makefile.

DB_URL=postgresql://root:secret@localhost:5432/simple_bank?sslmode=disable

Вот так и у нас всё готово!

Давайте попытаемся выполнить команду

make migratedown

в терминале.

Затем

make migrateup

Все они успешно выполнены! Превосходно!

Хочу рассказать вам ещё кое о чём! Когда мы используем DBML CLI для генерации SQL кода, он также создает файл dbml-error.log в корне проекта.

В этом файле находятся логи ошибок, которые сообщают, существуют ли какие-то проблемы в вашем файле DBML или нет. В нашем случае ошибок нет, поэтому содержимое файла пустое. Но в любом случае мы никогда не захотим передавать этот файл с логами на Github, верно?

Поэтому давайте создадим файл .gitignore в корне и поместим *.log внутрь файла, чтобы игнорировать все файлы логов.

Хорошо, теперь давайте создадим новую ветку с названием ft/dbdocs,

git checkout -b ft/dbdocs

добавим все изменения,

git add .

опять проверим её состояние

git status

и зафиксируем их с сообщением "add dbdocs" («добавляем dbdocs»).

git commit -m "add dbdocs"

Наконец, мы можем отправить её на GitHub

git push origin ft/dbdocs

и использовать эту ссылку https://github.com/techschool/simplebank/pull/new/ft/docs, чтобы создать новый пул-реквест.

После того как unit тесты успешно пройдены, мы можем безопасно объединить ветку с master и удалить её.

И на этом завершим эту короткую лекцию о создании страницы документации и SQL дампа структуры БД из терминала.

Надеюсь она была интересной и приобретенные знания будут вам полезны.

Большое спасибо за время, потраченное на чтение, и до встречи на следующей лекции!