Scala uses case classes for modeling domain objects.
quill-cache optimizes database access for read-mostly domain objects by providing a caching layer overtop
Quill.
This library depends on has-id, and case classes that need to be cached must extend
HasId.
HasId is generic and quite flexible, so you are encouraged to subclass all your domain objects from HasId,
even if they do not require database caching.
The current version of this library has no provision for distributed caches.
This could be retrofitted, however the author did not have the need, so the work was not done.
You are free to name DAOs anything you like; this library does not mandate any naming convention.
Scala DAOs are often given the same name as the class that they persist, but with a suffix indicating plurality.
For example, if a case class named Point needs to be persisted, the DAO is usually called Points.
Unlike some other persistence libraries for Scala, Quill allows you to define your DAO in the case class's companion object,
so you also have that option when using this library.
This library provides each DAO with its own cache.
DAOs that extend CachedPersistence have a method called preload()
which your application's initialization must invoke in order to fill that DAO's cache.
A cache can be flushed by calling the DAO's flushCache() method.
Because preload() always flushes the cache before loading it you probably won't ever need to explicitly call flushCache().
Cache Types
Two types of caches are supported by CachedPersistence:
StrongCache,
which is locked into memory until the cache is explicitly flushed.
Mix the StrongCacheLike
trait into the DAO to provide this behavior.
This type of cache is useful when there is enough memory to hold all instances of the case class.
SoftCache,
which contains "soft" values that might expire by timing out or might get bumped if memory fills up.
Mix the SoftCacheLike
trait into the DAO to provide this behavior.
DAOs that mix in SoftCacheLike do not assume that all instances of the case class can fit into memory.
SoftCacheLike finders query the database after every cache miss.
Because of this, SoftCacheLike finders run more slowly than StrongCacheLike finders when the cache does not contain the desired value.
This trait is experimental, do not use in production.
Caches require an ExecutionContext,
and the unit tests provide one:
package model.dao
import model.persistence.CacheExecutionContext
import scala.concurrent.{ExecutionContext, ExecutionContextExecutor}
/** Just delegates to standard Scala ExecutionContext, you can make this do whatever you want */object TestExecutionContext extends CacheExecutionContext {
protectedval ec: ExecutionContextExecutor = ExecutionContext.Implicits.global
overridedef execute(runnable: Runnable): Unit = ec.execute(runnable)
overridedef reportFailure(cause: Throwable): Unit = ec.reportFailure(cause)
}
Consistent APIs for Cached and Uncached DAOs
persistence.CachedPersistence subclasses persistence.UnCachedPersistence,
which you can use to derive DAOs for case classes that must have direct access to the database so the case classes are not cached.
You don't have to subclass UnCachedPersistence to get this behavior, but if you do then the DAOs for your cached
domain objects will have the same interface as the DAOs for your uncached domain objects,
and your code's structure will be more consistent.
Configuration
Your database configuration is specified by a HOCON file called application.conf on the classpath.
Please see src/main/scala/resources/reference.conf for an example of how to set that up.
Here is an excerpt showing configuration for H2 and Postgres databases.
Only one of these databases can be active per database context:
Quill-cache provides many flavors of Quill contexts, one for each type of supported database driver.
Each context is exposed as an abstract class.
Import the Quill context ctx from the appropriate type wherever you need to access the database.
Available abstract classes are: H2Ctx, MySqlCtx, PostgresCtx, and SqliteCtx.
Subclass the appropriate abstract class for the type of database driver you need, like this:
class MyClass extends model.persistence.H2Ctx
Asynchronous Drivers
Asynchronous drivers are not currently supported by quill-cache, but there is an
open issue for this enhancement.
The database contexts MysqlAsyncCtx and PostgresAsyncCtx were written in anticipation of async support.
Best Practice
Define a trait called SelectedCtx, and mix it into all your DAOs.
SelectedCtx merely extends the database context used in your application.
The PersistenceTest DAO in test/scala/model/dao follows this pattern:
trait SelectedCtx extends model.persistence.H2Ctx
Now define your application's Quill context as a singleton, and mix in the predefined implicits for Quill-cache defined in QuillCacheImplicits.
package model
import model.dao.SelectedCtx
import persistence.QuillCacheImplicits
caseobject Ctx extends SelectedCtx with QuillCacheImplicits
If you have more implicits to mix in, define a trait in the same manner as QuillCacheImplicits and mix it in as well:
trait MyQuillImplicits { ctx: JdbcContext[_, _] =>// define Quill Decoders, Encoders and Mappers here
}
After adding in MyQuillImplicits, your revised application Quill context Ctx is now:
package model
import model.dao.SelectedCtx
import persistence.QuillCacheImplicits
caseobject Ctx extends SelectedCtx with QuillCacheImplicits with MyQuillImplicits
Now import the Quill context's internally defined implicits into your DAO's scope.
Here are two examples of how to do that, one for cached and one for uncached persistence.
Notice that Users and Tokens are singletons, which makes them easy to work with.
Here is Users, a DAO with a strong cache, which means it needs an ExecutionContext like TestExecutionContext,
which is in scope because it resides in the same package:
import model.{Ctx, User}
import model.persistence._
object Users extends CachedPersistence[Long, Option[Long], User]
with StrongCacheLike[Long, Option[Long], User] {
import Ctx._
// DAO code for User goes here
}
Here is Tokens, a DAO without any cache, which means it does not need an ExecutionContext:
import model.{Ctx, Token}
import model.persistence._
object Tokens extends UnCachedPersistence[Long, Option[Long], Token] {
import Ctx._
// DAO code for Token goes here
}
Multiple Database Contexts
For circumstances where more than one database contexts need to share the same HikariCP pool, first construct a context,
then other contexts can be created from the first context's dataSource. In the following example, a context for an H2 database
is created using Ctx.dataSource:
caseobject Ctx2 extends H2Ctx(Ctx.dataSource) with MySpecialImplicits
Note that the new context need not have the same implicit decoders, encoders or mappers as the original context.
See the ContextTest unit test for a working example.
Here is another variation:
/** This causes a new Hikari pool to be created */object AuthCtx extends PostgresCtx with QuillCacheImplicits with IdImplicitLike
abstractclass DerivedCtx(dataSource: DataSource with Closeable)
extends PostgresCtx(dataSource) with QuillCacheImplicits with IdImplicitLike
/** Reuse the HikariCP pool from [[AuthCtx]] */object Ctx extends DerivedCtx(AuthCtx.dataSource) with MySpecialImplicits
Working with DAOs
Quill-cache automatically defines a read-only property for each DAO, called className.
This property is derived from the unqualified name of the case class persisted by the DAO.
For example, if model.User is being persisted, className will be User.
Each DAO needs the following functions defined:
_findAll – Quill query foundation - Encapsulates the Quill query that returns all instances of the case class from the database.
_deleteById – Encapsulates the Quill query that deletes the instance of the case class with the given Id from the database.
_findById – Encapsulates the Quill query that optionally returns the instance of the case class from
the database with the given Id, or None if not found.
_insert – Encapsulates the Quill query that inserts the given instance of the case class into the
database, and returns the case class as it was stored, including any auto-increment fields.
_update – Encapsulates the Quill query that updates the given instance of the case class into the
database, and returns the entity. Throws an Exception if the case class was not previously persisted.
DAO CRUD
Here is an example of the CRUD-related functions, implemented in the DAO for model.User in the quill-cache unit test suite.
@inlinedef _findAll: List[User] = run { quote { query[User] } }
val queryById: IdOptionLong => Quoted[EntityQuery[User]] =
(id: IdOptionLong) =>
quote { query[User].filter(_.id == lift(id)) }
val _deleteById: (IdOptionLong) =>Unit =
(id: IdOptionLong) => {
run { quote { queryById(id).delete } }
()
}
val _findById: IdOptionLong =>Option[User] =
(id: Id[Option[Long]]) =>
run { quote { queryById(id) } }.headOption
val _insert: User => User =
(user: User) => {
val id: Id[Option[Long]] = try {
run { quote { query[User].insert(lift(user)) }.returning(_.id) }
} catch {
case e: Throwable =>
logger.error(e.getMessage)
throw e
}
user.setId(id)
}
val _update: User => User =
(user: User) => {
run { queryById(user.id).update(lift(user)) }
user
}
With the above defined, quill-cache automatically provides the following CRUD-related methods for each DAO.
Only finders can take advantage of a cache, if present:
@inlinedef deleteById(id: Id[_IdType]): Unit@inlineoverridedef findAll: List[User]
def findById(id: Id[_IdType]): Option[User]
@inlinedef insert(user: User): User
@inlinedef update(user: User): User
@inlinedef remove(user: User): Unit@inlinedef upsert(user: User): User
@inlinedef zap(): Unit
See the unit tests for examples of how to use this library.
Features and Benefits
insert
,deleteById
,remove
,update
,upsert
,zap
,findAll
,findById
, plus application-specific finders)Background
Scala uses case classes for modeling domain objects.
quill-cache
optimizes database access for read-mostly domain objects by providing a caching layer overtop Quill. This library depends on has-id, and case classes that need to be cached must extend HasId.HasId
is generic and quite flexible, so you are encouraged to subclass all your domain objects fromHasId
, even if they do not require database caching.The current version of this library has no provision for distributed caches. This could be retrofitted, however the author did not have the need, so the work was not done.
DAOs
The data access object pattern (DAO) is common across all computer languages. DAOs for case classes that require database caching must extend the persistence.CachedPersistence abstract class.
You are free to name DAOs anything you like; this library does not mandate any naming convention. Scala DAOs are often given the same name as the class that they persist, but with a suffix indicating plurality. For example, if a case class named
Point
needs to be persisted, the DAO is usually calledPoints
. Unlike some other persistence libraries for Scala, Quill allows you to define your DAO in the case class's companion object, so you also have that option when using this library.This library provides each DAO with its own cache. DAOs that extend
CachedPersistence
have a method calledpreload()
which your application's initialization must invoke in order to fill that DAO's cache. A cache can be flushed by calling the DAO'sflushCache()
method. Becausepreload()
always flushes the cache before loading it you probably won't ever need to explicitly callflushCache()
.Cache Types
Two types of caches are supported by
CachedPersistence
:SoftCacheLike
do not assume that all instances of the case class can fit into memory.SoftCacheLike
finders query the database after every cache miss. Because of this,SoftCacheLike
finders run more slowly thanStrongCacheLike
finders when the cache does not contain the desired value. This trait is experimental, do not use in production.Caches require an ExecutionContext, and the unit tests provide one:
Consistent APIs for Cached and Uncached DAOs
persistence.CachedPersistence subclasses persistence.UnCachedPersistence, which you can use to derive DAOs for case classes that must have direct access to the database so the case classes are not cached. You don't have to subclass
UnCachedPersistence
to get this behavior, but if you do then the DAOs for your cached domain objects will have the same interface as the DAOs for your uncached domain objects, and your code's structure will be more consistent.Configuration
Your database configuration is specified by a HOCON file called
application.conf
on the classpath. Please seesrc/main/scala/resources/reference.conf
for an example of how to set that up.Here is an excerpt showing configuration for H2 and Postgres databases. Only one of these databases can be active per database context:
The
quill-cache
section of the configuration file specifies parameters for this library:dataSource
sections.See also the Quill test application.conf, Hikari initialization, HikariConfig.java, and Hikari pool sizing
Working with quill-cache
Quill Contexts
Quill-cache provides many flavors of Quill contexts, one for each type of supported database driver. Each context is exposed as an
abstract class
. Import the Quill contextctx
from the appropriate type wherever you need to access the database.Available abstract classes are:
H2Ctx
,MySqlCtx
,PostgresCtx
, andSqliteCtx
. Subclass the appropriateabstract class
for the type of database driver you need, like this:Asynchronous Drivers
Asynchronous drivers are not currently supported by
quill-cache
, but there is an open issue for this enhancement. The database contextsMysqlAsyncCtx
andPostgresAsyncCtx
were written in anticipation of async support.Best Practice
Define a trait called
SelectedCtx
, and mix it into all your DAOs.SelectedCtx
merely extends the database context used in your application. ThePersistenceTest
DAO intest/scala/model/dao
follows this pattern:Now define your application's Quill context as a singleton, and mix in the predefined implicits for Quill-cache defined in
QuillCacheImplicits
.If you have more implicits to mix in, define a trait in the same manner as
QuillCacheImplicits
and mix it in as well:After adding in
MyQuillImplicits
, your revised application Quill contextCtx
is now:Now import the Quill context's internally defined implicits into your DAO's scope. Here are two examples of how to do that, one for cached and one for uncached persistence. Notice that
Users
andTokens
are singletons, which makes them easy to work with. Here isUsers
, a DAO with a strong cache, which means it needs anExecutionContext
likeTestExecutionContext
, which is in scope because it resides in the same package:Here is
Tokens
, a DAO without any cache, which means it does not need anExecutionContext
:Multiple Database Contexts
For circumstances where more than one database contexts need to share the same HikariCP pool, first construct a context, then other contexts can be created from the first context's
dataSource
. In the following example, a context for an H2 database is created usingCtx.dataSource
:Note that the new context need not have the same implicit decoders, encoders or mappers as the original context. See the
ContextTest
unit test for a working example.Here is another variation:
Working with DAOs
Quill-cache
automatically defines a read-only property for each DAO, calledclassName
. This property is derived from the unqualified name of the case class persisted by the DAO. For example, ifmodel.User
is being persisted,className
will beUser
.Each DAO needs the following functions defined:
_findAll
– Quill query foundation - Encapsulates the Quill query that returns all instances of the case class from the database._deleteById
– Encapsulates the Quill query that deletes the instance of the case class with the givenId
from the database._findById
– Encapsulates the Quill query that optionally returns the instance of the case class from the database with the givenId
, orNone
if not found._insert
– Encapsulates the Quill query that inserts the given instance of the case class into the database, and returns the case class as it was stored, including any auto-increment fields._update
– Encapsulates the Quill query that updates the given instance of the case class into the database, and returns the entity. Throws an Exception if the case class was not previously persisted.DAO CRUD
Here is an example of the CRUD-related functions, implemented in the DAO for
model.User
in thequill-cache
unit test suite.With the above defined,
quill-cache
automatically provides the following CRUD-related methods for each DAO. Only finders can take advantage of a cache, if present:See the unit tests for examples of how to use this library.