Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

https://github.com/marceloemanoel/gradle-migrations-plugin

Mybatis migrations plugin to use with Gradle
https://github.com/marceloemanoel/gradle-migrations-plugin

Last synced: about 2 months ago
JSON representation

Mybatis migrations plugin to use with Gradle

Lists

README 

        
Gradle Migrations Plugin [![Build Status](https://travis-ci.org/marceloemanoel/gradle-migrations-plugin.png?branch=master)](https://travis-ci.org/marceloemanoel/gradle-migrations-plugin?branch=master)

=============================



Provide gradle build integration with [mybatis migrations](https://code.google.com/p/mybatis/wiki/Migration). 

The plugin adds a group of tasks named **Migrations** composed by:



  

    

      Task

    

    

      Description

    

    

      Parameters

    

  

  

    

      migrateInit

      Create migrations repository structure

      -

    

    

      migrateBootstrap

      Use an existing database structure as an starting point for migrations

      -

    

    

      migrateStatus

      Shows current database status

      -

    

    

      migrateNew

      Create a new migration file.

      description, template

    

    

      migrateUp

      Apply any pending migration following creation order.

      steps

    

    

      migrateDown

      Rewinds the database to a previous stage.

      steps

    

  



Install

=======



Just put the following code snippet in your build.gradle file.



```groovy

buildscript {

  repositories {

    mavenCentral()

  }

  dependencies {

    classpath "com.github.marceloemanoel:gradle-migrations:0.2.1"

  }

}



apply plugin: "migrations"

```



Configurations

==============



The only **required** configuration is made on your scripts dependencies section.

The plugin add a configuration scope known as `migrationsDriver`. As its name states,

this configuration scope should contain all JDBC drivers that will be used by your migrations.



To use the migrations with a mysql database for example, one should instruct the build as following:



```groovy

dependencies {

  migrationsDriver 'mysql:mysql-connector-java:5+'

}

```



This will ensure that the last mysql connector will be downloaded when you first run any migration task,

it will be cached by gradle and on later calls it will be used from the local repository.



Customization

=============



Following the rule of convention over configuration the plugin adds a configuration closure to your build.

If all default values are good for you, you're ready to go. But if you need to change anything, you'll see that 

it is an easy task. You only need to write the following on your `build.gradle` file: 



```groovy

migrations {

   baseDir = "anotherDirectory"

   environment = "test"

   force = true

}

```



All values are optional. The following table presents the default values of each property:



  

    Property

    Description

    Default Value

  

  

    

      baseDir

      Defines the base directory containing the migrations

      migrations

    

    

      environment

      Defines the database environment used by the tasks

      development

    

    

      force

      Forces the execution of the tasks

      false

    

  



Available Tasks

===============



migrateInit

-----------

The init command initializes a new repository’ of migration scripts. You’ll run init once to create the

workspace in which everything you need to manage database change will be placed. Running this

command will create the directory specified by the `baseDir` property (which is the directory "migrations"

by default). In case it already exists the command will fail unless the property `force` is true. 



When the command is completed, the directory will contain the following sub-directories:



> environments



In the environments folder you will find .properties files that represent your database instances. By

default a `development.properties` file is created for you to configure your development time database

properties. You can also create `test.properties`, `production.properties` or even a `anything.properties` file. 

The environment can be specified when running a migration by using the `environment` property 

without the path or ".properties" part (the default value is "development").



> scripts



This directory contains your migration SQL files. These are the files that contain your DDL to both

upgrade and downgrade your database structure. By default, the directory will contain the script to

create the changelog table, plus one empty example migration script. To create a new migration script,

use the [migrateNew](#migratenew) command. To run all pending migrations in order, use the [migrateUp](#migrateup) 

command. To undo the last migration applied, use the [migrateDown](#migratedown) command etc.



migrateBootstrap

----------------

The bootstrap command enables the starting point for migrations if you’re working from an existing database.

There’s no point in trying to rewind time and shoehorn your existing database into a series of migration scripts. 

It’s more practical to just accept the current state of your database schema and identify this as the starting point.

In the scripts directory you’ll find a file named `bootstrap.sql`. You can put your existing DDL script in this file. 

If you don’t have a DDL script, you can export your existing database schema and put it in the bootstrap file. 

You’ll want to clean it up so that it doesn’t contain anything specific to any one environment, but otherwise almost 

any script should work. Watch out for DDL that contains conditional elements or branching logic that could generate 

multiple schemas. While this is sometimes necessary, it’s a really good idea to try to eliminate this aspect of your

database schema (put such conditional and branching logic in your code or stored procedures instead).

If you have multiple DDL files, you’ll have to merge them into the single bootstrap file. But worry not,

it’s the last time you’ll ever modify it. 



In order to run, the [migrateBootstrap command](#migratebootstrap) need the JDBC driver of your database.

The plugin add the configuration `migrationsDriver` to your project. More information [here](#configurations).



migrateStatus

-------------

The status command will report the current state of the database. 




:migrateStatus

ID             Applied At          Description

================================================================================

20130314124532    ...pending...    create changelog

20130314124533    ...pending...    first migration




migrateNew

----------

This task enable the creation of new migrations. Every migration script file should have a .sql extension 

and have both sections **DO** and **UNDO**. As soon you init the migrations repository two files are 

created for you, the changelog migration and the first migration. The changelog migration contains 

the following code:



```sql

--// Create Changelog



-- Default DDL for changelog table that will keep

-- a record of the migrations that have been run.



-- You can modify this to suit your database before

-- running your first migration.



-- Be sure that ID and DESCRIPTION fields exist in

-- BigInteger and String compatible fields respectively.



CREATE TABLE ${changelog} (

ID NUMERIC(20,0) NOT NULL,

APPLIED_AT VARCHAR(25) NOT NULL,

DESCRIPTION VARCHAR(255) NOT NULL

);



ALTER TABLE ${changelog}

ADD CONSTRAINT PK_${changelog}

PRIMARY KEY (id);



--//@UNDO



DROP TABLE ${changelog};

```



This file is composed of three sections:



* Description: Delimited by `--//`, used to describe the migration in the database.



```sql

--// Create Changelog

```



* DO: Everything after the description, used to push forward the database



```sql



-- Default DDL for changelog table that will keep

-- a record of the migrations that have been run.



-- You can modify this to suit your database before

-- running your first migration.



-- Be sure that ID and DESCRIPTION fields exist in

-- BigInteger and String compatible fields respectively.



CREATE TABLE ${changelog} (

ID NUMERIC(20,0) NOT NULL,

APPLIED_AT VARCHAR(25) NOT NULL,

DESCRIPTION VARCHAR(255) NOT NULL

);



ALTER TABLE ${changelog}

ADD CONSTRAINT PK_${changelog}

PRIMARY KEY (id);



```



* UNDO: Everything after the `--//@UNDO` line, used to push backward the database



```sql



DROP TABLE ${changelog};

```



The migrateNew task needs **one** parameter to work as expected, the description of what this migration 

will do to your database. It is used like this:



> gradle migrateNew -Pdescription="This is a sample migration"



This parameter can be abreviated as simple as this:



> gradle migrateNew -Pd="This is a sample migration"



migrateUp and migrateDown

-------------------------



Theses tasks enable the evolving and devolving of your database. They use the script files inside the scripts directory.



The task `migrateUp` uses the **DO section** of the migration scripts to push forward your database and 

the `migrateDown`, in its turn, uses its **UNDO section** to push backward your database.



Both tasks have a parameter named `steps`. By default its value is **1** for `migrateDown` since you probably want to 

rollback only the last migration. For `migrateUp` the default value is `Integer.MAX_VALUE` this is because you probanly

want to execute all upwards pending migrations. The parameter is easily applied through the command line as following:



> gradle migrateUp -Psteps=2



or



> gradle migrateDown -Psteps=3



It is possible to abreviate it like this:



> gradle migrateUp -Ps=2



or 



> gradle migrateDown -Ps=3



License

=======



Copyright 2012 Marcelo Emanoel B. Diniz



Licensed under the Apache License, Version 2.0 (the "License");

you may not use this file except in compliance with the License.

You may obtain a copy of the License at



http://www.apache.org/licenses/LICENSE-2.0



Unless required by applicable law or agreed to in writing, software

distributed under the License is distributed on an "AS IS" BASIS,

WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.

See the License for the specific language governing permissions and

limitations under the License.



Developers

==========



* [Marcelo Emanoel B. Diniz](http://github.com/marceloemanoel)

* [Mircea Pop](http://github.com/mircea-pop)



Contributions

=============



Just fork the project and send a pull request :D