Code - Flyway Plugin Development
Published 25 October 2023
Code: Flyway Plugin Development
Between Flyway 9.0.0 and Flyway 10.0.0, the architecture of Flyway has changed significantly to a modularized system. This has made it easier to develop plugins for Flyway to expand its capabilities and allow for a more streamlined approach for contributions. This tutorial will walk you through the steps of creating a plugin for Flyway 10.0.0.
Creating a Flyway plugin
To create a Flyway plugin, you will need to create a new Maven module depending on the flyway-core
module and any other modules related to your database type.
For example, if you are creating a database support plugin for a PostgreSQL variation, you will need to depend on the flyway-core
and flyway-database-postgresql
modules.
Plugins are loaded in Flyway via the Flyway Plugin Register which uses the Java ServiceLoader
to load plugins at runtime.
To do this you will need a class which implements org.flywaydb.core.extensibility.Plugin
or a child interface and to create a file in src/main/resources/META-INF/services
called org.flywaydb.core.extensibility.Plugin
which contains the fully qualified name of your plugin class.
Example org.flywaydb.core.extensibility.Plugin
:
org.flywaydb.database.cockroachdb.CockroachDBDatabaseType
org.flywaydb.database.postgresql.PostgreSQLDatabaseType
org.flywaydb.database.postgresql.PostgreSQLConfigurationExtension
Plugin types
Flyway is now expandable via the Plugin interface within flyway-core
. This interface allows flyway to load plugins at runtime to use them to extend its functionality and can be extended to provide helper interfaces for specific functionality.
For the purposes of this tutorial, we will be explaining the following plugin types:
PluginMetadata
DatabaseType
ConfigurationExtension
PluginMetadata
The PluginMetadata
interface (org.flywaydb.core.extensibility.PluginMetadata
) is used to provide Flyway with metadata about a plugin.
DatabaseType
Open source database plugins have been moved to a separate repository, see: Contributing Database Compatibility to Flyway
ConfigurationExtension
The ConfigurationExtension
interface (org.flywaydb.core.extensibility.ConfigurationExtension
) is used to provide Flyway with the ability to support new configuration options. This is usually used to provide new configuration options for plugins.
ConfigurationExtensions
require the following methods to be implemented:
String getNamespace()
- This is the namespace for the configuration option under theflyway
configuration domain. This is used to group configuration options together. For example the configurationflyway.postgresql.transactional.lock
has the namespacepostgresql
String getConfigurationParameterFromEnvironmentVariable(String environmentVariable)
- This is used to get the configuration parameter from an environment variable. This is used to allow users to set configuration options via environment variables. For example, the configurationflyway.postgresql.transactional.lock
can be set via the environment variableFLYWAY_POSTGRESQL_TRANSACTIONAL_LOCK
. This is only necessary for legacy Flyway configuration. If you are using new Flyway configuration, the Environment Variable format will by default be screaming snake case of your configuration option's path.
Flyway Plugin Archetype
To make it easier to create plugins for Flyway, we have created a Maven archetype to create a basic plugin project.
This archetype can be found in the flyway-plugin-archetype
module in the flyway
repository.
Installing locally
If you wish to compile the Flyway Plugin Archetype locally, you can do so by running the following command from the root of the flyway
repository:
mvn clean install -DskipTests -DskipIts -pl flyway-plugin-archetype -am
Using the archetype
To create a new Flyway plugin project via commandline, run the following command:
mvn archetype:generate -DarchetypeGroupId=org.flywaydb
-DarchetypeArtifactId=flyway-plugin-archetype
-DarchetypeVersion=10.0.0
-DgroupId=org.flywaydb
-DartifactId=my-flyway-plugin
-Dversion=10.0.1-SNAPSHOT
-Dpackage=org.flywaydb.community.database.myflywayplugin
If using IntelliJ, you can create a new project by selecting File > New > Project...
and selecting Maven Archetype
from the list of project types.
Then fill in with the appropriate information, see below, and click create
:
This will create a new project in the my-flyway-plugin
directory.
This directory will contain the following:
- a
pom.xml
file which you can use to build your plugin - a
src/main/java
directory containing the source code for your plugin - a
src/test/java
directory containing unit tests for your plugin - a basic Plugin class which you can extend to implement your plugin in the package specified in your generate command
- a
META-INF/services
directory containing a file which you can use to register your plugin with Flyway.