Skip to content

Commit

Permalink
- README.md
Browse files Browse the repository at this point in the history
- Api improvements
  • Loading branch information
pefernan committed Sep 27, 2024
1 parent 7883791 commit c868a3a
Show file tree
Hide file tree
Showing 28 changed files with 797 additions and 498 deletions.
24 changes: 13 additions & 11 deletions addons/common/flyway/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -33,13 +33,15 @@ instead of using the Platform (Quarkus/Springboot) specific Flyway integration,
* Multi DB Support: a single module can provide SQL scripts for different DB vendors (and default as a fallback) that
will be loaded depending on the application configuration

> *IMPORTANT*: The usage of this add-on should be reserved only for development/test/examples purposes and not it is not recommended
> *IMPORTANT*: The usage of this add-on should be reserved only for development/test/examples purposes, and it is not recommended
> using it in productive environments.


## KIE Flyway Module Configuration

In order to allow the *KIE Flyway Initializer* identify the DB needs of a specific component (`extensions` or `add-on`)
the component has meet the following requirements:
the component has to meet the following requirements:

* Provide a `kie-flyway.properties` descriptor file in `/src/main/resources/META-INF/kie-flyway.properties`. The file
should provide the following information:
Expand All @@ -50,7 +52,8 @@ the component has meet the following requirements:
* `module.locations.<db>`: map containing the module `.sql` scripts location paths organized by database type (`postgresql`, `h2`...) to initialize the DB
(ej: `module.locations.postgresql=classpath:kie-flyway/db/test-module/postgresql`), the locations can be a comma-separated list to use multiple `.sql` locations in a single migration.
It's also possible using a `default` locations (`module.locations.default=...`) as a fallback to provide a default initialization
if no vendor-specific isn't available.
if no vendor-specific isn't available. It is important to avoid using the default flyway location (`src/main/resourcs/db/migrations`) to avoid
collisions with the Platform Flyway integration.

Example of `kie-flyway.properties` file:
```properties
Expand Down Expand Up @@ -106,20 +109,19 @@ kie.flyway.modules."jobs-service".enabled=false
```

## Usage
KIE Flyway is exposes the `KieFlywayInitializer` as entry point of the add-on and exposes a Fluent Api to configure it
and run it. This component will be incharge of loading all the `kie-flyway.properties` available in the application and run
KIE Flyway exposes the `KieFlywayInitializer` as entry point of the add-on and exposes a Fluent Api to configure it
and run it. This component will be in charge of loading all the `kie-flyway.properties` available in the application and run
migrations for each of them.

The required information that must be provided to the initializer is:
* DataSource (`java.sql.DataSource`) where the initialization should be executed. It should be the default application Data Source
* Data Base Type (`java.lang.String`) to identify the which script locations should be loaded.


```java
import org.kie.flyway.KieFlywayInitializer;
import org.kie.flyway.initializer.KieFlywayInitializer;

...
KieFlywayInitializer.builder()
KieFlywayInitializer.builder()
.withDbType("postgresql")
.withDatasource(dataSource)
.build()
Expand All @@ -131,10 +133,10 @@ Additional Parameters that can be used:
* Module Exclusions (`Collection<String>`) t

```java
import org.kie.flyway.KieFlywayInitializer;
import org.kie.flyway.initializer.KieFlywayInitializer;

...
KieFlywayInitializer.builder()
KieFlywayInitializer.builder()
.withDbType("postgresql")
.withDatasource(dataSource)
.withClassLoader(this.getClass().getClassLoader())
Expand All @@ -143,7 +145,7 @@ KieFlywayInitializer.builder()
.migrate();
```

> NOTE: The platform-specific add-ons (Quarkus/Spring-Boot) will be in charged obtain the DataSource and DataBase type
> NOTE: The platform-specific add-ons (Quarkus/Spring-Boot) will be in charge to obtain the DataSource and DataBase type
> and correctly configure the `KieFlywayInitializer` according to the `application.properties` and use it on during the application startup.

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -17,15 +17,16 @@
* under the License.
*/

package org.kie.flyway;
package org.kie.flyway.initializer;

import java.util.*;
import java.util.stream.Collectors;

import javax.sql.DataSource;

import org.flywaydb.core.Flyway;
import org.kie.flyway.impl.DefaultKieModuleFlywayConfigLoader;
import org.kie.flyway.KieFlywayException;
import org.kie.flyway.initializer.impl.DefaultKieModuleFlywayConfigLoader;
import org.kie.flyway.model.KieFlywayModuleConfig;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -17,7 +17,7 @@
* under the License.
*/

package org.kie.flyway;
package org.kie.flyway.initializer;

import java.util.Collection;

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -17,7 +17,7 @@
* under the License.
*/

package org.kie.flyway.impl;
package org.kie.flyway.initializer.impl;

import java.io.File;
import java.io.InputStream;
Expand All @@ -26,7 +26,7 @@
import java.util.stream.Collectors;

import org.kie.flyway.KieFlywayException;
import org.kie.flyway.KieModuleFlywayConfigLoader;
import org.kie.flyway.initializer.KieModuleFlywayConfigLoader;
import org.kie.flyway.model.KieFlywayModuleConfig;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
Expand Down
Original file line number Diff line number Diff line change
@@ -0,0 +1,29 @@
/*
* Licensed to the Apache Software Foundation (ASF) under one
* or more contributor license agreements. See the NOTICE file
* distributed with this work for additional information
* regarding copyright ownership. The ASF licenses this file
* to you under the Apache License, Version 2.0 (the
* "License"); you may not use this file except in compliance
* with the License. You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing,
* software distributed under the License is distributed on an
* "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
* KIND, either express or implied. See the License for the
* specific language governing permissions and limitations
* under the License.
*/

package org.kie.flyway.integration;

import java.util.Map;

public interface KieFlywayConfiguration<T extends KieFlywayNamedModule> {

boolean isEnabled();

Map<String, T> getModules();
}
Original file line number Diff line number Diff line change
@@ -0,0 +1,25 @@
/*
* Licensed to the Apache Software Foundation (ASF) under one
* or more contributor license agreements. See the NOTICE file
* distributed with this work for additional information
* regarding copyright ownership. The ASF licenses this file
* to you under the Apache License, Version 2.0 (the
* "License"); you may not use this file except in compliance
* with the License. You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing,
* software distributed under the License is distributed on an
* "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
* KIND, either express or implied. See the License for the
* specific language governing permissions and limitations
* under the License.
*/

package org.kie.flyway.integration;

public interface KieFlywayNamedModule {

boolean isEnabled();
}
Original file line number Diff line number Diff line change
@@ -0,0 +1,101 @@
/*
* Licensed to the Apache Software Foundation (ASF) under one
* or more contributor license agreements. See the NOTICE file
* distributed with this work for additional information
* regarding copyright ownership. The ASF licenses this file
* to you under the Apache License, Version 2.0 (the
* "License"); you may not use this file except in compliance
* with the License. You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing,
* software distributed under the License is distributed on an
* "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
* KIND, either express or implied. See the License for the
* specific language governing permissions and limitations
* under the License.
*/

package org.kie.flyway.integration;

import java.sql.Connection;
import java.sql.DatabaseMetaData;
import java.util.Collection;
import java.util.Map;
import java.util.Objects;

import javax.sql.DataSource;

import org.kie.flyway.KieFlywayException;
import org.kie.flyway.initializer.KieFlywayInitializer;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;

public class KieFlywayRunner {
private static final Logger LOGGER = LoggerFactory.getLogger(KieFlywayRunner.class);

private final KieFlywayConfiguration<? extends KieFlywayNamedModule> configuration;

private KieFlywayRunner(KieFlywayConfiguration<? extends KieFlywayNamedModule> configuration) {
this.configuration = configuration;
}

public static KieFlywayRunner get(KieFlywayConfiguration configuration) {
return new KieFlywayRunner(configuration);
}

public void runFlyway(DataSource dataSource) {
this.runFlyway(dataSource, null, Thread.currentThread().getContextClassLoader());
}

public void runFlyway(DataSource dataSource, String dbType, ClassLoader classLoader) {
assertValue(configuration, "Kie Flyway: Cannot run Kie Flyway migration configuration is null.");

if (!configuration.isEnabled()) {
LOGGER.warn("Kie Flyway is disabled, skipping initialization.");
return;
}

assertValue(dataSource, "Kie Flyway: Cannot run Kie Flyway migration default datasource is null");

if (Objects.isNull(dbType)) {
LOGGER.warn("dbType is not set, trying to resolve it from database");
dbType = this.getDataSourceType(dataSource);
}

assertValue(dbType, "Kie Flyway: Cannot run Kie Flyway migration `dbType` is null.");

Collection<String> excludedModules = configuration.getModules()
.entrySet()
.stream().filter(entry -> !entry.getValue().isEnabled())
.map(Map.Entry::getKey)
.toList();

KieFlywayInitializer.builder()
.withDatasource(dataSource)
.withDbType(dbType)
.withClassLoader(classLoader)
.withModuleExclusions(excludedModules)
.build().migrate();

}

private void assertValue(Object value, String message) {
if (Objects.isNull(value)) {
LOGGER.warn(message);
throw new KieFlywayException(message);
}
}

private String getDataSourceType(DataSource dataSource) {
try (Connection con = dataSource.getConnection()) {
DatabaseMetaData metadata = con.getMetaData();
return metadata.getDatabaseProductName();
} catch (Exception e) {
LOGGER.error("Kie Flyway: Couldn't extract database product name from datasource ", e);
}
return null;
}

}
Loading

0 comments on commit c868a3a

Please sign in to comment.