文档

§使用 Play Slick

Play Slick 模块使 Slick 成为 Play 的一等公民,它包含两个主要功能

Play Slick 目前支持 Play 2.8 的 Slick 3.3,适用于 Scala 2.12 和 Scala 2.13。

以前的版本也支持以前的 Play 版本以及 Scala 2.11 和 Scala 2.12。

注意:本指南假设您已经了解 Play 2.8 和 Slick 3.3。

§获取帮助

如果您在使用 Play Slick 时遇到问题,请查看 常见问题解答 是否包含答案。否则,请随时联系 Play 讨论论坛。另外,请注意,如果您需要有关 Slick 的帮助,Slick 用户社区 可能是更好的选择。

§关于此版本

Play Slick 以前版本的使用者会注意到一些重大变化。请阅读 迁移指南,了解有关从旧版本 Play Slick 升级的详细信息。

Play Slick 的首次使用者将欣赏 Slick 与 Play 无缝集成的优势。如果您熟悉 Play 和 Slick,配置和使用 Play Slick 模块将非常直观。

§设置

添加对 play-slick 的库依赖

libraryDependencies += "org.playframework" %% "play-slick" % "6.1.0"

上述依赖关系也会将 Slick 库作为传递依赖引入。这意味着您不需要显式添加对 Slick 的依赖关系,但如果需要,您可以这样做。如果您需要使用比 play-slick 中捆绑的版本更新的版本,则可以显式定义对 Slick 的依赖关系。由于 Slick 尾随点版本是二进制兼容的,因此使用与用于构建 play-slick 的版本不同的 Slick 尾随点版本不会带来任何风险。

§对 Play 数据库演变的支持

Play Slick 支持 Play 数据库演变

要启用演变,您需要以下依赖关系

libraryDependencies ++= Seq(
  "org.playframework" %% "play-slick"            % "6.1.0",
  "org.playframework" %% "play-slick-evolutions" % "6.1.0"
)

请注意,您无需将 Play evolutions 组件添加到您的依赖关系中,因为它 是 play-slick-evolutions 模块的传递依赖关系。

§JDBC 驱动程序依赖关系

Play Slick 模块不捆绑任何 JDBC 驱动程序。因此,您需要显式添加要在应用程序中使用的 JDBC 驱动程序。例如,如果您想使用内存数据库(如 H2),则必须添加对它的依赖关系

"com.h2database" % "h2" % "${H2_VERSION}" // replace `${H2_VERSION}` with an actual version number

§数据库配置

为了让 Play Slick 模块处理 Slick 数据库的生命周期,重要的是您永远不要在代码中显式创建数据库实例。相反,您应该在您的 application.conf 中提供有效的 Slick 驱动程序和数据库配置(按照惯例,默认的 Slick 数据库必须称为 default

# Default database configuration
slick.dbs.default.profile="slick.jdbc.H2Profile$"
slick.dbs.default.db.driver="org.h2.Driver"
slick.dbs.default.db.url="jdbc:h2:mem:play"

首先,请注意以上是一个有效的 Slick 配置(有关可用于配置数据库的完整配置参数列表,请参阅 Slick ScalaDoc for Database.forConfig - 确保在文档中展开 forConfig 行)。

其次,数据库名称之前的 slick.dbs 前缀是可配置的。实际上,您可以通过覆盖配置键 play.slick.db.config 的值来更改它。

第三,在上面的配置中,slick.dbs.default.profile 用于配置 Slick 配置文件,而 slick.dbs.default.db.driver 是 Slick 后端使用的底层 JDBC 驱动程序。在上面的配置中,我们正在配置 Slick 使用 H2 数据库,但 Slick 支持其他几种数据库。查看 Slick 文档 以获取支持的数据库的完整列表,并找到匹配的 Slick 驱动程序。

Slick 不像默认的 Play JBDC 连接池那样支持 DATABASE_URL 环境变量。但从 3.0.3 版本开始,Slick 提供了专门用于解析环境变量的 DatabaseUrlDataSource

slick.dbs.default.profile="slick.jdbc.PostgresProfile$"
slick.dbs.default.db.dataSourceClass = "slick.jdbc.DatabaseUrlDataSource"
slick.dbs.default.db.properties.driver = "org.postgresql.Driver"

在某些平台(例如 Heroku)上,您可以 替换 JDBC_DATABASE_URL 环境变量,该变量的格式为 jdbc:vendor://host:port/db?args(如果可用)。例如

slick.dbs.default.profile="slick.jdbc.PostgresProfile$"
slick.dbs.default.db.driver="org.postgresql.Driver"
slick.dbs.default.db.url=${JDBC_DATABASE_URL}

注意:如果未为 slick.dbs.default.profileslick.dbs.default.db.driver 提供有效的值,则在尝试运行 Play 应用程序时会导致异常。

要配置多个数据库

# Orders database
slick.dbs.orders.profile="slick.jdbc.H2Profile$"
slick.dbs.orders.db.driver="org.h2.Driver"
slick.dbs.orders.db.url="jdbc:h2:mem:play"

# Customers database
slick.dbs.customers.profile="slick.jdbc.H2Profile$"
slick.dbs.customers.db.driver="org.h2.Driver"
slick.dbs.customers.db.url="jdbc:h2:mem:play"

如果配置不正确,您将在浏览器中收到通知

注意:只有在提供有效的 Slick 配置时,才会启动您的应用程序。

§用法

在正确配置 Slick 数据库后,您可以使用依赖注入获取 DatabaseConfig(这是一个将数据库和驱动程序捆绑在一起的 Slick 类型)。

注意:Slick 数据库实例管理线程池和连接池。通常,您不需要在代码中显式关闭数据库(通过调用其 close 方法),因为 Play Slick 模块已经处理了此操作。

§通过运行时依赖注入获取 DatabaseConfig

虽然您可以通过访问 SlickApi 手动获取 DatabaseConfig 实例,但我们为运行时 DI 用户(Guice、Scaldi、Spring 等)提供了一些帮助程序,以便在您的控制器中获取特定实例。

以下是如何为默认数据库(即配置中名为 default 的数据库)注入 DatabaseConfig 实例的示例

class Application @Inject() (protected val dbConfigProvider: DatabaseConfigProvider, cc: ControllerComponents)(implicit
    ec: ExecutionContext
) extends AbstractController(cc)
    with HasDatabaseConfigProvider[JdbcProfile] {

在此示例中,我们还注入了 Play 的默认 ExecutionContext,它将在以后的转换中隐式使用。

为其他数据库注入 DatabaseConfig 实例也很容易。您只需在 dbConfigProvider 构造函数参数前添加注释 @NamedDatabase("<db-name>")

class Application2 @Inject() (
    @NamedDatabase("<db-name>") protected val dbConfigProvider: DatabaseConfigProvider,
    cc: ControllerComponents
)(implicit ec: ExecutionContext)
    extends AbstractController(cc)
    with HasDatabaseConfigProvider[JdbcProfile] {

当然,您应该将字符串 "<db-name>" 替换为您要使用的数据库配置的名称。

注意:要访问数据库对象,您只需在 HasDatabaseConfig 特性上调用函数 db。您不需要引用 dbConfigProvider 构造函数参数。

要查看完整示例,请查看此示例项目

§编译时依赖注入

如果您使用编译时 DI,您可以使用 slickApi.dbConfig(DbName(name)) 方法直接从 SlickApi 查询数据库配置。play.api.db.slick.SlickComponents 提供对 slickApi 的访问。

§在控制器中运行数据库查询

要在控制器中运行数据库查询,您需要一个 Slick 数据库和驱动程序。幸运的是,从上面我们现在知道如何获取 Slick DatabaseConfig,因此我们拥有运行数据库查询所需的一切。

您需要从驱动程序导入一些类型和隐式值

import dbConfig.profile.api._

然后您可以定义一个将运行数据库查询的控制器的函数

def index(name: String) = Action.async { implicit request =>
  val resultingUsers: Future[Seq[User]] = db.run(Users.filter(_.name === name).result)
  resultingUsers.map(users => Ok(views.html.index(users)))
}

这就像使用标准 Play 和 Slick 一样!

§配置连接池

阅读此处以了解如何配置连接池。

下一步:Play Slick 迁移指南


在此文档中发现错误?此页面的源代码可以在此处找到。阅读完文档指南后,请随时贡献拉取请求。有疑问或建议要分享?前往我们的社区论坛与社区开始对话。