Skip to content

Commit

Permalink
Merge branch 'develop' into update-from-template-merged
Browse files Browse the repository at this point in the history
  • Loading branch information
xdev-gh-bot committed Oct 14, 2024
2 parents 743c5c6 + ef17d82 commit d7cca41
Show file tree
Hide file tree
Showing 89 changed files with 5,327 additions and 77 deletions.
4 changes: 2 additions & 2 deletions .github/ISSUE_TEMPLATE/bug_report.yml
Original file line number Diff line number Diff line change
Expand Up @@ -14,9 +14,9 @@ body:
attributes:
label: "Checklist"
options:
- label: "I am able to reproduce the bug with the [latest version](https://github.com/xdev-software/template-placeholder/releases/latest)"
- label: "I am able to reproduce the bug with the [latest version](https://github.com/xdev-software/micro-migration/releases/latest)"
required: true
- label: "I made sure that there are *no existing issues* - [open](https://github.com/xdev-software/template-placeholder/issues) or [closed](https://github.com/xdev-software/template-placeholder/issues?q=is%3Aissue+is%3Aclosed) - which I could contribute my information to."
- label: "I made sure that there are *no existing issues* - [open](https://github.com/xdev-software/micro-migration/issues) or [closed](https://github.com/xdev-software/micro-migration/issues?q=is%3Aissue+is%3Aclosed) - which I could contribute my information to."
required: true
- label: "I have taken the time to fill in all the required details. I understand that the bug report will be dismissed otherwise."
required: true
Expand Down
2 changes: 1 addition & 1 deletion .github/ISSUE_TEMPLATE/enhancement.yml
Original file line number Diff line number Diff line change
Expand Up @@ -12,7 +12,7 @@ body:
attributes:
label: "Checklist"
options:
- label: "I made sure that there are *no existing issues* - [open](https://github.com/xdev-software/template-placeholder/issues) or [closed](https://github.com/xdev-software/template-placeholder/issues?q=is%3Aissue+is%3Aclosed) - which I could contribute my information to."
- label: "I made sure that there are *no existing issues* - [open](https://github.com/xdev-software/micro-migration/issues) or [closed](https://github.com/xdev-software/micro-migration/issues?q=is%3Aissue+is%3Aclosed) - which I could contribute my information to."
required: true
- label: "I have taken the time to fill in all the required details. I understand that the feature request will be dismissed otherwise."
required: true
Expand Down
2 changes: 1 addition & 1 deletion .github/ISSUE_TEMPLATE/question.yml
Original file line number Diff line number Diff line change
Expand Up @@ -12,7 +12,7 @@ body:
attributes:
label: "Checklist"
options:
- label: "I made sure that there are *no existing issues* - [open](https://github.com/xdev-software/template-placeholder/issues) or [closed](https://github.com/xdev-software/template-placeholder/issues?q=is%3Aissue+is%3Aclosed) - which I could contribute my information to."
- label: "I made sure that there are *no existing issues* - [open](https://github.com/xdev-software/micro-migration/issues) or [closed](https://github.com/xdev-software/micro-migration/issues?q=is%3Aissue+is%3Aclosed) - which I could contribute my information to."
required: true
- label: "I have taken the time to fill in all the required details. I understand that the question will be dismissed otherwise."
required: true
Expand Down
16 changes: 0 additions & 16 deletions .run/Run Demo.run.xml

This file was deleted.

37 changes: 37 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,37 @@
## 2.0.0
_Major refactoring_
* Consolidated all previous modules into a single one
* Dropped support for MicroStream as EclipseStore is it's successor
* Refactored and adjusted code accordingly
* Slimed down dependencies
* Minimal required Java version: 17

## 1.0.0
* Added support for EclipseStore v1
* Updated plenty of libraries

## 0.0.9
* Added support for MicroStream v8

## 0.0.8
* Access to the native embedded manager is now possible in the scripts (see ``VersionAgnosticMigrationEmbeddedStorageManager#getNativeStorageManager``)

## 0.0.7
* A lot of refactoring of the module structure
* A migration history is now available and automatically stored

## 0.0.6
* Tried a new release-action...again.

## 0.0.5
* Tried a new release-action.

## 0.0.4
* Fixed setup. 0.0.3 was not working with the release setup.

## 0.0.3
* Restructured the complete maven modules. Multiple MicroStream-Versions are now supported.
* Added plenty of documentation

## 0.0.2
* Updated MicroStream from v4 to v5.
4 changes: 2 additions & 2 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -34,10 +34,10 @@ You should have the following things installed:
* Ensure that the JDK/Java-Version is correct


## Releasing [![Build](https://img.shields.io/github/actions/workflow/status/xdev-software/template-placeholder/release.yml?branch=master)](https://github.com/xdev-software/template-placeholder/actions/workflows/release.yml)
## Releasing [![Build](https://img.shields.io/github/actions/workflow/status/xdev-software/micro-migration/release.yml?branch=master)](https://github.com/xdev-software/micro-migration/actions/workflows/release.yml)

Before releasing:
* Consider doing a [test-deployment](https://github.com/xdev-software/template-placeholder/actions/workflows/test-deploy.yml?query=branch%3Adevelop) before actually releasing.
* Consider doing a [test-deployment](https://github.com/xdev-software/micro-migration/actions/workflows/test-deploy.yml?query=branch%3Adevelop) before actually releasing.
* Check the [changelog](CHANGELOG.md)

If the ``develop`` is ready for release, create a pull request to the ``master``-Branch and merge the changes
Expand Down
120 changes: 114 additions & 6 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,12 +1,120 @@
[![Latest version](https://img.shields.io/maven-central/v/software.xdev/template-placeholder?logo=apache%20maven)](https://mvnrepository.com/artifact/software.xdev/template-placeholder)
[![Build](https://img.shields.io/github/actions/workflow/status/xdev-software/template-placeholder/check-build.yml?branch=develop)](https://github.com/xdev-software/template-placeholder/actions/workflows/check-build.yml?query=branch%3Adevelop)
[![Quality Gate Status](https://sonarcloud.io/api/project_badges/measure?project=xdev-software_template-placeholder&metric=alert_status)](https://sonarcloud.io/dashboard?id=xdev-software_template-placeholder)
[![Latest version](https://img.shields.io/maven-central/v/software.xdev/micro-migration?logo=apache%20maven)](https://mvnrepository.com/artifact/software.xdev/micro-migration)
[![Build](https://img.shields.io/github/actions/workflow/status/xdev-software/micro-migration/check-build.yml?branch=develop)](https://github.com/xdev-software/micro-migration/actions/workflows/check-build.yml?query=branch%3Adevelop)
[![Quality Gate Status](https://sonarcloud.io/api/project_badges/measure?project=xdev-software_micro-migration&metric=alert_status)](https://sonarcloud.io/dashboard?id=xdev-software_micro-migration)

# template-placeholder
# <img src="assets/Logo.png" width="400" alt="XDEV MicroMigration Logo">
Tiny java library to migrate [EclipseStore](https://github.com/eclipse-store/store) datastores.
Applies migration scripts on the datastores to keep them up to date.

## Intro
When you think about default database setup, you probably imagine something like this:

![Imaginative system layout](./assets/MigrationSequence_1.png "Imaginative system layout")

Yet in reality most workflows involve different systems like test systems and production systems.
In code this workflow is represented with version-control systems and different branches.

![Code workflow](./assets/MigrationSequence_2.png "Code workflow")

For this code workflow to behave correctly, for each system a separate datastore is needed.
To keep these datastores to represent the correspondend data for the code is a hassle.

![Code workflow with datastore](./assets/MigrationSequence_3.png "Code workflow with datastore")

That's why migration frameworks like [Flyway](https://flywaydb.org) and [Liquibase](https://www.liquibase.org/) exist.
Unfortunately both these frameworks are designed to support any type of SQL databases but no NoSQL databases like [EclipseStore](https://eclipsestore.io/). This led to the creation of this library.

This library delivers an easy concept to keep your EclipseStore datastore versioned with migration scripts written in plain java.
It's easy to create code, that automatically brings a datastore with an older version to the version, suited to the current code.

![Migrate datastore to new version](./assets/MigrationSequence_4.png "Migrate datastore to new version")

## Approaches
There are two possible usages with the Micro migration library:

The **first**, easier approach is to use the `MigrationEmbeddedStorageManager`.
It can be used on a brand new datastore or introduced later, after a EclipseStore datastore is already in use.
Only the storage manager (`MigrationEmbeddedStorageManager`) knows about the versioning.
The rest of application does not know about the version and can have no regards about it.

### MigrationEmbeddedStorageManager
Extensive examples can be found in its own [own module](./micro-migration-demo).
A simple example where scripts need to be registered in the `ExplicitMigrater`:

```java
public static void main(String[] args){
ExplicitMigrater migrater = new ExplicitMigrater(new UpdateToV1_0());
MigrationEmbeddedStorageManager storageManager = MigrationEmbeddedStorage.start(migrater);
// Do some business logic
storageManager.shutdown();
}
```

The update scripts can look like this:

```java
public class UpdateToV1_0 implements MigrationScript<Object>
{
@Override
public MigrationVersion getTargetVersion(){
return new MigrationVersion(1);
}

@Override
public void migrate(Context<String, EmbeddedStorageManager> context){
// Logic of the update
context.getStorageManager().setRoot("Update 1.0");
}
}
```

### MigrationManager
Although the approach with the `MigrationEmbeddedStorageManager` is pretty easy to handle, it is intrusive in the way, that it replaces the root entry point of the EclipseStore datastore and inserts its own `VersionedRoot` as root. Some users might find this too entrusive.

That's why a second approach can be used, where the `MigrationManager` is used. This class is also used internally by the `MigrationEmbeddedStorageManager`.

```java
public static void main(String[] args){
ExplicitMigrater migrater = new ExplicitMigrater(new UpdateToV1_0());
EmbeddedStorageManager storageManager = EmbeddedStorage.start();
VersionedObject<Object> versionedRoot =(VersionedObject<Object>)storageManager.root();
new MigrationManager(versionedRoot, migrater, storageManager).migrate(versionedBranch);
// Do some business logic
storageManager.shutdown();
}
```

## Migrater
### ExplicitMigrater
Scripts for the migrations must be registered in a `MicroMigrater`.
The simplest way for this is to use the `ExplicitMigrater` and just put the scripts in the constructor.
A downside of this method is that you need to register all scripts (new or old) manually in the constructor.

```java
final ExplicitMigrater migrater = new ExplicitMigrater(
new UpdateToV1_0(),
new UpdateToV1_1()
);
```

### ReflectiveMigrater
For a more convenient usage the `ReflectiveMigrater` was built.
You simply instanciate a object of this class with the package name of your `MicroMigrationScript`s.
The `ReflectiveMigrater` will search for any implementations of `MicroMigrationScript` in the given package.
This way scripts can simply be placed in the same package and on startup of the application all scripts are loaded in.

```java
final ReflectiveMigrater migrater = new ReflectiveMigrater("software.xdev.micromigration.examples.reflective.scripts");
```

## Installation
[Installation guide for the latest release](https://github.com/xdev-software/template-placeholder/releases/latest#Installation)
[Installation guide for the latest release](https://github.com/xdev-software/micro-migration/releases/latest#Installation)

### Compatibility
| Eclipse Store version | micro-migration version |
| --- | --- |
| [EclipseStore](https://github.com/eclipse-store/store) 1+ | ``2+`` |
| [MicroStream](https://github.com/microstream-one/microstream) 5-8<br/>EclipseStore 1.1 | ``1.x`` |

## Support
If you need support as soon as possible and you can't wait for any pull request, feel free to use [our support](https://xdev.software/en/services/support).
Expand All @@ -15,4 +123,4 @@ If you need support as soon as possible and you can't wait for any pull request,
See the [contributing guide](./CONTRIBUTING.md) for detailed instructions on how to get started with our project.

## Dependencies and Licenses
View the [license of the current project](LICENSE) or the [summary including all dependencies](https://xdev-software.github.io/template-placeholder/dependencies)
View the [license of the current project](LICENSE) or the [summary including all dependencies](https://xdev-software.github.io/micro-migration/dependencies)
2 changes: 1 addition & 1 deletion SECURITY.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,4 +2,4 @@

## Reporting a Vulnerability

Please report a security vulnerability [on GitHub Security Advisories](https://github.com/xdev-software/template-placeholder/security/advisories/new).
Please report a security vulnerability [on GitHub Security Advisories](https://github.com/xdev-software/micro-migration/security/advisories/new).
Binary file added assets/Logo.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added assets/Logo2.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
1 change: 1 addition & 0 deletions assets/MigrationSequence.drawio
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
<mxfile modified="2020-12-26T15:46:51.284Z" host="app.diagrams.net" agent="5.0 (Windows)" etag="FPBT0h_c40Cmh-uRLp35" version="14.1.2" type="onedrive"><diagram id="l8hXMBHkgcEJcSW0mbfh" name="Page-1">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</diagram></mxfile>
Binary file added assets/MigrationSequence_1.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added assets/MigrationSequence_2.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added assets/MigrationSequence_3.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added assets/MigrationSequence_4.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
21 changes: 21 additions & 0 deletions micro-migration-demo/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,21 @@
# micro-migration-examples
Examples for the MicroMigration-Library

Currently contains four major examples:
## Example with `ExplicitMigrater`
In the package `software.xdev.micromigration.examples.explicit` there is a simple example with explicitly listed upgrade scripts.
This is the most straight forward approach to use migration scripts.

## Example with `ReflectiveMigrater`
In package `software.xdev.micromigration.examples.reflective` a migrater which finds it's scripts through reflection is used.
So here all `MicroMigrationScript`s in the defined `software.xdev.micromigration.examples.reflective.scripts` package are used.

## Practical examples
The package `software.xdev.micromigration.examples.practical.embedded` contains examples
that are just a bit more complex than the other examples and should allow an insight about the usage in a
practical environment.

There is one example implemented with the `MigrationEmbeddedStorageManager` and another with the
plain `MigrationManager`, so it is clear what the difference between these two approaches is.
In both implementations the first update migrates from version 0 to 1 and converts an "old" `BusinessBranch`
to a newer one. The second update only adds more `Customer`s to the existing `BusinessBranch`.
Loading

0 comments on commit d7cca41

Please sign in to comment.