vidushi-devops / migrations

SBT plugin to handle database migrations.

sbt-migrations

Simple, but useful SBT plugin to manage database migrations (some sort of database versioning).

Databases supported:

• Postgresql
• MySQL

Before start

WORK IN PROGRESS

I only tested manually for both, Postgresql and MySQL (unit and integration tests remains to be done). This is a first raw version, so I didn't care much for handle failures or transactions (with commit and rollback), so it could happen that the database ends up in an inconsistent state and you are going to need to fix it by hand.

How to use it

Plugin dependency

It is built for SBT 1.x, not working (for the moment) on version 0.13.
This is an auto plugin and you need to add the following to your project/plugins.sbt:

addSbtPlugin("com.github.leonhardtdavid" % "sbt-migrations" % "0.1.2")

You also need to add the dependency to the JDBC driver in the same file as the plugin.
For example, for Postgresql:

libraryDependencies += "org.postgresql" % "postgresql" % "42.2.6"

Plugin configurations

Settings

Setting	Type	Default	Description
migrationsPath	String	{resourceDirectory}/migrations	Directory where the migrations are going to be.
migrationsTable	String	app_migrations	Table name to keep track of the applied migrations.
migrationsConfigs	Seq	--	No default, so it is required. List of database configurations. Usually it has only one config, but if you have more than one database, you can set multiple configurations.

NOTE:
Each value of migrationsConfigs has an id, the default value is "default". This ids must be unique.

Tasks

There is only one task for the moment, and is used to apply and update the migrations:

migratedb

Examples

Here you can find an empty SBT project containing the specifics configurations for this plugins as an example.

import com.github.leonhardtdavid.migrations.DatabaseConfig

migrationsConfigs := Seq(
  new DatabaseConfig(
    url = "jdbc:postgresql://localhost/some_schema",
    user = Some("some_user"),
    password = Some("some_password")
  )
)

migrationsConfigs := Seq(
  new DatabaseConfig(url = "jdbc:postgresql://some_user:some_password@localhost/some_schema")
)

migrationsConfigs := Seq(
  new DatabaseConfig(
    id = "animals_database",
    url = "jdbc:postgresql://localhost/animals_schema",
    user = Some("some_user"),
    password = Some("some_password")
  )
)

Setting up the migrations

Default migration files structure

Inside the directory configured in migrationsPath (usually src/main/resources/migrations, or conf/migrations in Play! proyects, or the value you set), you must create a subfolder that has to be named as the configuration id. So, if I have the default id, I am going to create the following directory: src/main/resources/migrations/default, instead, if I set the id animals_database, I am going to create the following directory: src/main/resources/migrations/animals_database.

Inside of each of this directories, there will be the migrations as SQL files.
The nomenclature of the files are as follow:

• Apply scrips:
  • UP_1.sql
  • UP_2.sql
  • ....
  • UP_n.sql
• Rollback scripts:
  • DOWN_1.sql
  • DOWN_2.sql
  • ....
  • DOWN_n.sql

Required things you need to know:

1. The versions must start from 1.
2. The versions numbers must be consecutive and positive integers (1, 2, 3, 4, ..., n).
3. Apply scripts must start with "UP_" (it could also be in lower case), followed by the version number, followed by .sql **.
4. Rollback script must start with "DOWN_"(it could also be in lower case), followed by the version number, followed by .sql **.

** Technically, It could be a dot and what you want, like, .txt, .#%%&.sql, etc., but the recommended extension is .sql.

Custom migration files

Inside the directory configured in migrationsPath (usually src/main/resources/migrations, or conf/migrations in Play! proyects, or the value you set), you must create a subfolder that has to be named as the configuration id. So, if I have the default id, I am going to create the following directory: src/main/resources/migrations/default, instead, if I set the id animals_database, I am going to create the following directory: src/main/resources/migrations/animals_database.

Now, the difference with the default structure is that you can define in the configuration a list of tuples, with the form (up_file, down_file), having the names you prefer.

For example:

migrationsConfigs := Seq(
  new DatabaseConfig(
    url = "jdbc:postgresql://localhost/some_schema",
    user = Some("some_user"),
    password = Some("some_password"),
    files = Seq(
      "100 Init database.sql" -> "100 Init database ROLLBACK.sql",
      "200 new table.sql" -> "200 new table ROLLBACK.sql"
    )
  )
)