Merge pull request #5516 from BimsaraBodaragama/fix-4145/recomended-db-props

Author: himeshsiriwardana

en/identity-server/5.10.0/docs/setup/changing-to-ibm-db2.md

@@ -281,4 +281,31 @@ The elements in the above configuration are described below:
  | **rollbackOnReturn** | If `                defaultAutoCommit               ` =false, then you can set `                rollbackOnReturn               ` =true so that the pool can terminate the transaction by calling rollback on the connection as it is returned to the pool. The default value is false.                                                                                                     |
 
 
-    
+## Driver-Level Timeouts (Recommended for Production)
+
+If the database becomes unresponsive, WSO2 Identity Server threads can get stuck waiting for a JDBC connection. This happens because the Tomcat JDBC Pool can't abort connection creation by itself ([source](https://github.com/apache/tomcat/blob/9.0.82/modules/jdbc-pool/src/main/java/org/apache/tomcat/jdbc/pool/ConnectionPool.java#L693-L702){: target="_blank"}).
+
+To prevent this, configure **driver-level timeouts** in the JDBC URL:
+
+- **`connectTimeout`** → Maximum time to wait while establishing a database connection.  
+- **`socketTimeout`** (or driver-specific equivalent) → Maximum time to wait for responses on an active connection.  
+- **`tcpKeepAlive=true`** (if supported) → Helps detect unresponsive database servers.
+
+Also note the distinction:
+
+- **`maxWait`** (Tomcat pool) controls how long to wait for a free connection from the pool.  
+- **`connectTimeout` / `socketTimeout`** (driver) → how long to connect/read at the DB level.
+
+> **Note:** The `PoolExhaustedException` warning log is logged only when `maxWait` expires ([source](https://github.com/apache/tomcat/blob/9.0.82/modules/jdbc-pool/src/main/java/org/apache/tomcat/jdbc/pool/ConnectionPool.java#L739-L741){: target="_blank"}). It does **not** cover delays inside the driver’s connection or read operations. Driver-level timeouts are required to handle those cases.
+
+### Example: IBM DB2 database
+
+```toml
+[database.identity_db]
+url = "jdbc:db2://DB_HOST:50000/WSO2_IDENTITY_DB:loginTimeout=10;queryTimeout=60;"
+username = "..."
+password = "..."
+driver = "com.ibm.db2.jcc.DB2Driver"
+```
+
+Learn more in [IBM DB2 connection settings](https://www.ibm.com/docs/en/db2/11.5?topic=client-jdbc-properties){: target="_blank"}.

en/identity-server/5.10.0/docs/setup/changing-to-mssql.md

@@ -269,4 +269,31 @@ The elements in the above configuration are described below:
  | **rollbackOnReturn** | If `                defaultAutoCommit               ` =false, then you can set `                rollbackOnReturn               ` =true so that the pool can terminate the transaction by calling rollback on the connection as it is returned to the pool. The default value is false.                                                                                                     |
 
 
-    
+## Driver-Level Timeouts (Recommended for Production)
+
+If the database becomes unresponsive, WSO2 Identity Server threads can get stuck waiting for a JDBC connection. This happens because the Tomcat JDBC Pool can't abort connection creation by itself ([source](https://github.com/apache/tomcat/blob/9.0.82/modules/jdbc-pool/src/main/java/org/apache/tomcat/jdbc/pool/ConnectionPool.java#L693-L702){: target="_blank"}).
+
+To prevent this, configure **driver-level timeouts** in the JDBC URL:
+
+- **`connectTimeout`** → Maximum time to wait while establishing a database connection.  
+- **`socketTimeout`** (or driver-specific equivalent) → Maximum time to wait for responses on an active connection.  
+- **`tcpKeepAlive=true`** (if supported) → Helps detect unresponsive database servers.
+
+Also note the distinction:
+
+- **`maxWait`** (Tomcat pool) controls how long to wait for a free connection from the pool.  
+- **`connectTimeout` / `socketTimeout`** (driver) → how long to connect/read at the DB level.
+
+> **Note:** The `PoolExhaustedException` warning log is logged only when `maxWait` expires ([source](https://github.com/apache/tomcat/blob/9.0.82/modules/jdbc-pool/src/main/java/org/apache/tomcat/jdbc/pool/ConnectionPool.java#L739-L741){: target="_blank"}). It does **not** cover delays inside the driver’s connection or read operations. Driver-level timeouts are required to handle those cases.
+
+### Example: MSSQL database
+
+```toml
+[database.identity_db]
+url = "jdbc:sqlserver://DB_HOST:1433;databaseName=WSO2_IDENTITY_DB;loginTimeout=10;socketTimeout=60000"
+username = "..."
+password = "..."
+driver = "com.microsoft.sqlserver.jdbc.SQLServerDriver"
+```
+
+Learn more in [Microsoft JDBC driver properties](https://learn.microsoft.com/sql/connect/jdbc/setting-the-connection-properties){: target="_blank"}.

en/identity-server/5.10.0/docs/setup/changing-to-mysql.md

@@ -279,4 +279,31 @@ The elements in the above configuration are described below:
  | **rollbackOnReturn** | If `                defaultAutoCommit               ` =false, then you can set `                rollbackOnReturn               ` =true so that the pool can terminate the transaction by calling rollback on the connection as it is returned to the pool. The default value is false.                                                                                                     |
 
 
-    
+## Driver-Level Timeouts (Recommended for Production)
+
+If the database becomes unresponsive, WSO2 Identity Server threads can get stuck waiting for a JDBC connection. This happens because the Tomcat JDBC Pool can't abort connection creation by itself ([source](https://github.com/apache/tomcat/blob/9.0.82/modules/jdbc-pool/src/main/java/org/apache/tomcat/jdbc/pool/ConnectionPool.java#L693-L702){: target="_blank"}).
+
+To prevent this, configure **driver-level timeouts** in the JDBC URL:
+
+- **`connectTimeout`** → Maximum time to wait while establishing a database connection.  
+- **`socketTimeout`** (or driver-specific equivalent) → Maximum time to wait for responses on an active connection.  
+- **`tcpKeepAlive=true`** (if supported) → Helps detect unresponsive database servers.
+
+Also note the distinction:
+
+- **`maxWait`** (Tomcat pool) controls how long to wait for a free connection from the pool.  
+- **`connectTimeout` / `socketTimeout`** (driver) → how long to connect/read at the DB level.
+
+> **Note:** The `PoolExhaustedException` warning log is logged only when `maxWait` expires ([source](https://github.com/apache/tomcat/blob/9.0.82/modules/jdbc-pool/src/main/java/org/apache/tomcat/jdbc/pool/ConnectionPool.java#L739-L741){: target="_blank"}). It does **not** cover delays inside the driver’s connection or read operations. Driver-level timeouts are required to handle those cases.
+
+### Example: MySQL database
+
+```toml
+[database.identity_db]
+url = "jdbc:mysql://DB_HOST:3306/WSO2_IDENTITY_DB?connectTimeout=10000&socketTimeout=60000&tcpKeepAlive=true"
+username = "..."
+password = "..."
+driver = "com.mysql.cj.jdbc.Driver"
+```
+
+Learn more in [MySQL Connector/J properties](https://docs.oracle.com/cd/E19509-01/820-3497/agqju/index.html){: target="_blank"}.

en/identity-server/5.10.0/docs/setup/changing-to-oracle-rac.md

@@ -201,4 +201,31 @@ validate, it will be dropped from the pool, and another attempt will be made to
     Pool](http://tomcat.apache.org/tomcat-9.0-doc/jdbc-pool.html#Tomcat_JDBC_Enhanced_Attributes).
 
 
-    
+## Driver-Level Timeouts (Recommended for Production)
+
+If the database becomes unresponsive, WSO2 Identity Server threads can get stuck waiting for a JDBC connection. This happens because the Tomcat JDBC Pool can't abort connection creation by itself ([source](https://github.com/apache/tomcat/blob/9.0.82/modules/jdbc-pool/src/main/java/org/apache/tomcat/jdbc/pool/ConnectionPool.java#L693-L702){: target="_blank"}).
+
+To prevent this, configure **driver-level timeouts** in the JDBC URL:
+
+- **`connectTimeout`** → Maximum time to wait while establishing a database connection.  
+- **`socketTimeout`** (or driver-specific equivalent) → Maximum time to wait for responses on an active connection.  
+- **`tcpKeepAlive=true`** (if supported) → Helps detect unresponsive database servers.
+
+Also note the distinction:
+
+- **`maxWait`** (Tomcat pool) controls how long to wait for a free connection from the pool.  
+- **`connectTimeout` / `socketTimeout`** (driver) → how long to connect/read at the DB level.
+
+> **Note:** The `PoolExhaustedException` warning log is logged only when `maxWait` expires ([source](https://github.com/apache/tomcat/blob/9.0.82/modules/jdbc-pool/src/main/java/org/apache/tomcat/jdbc/pool/ConnectionPool.java#L739-L741){: target="_blank"}). It does **not** cover delays inside the driver’s connection or read operations. Driver-level timeouts are required to handle those cases.
+
+### Example: Oracle RAC database
+
+```toml
+[database.identity_db]
+url = "jdbc:oracle:thin:@(DESCRIPTION=(ADDRESS_LIST=(ADDRESS=(PROTOCOL=TCP)(HOST=DB_HOST1)(PORT=1521))(ADDRESS=(PROTOCOL=TCP)(HOST=DB_HOST2)(PORT=1521)))(CONNECT_DATA=(SERVICE_NAME=WSO2_IDENTITY_DB)))?oracle.net.CONNECT_TIMEOUT=10000&oracle.jdbc.ReadTimeout=60000"
+username = "..."
+password = "..."
+driver = "oracle.jdbc.OracleDriver"
+```
+
+Learn more in [Oracle JDBC RAC URLs](https://docs.oracle.com/en/database/oracle/oracle-database/19/jjdbc/data-sources-and-URLs.html){: target="_blank"}.

en/identity-server/5.10.0/docs/setup/changing-to-oracle.md

@@ -267,4 +267,31 @@ The elements in the above configuration are described below:
  | **rollbackOnReturn** | If `                defaultAutoCommit               ` =false, then you can set `                rollbackOnReturn               ` =true so that the pool can terminate the transaction by calling rollback on the connection as it is returned to the pool. The default value is false.                                                                                                     |
 
 
-    
+## Driver-Level Timeouts (Recommended for Production)
+
+If the database becomes unresponsive, WSO2 Identity Server threads can get stuck waiting for a JDBC connection. This happens because the Tomcat JDBC Pool can't abort connection creation by itself ([source](https://github.com/apache/tomcat/blob/9.0.82/modules/jdbc-pool/src/main/java/org/apache/tomcat/jdbc/pool/ConnectionPool.java#L693-L702){: target="_blank"}).
+
+To prevent this, configure **driver-level timeouts** in the JDBC URL:
+
+- **`connectTimeout`** → Maximum time to wait while establishing a database connection.  
+- **`socketTimeout`** (or driver-specific equivalent) → Maximum time to wait for responses on an active connection.  
+- **`tcpKeepAlive=true`** (if supported) → Helps detect unresponsive database servers.
+
+Also note the distinction:
+
+- **`maxWait`** (Tomcat pool) controls how long to wait for a free connection from the pool.  
+- **`connectTimeout` / `socketTimeout`** (driver) → how long to connect/read at the DB level.
+
+> **Note:** The `PoolExhaustedException` warning log is logged only when `maxWait` expires ([source](https://github.com/apache/tomcat/blob/9.0.82/modules/jdbc-pool/src/main/java/org/apache/tomcat/jdbc/pool/ConnectionPool.java#L739-L741){: target="_blank"}). It does **not** cover delays inside the driver’s connection or read operations. Driver-level timeouts are required to handle those cases.
+
+### Example: Oracle database
+
+```toml
+[database.identity_db]
+url = "jdbc:oracle:thin:@//DB_HOST:1521/WSO2_IDENTITY_DB?oracle.net.CONNECT_TIMEOUT=10000&oracle.jdbc.ReadTimeout=60000"
+username = "..."
+password = "..."
+driver = "oracle.jdbc.OracleDriver"
+```
+
+Learn more in [Oracle JDBC data sources & URLs](https://docs.oracle.com/en/database/oracle/oracle-database/19/jjdbc/data-sources-and-URLs.html){: target="_blank"}.

en/identity-server/5.10.0/docs/setup/changing-to-postgresql.md

@@ -267,4 +267,31 @@ The elements in the above configuration are described below:
 | **rollbackOnReturn** | If `                defaultAutoCommit               ` =false, then you can set `                rollbackOnReturn               ` =true so that the pool can terminate the transaction by calling rollback on the connection as it is returned to the pool. The default value is false.                                                                                                     |
 
 
-    
+## Driver-Level Timeouts (Recommended for Production)
+
+If the database becomes unresponsive, WSO2 Identity Server threads can get stuck waiting for a JDBC connection. This happens because the Tomcat JDBC Pool can't abort connection creation by itself ([source](https://github.com/apache/tomcat/blob/9.0.82/modules/jdbc-pool/src/main/java/org/apache/tomcat/jdbc/pool/ConnectionPool.java#L693-L702){: target="_blank"}).
+
+To prevent this, configure **driver-level timeouts** in the JDBC URL:
+
+- **`connectTimeout`** → Maximum time to wait while establishing a database connection.  
+- **`socketTimeout`** (or driver-specific equivalent) → Maximum time to wait for responses on an active connection.  
+- **`tcpKeepAlive=true`** (if supported) → Helps detect unresponsive database servers.
+
+Also note the distinction:
+
+- **`maxWait`** (Tomcat pool) controls how long to wait for a free connection from the pool.  
+- **`connectTimeout` / `socketTimeout`** (driver) → how long to connect/read at the DB level.
+
+> **Note:** The `PoolExhaustedException` warning log is logged only when `maxWait` expires ([source](https://github.com/apache/tomcat/blob/9.0.82/modules/jdbc-pool/src/main/java/org/apache/tomcat/jdbc/pool/ConnectionPool.java#L739-L741){: target="_blank"}). It does **not** cover delays inside the driver’s connection or read operations. Driver-level timeouts are required to handle those cases.
+
+### Example: PostgreSQL database
+
+```toml
+[database.identity_db]
+url = "jdbc:postgresql://DB_HOST:5432/WSO2_IDENTITY_DB?connectTimeout=10&socketTimeout=60&tcpKeepAlive=true"
+username = "..."
+password = "..."
+driver = "org.postgresql.Driver"
+```
+
+Learn more in [PostgreSQL JDBC connection parameters](https://jdbc.postgresql.org/documentation/use/#connection-parameters){: target="_blank"}.

en/identity-server/5.10.0/docs/setup/changing-to-remote-h2.md

@@ -286,4 +286,31 @@ The elements in the above configuration are described below:
  | **rollbackOnReturn** | If `                defaultAutoCommit               ` =false, then you can set `                rollbackOnReturn               ` =true so that the pool can terminate the transaction by calling rollback on the connection as it is returned to the pool. The default value is false.                                                                                                     |
 
 
-    
+## Driver-Level Timeouts (Recommended for Production)
+
+If the database becomes unresponsive, WSO2 Identity Server threads can get stuck waiting for a JDBC connection. This happens because the Tomcat JDBC Pool can't abort connection creation by itself ([source](https://github.com/apache/tomcat/blob/9.0.82/modules/jdbc-pool/src/main/java/org/apache/tomcat/jdbc/pool/ConnectionPool.java#L693-L702){: target="_blank"}).
+
+To prevent this, configure **driver-level timeouts** in the JDBC URL:
+
+- **`connectTimeout`** → Maximum time to wait while establishing a database connection.  
+- **`socketTimeout`** (or driver-specific equivalent) → Maximum time to wait for responses on an active connection.  
+- **`tcpKeepAlive=true`** (if supported) → Helps detect unresponsive database servers.
+
+Also note the distinction:
+
+- **`maxWait`** (Tomcat pool) controls how long to wait for a free connection from the pool.  
+- **`connectTimeout` / `socketTimeout`** (driver) → how long to connect/read at the DB level.
+
+> **Note:** The `PoolExhaustedException` warning log is logged only when `maxWait` expires ([source](https://github.com/apache/tomcat/blob/9.0.82/modules/jdbc-pool/src/main/java/org/apache/tomcat/jdbc/pool/ConnectionPool.java#L739-L741){: target="_blank"}). It does **not** cover delays inside the driver’s connection or read operations. Driver-level timeouts are required to handle those cases.
+
+### Example: Remote H2 database
+
+```toml
+[database.identity_db]
+url = "jdbc:h2:tcp://localhost/~/WSO2_IDENTITY_DB;QUERY_TIMEOUT=60000"
+username = "..."
+password = "..."
+driver = "org.h2.Driver"
+```
+
+Learn more in [H2 connection settings](http://www.h2database.com/html/features.html#connection_settings){: target="_blank"}.

en/identity-server/5.11.0/docs/setup/changing-to-ibm-db2.md

@@ -280,5 +280,32 @@ The elements in the above configuration are described below:
  |                      |
  | **rollbackOnReturn** | If `                defaultAutoCommit               ` =false, then you can set `                rollbackOnReturn               ` =true so that the pool can terminate the transaction by calling rollback on the connection as it is returned to the pool. The default value is false.                                                                                                     |
 
+## Driver-Level Timeouts (Recommended for Production)
+
+If the database becomes unresponsive, WSO2 Identity Server threads can get stuck waiting for a JDBC connection. This happens because the Tomcat JDBC Pool can't abort connection creation by itself ([source](https://github.com/apache/tomcat/blob/9.0.82/modules/jdbc-pool/src/main/java/org/apache/tomcat/jdbc/pool/ConnectionPool.java#L693-L702){: target="_blank"}).
+
+To prevent this, configure **driver-level timeouts** in the JDBC URL:
+
+- **`connectTimeout`** → Maximum time to wait while establishing a database connection.  
+- **`socketTimeout`** (or driver-specific equivalent) → Maximum time to wait for responses on an active connection.  
+- **`tcpKeepAlive=true`** (if supported) → Helps detect unresponsive database servers.
+
+Also note the distinction:
+
+- **`maxWait`** (Tomcat pool) controls how long to wait for a free connection from the pool.  
+- **`connectTimeout` / `socketTimeout`** (driver) → how long to connect/read at the DB level.
+
+> **Note:** The `PoolExhaustedException` warning log is logged only when `maxWait` expires ([source](https://github.com/apache/tomcat/blob/9.0.82/modules/jdbc-pool/src/main/java/org/apache/tomcat/jdbc/pool/ConnectionPool.java#L739-L741){: target="_blank"}). It does **not** cover delays inside the driver’s connection or read operations. Driver-level timeouts are required to handle those cases.
+
+### Example: IBM DB2 database
+
+```toml
+[database.identity_db]
+url = "jdbc:db2://DB_HOST:50000/WSO2_IDENTITY_DB:loginTimeout=10;queryTimeout=60;"
+username = "..."
+password = "..."
+driver = "com.ibm.db2.jcc.DB2Driver"
+```
+
+Learn more in [IBM DB2 connection settings](https://www.ibm.com/docs/en/db2/11.5?topic=client-jdbc-properties){: target="_blank"}.
 
-