Skip to content

Commit

Permalink
Add flyway defaults properties, autoloading default config file (#19)
Browse files Browse the repository at this point in the history 
* Add flyway defaults properties

* Basedir prop

* Move last section about dependency

* Update readme

* Fix readme review

* Db block

* Two empty lines instead of html br
  • Loading branch information
@romchellis
romchellis authored Jul 5, 2023
1 parent 7bc9033 commit 7ee5199
Show file tree
Hide file tree
Showing 40 changed files with 483 additions and 463 deletions.
304 changes: 192 additions & 112 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,140 +1,220 @@
# testcontainers-jooq-codegen-maven-plugin

The `testcontainers-jooq-codegen-maven-plugin` simplifies the jOOQ code generation
The `testcontainers-jooq-codegen-maven-plugin` simplifies the jOOQ code generation
by using [Testcontainers](https://www.testcontainers.org/) and applying database migrations.

[![Build](https://github.com/testcontainers/testcontainers-jooq-codegen-maven-plugin/actions/workflows/build.yml/badge.svg)](https://github.com/testcontainers/testcontainers-jooq-codegen-maven-plugin/actions/workflows/build.yml)

## Supported databases:
* Postgres
* MySQL
* MariaDB
## Summary

## Supported migration tools:
* Flyway - [supported properties](https://flywaydb.org/documentation/configuration/parameters/ )
* Liquibase - [supported properties](src/main/java/org/testcontainers/jooq/codegen/migration/runner/LiquibaseRunner.java)
- Plugin migration and code generation might be skipped using `skip` property
- If you need to reuse existing database connection - take a look at [Jooq section](#Jooq)

## How to use?
## Database Configuration
To configure a target database, you need to specify at least database `type` property.

1. **With PostgreSQL and Flyway/Liquibase migrations**
#### Properties

| Parameter | Required | Default value | Description |
|----------------|----------|----------------------------------------------------------------------------|----------------------------------------------------------------|
| type | yes | | Database implementation one of: `POSTGRES` `MYSQL` `MARIADB` |
| containerImage | | Provided from database type,usually latest version from official container | Image of used container if not default picked |
| username | | Provided from database container if not specified | Database username for container |
| password | | Provided from database container if not specified | Database password for container |
| databaseName | | Provided from database container if not specified | Database name for container |

#### `database` block configuration

```xml

<project>
<properties>
<project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
<maven.compiler.source>17</maven.compiler.source>
<maven.compiler.target>17</maven.compiler.target>
<testcontainers.version>1.18.3</testcontainers.version>
<testcontainers-jooq-codegen-maven-plugin.version>0.0.2</testcontainers-jooq-codegen-maven-plugin.version>
<jooq.version>3.18.3</jooq.version>
<postgresql.version>42.6.0</postgresql.version>
</properties>
<database>
<type>POSTGRES</type>
<containerImage>postgres:15-alpine</containerImage>
<username>test</username>
<password>test</password>
<databaseName>test</databaseName>
</database>
```

## Migration tools:

### Flyway

Flyway works the same way as the original plugin
Please find original documentation by link https://flywaydb.org/documentation/usage/maven/

#### Configuration

At runtime default configuration files will be autoloaded as it documented -
https://flywaydb.org/documentation/configuration/configfile
Currently, the plugin supports all properties existing in Flyway
You can find them by original link
https://flywaydb.org/documentation/configuration/parameters/
<b>Now [config files parameter](https://flywaydb.org/documentation/configuration/parameters/configFiles) is not
implemented yet</b>

#### `flyway` block configuration

- Zero configuration with defaults

```xml

<flyway/>
```

- Adding properties

```xml

<flyway>
<defaultSchema>bank</defaultSchema>
<createSchemas>true</createSchemas>
<table>my_custom_history_table</table>
<locations>
filesystem:src/main/resources/db/migration/postgres,
filesystem:src/main/resources/db/migration/postgresql
</locations>
</flyway>
```

### Liquibase

Liquibase's configuration works the same way as the original maven plugin, with some limitations
Please find documentation by
link https://docs.liquibase.com/tools-integrations/maven/using-liquibase-and-maven-pom-file.html

#### Properties

Now supports only the most useful properties

| Property | Required | type |
|--------------------------------|----------|--------|
| changeLogPath | yes | String |
| changeLogDirectory | | String |
| parameters | | Map |
| defaultSchemaName | | String |
| liquibaseSchemaName | | String |
| databaseChangeLogTableName | | String |
| databaseChangeLogLockTableName | | String |

Reference to Liquibase properties - https://docs.liquibase.com/concepts/connections/creating-config-properties.html

#### `liquibase` block configuration

```xml

<liquibase>
<changeLogPath>db.changelog-root.xml</changeLogPath>
<changeLogDirectory>src/main/resources/db/changelog</changeLogPath>
</liquibase>
```

### JOOQ

#### Properties

`generator` - property to configure JOOQ code generation settings.
See https://www.jooq.org/doc/latest/manual/code-generation/codegen-configuration for all the supporting configuration
properties.
`configurationFiles` / `configurationFile` - are not implemented yet
`jdbc` - if contains all required jdbc parameters (url,name,password) -
existing database will be used, no container won't be spin up
`baseDir` - directory relative to which generated sources will be generated , `{project.basedir}` - default

#### `jooq` block configuration

```xml

<jooq>
<generator>
<database>
...
</database>
</generator>
<jdbc>
....
</jdbc>
</jooq>
```

#### Plugin dependencies configuration

```xml

<dependency>
<groupId>org.postgresql</groupId>
<artifactId>postgresql</artifactId>
<version>${postgresql.version}</version>
</dependency>
```

## Examples

### Complete example
Example with `PostgreSQL` and minimal configuration with `Flyway` and `JOOQ`
```xml
<plugin>
<groupId>org.testcontainers</groupId>
<artifactId>testcontainers-jooq-codegen-maven-plugin</artifactId>
<version>${testcontainers-jooq-codegen-maven-plugin.version}</version>
<dependencies>
<dependency>
<groupId>org.jooq</groupId>
<artifactId>jooq</artifactId>
<version>${jooq.version}</version>
<groupId>org.testcontainers</groupId>
<artifactId>postgresql</artifactId>
<version>${testcontainers.version}</version>
</dependency>
<dependency>
<groupId>org.postgresql</groupId>
<artifactId>postgresql</artifactId>
<version>${postgresql.version}</version>
</dependency>
</dependencies>
<build>
<plugins>
<plugin>
<groupId>org.testcontainers</groupId>
<artifactId>testcontainers-jooq-codegen-maven-plugin</artifactId>
<version>${testcontainers-jooq-codegen-maven-plugin.version}</version>
<dependencies>
<dependency>
<groupId>org.testcontainers</groupId>
<artifactId>postgresql</artifactId>
<version>${testcontainers.version}</version>
</dependency>
<dependency>
<groupId>org.postgresql</groupId>
<artifactId>postgresql</artifactId>
<version>${postgresql.version}</version>
</dependency>
</dependencies>
<executions>
<execution>
<id>generate-jooq-sources</id>
<goals>
<goal>generate</goal>
</goals>
<phase>generate-sources</phase>
<configuration>
<database>
<!--
"type" can be: POSTGRES, MYSQL, MARIADB
-->
<type>POSTGRES</type>
<!--
"containerImage" is optional.
The defaults are
POSTGRES: postgres:15.2-alpine
MYSQL: mysql:8.0.33
MARIADB: mariadb:10.11
-->
<containerImage>postgres:15.2-alpine</containerImage>
<username>test</username> <!-- optional -->
<password>test</password> <!-- optional -->
<databaseName>test</databaseName> <!-- optional -->
</database>
<flyway>
<!--
You can configure any supporting flyway config here.
see https://flywaydb.org/documentation/configuration/parameters/
-->
<defaultSchema>bank</defaultSchema> <!-- optional -->
<createSchemas>true</createSchemas> <!-- optional -->
<locations> <!-- optional -->
filesystem:src/main/resources/db/migration/postgres,
filesystem:src/main/resources/db/migration/postgresql
</locations>
</flyway>
<!-- or
Now supports only most useful properties which you can find in LiquibaseRunner.java
https://docs.liquibase.com/concepts/connections/creating-config-properties.html
<liquibase>
<changeLogPath>db.changelog-root.xml</changeLogPath>
<changeLogDirectory>src/main/resources/db/changelog</changeLogPath>
</liquibase> -->
<!--
You can configure any supporting jooq config here.
see https://www.jooq.org/doc/latest/manual/code-generation/codegen-configuration/
-->
<jooq>
<skip>false</skip> <!-- optional -->
<generator>
<database>
<includes>.*</includes>
<excludes>flyway_schema_history</excludes>
<inputSchema>public</inputSchema>
</database>
<target>
<packageName>org.jooq.codegen.maven.example</packageName>
<directory>target/generated-sources/jooq</directory>
</target>
</generator>
</jooq>
</configuration>
</execution>
</executions>
</plugin>
</plugins>
</build>
</project>
<executions>
<execution>
<id>generate-jooq-sources</id>
<goals>
<goal>generate</goal>
</goals>
<phase>generate-sources</phase>
<configuration>
<database>
<type>POSTGRES</type>
</database>
<flyway/>
<jooq>
<generator>
<database>
<includes>.*</includes>
<inputSchema>public</inputSchema>
</database>
<target>
<packageName>org.jooq.codegen.maven.example</packageName>
<directory>target/generated-sources/jooq</directory>
</target>
</generator>
</jooq>
</configuration>
</execution>
</executions>
</plugin>
```

Try with example application
### More examples

[MariaDB + Flyway](examples/mariadb-flyway-example )
[MySQL + Flyway](examples/mysql-flyway-example )
[Postgres + Flyway](examples/postgres-flyway-example )
[Postgres + Liquibase](examples/postgres-liquibase-example )

### Try with example application

```shell
$ cd examples/postgres-flyway-example
$ mvn clean package
```

The JOOQ code should be generated under `example/target/generated-sources/jooq` folder.
The JOOQ code should be generated under example/target/generated-sources/jooq folder.

## CREDITS:

This plugin is heavily based on official https://github.com/jOOQ/jOOQ/tree/main/jOOQ-codegen-maven.
8 changes: 2 additions & 6 deletions examples/mariadb-flyway-example/pom.xml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -14,7 +14,7 @@
<maven.compiler.target>17</maven.compiler.target>
<project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
<testcontainers.version>1.18.3</testcontainers.version>
<testcontainers-jooq-codegen-maven-plugin.version>0.0.2</testcontainers-jooq-codegen-maven-plugin.version>
<testcontainers-jooq-codegen-maven-plugin.version>0.0.3-SNAPSHOT</testcontainers-jooq-codegen-maven-plugin.version>
<jooq.version>3.18.3</jooq.version>
<mariadb-java-client.version>3.1.2</mariadb-java-client.version>
</properties>
Expand Down Expand Up @@ -59,11 +59,7 @@
<password>test</password> <!-- optional -->
<databaseName>test</databaseName> <!-- optional -->
</database>
<flyway>
<locations>
filesystem:src/main/resources/db/migration/mariadb
</locations>
</flyway>
<flyway/>
<!-- Generator parameters -->
<jooq>
<generator>
Expand Down
0 ...b/migration/mariadb/V1__create_tables.sql → ...ources/db/migration/V1__create_tables.sql
View file
File renamed without changes.
8 changes: 2 additions & 6 deletions examples/mysql-flyway-example/pom.xml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -14,7 +14,7 @@
<maven.compiler.target>17</maven.compiler.target>
<project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
<testcontainers.version>1.18.3</testcontainers.version>
<testcontainers-jooq-codegen-maven-plugin.version>0.0.2</testcontainers-jooq-codegen-maven-plugin.version>
<testcontainers-jooq-codegen-maven-plugin.version>0.0.3-SNAPSHOT</testcontainers-jooq-codegen-maven-plugin.version>
<jooq.version>3.18.3</jooq.version>
<mysql-connector-j.version>8.0.32</mysql-connector-j.version>
</properties>
Expand Down Expand Up @@ -59,11 +59,7 @@
<password>test</password> <!-- optional -->
<databaseName>test</databaseName> <!-- optional -->
</database>
<flyway>
<locations>
filesystem:src/main/resources/db/migration/mysql
</locations>
</flyway>
<flyway/>
<!-- Generator parameters -->
<jooq>
<generator>
Expand Down
0 .../db/migration/mysql/V1__create_tables.sql → ...ources/db/migration/V1__create_tables.sql
View file
File renamed without changes.
3 changes: 3 additions & 0 deletions examples/postgres-flyway-example/flyway.conf
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,3 @@
flyway.table=config_overridden_history_table
flyway.defaultSchema=overridden
flyway.createSchemas=true
Loading

0 comments on commit 7ee5199

Please sign in to comment.