Managing registry data model table structures
- 1. Problem description
- 2. Basic use cases
- 3. Out of scope
- 4. Principles of working with changes in the database
- 4.1. Existing mechanism for working with changes in the database
- 4.2. Advanced mechanism for working with changes in the database
- 4.3. Basic concepts
- 4.4. DataModelSnapshot structure description
- 4.5. Description of the file structure in the file system
- 4.6. Description of the DataModelSnapshot data format
- 5. Permissible operations with the objects of a domain model
- 6. Description of the domain model attributes
- 7. General implementation principles
- 8. Description of the technical solution
- 9. System component interaction scenario when editing the structure of the registry tables
- 10. General diagram of the system components interaction when editing the data model of the registry regulations
| 🌐 This document is available in both English and Ukrainian. Use the language toggle in the top right corner to switch between versions. |
1. Problem description
The part of the process of creating/editing registry rules is to describe the registry data model. The current approach uses only configuration files to create a registry data model. The user must use liquibase changelog data model description format, which is de facto a description of the database structure.
The part of the web-based admin portal for editing the version of the registry regulations is editing the database structure. It is necessary to develop a technical design of the subsystem for creating a registry data model.
1.1. Key points of the problem
-
Simultaneous work of several users with one candidate version of the regulations.
-
Preserving the mechanism for ensuring the existing life cycle of the version rules (gerrit, jenkins).
-
Preserving the technical tool for recreating the database structure (liquibase).
-
Preserving the mechanism for changing the rules by changing the configuration files in git.
-
Synchronization between changes made from the admin portal and changes made through Gerrit.
-
Creation of GUI based mechanism for changing registry regulations.
2. Basic use cases
-
Creating a new version of the registry regulations.
-
Performing permitted CRUD-like operations with model data as described below.
-
View the entire history of changes made to the data model of the registry regulations.
-
View the history of changes made to the data model of the registry regulations in a candidate version.
-
Saving changes made in the data model to the candidate version.
-
Inspection of the candidate version of the register regulations.
3. Out of scope
-
Working with data types
-
Working with analytical representations
-
Resolving conflicts using the administrative portal of the registry regulations management
4. Principles of working with changes in the database
4.1. Existing mechanism for working with changes in the database
The existing mechanism for working with changes in the database is based on two principles:
-
Creation of liquibase changeset
-
Saving liquibase changeset in git
4.2. Advanced mechanism for working with changes in the database
It is suggested to extend the existing mechanism for working with database changes by adding a DataModelSnapshot document to the git repository, which will reflect the state of the data model.
4.3. Basic concepts
-
DataModelSnapshot model: JSON documents reflecting the state of the registry regulations data model.
-
Diff Document: The document showing the difference between the two states of the registry regulations data model.
-
History Document: The document reflecting the history of changes made to the master version or the candidate version of the registry regulations.
4.4. DataModelSnapshot structure description
| The above data model was obtained as the result of the analysis of the existing state of lqiuibase changelogs (including the functionality analysis of the custom liquibase tags). |
4.5. Description of the file structure in the file system
The DataModelSnapshot model has the following file structure in the file system:
-
The list of tables is determined by the list of files in the file system.
-
The name of the table file matches the name of the table and is
<table-name>.json. -
The name of the role permission file corresponds to the name id role permission and is the following:
<role-id>.json.
4.6. Description of the DataModelSnapshot data format
The Json format is used as a technical tool for describing the data structure of DataModelSnapshot. As a description of the contract document, https://json-schema.org/ [JsonSchema] is used.
5. Permissible operations with the objects of a domain model
| The information below is based on the existing contract on working with the data model of the registry regulations. In the context of this problem, this contract is a source of functionalities that should be taken into account when developing the technical design. |
Permissible operations with respect to the data model of the registry regulations can be divided into 2 groups:
-
Limited capacity to change the data model.
-
Full possibility to change the data model.
| The data model objects that have not been integrated into the master version of the registry regulations can be changed in any way, regardless of the following limitations. |
Data model objects included in the master version of snapshot data model have limited editing capabilities. Tables created in CandidateSnapshot have no restrictions on editing capabilities.
5.1. Valid operations with domain model objects included in the previous release
| Entity | Create | Update | Delete |
|---|---|---|---|
Table |
Y |
Y |
N |
Column |
Y |
Y |
N |
Index |
Y |
Y |
Y |
Constraint |
Y |
Y |
Y |
ForeignKey |
Y |
Y |
Y |
AccessRule |
Y |
Y |
Y |
6. Description of the domain model attributes
6.1. Table
| Attribute | Type | Read only | Description |
|---|---|---|---|
Name |
string |
true |
|
HistoricalFlag |
boolean |
true |
|
ObjectReference |
true |
||
Description |
String |
false |
6.2. Column
Attribute |
Type |
Read only |
Description |
Name |
string |
true |
|
Description |
string |
false |
|
Type |
enum[clarify types] |
true |
|
DefaultValue |
object |
false |
|
NotNull |
boolean |
true |
|
Unique |
boolean |
true |
|
PrimaryKey |
boolean |
true |
6.3. Index
Attribute |
Type |
Read only |
Description |
Name |
string |
true |
|
Columns |
[{ name string sorting: enum[ASC, DESC, NONE] }] |
false |
6.4. Constraint
Attribute |
Type |
Read only |
Description |
Name |
string |
true |
|
Columns |
array[columnName] |
true |
6.5. ForeignKey
Attribute |
Type |
Read only |
Description |
Name |
string |
true |
|
SourceColumnName |
string |
true |
|
TargetTable |
string |
true |
|
TargetColumnName |
string |
true |
6.6. AccessRule
Attribute |
Type |
Read only |
Description |
ColumnName |
string |
true |
|
Actions |
enum[CREATE, READ, UPDATE, DELETE] |
false |
|
RoleNames |
[roleName: string] |
false |
7. General implementation principles
-
The mechanism allows CRUD operations with the objects of the domain model.
-
Simultaneous editing of the registry regulations both using the admin portal and by changing the configuration files in the regulations repository.
-
The status of the database structure and metadata is fully reflected in the DataModelSnapshot documents.
-
The structure of the DataModelSnapshot json documents is described using JSONSchema.
-
The DataModelSnapshot documents (with JSONSchema) shall be used as a data exchange structure at the RestAPI level between the Front-End application and Backend services.
-
Conflict resolution when editing registry regulations using the administrative portal is required only at the level of the DataModelSnapshot documents.
-
Maintaining consistent DataModelSnapshot model and liquibase changelog.
-
DataModelSnapshot model synchronization process on the basis of liquibase changelog is idempotent.
-
Changes made from the administrative portal are in a separate liquibase changeset. The candidate version ID is a part of the liquibase changeset id attribute.
