@ServiceConnection on a PostgreSQL container produces JdbcConnectionDetails but not R2dbcConnectionDetails

[dreamstar-enterprises]

@ServiceConnection on a PostgreSQLContainer produces JdbcConnectionDetails but not R2dbcConnectionDetails

Spring Boot version: 4.0.0
Testcontainers version: reproduced on both 2.0.4 and 1.21.2
Java: 25 · Kotlin: 2.4.10 · Build: Gradle, io.spring.dependency-management
Docker: 28.3.2 (macOS, aarch64)

Summary

A PostgreSQLContainer @Bean annotated @ServiceConnection in a @TestConfiguration supplies connection
details to Flyway (JDBC) but not to R2DBC. Flyway connects to the container and migrates successfully, proving
JdbcConnectionDetails is published. In the same context, the application's ConnectionFactory ignores the
container and uses whatever spring.r2dbc.url resolves to, which means R2dbcConnectionDetails is absent.

Because the fallback is a working property rather than an error, this fails as an obscure connection error to
whatever host the property names, rather than as a missing-bean or misconfiguration message.

Reproduction

@TestConfiguration(proxyBeanMethods = false)
class ContainerConfiguration {

    @Bean
    @ServiceConnection
    fun postgres(): PostgreSQLContainer = PostgreSQLContainer("postgres:17")
}

@SpringBootApplication
@Import(ContainerConfiguration::class)
class TestApplication

@SpringBootTest(classes = [TestApplication::class])
@ActiveProfiles("test")
class SomeIntegrationTest { /* autowires a repository backed by R2DBC */ }

application-test.yaml:

spring:
  r2dbc:
    url: r2dbc:postgresql://ignored.invalid:5432/ignored   # deliberately unreachable
    pool:
      enabled: true

Expected: the container's R2dbcConnectionDetails takes precedence and the application connects to the
container, as it does for Flyway over JDBC.

Actual:

org.springframework.dao.DataAccessResourceFailureException: Failed to obtain R2DBC Connection
Caused by: io.r2dbc.postgresql.PostgresqlConnectionFactory$PostgresConnectionException:
          [08003] Cannot connect to ignored.invalid/<unresolved>:5432
Caused by: java.net.UnknownHostException: ignored.invalid

The container is running and healthy throughout.

Evidence that R2dbcConnectionDetails is genuinely absent

R2dbcAutoConfiguration.propertiesR2dbcConnectionDetails is annotated
@ConditionalOnMissingBean(R2dbcConnectionDetails.class). The properties-backed implementation is therefore
created only when no other R2dbcConnectionDetails bean exists. Since the application demonstrably uses the
property value, the container's bean is not present.

Cross-check: removing spring.r2dbc.url from the test profile and giving the placeholder in the main
application.yaml an unreachable default made the application connect to that default instead — again showing
the property is being consulted rather than overridden.

Flyway, in the same context and from the same container bean, connects correctly and migrates the full schema.
So @ServiceConnection processing is working; only the R2DBC side produces nothing.

What was ruled out

Each of these was changed independently and the behaviour did not change:

variable	values tried
Testcontainers version	2.0.4 (org.testcontainers.postgresql.PostgreSQLContainer) and 1.21.2 (org.testcontainers.containers.PostgreSQLContainer)
container image	custom image built via ImageFromDockerfile + asCompatibleSubstituteFor("postgres"), and stock postgres:17
where the configuration is imported	@Import on the @SpringBootApplication class named in @SpringBootTest(classes = …), and @Import directly on the test class
connection name	default, and explicit @ServiceConnection("postgresql")
Flyway	enabled and disabled, to remove it as a factor

The factory itself appears correctly wired:

• org.springframework.boot.r2dbc.testcontainers.PostgresR2dbcContainerConnectionDetailsFactory is present in
  spring-boot-r2dbc-4.0.0.jar
• it is registered in that jar's META-INF/spring.factories
• its generic parameter is org.testcontainers.postgresql.PostgreSQLContainer — the exact class of the bean
• its required class, io.r2dbc.spi.ConnectionFactoryOptions, is on the test runtime classpath
  (io.r2dbc:r2dbc-spi:1.0.0.RELEASE, org.postgresql:r2dbc-postgresql:1.1.1.RELEASE)

Note the jar also ships DeprecatedPostgresR2dbcContainerConnectionDetailsFactory, whose generic parameter is the
1.x org.testcontainers.containers.PostgreSQLContainer<?>. Neither path produced details in our testing.

spring-boot-testcontainers-4.0.0.jar itself contains no Postgres classes; the factories live in the
technology-specific modules, which may be relevant to how they are discovered.

Workaround

Publishing the connection as system properties from the container works, since system properties outrank
configuration files:

init {
    CONTAINER.start()
    System.setProperty("spring.r2dbc.url",
        "r2dbc:postgresql://${CONTAINER.host}:${CONTAINER.firstMappedPort}/$DATABASE_NAME")
    System.setProperty("spring.r2dbc.username", CONTAINER.username)
    System.setProperty("spring.r2dbc.password", CONTAINER.password)
}

Notes

• The application is WebFlux with spring.main.web-application-type: none in the test profile.
• Dependency versions are managed by io.spring.dependency-management; the org.testcontainers coordinates are
  not managed by it under Boot 4 and carry explicit versions.
• We did not test the static-field / @ImportTestcontainers style of declaring the container, only the
  @Bean + @ServiceConnection style shown above.

[snicoll]

Thanks for the report.

We find that the quickest way for us to understand the problem that you're facing is to look at a sample that reproduces it. This allows us to see exactly what code, dependencies, and configuration is involved. It also reduces the need for us to make educated guesses and the potential for us misunderstanding what you've described.

You can share a sample with us by pushing it to a separate repository on GitHub or by zipping it up and attaching it to this issue.

[dreamstar-enterprises]

Hi Stephane,

Thanks for offering to look into this.

I may have just found a fix, but its still worth your team looking at, still, I think. See the read me file first in the attached zip.

spring-boot-51502-repro.zip

KR,

ST

More info below:

# =====================================================================================================================
# TESTCONTAINERS
# =====================================================================================================================
# Starts a real PostgreSQL in Docker for a test run, so tests need no database on the machine and no environment
# file pointing at one. `@ServiceConnection` wires it: ContainerConfiguration declares the container and Boot reads
# its address for both R2DBC and Flyway.
#
# `testcontainers-r2dbc` is not optional and is easy to miss. Boot's
# `PostgresR2dbcContainerConnectionDetailsFactory` refers to `org.testcontainers.r2dbc.R2DBCDatabaseContainer`,
# which lives in that module and which `testcontainers-postgresql` does not depend on. Without it the factory
# cannot load, no `R2dbcConnectionDetails` is published, and Boot falls back to whatever `spring.r2dbc.url` says —
# reaching nothing, and reporting an unknown host rather than a missing class. Note the asymmetry that hides it:
# JDBC needs no equivalent module, because Boot registers one generic factory there that matches on the container
# base type, where R2DBC registers one per database bound to a concrete container class.
#
# Versions: spring-boot-testcontainers is a Boot artifact and takes Boot's. The org.testcontainers coordinates
# need an explicit ref — io.spring.dependency-management supplies none for them, so they would resolve to nothing.
# Keep them in step; they are one release train. Crossing the 1.x/2.x boundary is a rename, not a bump: 2.x
# prefixes every module `testcontainers-`, where 1.x was bare (`org.testcontainers:postgresql`).
# =====================================================================================================================
spring-boot-testcontainers = { module = "org.springframework.boot:spring-boot-testcontainers" }
testcontainers-postgresql = { module = "org.testcontainers:testcontainers-postgresql", version.ref = "testcontainers" }
testcontainers-r2dbc = { module = "org.testcontainers:testcontainers-r2dbc", version.ref = "testcontainers" }
testcontainers-junit-jupiter = { module = "org.testcontainers:testcontainers-junit-jupiter", version.ref = "testcontainers" }

[dreamstar-enterprises]

Hi Stéphane,

I've traced this to the end. There are three separate things in it, and only the first is specific to my
application — the other two look like they may be worth your team's attention, and the attached sample
reproduces the second in isolation.

Latest zip file >>

spring-boot-51502-repro.zip

1. Why it did not work in my application

My application declares its own ConnectionFactory:

@Bean
fun connectionFactory(): ConnectionFactory {
    val url = requireNotNull(r2dbcProperties.url) { "spring.r2dbc.url must be set" }
    ...
    return ConnectionFactoryBuilder.withUrl(url).username(username).password(password)...
}

It reads R2dbcProperties and nothing else. Boot's own factory is @ConditionalOnMissingBean, so mine replaced
it — and with it the whole R2dbcConnectionDetails path. The container details were being published; nothing in
my application ever consulted them.

What made this hard to see is that the two mechanisms fail identically from the outside. A missing
R2dbcConnectionDetails and an ignored R2dbcConnectionDetails both present as "my container is up, and the
application connected to whatever spring.r2dbc.url says". There is no signal distinguishing them, which is why
I read it as @ServiceConnection not producing the bean.

The fix is to apply the same precedence Boot's auto-configuration applies:

val builder = connectionDetails.getIfAvailable()
    ?.let { ConnectionFactoryBuilder.withOptions(it.connectionFactoryOptions.mutate()) }
    ?: ConnectionFactoryBuilder.withUrl(url).username(username).password(password)

Possibly worth considering: a custom ConnectionFactory bean silently disables connection details, including
@ServiceConnection, Docker Compose support and the Testcontainers integration. Nothing warns, and the
ConnectionFactoryBuilder API gives no hint that withUrl(...) is the branch that opts out. A note in the
R2DBC documentation — or a WARN when an R2dbcConnectionDetails bean exists but no auto-configured factory
consumes it — would have saved this issue entirely.

2. A missing Testcontainers module, silently

While reducing the above I hit a second and independent problem. The attached sample reproduces it with no custom
ConnectionFactory — a single @ServiceConnection bean and nothing else:

@ServiceConnection on a PostgreSQLContainer produces no R2dbcConnectionDetails unless
org.testcontainers:testcontainers-r2dbc is on the test classpath.

spring-boot-r2dbc registers PostgresR2dbcContainerConnectionDetailsFactory, which refers to
org.testcontainers.r2dbc.R2DBCDatabaseContainer. That class ships in Testcontainers' separate r2dbc module,
which org.testcontainers:testcontainers-postgresql does not depend on. Without it the factory cannot load, and
Boot falls back to spring.r2dbc.*.

The sample toggles exactly that one dependency:

./gradlew test                          # fails
./gradlew test -PwithR2dbcModule=true   # passes

Depending on surrounding configuration the failure surfaces either as a property-fallback connection error, or as
NoClassDefFoundError: org/testcontainers/r2dbc/R2DBCDatabaseContainer while creating connectionFactory.
Neither mentions testcontainers-r2dbc.

3. The packaging asymmetry that hides it

This is what made (2) counter-intuitive, and it may be the more interesting of the two:

• spring-boot-jdbc registers one generic JdbcContainerConnectionDetailsFactory, matching on the
  JdbcDatabaseContainer base type. It needs no additional Testcontainers module.
• spring-boot-r2dbc registers one factory per database, each bound to a concrete container class, and each
  depending on a Testcontainers module that the corresponding database module does not bring in.

So adding testcontainers-postgresql is sufficient for JDBC and insufficient for R2DBC, and the JDBC half
working is actively misleading — it reads as "@ServiceConnection is wired up correctly, so the R2DBC gap must
be a Boot bug", which is exactly the conclusion I reached.

Suggestions, entirely your call:

1. Have spring-boot-r2dbc declare an optional dependency on the Testcontainers r2dbc module, or document the
   requirement next to @ServiceConnection.
2. Log at WARN when a ContainerConnectionDetailsFactory matches a container but cannot load, rather than
   falling through to properties silently.
3. Consider whether the R2DBC side could match on a base type the way the JDBC side does.

Environment as before: Boot 4.0.0, Testcontainers 2.0.4 (also 1.21.2), Kotlin 2.4.10, JDK 25, Gradle 9.7.0,
r2dbc-postgresql 1.1.1.RELEASE.

KR,
ST

[cfcromn]

I took a look at this on current main as well.

The same structure is still present there. One detail worth noting is that spring-boot-r2dbc already declares testcontainers-r2dbc as an optional dependency, so simply adding that dependency does not appear to address the consumer classpath issue.

I also traced the factory loading path. A missing R2DBC Testcontainers class can cause the factory to be skipped during loading, which makes the fallback to spring.r2dbc.* difficult to diagnose. A relatively small option may therefore be to improve the diagnostics when a matching connection details factory cannot be loaded due to a missing class. This should also be possible to cover with a focused test without starting a container.

I’d be happy to work on that if improving the diagnostics is the direction you’d prefer.