§Storing Persistent Entities in a Relational Database

This page describes how to configure a relational database for use with Lagom’s Persistent Entity API.

§Project dependencies

To use a relational database add the following in your project’s build:

In Maven:

<dependency>
    <groupId>com.lightbend.lagom</groupId>
    <artifactId>lagom-scaladsl-persistence-jdbc_2.11</artifactId>
    <version>${lagom.version}</version>
</dependency>

In sbt:

libraryDependencies += lagomScaladslPersistenceJdbc

You will also need to add the jar for your JDBC database driver.

To enable the RDBMS Persistence on your Application you will have to mix in | JdbcPersistenceComponents and HikariCPComponents as described in Dependency Injection.

§Configuration

Lagom uses the akka-persistence-jdbc plugin to persist entities to the database. This supports four different relational databases:

• PostgreSQL
• MySQL
• Oracle
• H2

We advise against using H2 in production, however, it is suitable for use in development and testing.

In Lagom’s default configuration, Lagom will use Play’s JDBC support to configure and create a connection pool. Details on how to configure it can be found here. Play should be configured to provide a JNDI binding for the datasource, by default Lagom binds it to DefaultDS.

Lagom then configures akka-persistence-jdbc to use that DefaultDS JNDI binding. akka-persistence-jdbc uses Slick to map tables and manage asynchronous execution of JDBC calls. This means we need to configure it to use the right Slick profile for your database, by default Lagom will use the H2 profile.

So for example, to configure a PostgreSQL database, you can add the following to your application.conf:

db.default {
  driver = "org.postgresql.Driver"
  url = "jdbc:postgresql://database.example.com/playdb"
}

jdbc-defaults.slick.driver = "slick.driver.PostgresDriver$"

§Table creation

By default, Lagom will automatically create the tables it needs for you if they don’t already exist. This is great for development and testing, but in some circumstances may not be appropriate for production. The table auto creation feature can be disabled by using the following configuration:

lagom.persistence.jdbc.create-tables.auto = false

The database schemas needed for the tables can be found here.

The full configuration options that Lagom provides for managing the creation of tables is here:

# Defaults to use for each Akka persistence plugin
jdbc-defaults.slick {

  # The driver to use
  driver = "slick.driver.H2Driver$"

  # The JNDI name
  jndiName = "DefaultDS"
}

# Configure the default database to be bound to JNDI
db.default.jndiName=DefaultDS

lagom.persistence.jdbc {

  # Configuration for creating tables
  create-tables {

    # Whether tables should be created automatically as needed
    auto = true

    # How long to wait for tables to be created, before failing
    timeout = 20s

    # The cluster role to create tables from
    run-on-role = ""

    # Exponential backoff for failures configuration for creating tables
    failure-exponential-backoff {

      # minimum (initial) duration until processor is started again
      # after failure
      min = 3s

      # the exponential back-off is capped to this duration
      max = 30s

      # additional random delay is based on this factor
      random-factor = 0.2
    }
  }
}

§Application Loader

The Lagom Application Loader needs to load the correct persistence components based on whether you’re working with Cassandra or JDBC. For an RDBMS not only the JDBC persistence components must be loaded but also a connection pool must be configured. By default the Hikari connection pool is available in Play and can be configured as follows:

abstract class BlogApplication(context: LagomApplicationContext)
  extends LagomApplication(context)
    with JdbcPersistenceComponents
    with HikariCPComponents
    with AhcWSComponents {