Share your experience with Database DevOps by taking part in the 2021 State of Database DevOps survey Take the survey
Flyway follows an Open Source model for the Community edition. We welcome code contributions through Pull Requests on the Flyway GitHub page. This article will provide help with contributing code to make Flyway support a new database platform.
Flyway supports migrations for a large number of database platforms in a unified and consistent way. It does this by abstracting away the details of each database into a set of classes for each platform, plus factory classes that construct the appropriate objects for the database at hand; all communication with the database is done through a JDBC connection. The advantage of this approach is that JDBC is a widely adopted standard; with little more than a JDBC driver and knowledge of the SQL dialect used by a database it is possible to add Flyway support.
We welcome pull requests for database support, but not all requests are automatically accepted. Once support for a new database platform is introduced, we become responsible for ongoing maintenance. Maintenance of a database platform has a cost, which has to be balanced against our other priorities for Flyway.
Before we can support a database platform, we need an effective way of testing against an instance of that platform. This generally takes the form of a Docker image per version for on-premise databases, or a test account with a cloud provider. Unfortunately, it’s not always possible to access a test instance without excessive cost.
Finally, contributions need to be based on a recent fork of the Flyway repository with no merge conflicts, and also meet the high bar we set for Flyway’s code standard – we can provide advice and code review.
Note for organizations: let us know whether you will allow us to ship your JDBC driver with Flyway. This helps us deliver a more frictionless out-of-the-box experience for end users. If you follow step 2 below, this will happen automatically.
Fork the Flyway repo. If you’re using IntelliJ, you should be able to open the Flyway top level folder and see a number of projects. Copy the file
/flyway-commandline/src/main/assembly/flyway.conf to an accessible location on your machine. This location will be a temporary ‘scratch’ area for testing. Use this copy to set up the following properties:
flyway.url- the JDBC URL of your development database
flyway.user- the user account
flyway.password- the password to the database
flyway.locations- to point to an accessible folder where you can put test migrations.
You can now set up a run configuration in your IDE that will compile Flyway and run using your newly created configuration:
info -X -configFiles=<scratch location>\flyway.conf
Flyway itself should start. Since Flyway doesn’t yet support your database you should see a message like:
org.flywaydb.core.api.FlywayException: Unable to autodetect JDBC driver for url: jdbc:mydatabase://<host>:<port>/<databasename>
You’re now ready to start adding that database support. We’re going to assume your database platform is called FooDb. Change the obvious naming conventions to suit your database.
Here are all the changes and additions you’ll need to make:
.pomif you wish the driver to be automatically shipped with the Flyway product.
flyway.conf, document the format of the JDBC connection url for your database. This is not necessary to make Flyway work but it will help adoption of your database!
DriverDataSource.DriverTypeenumeration for your database. You will need to specify the JDBC url prefix and the driver class it should instantiate.
DatabaseTypeenumeration for your database. You will need to specify the JDBC type used to represent NULL in prepared statements for your database, and whether the database supports read-only transactions. Then add a case to
DatabaseType.fromProductNameAndVersion()which should return this DatabaseType when the JDBC connection metadata contains a specific database name. Once you have done this, Flyway can select the correct JDBC driver and other classes for this configuration.
FooDatabase(subclassed from Database),
FooSchema(subclassed from Schema), and
FooTable(subclassed from Table), using the canonical signatures. These classes make up Flyway’s internal representation of the parts of your database that it works on.
FooParser(subclassed from Parser) using the canonical signature. This represents a simplified version of a parser for your database’s dialect of SQL. When finished it will be able to decompose a migration script into separate statements and report on serious errors, but it does not need to fully understand them.
DatabaseFactory, add cases to
createParser()that construct these two objects. We will come back to override methods on these classes later.
Connection<FooDatabase>using the canonical signature. This represents a JDBC connection to your database. You probably won’t use it in isolation but it is an important component of a
JdbcTemplate, which provides numerous convenience methods for running queries on your database.
FooConnection, you can use the
Connectionto query for any database properties that you need to acquire immediately and maintain as part of the state of the connection. You will need to override the following methods as a minimum:
doRestoreOriginalState()– to reset anything that a migration may have changed
getCurrentSchemaNameOrSearchPath()– to return the current database schema for the connection, if this is a concept in your database, or the default schema name if not.
doChangeCurrentSchemaOrSearchPath()– to change the current database schema, if this is a concept in your database. If not, use the default which is a no-op.
getSchema()– to return a constructed
FooDatabaseto customized it to fit the SQL conventions of your database:
doGetConnection()- to return a new
ensureSupported()- to determine which versions of your database will be supported by Flyway. During development, you can leave this as a no-op.
getRawCreateScript()- to return SQL appropriate for your database to create the schema history table. Refer to an existing database type to see the column types needed. The table name will be provided by the table argument. If the baseline argument is true, this method should also insert a row for the baseline migration.
getSelectStatement()– to return SQL appropriate for your database to select all rows from the history table with installed_rank greater than a parameter value.
getInsertStatement()– to return SQL appropriate to insert a row into the history table with nine parameter values (corresponding to the table columns in order).
supportsDdlTransactions()– to return whether the database can support executing DDL statements inside a transaction or not.
supportsChangingCurrentSchema()– to return whether the database can support the concept of a current schema attached to a connection, which can be changed via SQL.
supportsEmptyMigrationDescription()- if your database can’t support an empty string in the description column of the history table verbatim (eg. Oracle implicitly converts it to NULL), override this to return false.
getBooleanFalse()– to return string representations of the Boolean values as used in your database’s dialect of SQL. Typically these are “true” and “false”, but could be, for example, “1” and “0”
doQuote()- to return an escaped version of an identifier for use in SQL. Typically this is the provided value with a double-quote added either side, but could be, for example, square brackets either side as in SQL Server.
catalogIsSchema()– to return true if the database uses a catalog to represent a single schema (eg. MySQL, SQLite); false if a catalog is a collection of schemas.
FooParserto customized it to fit the SQL dialect your database uses:
getDefaultDelimiter()if your database uses something other than a semicolon to delimit separate statements
getIdentifierQuote()if your database uses something other than a double-quote to escape identifiers (eg. MySQL uses backticks)
getAlternativeIdentifierQuote()if your database has a second way to escape identifiers in addition to double-quotes.
getAlternativeStringLiteralQuote()if your database has a second way to mark string literals in addition to single-quotes (eg. MySql allows double-quotes)
getValidKeywords()if your database has a different set of valid keywords to the standard ones. It’s not strictly necessary to include keywords that cannot be found in migration scripts.
FooSchemato customized it to fit the SQL dialect your database uses:
doExists()– to query whether the schema described exists in the database
doEmpty()– to query whether the schema contains any sub-objects eg. tables, views, procedures.
getObjectCount()– to query the number of objects of a given type that exist in the schema
doCreate()– to create the schema in the database
doDrop()– to drop the schema in the database
doClean()– to drop all the objects that exist in the schema
doAllTables()– to query for all the tables in the schema and return a populated array of
getTable()– to return a
FooTableobject for the given name
FooTableto customized it to fit the SQL dialect your database uses:
doDrop()– to drop the table
doExists()– to query whether the table described exists in the database
doLock()– to lock the table with a read/write pessimistic lock until the end of the current transaction. This is used to prevent concurrent reads and writes to the schema history while a migration is underway. If your database doesn’t support table-level locks, do nothing.
You should at this point be able to run the
flyway info build configuration and see an empty version history. Congratulations! You have got a basic implementation up and running. You can now start creating migration scripts and running
flyway migrate on them.
Basic SQL scripts should run with few problems, but you may find more edge cases, particularly in
Parser. Look at the existing overrides for existing platforms for examples of how to deal with them. If you find you need to make more invasive changes in the core of Flyway, please do contact us for advice. We will need to test bigger changes ourselves against all our test instances before we can accept them.