From 0ec7ddb82dcad967e558f3d6f566ac2147e415ad Mon Sep 17 00:00:00 2001 From: "robin.bygrave" Date: Fri, 1 May 2026 14:59:36 +1200 Subject: [PATCH] Docs: Change the ordering so that test container setup proceeds the main database configuration --- docs/guides/README.md | 4 ++-- docs/guides/add-ebean-postgres-database-config.md | 11 ++++++----- docs/guides/add-ebean-postgres-maven-pom.md | 6 ++++-- docs/guides/add-ebean-postgres-test-container.md | 14 +++++++++++--- 4 files changed, 23 insertions(+), 12 deletions(-) diff --git a/docs/guides/README.md b/docs/guides/README.md index e500d9463..1322b5de2 100644 --- a/docs/guides/README.md +++ b/docs/guides/README.md @@ -15,8 +15,8 @@ existing Maven project. Complete the steps in order. | Step | Guide | Description | |------|-------|-------------| | 1 | [Maven POM setup](add-ebean-postgres-maven-pom.md) | Add Ebean dependencies, the enhancement plugin, and the querybean-generator annotation processor to `pom.xml` | -| 2 | [Database configuration](add-ebean-postgres-database-config.md) | Configure the Ebean `Database` bean using `DataSourceBuilder` and `DatabaseBuilder` with Avaje Inject | -| 3 | [Test container setup](add-ebean-postgres-test-container.md) | Start a PostgreSQL (or PostGIS) Docker container for tests using `@TestScope @Factory` with Avaje Inject; covers image mirror, read-only datasource, and PostGIS variant | +| 2 | [Test container setup](add-ebean-postgres-test-container.md) | Start a PostgreSQL (or PostGIS) Docker container for tests using `@TestScope @Factory` with Avaje Inject; verify the test database works with `mvn verify` before adding production configuration | +| 3 | [Database configuration](add-ebean-postgres-database-config.md) | Configure the production Ebean `Database` bean using `DataSourceBuilder` and `DatabaseBuilder` with Avaje Inject | ## Entity beans diff --git a/docs/guides/add-ebean-postgres-database-config.md b/docs/guides/add-ebean-postgres-database-config.md index 7e06ffb7b..8e39f3105 100644 --- a/docs/guides/add-ebean-postgres-database-config.md +++ b/docs/guides/add-ebean-postgres-database-config.md @@ -4,7 +4,7 @@ This guide provides step-by-step instructions for configuring an Ebean `Database` bean using **Avaje Inject** (`@Factory` / `@Bean`), backed by a PostgreSQL datasource built -with Ebean's `DataSourceBuilder`. Follow every step in order. This is Step 2 of 3. +with Ebean's `DataSourceBuilder`. Follow every step in order. This is Step 3 of 3. --- @@ -12,6 +12,8 @@ with Ebean's `DataSourceBuilder`. Follow every step in order. This is Step 2 of - **Step 1 complete**: `pom.xml` already includes `ebean-postgres`, `ebean-maven-plugin`, and `querybean-generator` (see `add-ebean-postgres-maven-pom.md`) +- **Step 2 complete**: Test container setup is working and `mvn verify` passes + (see `add-ebean-postgres-test-container.md`) - **Avaje Inject** is on the classpath (e.g. `io.avaje:avaje-inject`) - A configuration source is available at runtime (e.g. `avaje-config` reading `application.yml` or environment variables) @@ -283,8 +285,7 @@ validation best practices, see the [ebean-datasource guides](https://github.com/ --- -## Next Step +## Related -Proceed to **Step 3: Test container setup** -(`add-ebean-postgres-test-container.md`) to wire an injectable test `Database` -backed by `ebean-test` containers. +The test container setup (Step 2) should already be complete and passing +before this step. See `add-ebean-postgres-test-container.md`. diff --git a/docs/guides/add-ebean-postgres-maven-pom.md b/docs/guides/add-ebean-postgres-maven-pom.md index a049cc5e6..0248702a2 100644 --- a/docs/guides/add-ebean-postgres-maven-pom.md +++ b/docs/guides/add-ebean-postgres-maven-pom.md @@ -171,5 +171,7 @@ Expected result: `BUILD SUCCESS` with no errors from Ebean or the annotation pro ## Next Step -Proceed to **Step 2: Configure the Datasource and Ebean Database bean** -(`add-ebean-postgres-database-config.md`). +Proceed to **Step 2: Test container setup** +(`add-ebean-postgres-test-container.md`) to wire an injectable test `Database` +backed by `ebean-test` containers. Verify with `mvn verify` before continuing +to production database configuration. diff --git a/docs/guides/add-ebean-postgres-test-container.md b/docs/guides/add-ebean-postgres-test-container.md index e5e0eefb1..76c95fec1 100644 --- a/docs/guides/add-ebean-postgres-test-container.md +++ b/docs/guides/add-ebean-postgres-test-container.md @@ -4,7 +4,12 @@ This guide provides step-by-step instructions for setting up a PostgreSQL Docker container for tests using `ebean-test-containers`, exposing an `io.ebean.Database` -bean via an Avaje Inject `@TestScope @Factory` class. This is Step 3 of 3. +bean via an Avaje Inject `@TestScope @Factory` class. This is Step 2 of 3. + +Complete this step before configuring the production database in Step 3. Getting +the test container working first gives you a fast feedback loop — you can verify +entity changes compile, enhance, and persist correctly with `mvn verify` before +wiring up production datasource configuration. Two variants are covered: - **Variant A** — plain PostgreSQL @@ -17,7 +22,6 @@ Two variants are covered: - **Step 1 complete**: `pom.xml` includes `ebean-postgres`, `ebean-maven-plugin`, `querybean-generator`, and **`ebean-test`** as a test-scoped dependency (see `add-ebean-postgres-maven-pom.md`) -- **Step 2 complete**: A production `Database` bean exists (see `add-ebean-postgres-database-config.md`) - **Avaje Inject** is on the classpath with test support (`io.avaje:avaje-inject-test`) - **Docker** is installed and running on the developer machine @@ -181,7 +185,7 @@ class DatabaseTest { Run the tests: ```bash -mvn test -pl +mvn verify ``` Expected log output confirming the container started and Ebean connected: @@ -194,6 +198,10 @@ INFO DatabasePlatform name:my_app platform:postgres INFO Executing db-create-all.sql - ... ``` +**Important:** Verify this step passes with `mvn verify` before proceeding to +Step 3 (production database configuration). A working test container gives you +a fast feedback loop for all subsequent entity and query changes. + --- ## Optional configurations