Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/kumuluz/kumuluzee-database-schema-migrations

Database schema migrations extensions for the lightweight KumuluzEE framework.
https://github.com/kumuluz/kumuluzee-database-schema-migrations

Last synced: about 13 hours ago
JSON representation

Database schema migrations extensions for the lightweight KumuluzEE framework.

Awesome Lists containing this project

README 

        
# KumuluzEE Database Schema Migrations

[![KumuluzEE CI](https://github.com/kumuluz/kumuluzee-database-schema-migrations/actions/workflows/kumuluzee-ci.yml/badge.svg)](https://github.com/kumuluz/kumuluzee-database-schema-migrations/actions/workflows/kumuluzee-ci.yml)



> KumuluzEE Database Schema Migrations project for database schema migrations with Liquibase.



KumuluzEE Database Schema Migrations is a database schema migration project for the KumuluzEE microservice framework 

that provides an easy way to migrate database schemas with [Liquibase](https://www.liquibase.com/). It supports 

migrations at application startup or at runtime when the application is already running.



## Usage



You can enable KumuluzEE database schema migrations with Liquibase by adding the following dependency:



```xml



    com.kumuluz.ee.database-schema-migrations

    kumuluzee-database-schema-migrations-liquibase

    ${kumuluzee-database-schema-migrations.version}



```



**At least one data source** must be configured for the extension to work.

For example, PostgreSQL can be used by adding the following dependency:

```xml



    org.postgresql

    postgresql

    ${postgresql.version}



```



### Configure migrations



Liquibase database schema migrations are configured using the common KumuluzEE configuration framework.

The configuration properties can be defined via the environment variables or via the configuration file.

For more details, see the [KumuluzEE configuration wiki page](https://github.com/kumuluz/kumuluzee/wiki/Configuration)

and [KumuluzEE Config](https://github.com/kumuluz/kumuluzee-config).



To use Liquibase database schema migrations, **at least one data source** must be configured.



The only required Liquibase configuration property is `jndi-name`, which must correspond to a JNDI name of the 

preconfigured data source.



Minimum configuration for Liquibase database schema migration (without data source configuration):

```yaml

kumuluzee:

  database-schema-migrations:

    liquibase:

      changelogs:

        - jndi-name: jdbc/example-db             # Required

```



To specify the location of a custom changelog file, the `file` property can be used (default is

`db/changelog-master.xml`). The location must be specified relative to the `resource` directory.



Example configuration:

```yaml

kumuluzee:

  database-schema-migrations:

    liquibase:

      changelogs:

        - jndi-name: jdbc/example-db

          file: db/changelog-master.xml          # default: "db/changelog-master.xml"

```



#### Configure migrations at startup



There are two actions that can be performed when the application starts. 

One is `dropAll` and the other is `update`.

The `dropAll` action drops the database and the `update` action updates the database according to the changelog

at the location specified in the `file` property. Note that the `dropAll` action is executed before the `update` 

action if both are enabled.



Example configuration:

```yaml

kumuluzee:

  database-schema-migrations:

    liquibase:

      changelogs:

        - jndi-name: jdbc/example-db

          startup:

            drop-all: false                      # default: false  

            update: true                         # default: false

```



#### Disable migrations



To disable database schema migrations at application startup, set `kumuluzee.database-schema-migrations.enabled` 

to false (default is `true`). This will disable migrations at startup and the injection of `LiquibaseContainer` will 

always return `null`.

```yaml

kumuluzee:

  database-schema-migrations:

    enabled: false                               # default: true

```



#### Contexts and labels



With contexts and labels, Liquibase provides a way to selectively execute *changeSets*.

Contexts allow you to select specific *changeSets* for execution, while labels allow you to select *changeSets* 

for execution using complex expressions (note that the comma (`,`) in labels means the same as the `or` operator).



Both contexts and labels can be configured in the KumuluzEE configuration file.



Example configuration:

```yaml

kumuluzee:

  database-schema-migrations:

    liquibase:

      changelogs:

        - jndi-name: jdbc/example-db

          labels: "label1 and !label2, label3"   # default: ""

          contexts: "context1, context2"         # default: ""

```



Note that contexts that are not specified are ignored by Liquibase. The same is true for labels.



### Database Schema Migrations via CDI



KumuluzEE database schema migrations provide LiquibaseContainer, a wrapper for the Liquibase object, that can be 

injected via CDI. The Liquibase object provides a way to perform schema migrations on the connected data source 

at runtime.



The LiquibaseContainer is created by first selecting an appropriate configuration based on the JNDI name specified

in the @LiquibaseChangelog annotation, and then connecting it to the appropriate data source.

The annotation can also be omitted if only one Liquibase migration is specified in the KumuluzEE configuration file.



Example:

```java

/*

 * Injects LiquibaseContainer if only 1 Liquibase 

 * configuration is specified in the config file.

 */

@Inject

private LiquibaseContainer liquibaseContainer;



/* 

 * Injects LiquibaseContainer if only 1 Liquibase 

 * configuration is specified in the config file.

 */

@Inject

@LiquibaseChangelog

private LiquibaseContainer liquibaseContainer2;



/* 

 * Injects LiquibaseContainer for changelog with the JNDI

 * name specified in the argument of the annotation.

 */

@Inject

@LiquibaseChangelog(jndiName = "jdbc/example-db")

private LiquibaseContainer liquibaseContainer3;



public void dropAll() throws LiquibaseException {



    Liquibase liquibase = liquibaseContainer.createLiquibase();



    liquibase.dropAll();

    liquibase.validate();



}

```



## Building



Ensure you have JDK 8 (or newer), Maven 3.2.1 (or newer) and Git installed



```bash

    java -version

    mvn -version

    git --version

```



First clone the repository:



```bash

    git clone https://github.com/kumuluz/kumuluzee-database-schema-migrations.git

    cd kumuluzee-database-schema-migrations

```



To build run:



```bash

    mvn install

```



This will build all modules and run the testsuite.



Once completed you will find the build archives in the modules respected `target` folder and local `.m2` repository.



## Changelog



Recent changes can be viewed on Github on the [Releases Page](https://github.com/kumuluz/kumuluzee-database-schema-migrations/releases)



## Contribute



See the [contributing docs](https://github.com/kumuluz/kumuluzee-database-schema-migrations/blob/master/CONTRIBUTING.md)



When submitting an issue, please follow the

[guidelines](https://github.com/kumuluz/kumuluzee-database-schema-migrations/blob/master/CONTRIBUTING.md#bugs).



When submitting a bugfix, write a test that exposes the bug and fails before applying your fix. Submit the test

alongside the fix.



When submitting a new feature, add tests that cover the feature.



## License



MIT