gomoob / grunt-flyway

Run Flyway database migration tool with Grunt.

grunt-flyway

Run Flyway database migration tool with Grunt.

WARNING

This Grunt plugin and has not been tested thoroughly yet so use it at your own risk!

The plugin supports all Flyway configuration options for clean, baseline, migrate, repair, validate and info commands.

Getting Started

Installing the plugin

This plugin requires Grunt ~0.4.2

If you haven't used Grunt before, be sure to check out the Getting Started guide, as it explains how to create a Gruntfile as well as install and use Grunt plugins. Once you're familiar with that process, you may install this plugin with this command:

npm install grunt-flyway --save-dev

One the plugin has been installed, it may be enabled inside your Gruntfile with this line of JavaScript:

grunt.loadNpmTasks('grunt-flyway');

Installing Java

The plugin uses Flyway "The Agile Database Migration Framework" which is developed in Java.

So, you have to install Java and have the java executable available in your PATH.

Flyway version

The plugin uses Flyway 3.2.

The "flyway" task

Overview

In your project's Gruntfile, add a section named flyway to the data object passed into grunt.initConfig().

grunt.initConfig({
  flyway: {
    options: {
      driver: 'com.mysql.jdbc.Driver',
      url: 'jdbc:mysql://localhost/flyway',
      user: 'flyway',
      password: 'flyway'
    },
    clean: {
      command: 'clean'
    },
    baseline: {
      options: {
        baselineDescription: 'Sample database created using Flyway:-)',
        baselineVersion: '1.0'
      },
      command: 'baseline'
    },
    migrate: {
      options: {
        locations: 'filesystem:src/main/resources/sql/migration'
      },
      command: 'migrate'
    }
  }
})

The name of the Grunt targets to use inside the flyway task configuration are not pre-defined, you can choose what you want to name those targets.

Any number of targets can be defined and you can have multiple targets with different configurations, for example:

grunt.initConfig({
  flyway: {
    options: {
      driver: 'com.mysql.jdbc.Driver',
      url: 'jdbc:mysql://localhost/db1',
      user: 'flyway',
      password: 'flyway'
    },
    clean_db1: {
      command: 'clean'
    },
    clean_db2: {
      options {
        url: 'jdbc:mysql://localhost/db2'
      },
      command: 'clean',
    },
    baseline_db1: {
      options: {
        baselineDescription: 'Sample database created using Flyway:-)',
        baselineVersion: '1.0'
      },
      command: 'baseline'
    },
    baseline_db2: {
      options {
        url: 'jdbc:mysql://localhost/db2',
        baselineDescription: 'Sample database created using Flyway:-)',
        baselineVersion: '1.0'
      },
      command: 'baseline'
    },
    migrate_db1: {
      options: {
        locations: 'filesystem:src/main/resources/sql/migration'
      },
      command: 'migrate'
    },
    migrate_db2: {
      options {
        url: 'jdbc:mysql://localhost/db2',
        locations: 'filesystem:src/main/resources/sql/migration',
        placeholders: {
          name: 'Tom'
        }
      },
      command: 'migrate'
    }
  }
})

The only commands which are supported for the moment are clean, baseline, migrate, repair, validate and info.

Options

Options' descriptions come from Flyway's documentation.

NOTE: These options may be out of sync with the official documentation. Please only use this version as a basic reference and consult the official docs for accurate information.

clean

option	required	default	description
url	yes		The jdbc url to use to connect to the database
driver	no	Auto-detected based on url	The fully qualified classname of the jdbc driver to use to connect to the database
user	no		The user to use to connect to the database
password	no		The password to use to connect to the database
schemas	no	default schema of the connection	Comma-separated case-sensitive list of schemas managed by Flyway. The schemas will be cleaned in the order of this list.
jarDir	no	<install-dir>/jars	The directory containing the JDBC driver

baseline

option	required	default	description
url	yes		The jdbc url to use to connect to the database
driver	no	Auto-detected based on url	The fully qualified classname of the jdbc driver to use to connect to the database
user	no		The user to use to connect to the database
password	no		The password to use to connect to the database
schemas	no	default schema of the connection	Comma-separated case-sensitive list of schemas managed by Flyway. The first schema will be the one containing the metadata table.
table	no	schema_version	The name of Flyway's metadata table. By default (single-schema mode) the metadata table is placed in the default schema for the connection provided by the datasource. When the schemas property is set (multi-schema mode), the metadata table is placed in the first schema of the list.
jarDir	no	<install-dir>/jars	The directory containing the JDBC driver
baselineVersion	no	1	The initial version to put in the database
baselineDescription	no	<< Flyway Baseline >>	The description of the initial version

migrate

option	required	default	description
url	yes		The jdbc url to use to connect to the database
driver	no	Auto-detected based on url	The fully qualified classname of the jdbc driver to use to connect to the database
user	no		The user to use to connect to the database
password	no		The password to use to connect to the database
schemas	no	default schema of the connection	Comma-separated case-sensitive list of schemas managed by Flyway. The first schema in the list will be automatically set as the default one during the migration. It will also be the one containing the metadata table.
table	no	schema_version	The name of Flyway's metadata table. By default (single-schema mode) the metadata table is placed in the default schema for the connection provided by the datasource. When the schemas property is set (multi-schema mode), the metadata table is placed in the first schema of the list.
locations	no	filesystem:<install-dir>/sql	Comma-separated list of locations to scan recursively for migrations. The location type is determined by its prefix. Unprefixed locations or locations starting with classpath: point to a package on the classpath and may contain both sql and java-based migrations. Locations starting with filesystem: point to a directory on the filesystem and may only contain sql migrations.
jarDir	no	<install-dir>/jars	The directory containing the JDBC driver
sqlMigrationPrefix	no	V	The file name prefix for sql migrations
sqlMigrationSuffix	no	.sql	The file name suffix for sql migrations
encoding	no	UTF-8	The encoding of sql migrations
placeholders.name	no		Placeholders to replace in sql migrations
placeholderPrefix	no	${	The prefix of every placeholder
placeholderSuffix	no	}	The suffix of every placeholder
target	no	latest version	The target version up to which Flyway should run migrations. Migrations with a higher version number will not be applied.
outOfOrder	no	false	Allows migrations to be run "out of order". If you already have versions 1 and 3 applied, and now a version 2 is found, it will be applied too instead of being ignored.
validateOnMigrate	no	false	Whether to automatically call validate or not when running migrate. For each sql migration a CRC32 checksum is calculated when the sql script is executed. The validate mechanism checks if the sql migration in the classpath still has the same checksum as the sql migration already executed in the database.
cleanOnValidationError	no	false	Whether to automatically call clean or not when a validation error occurs. This is exclusively intended as a convenience for development. Even tough we strongly recommend not to change migration scripts once they have been checked into SCM and run, this provides a way of dealing with this case in a smooth manner. The database will be wiped clean automatically, ensuring that the next migration will bring you back to the state checked into SCM. Warning! Do not enable in production!
baselineOnMigrate	no	false	Whether to automatically call baseline when migrate is executed against a non-empty schema with no metadata table. This schema will then be initialized with the baselineVersion before executing the migrations. Only migrations above baselineVersion will then be applied. This is useful for initial Flyway production deployments on projects with an existing DB. Be careful when enabling this as it removes the safety net that ensures Flyway does not migrate the wrong database in case of a configuration mistake!
baselineVersion	no	1	The initial version to put in the database
baselineDescription	no	<< Flyway Baseline >>	The description of the initial version

validate

option	required	default	description
url	yes		The jdbc url to use to connect to the database
driver	no	Auto-detected based on url	The fully qualified classname of the jdbc driver to use to connect to the database
user	no		The user to use to connect to the database
password	no		The password to use to connect to the database
schemas	no	default schema of the connection	Comma-separated case-sensitive list of schemas managed by Flyway. The first schema will be the one containing the metadata table.
table	no	schema_version	The name of Flyway's metadata table. By default (single-schema mode) the metadata table is placed in the default schema for the connection provided by the datasource. When the schemas property is set (multi-schema mode), the metadata table is placed in the first schema of the list.
locations	no	filesystem:<install-dir>/sql	Comma-separated list of locations to scan recursively for migrations. The location type is determined by its prefix. Unprefixed locations or locations starting with classpath: point to a package on the classpath and may contain both sql and java-based migrations. Locations starting with filesystem: point to a directory on the filesystem and may only contain sql migrations.
jarDir	no	<install-dir>/jars	The directory containing the JDBC driver
sqlMigrationPrefix	no	V	The file name prefix for sql migrations
sqlMigrationSuffix	no	.sql	The file name suffix for sql migrations
encoding	no	UTF-8	The encoding of sql migrations
placeholders.name	no		Placeholders to replace in sql migrations
placeholderPrefix	no	${	The prefix of every placeholder
placeholderSuffix	no	}	The suffix of every placeholder
target	no	latest version	The target version up to which Flyway should run migrations. Migrations with a higher version number will not be applied.
outOfOrder	no	false	Allows migrations to be run "out of order". If you already have versions 1 and 3 applied, and now a version 2 is found, it will be applied too instead of being ignored.
cleanOnValidationError	no	false	Whether to automatically call clean or not when a validation error occurs. This is exclusively intended as a convenience for development. Even tough we strongly recommend not to change migration scripts once they have been checked into SCM and run, this provides a way of dealing with this case in a smooth manner. The database will be wiped clean automatically, ensuring that the next migration will bring you back to the state checked into SCM. Warning! Do not enable in production!

Usage Examples

Simply call the Flyway targets you've defined inside your Gruntfile:

grunt flyway:clean

grunt flyway:baseline

grunt flyway:migrate

grunt flyway:repair

grunt flyway:validate

grunt flyway:info

Release History

0.3.2

• Upgrade to Flyway 3.2

0.3.0

• Upgrade to Flyway 3.0

0.2.1

• Add develop branch has been created, pull request have to be performed on this branch now
• Upgrade to Flyway 2.3
• WARNING : The plugin requires requires Grunt ~0.4.2 now

0.2.0

• Added support for validate command
• Added support for all options for each supported command
• Added configuration validation
  • Required options cause an error when not present
  • Any extra option that is not available for selected command also causes an error
• Fix JSHint Lint errors

0.1.1

• Fix a Flyway classpath build problem under UNIX. The ';' character was used instead ':'.

grunt-flyway's Issues

Paths with spaces on Windows result in error

Paths with spaces result in an error on windows:

java -cp C:\data\Path with spaces\node_modules\grunt-flyway\flyway-2.3\bin/flyway-commandline-2.3.jar;C:\data\Path with spaces\node_modules\grunt-flyway\flyway-2.3\bin/flyway-core-2.3.jar com.googlecode.flyway.commandline.Main init -url="jdbc:mysql://localhost/test" -driver="com.mysql.jdbc.Driver" -user="username" -password="password" -initVersion="1.0" -initDescription="check online db using Flyway:-)">> Exited with code: 1.

Error: Command failed: Usage: java [-options] class [args...]
           (to execute a class)
    or  java [-options] -jar jarfile [args...]
           (to execute a jar file)
...

I can provide a fix but I am confused about the usage of the develop and master branches. I understand that all changes should be done on develop, but the latest changes are in master and they are not in develop. How am I supposed to do this?

mask the credentials in the build output

no matter how carefully the credentials are passed to the task, they are printed in the build output, where anyone with access to the build can see them. flyway itself is careful to prevent this.

Could something be done to mask at least the credentials in the output?

Placeholder issue

According to the documentation the way to add a placeholder is :

     placeholders:{
       name: 'test',
     },

However, when running the task i get:

java -cp /home/robixxu/root/<project>/node_modules/grunt-flyway/flyway-3.2.1/lib/flyway-commandline-3.2.1.jar:/home/robixxu/root/<project>/node_modules/grunt-flyway/flyway-3.2.1/lib/flyway-core-3.2.1.jar org.flywaydb.commandline.Main migrate -url="jdbc:postgresql://localhost:5432/somedb" -driver="org.postgresql.Driver" -user="someuser" -password="somepassword" -locations="filesystem:db/migration" -placeholders.0="undefined"

It seems like placeholders should be an array.
I tried using ${0}in the migration file and pass:

placeholders:{
  'test'
},

It seems to work, but is not a good solution if you have many placeholders.

Flyway 3.0 Out

Any plans to upgrade to Flyway 3.0?

Flyway v4 has been released

My org has not upgraded to v4 yet but we plan to do so in the next few months. If someone would like to update the built-in version of flyway and the supported methods before I get around to it, it would be much appreciated. Thanks!

Flyway blog post