oh-migrations

Data migrations through implicit function composition at the type-level.

This library provides the ability to version, decode and migrate data types.

Install

For core functionality add the following to your build.sbt:

"io.github.mcgizzle" %% "oh-migrations-core" % "<version>"

to interop with circe add:

"io.github.mcgizzle" %% "oh-migrations-circe" % "<version>"

to interop with Argonaut add:

"io.github.mcgizzle" %% "oh-migrations-argonaut" % "<version>"

versions can be found in the releases section.

Usage

Lets say you have a stringly typed User data type.

case class UserV1(firstName: String, lastName: String)

You then decide to add some type information through the use of value classes.

case class FirstName(value: String)
case class LastName(value: String)
case class UserV2(firstName: FirstName, lastName: LastName)

Next it is decided that we need a way to uniquely identify Users through a UUID, and while we are at it, combine the names.

import java.util.UUID

case class Name(value: String)
case class UserV3(name: Name, id: UUID)

Versioned

We must version all our data types in the chain by implementing the Versioned typeclass.

import shapeless.nat._

trait User
object User {
  implicit val v1 = Versioned[User, _1, UserV1]
  implicit val v2 = Versioned[User, _2, UserV2]
  implicit val v3 = Versioned[User, _3, UserV3]
}

MigrationFunction

Now we provide migrations from n to n + 1. This is a way to go from the current data type to the next version.

implicit val m1: UserV1 +=> UserV2 = u1 => 
  UserV2(FirstName(u1.firstName), LastName(u1.lastName))

implicit val m2: UserV2 +=> UserV3 = u1 => 
  UserV3(Name(u1.firstName.value + " " + u1.lastName.value), getUUID)

MigrationFunctionF

Sometimes it may be necessary to migrate our data types effectfully.

implicit val m1: MigrationFunctionF[F, UserV1, UserV2] = u1 => 
  UserV2(FirstName(u1.firstName), LastName(u1.lastName))

implicit val m2: MigrationFunctionF[F, UserV2, UserV3] = u1 => 
  getUUID.map( uuid => UserV3(Name(u1.firstName.value + " " + u1.lastName.value), uuid))

Migrate

Here we get our migration composition 1 -> 3 for free

val u1 = UserV1("Frederick", "Wiley")
Migrate[User].from[_1, _3].apply(u1) == UserV3(Name("Frederick Wiley"), getUUID)

DecodeAndMigrate

The DecodeAndMigrate typeclass provides the ability to attempt to decode our User from the latest version and then migrate it to our desired version. As long as we have defined Versioned, MigrationFunction and Decoder for all our versions, we get the following for free.

// We provide Decoders for each version of User
implicit val d1: Decoder[String, UserV1] = Decoder.from(_ => Left(DecodeFailure("failed on d1")))   
implicit val d2: Decoder[String, UserV2] = Decoder.from(_ => Right(UserV2(FirstName("Decoded"), LastName("By UserV2"))))   
implicit val d3: Decoder[String, UserV3] = Decoder.from(_ => Left(DecodeFailure("failed on d3")))   

// It decodes a UserV2 as it is the latest available and then migrates it to UserV3
DecodeAndMigrate[User].from[String, _1, _3]("{ json value for example}") shouldBe Right(UserV3(Name("Decoded By UserV2")))

Interop

This functionality can be easily interoped with circe using oh-migrations-circe.

import io.circe._
import io.circe.generic.auto._
import io.github.mcgizzle.circe._

val json = UserV2(FirstName("Decoded"), LastName("By Circe")).asJson
DecodeAndMigrate[User].from[Json, _1, _3](json) shouldBe Right(UserV3(Name("Decoded By Circe")))