Skip to content

[8.x] Fix the default datasource setting in the docs, explain startup usage - #911

Merged
mkurz merged 2 commits into
playframework:8.xfrom
mkurz:docs-ebean-startup-8.x
Oct 8, 2026
Merged

mkurz merged 2 commits into
playframework:8.xfrom
mkurz:docs-ebean-startup-8.x

Conversation

@mkurz

@mkurz mkurz commented Oct 8, 2026 •

Copy link
Copy Markdown
Member

The docs named a non-existent ebeanconfig.datasource.default setting to choose the default Ebean server, but it's play.ebean.defaultDatasource (as reported in #145).

Also add a section about using Ebean during application startup (see #457 and #65):

  • Components that use Ebean while they get created, e.g. eagerly bound ones or ones created via Guice's static injection (which runs even before eager singletons get created), have to depend on DynamicEvolutions, which creates the Ebean databases. Otherwise Ebean tries to create the database itself from its own configuration, which usually fails and leaves Ebean unusable until the JVM restarts. Later NoClassDefFoundError: Could not initialize class ... errors only point back to that first failure.
  • That doesn't mean that the evolutions have been applied. In dev mode, Play doesn't wait for pending evolutions (not even for components depending on ApplicationEvolutions), and can't show the evolutions page if the application fails to start. So the docs recommend not to use the database schema while components get created, or to let Play apply evolutions automatically, limited to dev mode via PlayKeys.devSettings, which is also what Evolutions not run property on play 2.8 #220 asks for.

Testing

  • Reproduced on current main: a repository created via Guice's requestStaticInjection that calls DB.getDefault() in its constructor makes the application fail to start, in prod as well as in dev mode. With a dependency on DynamicEvolutions, as in the new docs sample, it starts.
  • Reproduced that in dev mode with pending evolutions, a component querying the schema while it gets created makes the application fail to start, also when depending on ApplicationEvolutions. With autoApply, it starts.
  • The new docs sample gets compiled by the docs build; cd docs && sbt "validateCode; test" passes.

The docs named a non-existent ebeanconfig.datasource.default setting to
choose the default Ebean server; it's play.ebean.defaultDatasource.

Also explain that components using Ebean while they get created have to
depend on DynamicEvolutions, which creates the Ebean databases, that this
doesn't mean that the evolutions have been applied yet, and how to let
Play apply them automatically in dev mode only.
@mergify

mergify Bot commented Oct 8, 2026 •

Copy link
Copy Markdown
Contributor

This pull request does not currently match the merge queue conditions, so it cannot be queued from here. The box comes back if it matches again.

In dev mode, Play only waits for pending evolutions to be confirmed by
default, i.e. without autoApply. And with autoApply, a regenerated
1.sql makes Play apply the downs of its previous version first, which
drops the tables, so the development data gets lost.
@mkurz
mkurz merged commit 64d3b82 into playframework:8.x Oct 8, 2026
21 checks passed
@mkurz
mkurz deleted the docs-ebean-startup-8.x branch October 8, 2026 17:31
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant