Data model setup

To add a field or entity to the application’s data model, it is necessary to configure the required fields/Java entity classes. After that, you need to update the database structure using SQL scripts.

After configuring the fields in Java classes/entities, you need to run the application so that, based on the changes made to the Java classes, the version control tool generates an SQL script with changes to the database structure.

By default, the version control tool generates files whose names include a timestamp of the moment of generation. Example: V241012192920.sql

• V- static prefix

• 24 - year

• 10 - month

• 12 - day

• 19 - hours

• 29 - minutes

• 20 - seconds

The generated file should be moved to the application’s resources (generally, this is /src/main/resources/migration) and a postfix in the form of a brief description of the essence of the changes made should be added to the file name: V241012192920__addParticipant.sql

• __ - double underscore, a separator between the timestamp and the brief description

• addParticipant - brief description.

Let’s consider example (1) for adding the Participant entity to the system and example (2) for modifying the Application entity by adding an optional String field named purpose.

Example 1

First, configure the Java class/entity Participant. You need to create a Java class named Participant. It should inherit from BaseEntity (a base entity of Timvero OS). Add @Entity and @Table annotations to the class, add mandatory (nullable = false) fields (in our case, first name, last name, and a unique identifier) and annotate the fields with the @Column annotation.

Participant.java

Unresolved directive in _data-model.adoc - include::/opt/teamcity-agent3/work/22975dcd6c67da8a/src/main/java/participant/entity/Participant.java[tags=participant]

    ...
}

After the class is configured, run the application. The system will analyze changes in the data model of Java classes and generate an SQL script with the necessary changes V241012192920.sql in the project’s home directory (application.home=path), in the subdirectory hbm2ddl.

V241012192920.sql

    create table participant (
        id bigserial not null,
        created_at timestamp(6) with time zone not null,
        updated_at timestamp(6) with time zone not null,
        first_name varchar(255) not null,
        last_name varchar(255) not null,
        primary_id varchar(255) not null,
        created_by bigint,
        updated_by bigint,
        primary key (id)
    );

Move the generated file to the application’s resources (generally, this is /src/main/resources/migration) and add a postfix in the form of a brief description of the essence of the changes made V241012192920__addParticipant.sql.

After that, you can run the application, and the system will make changes to the database structure according to the SQL script, and the Java data model will be available with the newly created Participant entity for further work in the application.

Example 2

To make changes to an existing entity, simply add the necessary fields to that entity/class, run the application, receive, move, and rename the SQL script, and then run the application again to apply the changes made.

To the existing entity Application

Unresolved directive in _data-model.adoc - include::/opt/teamcity-agent3/work/22975dcd6c67da8a/src/main/java/application/entity/Application.java[tags=application]

    ...
}

add an optional field String purpose

Unresolved directive in _data-model.adoc - include::/opt/teamcity-agent3/work/22975dcd6c67da8a/src/main/java/application/entity/Application.java[tags=purpose]

After running the application, the system will generate the following file V241012203045.sql

    alter table if exists application 
       add column purpose varchar(255);

Move the generated file to the application’s resources (generally, this is /src/main/resources/migration) and add a postfix in the form of a brief description of the essence of the changes made V241012203045__addPurpose.sql.

After that, you can run the application, and the system will make changes to the database structure according to the SQL script, and the Java data model will be available with the newly added optional field purpose in the Application entity for further work in the application.