Skip to content

Структура проекта

Проект в терминологии dbFirst - это папка со следующим содержанием:

  • migrations/
  • queries/
  • project.dbfirst-v1.yaml

Рассмотрим каждый пункт в отдельности.

Папка migrations

Содержит файлы миграции схемы БД в формате SQL.

Пример содержимого файла миграции:

create table artist (
  id bigserial not null primary key,
  name text not null
);

create index artist_name on artist (name);

К названиям файлов есть следующие требования:

  • Они должны иметь расширение .sql или .psql. Файлы с другими расширениями игнорируются.
  • Названия должны быть сортируемы в соответствии с желаемым порядком исполнения миграций.

В остальном вы вольны называть их как угодно.

Папка queries

Содержит файлы с запросами против последней версии схемы БД, формируемой из файлов миграции. Каждый запрос находится в отдельном файле.

Названия файлов предопределяют названия запросов в генерируемых артефактах. Должны указываться в kebab-case (spinal-case) в нижнем регистре. Например, select-artist-by-id.sql. В генерируемых артефактах названия будут транслированы в соответствующий артефакту вид. Например, соответствующий метод в Java будет называться selectArtistById.

Запросы пишутся в SQL диалекта PostgreSQL без каких-либо ограничений.

Параметризация запросов осуществляется подставлением именованных переменных после символа $. Имена указываются в snake-case в нижнем регистре. Например, $artist_name.

Вот пример полного содержимого файла с запросом с двумя параметрами:

insert into album (name, released)
values ($name, $released)
returning id

Допускается использование одного параметра несколько раз.

Файл конфигурации

Описывает метаданные проекта. Это название и версия вашего проекта, а также настройки генерируемых артефактов. Это предопределяет структуру, неймспейсинг и прочие настройки в генерируемых артефактах.

Файл должен называться project.dbfirst-v1.yaml. v1 определяет версию синтаксиса конфигурации.

Пример содержимого файла конфигурации:

# Неймспейс.
# Определяет название корневого неймспейса в генерируемых артефактах.
# Рекомендуем указывать здесь название вашей компании.
space: my-space

# Название проекта.
# Определяет неймспейс второго уровня в генерируемых артефактах,
# а также названия библиотек.
name: music-catalogue

# Версия для артефактов.
# Определяет версию в генерируемых библиотеках.
# 
# Должна соответствовать конвенции [SemVer](https://semver.org/).
# Кодогенераторы траснформируют это в конвенции, соответствующие языкам.
version: 1.0.0

# Список артефактов, которые требуется сгенерировать.
# Если он пустой, то dbFirst просто валидирует вашу схему и запросы.
artifacts:
  - haskell-hasql-v1
  - java-jdbc-v1