Бібліотека liquibase-ddm-ext

🌐 Цей документ доступний українською та англійською мовами. Використовуйте перемикач у правому верхньому куті, щоб змінити версію.

1. Проблематика

Для створення фізичної моделі даних реєстру для СКБД PostgreSQL використовується Liquibase.

Liquibase за замовчуванням підтримує функціональність для розгортання та версіонування об’єктів в базі даних, тобто створення або видалення таблиць, створення зв’язків між цими таблицями, створення views та налаштування обмежень (constraints) тощо.

Для цього Liquibase має власний набір конструкцій — change types, кожна з яких визначає певну версію змін до БД, а формується набором XML-тегів. Наприклад, <createTable>, <dropTable>, тощо.

Оскільки в рамках Платформи реєстрів Liquibase використовується як єдиний інструмент для роботи з фізичною моделлю даних в PostgreSQL, то його стандартної функціональності не достатньо для покриття всіх сценаріїв роботи з регламентом реєстру.

З огляду на це, було розроблено:

  • liquibase-схему liquibase-ext-schema, яка розширює набір стандартних liquibase тегів та атрибутів, новими, специфічними для Платформи

  • бібліотеку розширень Liquibase liquibase-ddm-ext, що містить програмну обробку XML тегів та атрибутів, доданих у liquibase-ext-schema, а також модифікує чинну поведінку для тегів та атрибутів, що присутні за замовчуванням.

2. Загальний опис

liquibase-ddm-ext - бібліотека, що розширює функціональність Liquibase і відповідальна за обробку XML-тегів та атрибутів, що можуть використовуватись при моделюванні регламенту реєстру

Дана бібліотека додає обробку нових тегів та атрибутів, специфічних саме для Платформи, а також змінює логіку обробки деяких тегів, що присутні у Liquibase за замовчуванням

3. Принципи реалізації

Дане розширення використовує усі основні принципи та поняття, що надаються за замовчуванням розробникам та користувачам Liquibase (детальніше) та використовує механізми, надані розробникам розширень (приклади інших розширень, створених розробниками Liquibase для відкритого використання: https://github.com/orgs/liquibase/repositories)

4. Сценарії використання

Використовується в рамках пайплайну публікації регламенту (registry-regulation-publication-pipeline) на етапі розгортання дата моделі (стейдж create-schema пайпу registry-regulations-data-model) для заповнення схеми реєстрової БД та створення метаданих, необхідних для генерації data-model сервісів

5. Суміжні компоненти

  • registry-regulation-publication-pipeline - безпосередньо викликає Liquibase-утиліту на етапі публікації регламенту

  • dataplatform-jenkins-agent - імпортує дану бібліотеку у pom.xml для подальшого використання пайплайном публікації регламенту

  • liquibase-ext-schema - розширена XSD-схема liquibase тегів та атрибутів, які можуть використовуватись при розробці реєстру Платформи, включається у всі файли регламенту, які обробляються Liquibase з використанням liquibase-ddm-ext

  • service-generation-utility - генерує сервіси registry-model, registry-rest-api, registry-soap-api, використовуючи схему бази даних, яку наповнює Liquibase з використанням liquibase-ddm-ext

6. Перелік наявних розширень

Назва тегу

Існує у стандартному Liquibase

Опис

addColumn

так

розширює логіку Liquibase-тегу додавання колонки до існуючої таблиці

createAnalyticsIndex

ні

надає можливість створити індекс для попередньо створеного view на репліці БД

createAnalyticsView

ні

для створення аналітичної view на репліці БД

createCompositeEntity

ні

для створення метаданих, необхідних для генерації у registry-rest-api ендпоінта збереження декількох сутностей в рамках однієї транзакції

createDomain

ні

для створення користувацьких типів даних (доменів)

createMany2Many

ні

для створення між таблицями зв’язку many-to-many, що використовуватиметься при збереженні та отриманні даних

createSearchCondition

ні

для створення пошукового критерію з БД за певними параметрами

createSimpleSearchCondition

ні

для створення простого пошукового критерію (пошук за одним полем з однієї таблиці)

createTable

так

розширює логіку Liquibase-тегу створення нової таблиці

createType

ні

для створення типів даних ENUM

distributeTable

ні

для створення розподілених таблиць

dropAnalyticsView

ні

для видалення аналітичної view з репліки БД

dropColumn

так

Не підтримується Платформою. При використанні тегу dropColumn ви отримаєте помилку валідації: 'dropColumn' is not allowed.

dropDomain

ні

для видалення користувацьких типів даних (доменів)

dropSearchCondition

ні

для видалення пошукових критеріїв з БД

dropType

ні

для видалення типів даних ENUM

exposeSearchCondition

ні

для створення метаданих, необхідних для генерації у registry-rest-api ендпоінтів пошукових критеріїв, доступних для виклику з зовнішніх систем

grantAll

ні

для видачі прав на усі аналітичні view

grant

ні

для видачі прав на окрему view

makeObject

ні

для визначення існуючої таблиці об’єктом (додаються посилання на таблицю subject, що створена попередньо)

modifyDataType

так

розширює логіку Liquibase-тегу зміни типу даних колонки таблиці

partialUpdate

ні

для створення метаданих, необхідних для генерації у registry-rest-api ендпоінтів часткового оновлення сутності у БД (лише деяких визначених колонок)

rbac

ні

для створення метаданих, необхідних для керування доступом до registry-rest-api ендпоінтів для визначених ролей

referenceTable

ні

для створення reference-таблиці

renameColumn

так

розширює логіку Liquibase-тегу перейменування колонки таблиці

revokeAll

ні

для видалення прав на усі аналітичні view

revoke

ні

для видалення прав на окрему view

rls

ні

для застосування правил Row-Level Security до роботи з даними у таблиці

tableReadParameters

ні

для створення метаданих, необхідних для генерації у registry-rest-api коректних запитів на читання даних (з вкладеними сутностями/без і т.д)

truncateLocalDataAfterDistributingTable

ні

для видалення локальних даних після створення розподіленої таблиці

undistributeTable

ні

для відміни функції розподілення таблиці

7. Діаграми

У загальному процесі розгортання моделі даних пайплайном публікації регламенту, виконання необхідних Liquibase-скриптів розширенням, відбувається на етапі Створення схеми БД (стейдж create-schema)

datamodel

Приклад пайпу публікації дата-моделі у Jenkins, liquibase-ddm-ext викликається на етапі create-schema

data model pipe

Діаграма, що відображає приблизну структуру пакетів у розширенні, а також основні точки, через які відбувається розширення основної функціональності Liquibase (класи AbstractChange, CreateTableChange і т.д)

classes

8. БД

Окрім створення власне схеми бази даних, liquibase-ddm-ext також заповнює таблиці з метаданими, необхідними для коректної генерації registry-сервісів

Таблиці, в які потрапляють ці метадані: ddm_liquibase-metadata, ddm_rls_metadata, ddm_role_permission.

8.1. ddm_liquibase_metadata

Таблиця для метаданих, що не потребують структури, виділеної в окрему таблицю

8.1.1. Структура таблиці

CREATE TABLE public.ddm_liquibase_metadata (
    metadata_id INTEGER GENERATED BY DEFAULT AS IDENTITY NOT NULL,
    change_type TEXT NOT NULL,
    change_name TEXT NOT NULL,
    attribute_name TEXT NOT NULL,
    attribute_value TEXT NOT NULL,
    created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW() NOT NULL,
    CONSTRAINT pk_ddm_liquibase_metadata PRIMARY KEY (metadata_id)
);

8.1.2. Призначення колонок таблиці

Назва колонки

Призначення

Приклад

change_type

тип метаінформації

search_condition

change_name

до якого об’єкта відноситься метаінформація

назва критерію пошуку

attribute_name

назву одного атрибуту вказаного change

pagination

attribute_value

значення для вказаного атрибуту

limit

8.2. ddm_rls_metadata

Таблиця, що зберігає інформацію про Row-Level Security правила, що мають застосовуватись до запитів registry-rest-api

8.2.1. Структура таблиці

CREATE TABLE public.ddm_rls_metadata (
    rls_id INTEGER GENERATED BY DEFAULT AS IDENTITY NOT NULL,
    name TEXT NOT NULL,
    type TEXT NOT NULL,
    jwt_attribute TEXT NOT NULL,
    check_column TEXT NOT NULL,
    check_table TEXT NOT NULL,
    CONSTRAINT pk_ddm_rls_metadata PRIMARY KEY (rls_id)
);

8.2.2. Призначення колонок таблиці

Назва колонки

Призначення

Приклад

name

назва зміни правила

write_rls_katottg

type

до якої операції має застосовуватись

write

jwt_attribute

атрибут jwt-токену, в якому знаходиться необхідна для перевірки інформація

katottg_jwt_attr

check_table

таблиця, до якої застосовується RLS

katottg_table

check_column

колонка таблиці, значення з якої будуть перевірятись для RLS

katottg_value

8.3. ddm_role_permission

Таблиця, що зберігає інформацію про параметри доступу до даних за RBAC

8.3.1. Структура таблиці

CREATE TABLE public.ddm_role_permission (
    permission_id INTEGER GENERATED BY DEFAULT AS IDENTITY NOT NULL,
    role_name TEXT NOT NULL,
    object_name TEXT NOT NULL,
    column_name TEXT,
    operation TYPE_OPERATION NOT NULL,
    created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW() NOT NULL,
    CONSTRAINT pk_ddm_role_permission PRIMARY KEY (permission_id)
);

8.3.2. Призначення колонок таблиці

Назва колонки

Призначення

Приклад

role_name

роль користувача, для якої виконується налаштування

officer

object_name

назва об’єкту, доступ до якого обмежується

назва таблиці чи критерію пошуку

column_name

атрибут об’єкту, доступ до якого обмежується

колонка таблиці чи критерію пошуку

operation

тип операції (читання, запис і т.д)

S / I / U / D