Running evolutions using compile-time DI

[arbitrary-dev]

Problem

I'm trying to follow the documentation on Running evolutions using compile-time DI.

And ran into problems with this:

Since applicationEvolutions is a lazy val, you either need to explicitly access that val, for example in your ApplicationLoader`

Play Version (2.5.x / etc)

2.6

API (Scala / Java / Neither / Both)

Scala

Operating System (Ubuntu 15.10 / MacOS 10.10 / Windows 10)

Linux mother 4.9.16-gentoo #1 SMP PREEMPT Wed Apr 19 18:47:56 +05 2017 x86_64 Intel(R) Core(TM) i7-4790K CPU @ 4.00GHz GenuineIntel GNU/Linux

JDK (Oracle 1.8.0_72, OpenJDK 1.8.x, Azul Zing)

java version "1.8.0_131"
Java(TM) SE Runtime Environment (build 1.8.0_131-b11)
Java HotSpot(TM) 64-Bit Server VM (build 25.131-b11, mixed mode)

Library Dependencies

libraryDependencies ++= Seq(
  "com.typesafe.slick" %% "slick" % "3.2.0",
  "com.typesafe.play" %% "play-slick" % "3.0.0-M4",
  "com.typesafe.play" %% "play-slick-evolutions" % "3.0.0-M4",
  "com.h2database" % "h2" % "1.4.195",

  "com.typesafe.akka" %% "akka-stream-kafka" % "0.13",

  "ch.qos.logback" % "logback-classic" % "1.1.3",
  "org.slf4j" % "log4j-over-slf4j" % "1.7.12",
  "com.typesafe.scala-logging" %% "scala-logging" % "3.5.0",
  "com.typesafe.akka" %% "akka-slf4j" % akkaVersion,

  "net.manub" %% "scalatest-embedded-kafka" % "0.12.0"
    exclude("log4j", "log4j")
)

Expected Behavior

import controllers.HomeController
import play.api.ApplicationLoader
import play.api.ApplicationLoader.Context
import play.api.BuiltInComponentsFromContext
import play.api.db.evolutions.EvolutionsComponents
import play.api.db.slick.{ DefaultSlickApi, SlickComponents }
import play.api.db.slick.evolutions.SlickEvolutionsComponents
import play.filters.HttpFiltersComponents
import router.Routes

class AppLoader extends ApplicationLoader {

  def load(context: Context) = {
    val ac = new AppComponents(context)
    println("BEFORE")
    ac.applicationEvolutions.start()
    println("AFTER")
    ac.application
  }
}

class AppComponents(context: Context)
    extends BuiltInComponentsFromContext(context)
    with HttpFiltersComponents
    with SlickComponents
    with EvolutionsComponents with SlickEvolutionsComponents {

  lazy val router = new Routes(httpErrorHandler, homeController)
  lazy val homeController = new HomeController(controllerComponents)

  override lazy val slickApi = new DefaultSlickApi(environment, configuration,
    applicationLifecycle)(executionContext)
}

works as advertised, and evolutions run at application start.

Actual Behavior

BEFORE
[error] application -

! @73pnjf5eo - Internal server error, for (HEAD) [/] ->

play.api.db.evolutions.InvalidDatabaseRevision: Database 'default' needs evolution![An SQL script need to be run on your database.]
        at play.api.db.evolutions.ApplicationEvolutions.$anonfun$runEvolutions$1(ApplicationEvolutions.scala:78)
        at play.api.db.evolutions.ApplicationEvolutions.withLock(ApplicationEvolutions.scala:100) 
...

But after adding this line to conf/application.conf:

play.evolutions.db.default.autoApply=true

Everything works as expected, even without ac.applicationEvolutions.start() in AppLoader.load().

Am I having some wrong expectations from the documentation? Or should it be updated?

[gmethvin]

In your "Actual Behavior", the evolutions are being loaded by the ApplicationEvolutions. That error message is coming from your invocation of the start() method. Because you have not asked for the evolutions to be auto-applied, you need to manually intervene to complete the process. See https://www.playframework.com/documentation/2.6.x/Evolutions#Evolutions-configuration

I think the issue is that the documentation says "... ApplicationEvolutions, which will run the evolutions when instantiated." It would probably be best to simply say that this "activates" the evolutions, and will execute whichever behavior you have configured.

Can you clarify where your confusion is? How would you update the documentation? If you'd like you can submit a PR to clarify the docs.

[marcospereira]

See also if #7173 is enough to resolve this confusion.