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

Reply via email to