This is an automated email from the ASF dual-hosted git repository.
Croway pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/camel.git
The following commit(s) were added to refs/heads/main by this push:
new e2daddd135e9 camel-sql/camel-jdbc: docs - set the driver socket
timeout and a validating pool, so a dead or silent database is noticed (#30060)
e2daddd135e9 is described below
commit e2daddd135e9ddd3564d7aa41d3698e0d69750bc
Author: Federico Mariani <[email protected]>
AuthorDate: Mon Nov 16 10:38:48 2026 +0100
camel-sql/camel-jdbc: docs - set the driver socket timeout and a validating
pool, so a dead or silent database is noticed (#30060)
* camel-sql/camel-jdbc: docs - set the driver socket timeout and a
validating pool, so a dead or silent database is noticed
* camel-sql/camel-jdbc: docs - drop the StreamList redelivery note,
CAMEL-26996 changed that behaviour
Since CAMEL-26996 a StreamList whose read failed keeps failing, so a
redelivered
Splitter fails too; main already documents this in the StreamList section.
* camel-jdbc: docs - drop the StreamList commit note, CAMEL-26997 changed
that behaviour, and spell forever
Since CAMEL-26997 the producer commits a StreamList when the exchange is
done, and main
documents how statement.fetchSize then works on PostgreSQL.
---
.../apache/camel/catalog/docs/jdbc-component.adoc | 32 ++++++++++
.../apache/camel/catalog/docs/sql-component.adoc | 70 ++++++++++++++++++++++
.../camel-jdbc/src/main/docs/jdbc-component.adoc | 32 ++++++++++
.../camel-sql/src/main/docs/sql-component.adoc | 70 ++++++++++++++++++++++
4 files changed, 204 insertions(+)
diff --git
a/catalog/camel-catalog/src/generated/resources/org/apache/camel/catalog/docs/jdbc-component.adoc
b/catalog/camel-catalog/src/generated/resources/org/apache/camel/catalog/docs/jdbc-component.adoc
index e8018682977d..a5ea7f706a2a 100644
---
a/catalog/camel-catalog/src/generated/resources/org/apache/camel/catalog/docs/jdbc-component.adoc
+++
b/catalog/camel-catalog/src/generated/resources/org/apache/camel/catalog/docs/jdbc-component.adoc
@@ -183,6 +183,38 @@ from("direct:projects")
.to("jdbc:myDataSource?useHeadersAsParameters=true");
----
+=== Noticing a dead or silent database
+
+The JDBC component has no network timeout of its own: how long the producer
waits for a database that stopped
+answering depends on the JDBC driver and the connection pool of the
`DataSource`. The durations below describe how
+those libraries behave by default; they are approximate, not guarantees of
Camel.
+
+The common JDBC drivers have no read timeout by default. A statement on a
connection that went silent (the database
+host is gone, or a firewall or NAT dropped the connection without a reset)
waits in a socket read, with no error and
+nothing logged, until the operating system gives up on the connection: on
Linux about 15 minutes when the request was
+not acknowledged, and never when it was and TCP keep-alive is off. Set the
driver's socket timeout, longer than your
+slowest statement, so the producer fails and the error handler can redeliver:
+
+[cols="2,2,1,1"]
+|===
+| Driver | Property | Unit | Default
+
+| PostgreSQL (pgjdbc) | `socketTimeout` | seconds | 0 (no timeout)
+| MySQL Connector/J | `socketTimeout` | milliseconds | 0 (no timeout)
+| MariaDB Connector/J | `socketTimeout` | milliseconds | 0 (no timeout)
+| Microsoft SQL Server (mssql-jdbc) | `socketTimeout` | milliseconds | 0 (no
timeout)
+| Oracle (thin driver) | `oracle.jdbc.ReadTimeout` | milliseconds | not set
(no timeout)
+|===
+
+For example `jdbc:postgresql://db:5432/orders?socketTimeout=30` in the JDBC
URL, or the same property as a driver
+property of the pool.
+
+After a socket timeout or a reset the connection is broken, and the pool must
not hand it out again. HikariCP and the
+Agroal pool that Quarkus configures drop it by default; Agroal used directly
needs a connection validator and an
+exception sorter. See
xref:sql-component.adoc#_noticing_a_dead_or_silent_database[Noticing a dead or
silent database]
+in the SQL component for the pool settings, Spring Boot and Quarkus
properties, and starting while the database is
+down.
+
== Examples
In the following example, we set up the DataSource that camel-jdbc requires.
diff --git
a/catalog/camel-catalog/src/generated/resources/org/apache/camel/catalog/docs/sql-component.adoc
b/catalog/camel-catalog/src/generated/resources/org/apache/camel/catalog/docs/sql-component.adoc
index 413895a4eff9..c8a827131e95 100644
---
a/catalog/camel-catalog/src/generated/resources/org/apache/camel/catalog/docs/sql-component.adoc
+++
b/catalog/camel-catalog/src/generated/resources/org/apache/camel/catalog/docs/sql-component.adoc
@@ -314,6 +314,76 @@ You can set a reference to a `DataSource` in the URI
directly:
sql:select * from table where id=# order by name?dataSource=#myDS
----
+==== Noticing a dead or silent database
+
+The SQL component has no network timeout of its own: how long a poll or a send
waits for a database that stopped
+answering depends on the JDBC driver and the connection pool of the
`DataSource`. The durations below describe how
+those libraries behave by default; they are approximate, not guarantees of
Camel.
+
+*Set the driver's socket timeout.* The common JDBC drivers have no read
timeout by default. A statement on a
+connection that went silent (the database host is gone, or a firewall or NAT
dropped the connection without a reset)
+waits in a socket read, with no error and nothing logged, until the operating
system gives up on the connection:
+on Linux about 15 minutes when the request was not acknowledged, and never
when it was and TCP keep-alive is off.
+Meanwhile the consumer's xref:manual::health-check.adoc[health check] stays
UP, because it counts only the polls that
+failed.
+
+A socket timeout ends such a read with an error: the poll fails and is retried
at the next poll, or the producer
+fails and the error handler can redeliver. Set it longer than your slowest
statement:
+
+[cols="2,2,1,1"]
+|===
+| Driver | Property | Unit | Default
+
+| PostgreSQL (pgjdbc) | `socketTimeout` | seconds | 0 (no timeout)
+| MySQL Connector/J | `socketTimeout` | milliseconds | 0 (no timeout)
+| MariaDB Connector/J | `socketTimeout` | milliseconds | 0 (no timeout)
+| Microsoft SQL Server (mssql-jdbc) | `socketTimeout` | milliseconds | 0 (no
timeout)
+| Oracle (thin driver) | `oracle.jdbc.ReadTimeout` | milliseconds | not set
(no timeout)
+|===
+
+Set it in the JDBC URL, for example
`jdbc:postgresql://db:5432/orders?socketTimeout=30`, or as a driver property of
+the pool:
+
+* Spring Boot with HikariCP:
`spring.datasource.hikari.data-source-properties.socketTimeout=30`
+* Quarkus 3.36 or later: `quarkus.datasource.jdbc.read-timeout=30S` sets the
property of the database kind; with an
+older Quarkus,
`quarkus.datasource.jdbc.additional-jdbc-properties.socketTimeout=30`
(PostgreSQL).
+
+*Let the pool drop broken connections.* After a socket timeout or a reset the
connection is broken, and the pool must
+not hand it out again:
+
+* HikariCP does it by default: it checks a connection with
`Connection.isValid()` (bounded by `validationTimeout`,
+5 seconds) when the connection is borrowed after more than 500 ms idle, and
evicts a connection whose error has an
+SQLState of class `08` (connection exception).
+* Quarkus configures Agroal with a `Connection.isValid()` validator, a
background validation every 2 minutes, the
+exception sorter of the database kind, and an acquisition timeout of 5 seconds.
+* Agroal used directly has no validator and no exception sorter by default: a
broken connection goes back to the pool
+and fails each statement it is given again. Its default `acquisitionTimeout`
of 0 waits forever when the pool is
+exhausted. Configure them:
++
+._Java-only: an Agroal pool that drops broken PostgreSQL connections_
+[source,java]
+----
+AgroalDataSource ds = AgroalDataSource.from(new
AgroalDataSourceConfigurationSupplier()
+ .connectionPoolConfiguration(pool -> pool
+ .maxSize(10)
+ .acquisitionTimeout(Duration.ofSeconds(5))
+
.connectionValidator(ConnectionValidator.defaultValidatorWithTimeout(5))
+ .validationTimeout(Duration.ofMinutes(1)) // interval of the
background validation
+ .exceptionSorter(new PostgreSQLExceptionSorter())
+ .connectionFactoryConfiguration(cf -> cf
+ .jdbcUrl("jdbc:postgresql://db:5432/orders")
+ .jdbcProperty("socketTimeout", "30")
+ .principal(new NamePrincipal("app"))
+ .credential(new SimplePassword("secret")))));
+----
+* Spring `SingleConnectionDataSource` keeps one connection and fails every
call once that connection is closed: it
+never recovers, so keep it for tests.
+
+*Starting while the database is down.* `new HikariDataSource(hikariConfig)`
opens a connection in the constructor and
+throws when the database cannot be reached, so the application does not start.
Set `initializationFailTimeout` to
+`-1` on the `HikariConfig`, or create the pool with the no-argument
constructor and its setters (as Spring Boot
+does): the pool then connects on first use, and the consumer polls again until
the database is back.
+
=== Using named parameters
In the given route below, we want to get all the projects from the
diff --git a/components/camel-jdbc/src/main/docs/jdbc-component.adoc
b/components/camel-jdbc/src/main/docs/jdbc-component.adoc
index e8018682977d..a5ea7f706a2a 100644
--- a/components/camel-jdbc/src/main/docs/jdbc-component.adoc
+++ b/components/camel-jdbc/src/main/docs/jdbc-component.adoc
@@ -183,6 +183,38 @@ from("direct:projects")
.to("jdbc:myDataSource?useHeadersAsParameters=true");
----
+=== Noticing a dead or silent database
+
+The JDBC component has no network timeout of its own: how long the producer
waits for a database that stopped
+answering depends on the JDBC driver and the connection pool of the
`DataSource`. The durations below describe how
+those libraries behave by default; they are approximate, not guarantees of
Camel.
+
+The common JDBC drivers have no read timeout by default. A statement on a
connection that went silent (the database
+host is gone, or a firewall or NAT dropped the connection without a reset)
waits in a socket read, with no error and
+nothing logged, until the operating system gives up on the connection: on
Linux about 15 minutes when the request was
+not acknowledged, and never when it was and TCP keep-alive is off. Set the
driver's socket timeout, longer than your
+slowest statement, so the producer fails and the error handler can redeliver:
+
+[cols="2,2,1,1"]
+|===
+| Driver | Property | Unit | Default
+
+| PostgreSQL (pgjdbc) | `socketTimeout` | seconds | 0 (no timeout)
+| MySQL Connector/J | `socketTimeout` | milliseconds | 0 (no timeout)
+| MariaDB Connector/J | `socketTimeout` | milliseconds | 0 (no timeout)
+| Microsoft SQL Server (mssql-jdbc) | `socketTimeout` | milliseconds | 0 (no
timeout)
+| Oracle (thin driver) | `oracle.jdbc.ReadTimeout` | milliseconds | not set
(no timeout)
+|===
+
+For example `jdbc:postgresql://db:5432/orders?socketTimeout=30` in the JDBC
URL, or the same property as a driver
+property of the pool.
+
+After a socket timeout or a reset the connection is broken, and the pool must
not hand it out again. HikariCP and the
+Agroal pool that Quarkus configures drop it by default; Agroal used directly
needs a connection validator and an
+exception sorter. See
xref:sql-component.adoc#_noticing_a_dead_or_silent_database[Noticing a dead or
silent database]
+in the SQL component for the pool settings, Spring Boot and Quarkus
properties, and starting while the database is
+down.
+
== Examples
In the following example, we set up the DataSource that camel-jdbc requires.
diff --git a/components/camel-sql/src/main/docs/sql-component.adoc
b/components/camel-sql/src/main/docs/sql-component.adoc
index 413895a4eff9..c8a827131e95 100644
--- a/components/camel-sql/src/main/docs/sql-component.adoc
+++ b/components/camel-sql/src/main/docs/sql-component.adoc
@@ -314,6 +314,76 @@ You can set a reference to a `DataSource` in the URI
directly:
sql:select * from table where id=# order by name?dataSource=#myDS
----
+==== Noticing a dead or silent database
+
+The SQL component has no network timeout of its own: how long a poll or a send
waits for a database that stopped
+answering depends on the JDBC driver and the connection pool of the
`DataSource`. The durations below describe how
+those libraries behave by default; they are approximate, not guarantees of
Camel.
+
+*Set the driver's socket timeout.* The common JDBC drivers have no read
timeout by default. A statement on a
+connection that went silent (the database host is gone, or a firewall or NAT
dropped the connection without a reset)
+waits in a socket read, with no error and nothing logged, until the operating
system gives up on the connection:
+on Linux about 15 minutes when the request was not acknowledged, and never
when it was and TCP keep-alive is off.
+Meanwhile the consumer's xref:manual::health-check.adoc[health check] stays
UP, because it counts only the polls that
+failed.
+
+A socket timeout ends such a read with an error: the poll fails and is retried
at the next poll, or the producer
+fails and the error handler can redeliver. Set it longer than your slowest
statement:
+
+[cols="2,2,1,1"]
+|===
+| Driver | Property | Unit | Default
+
+| PostgreSQL (pgjdbc) | `socketTimeout` | seconds | 0 (no timeout)
+| MySQL Connector/J | `socketTimeout` | milliseconds | 0 (no timeout)
+| MariaDB Connector/J | `socketTimeout` | milliseconds | 0 (no timeout)
+| Microsoft SQL Server (mssql-jdbc) | `socketTimeout` | milliseconds | 0 (no
timeout)
+| Oracle (thin driver) | `oracle.jdbc.ReadTimeout` | milliseconds | not set
(no timeout)
+|===
+
+Set it in the JDBC URL, for example
`jdbc:postgresql://db:5432/orders?socketTimeout=30`, or as a driver property of
+the pool:
+
+* Spring Boot with HikariCP:
`spring.datasource.hikari.data-source-properties.socketTimeout=30`
+* Quarkus 3.36 or later: `quarkus.datasource.jdbc.read-timeout=30S` sets the
property of the database kind; with an
+older Quarkus,
`quarkus.datasource.jdbc.additional-jdbc-properties.socketTimeout=30`
(PostgreSQL).
+
+*Let the pool drop broken connections.* After a socket timeout or a reset the
connection is broken, and the pool must
+not hand it out again:
+
+* HikariCP does it by default: it checks a connection with
`Connection.isValid()` (bounded by `validationTimeout`,
+5 seconds) when the connection is borrowed after more than 500 ms idle, and
evicts a connection whose error has an
+SQLState of class `08` (connection exception).
+* Quarkus configures Agroal with a `Connection.isValid()` validator, a
background validation every 2 minutes, the
+exception sorter of the database kind, and an acquisition timeout of 5 seconds.
+* Agroal used directly has no validator and no exception sorter by default: a
broken connection goes back to the pool
+and fails each statement it is given again. Its default `acquisitionTimeout`
of 0 waits forever when the pool is
+exhausted. Configure them:
++
+._Java-only: an Agroal pool that drops broken PostgreSQL connections_
+[source,java]
+----
+AgroalDataSource ds = AgroalDataSource.from(new
AgroalDataSourceConfigurationSupplier()
+ .connectionPoolConfiguration(pool -> pool
+ .maxSize(10)
+ .acquisitionTimeout(Duration.ofSeconds(5))
+
.connectionValidator(ConnectionValidator.defaultValidatorWithTimeout(5))
+ .validationTimeout(Duration.ofMinutes(1)) // interval of the
background validation
+ .exceptionSorter(new PostgreSQLExceptionSorter())
+ .connectionFactoryConfiguration(cf -> cf
+ .jdbcUrl("jdbc:postgresql://db:5432/orders")
+ .jdbcProperty("socketTimeout", "30")
+ .principal(new NamePrincipal("app"))
+ .credential(new SimplePassword("secret")))));
+----
+* Spring `SingleConnectionDataSource` keeps one connection and fails every
call once that connection is closed: it
+never recovers, so keep it for tests.
+
+*Starting while the database is down.* `new HikariDataSource(hikariConfig)`
opens a connection in the constructor and
+throws when the database cannot be reached, so the application does not start.
Set `initializationFailTimeout` to
+`-1` on the `HikariConfig`, or create the pool with the no-argument
constructor and its setters (as Spring Boot
+does): the pool then connects on first use, and the consumer polls again until
the database is back.
+
=== Using named parameters
In the given route below, we want to get all the projects from the