Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add missing documentation for 5.0.x #646

Merged
merged 9 commits into from
Jan 23, 2022
2 changes: 1 addition & 1 deletion CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@ Before making a contribution, it is important to make sure that the change you w

### Procedure

1. Make sure you have signed the [Typesafe CLA](http://www.typesafe.com/contribute/cla); if not, sign it online.
1. Make sure you have signed the [Lightbend CLA](https://www.lightbend.com/contribute/cla); if not, sign it online.
2. Ensure that your contribution meets the following guidelines:
1. Live up to the current code standard:
- Not violate [DRY](http://programmer.97things.oreilly.com/wiki/index.php/Don%27t_Repeat_Yourself).
Expand Down
2 changes: 1 addition & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,7 @@ The Play Slick module makes [Slick] a first-class citizen of [Play]. It consists
Because Slick creates and manages both a connection pool and a thread pool, integrating Slick with Play boils down to ensuring that all resources allocated by Slick are shutdown when a Play application is stopped (or reloaded).

[Play]: https://www.playframework.com
[Slick]: http://slick.typesafe.com
[Slick]: https://scala-slick.org/

The plugin has its own release cycle and therefore is not integrated into either core Play or Slick.

Expand Down
23 changes: 13 additions & 10 deletions docs/manual/working/scalaGuide/main/sql/slick/PlaySlick.md
Original file line number Diff line number Diff line change
@@ -1,19 +1,21 @@
# Using Play Slick

The Play Slick module makes [Slick](http://slick.typesafe.com/) a first-class citizen of Play, and consists of two primary features:
The Play Slick module makes [Slick](https://scala-slick.org/) a first-class citizen of Play, and consists of two primary features:

- Integration of Slick into Play's application lifecycle.
- Support for [[Play database evolutions|Evolutions]].

Play Slick currently supports Slick 3.3 with Play 2.7, for Scala 2.12 and Scala 2.11.
Play Slick currently supports Slick 3.3 with Play 2.8, for Scala 2.12 and Scala 2.13.

> **Note**: This guide assumes you already know both Play 2.7 and Slick 3.3.
Previous versions support previous versions of Play! as well as Scala 2.11.

> **Note**: This guide assumes you already know both Play 2.8 and Slick 3.3.

## Getting Help

If you are having trouble using Play Slick, check if the [[FAQ|PlaySlickFAQ]] contains the answer. Otherwise, feel free to reach out to [play-framework user group](https://groups.google.com/forum/#!forum/play-framework). Also, note that if you are seeking help on Slick, the [slick user group](https://groups.google.com/forum/#!forum/scalaquery) may be a better place.
If you are having trouble using Play Slick, check if the [[FAQ|PlaySlickFAQ]] contains the answer. Otherwise, feel free to reach out to [play-framework user community](https://discuss.playframework.com). Also, note that if you are seeking help on Slick, the [slick user community](https://scala-slick.org/community/) may be a better place.

Finally, if you prefer to get an answer for your Play and Slick questions in a timely manner, and with a well-defined SLA, you may prefer [to get in touch with Lightbend](http://www.lightbend.com/subscription), as it offers commercial support for these technologies.
Finally, if you prefer to get an answer for your Play and Slick questions in a timely manner, and with a well-defined SLA, you may prefer [to get in touch with Lightbend](https://www.lightbend.com/subscription), as it offers commercial support for these technologies.

## About this release

Expand Down Expand Up @@ -44,7 +46,8 @@ Note there is no need to add the Play `evolutions` component to your dependencie
The Play Slick module does not bundle any JDBC driver. Hence, you will need to explicitly add the JDBC driver(s) you want to use in your application. For instance, if you would like to use an in-memory database such as H2, you will have to add a dependency to it:

```scala
"com.h2database" % "h2" % "${H2_VERSION}" // replace `${H2_VERSION}` with an actual version number
// play-slick 5.0.x is currently built and tested against version 1.4.200
"com.h2database" % "h2" % "1.4.200"
```

## Database Configuration
Expand All @@ -58,11 +61,11 @@ slick.dbs.default.db.driver="org.h2.Driver"
slick.dbs.default.db.url="jdbc:h2:mem:play"
```

First, note that the above is a valid Slick configuration (for the complete list of configuration parameters that you can use to configure a database see the Slick ScalaDoc for [Database.forConfig](http://slick.typesafe.com/doc/3.1.0/api/index.html#slick.jdbc.JdbcBackend$DatabaseFactoryDef@forConfig%28path:String,config:com.typesafe.config.Config,driver:java.sql.Driver,classLoader:ClassLoader%29:JdbcBackend.this.Database) - make sure to expand the `forConfig` row in the doc).
First, note that the above is a valid Slick configuration (for the complete list of configuration parameters that you can use to configure a database see the Slick ScalaDoc for [Database.forConfig](https://scala-slick.org/doc/3.3.2/api/index.html#slick.jdbc.JdbcBackend$DatabaseFactoryDef@forConfig%28path:String,config:com.typesafe.config.Config,driver:java.sql.Driver,classLoader:ClassLoader%29:JdbcBackend.this.Database) - make sure to expand the `forConfig` row in the doc).

Second, the `slick.dbs` prefix before the database's name is configurable. In fact, you may change it by overriding the value of the configuration key `play.slick.db.config`.

Third, in the above configuration `slick.dbs.default.profile` is used to configure the Slick profile, while `slick.dbs.default.db.driver` is the underlying JDBC driver used by Slick's backend. In the above configuration we are configuring Slick to use H2 database, but Slick supports several other databases. Check the [Slick documentation](http://slick.typesafe.com/docs) for a complete list of supported databases, and to find a matching Slick driver.
Third, in the above configuration `slick.dbs.default.profile` is used to configure the Slick profile, while `slick.dbs.default.db.driver` is the underlying JDBC driver used by Slick's backend. In the above configuration we are configuring Slick to use H2 database, but Slick supports several other databases. Check the [Slick documentation](https://scala-slick.org/docs/) for a complete list of supported databases, and to find a matching Slick driver.

Slick does not support the `DATABASE_URL` environment variable in the same way as the default Play JBDC connection pool. But starting in version 3.0.3, Slick provides a `DatabaseUrlDataSource` specifically for parsing the environment variable.

Expand All @@ -72,15 +75,15 @@ slick.dbs.default.db.dataSourceClass = "slick.jdbc.DatabaseUrlDataSource"
slick.dbs.default.db.properties.driver = "org.postgresql.Driver"
```

On some platforms, such as Heroku, you may substitute the `JDBC_DATABASE_URL`, which is in the format `jdbc:vendor://host:port/db?args`, if it is available. For example:
On some platforms, such as Heroku, you may [substitute](https://github.com/lightbend/config/blob/master/HOCON.md#substitution-fallback-to-environment-variables) the `JDBC_DATABASE_URL` environment variable, which is in the format `jdbc:vendor://host:port/db?args`, if it is available. For example:

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

> **Note**: Failing to provide a valid value for both `slick.dbs.default.driver` and `slick.dbs.default.db.driver` will lead to an exception when trying to run your Play application.
> **Note**: Failing to provide a valid value for both `slick.dbs.default.profile` and `slick.dbs.default.db.driver` will lead to an exception when trying to run your Play application.

To configure several databases:

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -4,19 +4,19 @@

With Slick 3 release, Slick starts and controls both a connection pool and a thread pool for optimal asynchronous execution of your database actions.

In Play Slick we have decided to let Slick be in control of creating and managing the connection pool (the default connection pool used by Slick 3 is [HikariCP](http://brettwooldridge.github.io/HikariCP/)), which means that to tune the connection pool you will need to look at the Slick ScalaDoc for [Database.forConfig](http://slick.typesafe.com/doc/3.1.0/api/index.html#slick.jdbc.JdbcBackend$DatabaseFactoryDef@forConfig(String,Config,Driver,ClassLoader):Database) (make sure to expand the `forConfig` row in the doc). In fact, be aware that any value you may pass for setting the Play connection pool (e.g., under the key `play.db.default.hikaricp`) is simply not picked up by Slick, and hence effectively ignored.
In Play Slick we have decided to let Slick be in control of creating and managing the connection pool (the default connection pool used by Slick 3 is [HikariCP](https://github.com/brettwooldridge/HikariCP)), which means that to tune the connection pool you will need to look at the Slick ScalaDoc for [Database.forConfig](https://scala-slick.org/doc/3.3.2/api/index.html#slick.jdbc.JdbcBackend$DatabaseFactoryDef@forConfig%28path:String,config:com.typesafe.config.Config,driver:java.sql.Driver,classLoader:ClassLoader%29:JdbcBackend.this.Database) (make sure to expand the `forConfig` row in the doc). In fact, be aware that any value you may pass for setting the Play connection pool (e.g., under the key `play.db.default.hikaricp`) is simply not picked up by Slick, and hence effectively ignored.

Also, note that as stated in the [Slick documentation](http://slick.typesafe.com/doc/3.1.0/database.html#connection-pools), a reasonable default for the connection pool size is calculated from the thread pool size. In fact, you should only need to tune `numThreads` and `queueSize` in most cases, for each of your database configuration.
Also, note that as stated in the [Slick documentation](https://scala-slick.org/doc/3.3.2/database.html#connection-pools), a reasonable default for the connection pool size is calculated from the thread pool size. In fact, you should only need to tune `numThreads` and `queueSize` in most cases, for each of your database configurations.

Finally, it's worth mentioning that while Slick allows using a different connection pool than [HikariCP](http://brettwooldridge.github.io/HikariCP/) (though, Slick currently only offers built-in support for HikariCP, and requires you to provide an implementation of [JdbcDataSourceFactory](http://slick.typesafe.com/doc/3.1.0/api/index.html#slick.jdbc.JdbcDataSourceFactory) if you want to use a different connection pool), Play Slick currently doesn't allow using a different connection pool than HikariCP.
Finally, it's worth mentioning that while Slick allows using a different connection pool than [HikariCP](https://github.com/brettwooldridge/HikariCP) (though, Slick currently only offers built-in support for HikariCP, and requires you to provide an implementation of [JdbcDataSourceFactory](https://scala-slick.org/doc/3.3.2/api/index.html#slick.jdbc.JdbcDataSourceFactory) if you want to use a different connection pool), Play Slick currently doesn't allow using a different connection pool than HikariCP.

> **Note**: Changing the value of `play.db.pool` won't affect what connection pool Slick is using. Furthermore, be aware that any configuration under `play.db` is not considered by Play Slick.

## Thread Pool

With Slick 3.0 release, Slick starts and controls both a thread pool and a connection pool for optimal asynchronous execution of your database actions.

For optimal execution, you may need to tune the `numThreads` and `queueSize` parameters, for each of your database configuration. Refer to the [Slick documentation](http://slick.typesafe.com/doc/3.1.0/database.html#database-thread-pool) for details.
For optimal execution, you may need to tune the `numThreads` and `queueSize` parameters, for each of your database configuration. Refer to the [Slick documentation](https://scala-slick.org/doc/3.3.2/database.html#database-thread-pool) for details.

Since `3.2.2` of Slick, there is a requirement that `maxConnections = maxThreads` otherwise you might see these messages in your logs:

Expand All @@ -25,7 +25,7 @@ Since `3.2.2` of Slick, there is a requirement that `maxConnections = maxThreads
To fix this, simply set them in your config. For example,

```
slick.dbs.default.driver="slick.driver.PostgresDriver$"
slick.dbs.default.profile="slick.profile.PostgresProfile$"
slick.dbs.default.db.dataSourceClass="slick.jdbc.DatabaseUrlDataSource"
slick.dbs.default.db.numThreads=20
slick.dbs.default.db.maxConnections=20
Expand Down
4 changes: 2 additions & 2 deletions docs/manual/working/scalaGuide/main/sql/slick/PlaySlickFAQ.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,11 +6,11 @@ Have a look at the [compatibility matrix](https://github.com/playframework/play-

## `play.db.pool` is ignored

It's indeed the case. Changing the value of `play.db.pool` won't affect what connection pool Slick is going to use. The reason is simply that the Play Slick module currently doesn't support using a different connection pool than [HikariCP](http://brettwooldridge.github.io/HikariCP/).
It's indeed the case. Changing the value of `play.db.pool` won't affect what connection pool Slick is going to use. The reason is simply that the Play Slick module currently doesn't support using a different connection pool than [HikariCP](https://github.com/brettwooldridge/HikariCP).

## Changing the connection pool used by Slick

While Slick allows using a different connection pool than [HikariCP](http://brettwooldridge.github.io/HikariCP/) (though, Slick currently only offers built-in support for HikariCP, and requires you to provide an implementation of [JdbcDataSourceFactory](http://slick.typesafe.com/doc/3.1.0/api/index.html#slick.jdbc.JdbcDataSourceFactory) if you want to use a different connection pool), Play Slick currently doesn't allow using a different connection pool than HikariCP. If you find yourself needing this feature, you can try to drop us a note on [our forums](https://discuss.lightbend.com/).
While Slick allows using a different connection pool than [HikariCP](https://github.com/brettwooldridge/HikariCP) (though, Slick currently only offers built-in support for HikariCP, and requires you to provide an implementation of [JdbcDataSourceFactory](https://scala-slick.org/doc/3.3.2/api/index.html#slick.jdbc.JdbcDataSourceFactory) if you want to use a different connection pool), Play Slick currently doesn't allow using a different connection pool than HikariCP. If you find yourself needing this feature, you can try to drop us a note on [our forums](https://discuss.lightbend.com/).

## A binding to `play.api.db.DBApi` was already configured

Expand Down
Original file line number Diff line number Diff line change
@@ -1,8 +1,8 @@
# Play Slick Migration Guide

This is a guide for migrating from Play Slick v0.8 to v1.0, v1.1 or v2.0.0.
This is a guide for migrating from Play Slick to a version that supports the new Slick 3.0 APIs.

It assumes you have already migrated your project to use Play 2.5 (see [Play 2.5 Migration Guide](https://www.playframework.com/documentation/2.5.x/Migration25)), that you have read the [Slick 3.1 documentation](http://slick.typesafe.com/docs/), and are ready to migrate your Play application to use the new Slick Database I/O Actions API.
It assumes you have already migrated your project to use Play 2.5 (see [Play 2.5 Migration Guide](https://www.playframework.com/documentation/2.5.x/Migration25)), that you have read the [Slick documentation](https://scala-slick.org/docs/), and are ready to migrate your Play application to use the new Slick Database I/O Actions API.

## Build changes

Expand All @@ -24,7 +24,7 @@ While, if you are not using evolutions, you can now safely remove `evolutionplug

## Database configuration

With the past releases of Slick Play (which used Slick 2.1 or earlier), you used to configure Slick datasources exactly like you would configure Play JDBC datasources. This is no longer the case, and the following configuration will now be **ignored** by Play Slick:
With the past releases of Play Slick (which used Slick 2.1 or earlier), you used to configure Slick datasources exactly like you would configure Play JDBC datasources. This is no longer the case, and the following configuration will now be **ignored** by Play Slick:

```conf
db.default.driver=org.h2.Driver
Expand All @@ -38,7 +38,7 @@ There are several reasons for this change. First, the above is not a valid Slick
Here is how you would need to migrate the above configuration:

```conf
slick.dbs.default.driver="slick.driver.H2Driver$" # You must provide the required Slick driver!
slick.dbs.default.profile="slick.jdbc.H2Profile$" # You must provide the required Slick profile!
slick.dbs.default.db.driver=org.h2.Driver
slick.dbs.default.db.url="jdbc:h2:mem:play"
slick.dbs.default.db.user=sa
Expand Down Expand Up @@ -80,7 +80,7 @@ db.$dbName.maxQueriesPerRequest
slick.db.execution.context
```

The parameter `db.$dbName.maxQueriesPerRequest` was used to limit the number of tasks queued in the thread pool. In Slick 3 you can reach similar results by tuning the configuration parameters `numThreads` and `queueSize`. Read the Slick ScalaDoc for [Database.forConfig](http://slick.typesafe.com/doc/3.1.0/api/index.html#slick.jdbc.JdbcBackend$DatabaseFactoryDef@forConfig(String,Config,Driver,ClassLoader):Database) (make sure to expand the `forConfig` row in the doc).
The parameter `db.$dbName.maxQueriesPerRequest` was used to limit the number of tasks queued in the thread pool. In Slick 3 you can reach similar results by tuning the configuration parameters `numThreads` and `queueSize`. Read the Slick ScalaDoc for [Database.forConfig](https://scala-slick.org/doc/3.1.0/api/index.html#slick.jdbc.JdbcBackend$DatabaseFactoryDef@forConfig%28path:String,config:com.typesafe.config.Config,driver:java.sql.Driver,classLoader:ClassLoader%29:JdbcBackend.this.Database) (make sure to expand the `forConfig` row in the doc).

While the parameter `slick.db.execution.context` was used to name the thread pools created by Play Slick. In Slick 3, each thread pool is named using the Slick database configuration path, i.e., if in your **`application.conf`** you have provided a Slick configuration for the database named `default`, then Slick will create a thread pool named `default` for executing the database action on the default database. Note that the name used for the thread pool is not configurable.

Expand Down
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
/*
* Copyright (C) 2011-2015 Typesafe Inc. <http://www.typesafe.com>
* Copyright (C) Lightbend Inc. <https://www.lightbend.com>
*/
package scalaguide.slick
package di
Expand Down
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
/*
* Copyright (C) 2011-2015 Typesafe Inc. <http://www.typesafe.com>
* Copyright (C) Lightbend Inc. <https://www.lightbend.com>
*/
package scalaguide.slick
package global
Expand Down
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
/*
* Copyright (C) 2009-2014 Typesafe Inc. <http://www.typesafe.com>
* Copyright (C) Lightbend Inc. <https://www.lightbend.com>
*/
package scalaguide.slick

Expand Down
6 changes: 3 additions & 3 deletions docs/manual/working/scalaGuide/main/sql/slick/code/slick.sbt
Original file line number Diff line number Diff line change
@@ -1,10 +1,10 @@
// #add-library-dependencies
libraryDependencies += "com.typesafe.play" %% "play-slick" % "4.0.0"
libraryDependencies += "com.typesafe.play" %% "play-slick" % "5.0.0"
// #add-library-dependencies

// #add-dependency-with-evolutions
libraryDependencies ++= Seq(
"com.typesafe.play" %% "play-slick" % "4.0.0",
"com.typesafe.play" %% "play-slick-evolutions" % "4.0.0"
"com.typesafe.play" %% "play-slick" % "5.0.0",
"com.typesafe.play" %% "play-slick-evolutions" % "5.0.0"
)
// #add-dependency-with-evolutions