Package org.pjdbc.drivers

Class RetryDriver

java.lang.Object

org.pjdbc.sql.AbstractDriver

org.pjdbc.sql.AbstractProxyDriver

org.pjdbc.drivers.RetryDriver

All Implemented Interfaces:

Driver

@DriverCapability(prefix="retry",
                  description="Automatically retries failed queries on transient errors",
                  capabilities="resilience")
@DriverParameter(name="maxRetries",type=INTEGER,description="Maximum retry attempts",defaultValue="3",min=0L) @DriverParameter(name="initialDelay",type=INTEGER,description="Initial delay in ms before first retry",defaultValue="100",min=0L) @DriverParameter(name="maxDelay",type=INTEGER,description="Maximum delay cap in ms",defaultValue="5000",min=0L) @DriverParameter(name="backoffMultiplier",type=FLOAT,description="Multiplier for exponential backoff",defaultValue="2.0") @DriverParameter(name="jitter",type=BOOLEAN,description="Add random jitter to delays",defaultValue="true") @DriverParameter(name="retryOnSqlStates",type=STRING,description="Semicolon-separated SQL states to retry on")
public class RetryDriver
extends AbstractProxyDriver

RetryDriver automatically retries failed queries on transient errors.

WARNING: Idempotency Required

This driver should only be used with idempotent operations. Retrying non-idempotent operations (INSERT, UPDATE, DELETE) can cause data corruption, duplicate records, or inconsistent state.

Safe to retry:

• SELECT queries (read-only)
• Idempotent writes (e.g., UPDATE with WHERE clause on unique key)
• Operations wrapped in application-level idempotency checks

NOT safe to retry without additional safeguards:

• INSERT statements (may create duplicates)
• UPDATE without unique key constraint (may apply multiple times)
• DELETE statements (usually safe but verify business logic)
• Statements with side effects (triggers, sequences)

For non-idempotent operations, consider using ReadonlyDriver in combination with RetryDriver, or implement application-level idempotency using idempotency keys or optimistic locking.

PreparedStatement Parameter Tracking

This driver tracks all parameter bindings (setXxx calls) on PreparedStatements. When a connection failure occurs (SQL states starting with "08"), the driver automatically reconnects, recreates the PreparedStatement, and replays all parameter bindings before retrying the operation.

Stream parameters (InputStream, Reader) are buffered into memory when set, enabling replay after reconnection. This adds memory overhead proportional to stream size.

Note: CallableStatement retry after connection failure is not yet supported due to the additional complexity of OUT parameter handling.

Default Retryable SQL States

• 08001, 08003, 08004, 08006, 08007 - Connection errors
• 40001, 40P01 - Deadlock/serialization failures
• 57P01 - Admin shutdown
• HYT00, HYT01 - Timeout errors

Example URLs

 jdbc:retry:jdbc:postgresql://localhost/mydb
 jdbc:retry[maxRetries=5,initialDelay=200]:jdbc:postgresql://localhost/mydb
 jdbc:retry[retryOnSqlStates=40001;08006]:jdbc:mysql://localhost/db
 

See Also:

• ReadonlyDriver

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static class	RetryDriver.RetryConfig	Configuration holder for retry parameters, parsed once at connection time.

Driver Parameters

URL format: jdbc:retry[param=value,...]:<target-url>

Parameter	Type	Default	Constraints	Description
maxRetries	integer	3	≥ 0	Maximum retry attempts
initialDelay	integer	100	≥ 0	Initial delay in ms before first retry
maxDelay	integer	5000	≥ 0	Maximum delay cap in ms
backoffMultiplier	float	2.0	-	Multiplier for exponential backoff
jitter	boolean	true	-	Add random jitter to delays
retryOnSqlStates	string	-	-	Semicolon-separated SQL states to retry on

Constructor Summary

Constructors

Constructor	Description
RetryDriver()

Method Summary

Modifier and Type	Method	Description
protected boolean	acceptsSubName(String subname)
protected boolean	acceptsSubProtocol(String subprotocol)
Connection	connect(String url, Properties info)
protected CallableStatement	proxyCallableStatement(CallableStatement delegate, Connection conn)
protected CallableStatement	proxyCallableStatement(CallableStatement delegate, Connection conn, String sql)	Proxy a CallableStatement with access to the original SQL.
protected Connection	proxyConnection(Connection delegate, String url, Properties info, Driver driver)
protected PreparedStatement	proxyPreparedStatement(PreparedStatement delegate, Connection conn)
protected PreparedStatement	proxyPreparedStatement(PreparedStatement delegate, Connection conn, String sql)	Proxy a PreparedStatement with access to the original SQL.
protected Statement	proxyStatement(Statement delegate, Connection conn)

Methods inherited from class org.pjdbc.sql.AbstractProxyDriver

getPropertyInfo, isCompositionValidationEnabled, isValidateParametersEnabled, proxyConnection, proxyConnection, proxyResultSet

Methods inherited from class org.pjdbc.sql.AbstractDriver

acceptsProtocol, acceptsURL, getMajorVersion, getMinorVersion, getParentLogger, getUrlParameter, getUrlParameter, getUrlParameters, jdbcCompliant, parseUrl, protocol, subname, subprotocol, validateParameters

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Details

RetryDriver

public RetryDriver()

Method Details

acceptsSubProtocol

protected boolean acceptsSubProtocol(String subprotocol)

Specified by:

acceptsSubProtocol in class AbstractDriver

acceptsSubName

protected boolean acceptsSubName(String subname)

Overrides:

acceptsSubName in class AbstractProxyDriver

connect

public Connection connect(String url,
 Properties info)
                   throws SQLException

Specified by:

connect in interface Driver

Overrides:

connect in class AbstractProxyDriver

Throws:

SQLException

proxyConnection

protected Connection proxyConnection(Connection delegate,
 String url,
 Properties info,
 Driver driver)
                              throws SQLException

Overrides:

proxyConnection in class AbstractProxyDriver

Throws:

SQLException

proxyStatement

protected Statement proxyStatement(Statement delegate,
 Connection conn)
                            throws SQLException

Overrides:

proxyStatement in class AbstractProxyDriver

Throws:

SQLException

proxyPreparedStatement

protected PreparedStatement proxyPreparedStatement(PreparedStatement delegate,
 Connection conn)
                                            throws SQLException

Overrides:

proxyPreparedStatement in class AbstractProxyDriver

Throws:

SQLException

proxyPreparedStatement

protected PreparedStatement proxyPreparedStatement(PreparedStatement delegate,
 Connection conn,
 String sql)
                                            throws SQLException

Description copied from class: AbstractProxyDriver

Proxy a PreparedStatement with access to the original SQL. Override this method when you need to recreate the statement (e.g., on connection failure). The default implementation ignores the SQL and delegates to AbstractProxyDriver.proxyPreparedStatement(PreparedStatement, Connection).

Overrides:

proxyPreparedStatement in class AbstractProxyDriver

Parameters:

delegate - the delegate PreparedStatement

conn - the connection

sql - the SQL used to prepare the statement

Returns:

the proxied PreparedStatement

Throws:

SQLException - if an error occurs

proxyCallableStatement

protected CallableStatement proxyCallableStatement(CallableStatement delegate,
 Connection conn)
                                            throws SQLException

Overrides:

proxyCallableStatement in class AbstractProxyDriver

Throws:

SQLException

proxyCallableStatement

protected CallableStatement proxyCallableStatement(CallableStatement delegate,
 Connection conn,
 String sql)
                                            throws SQLException

Description copied from class: AbstractProxyDriver

Proxy a CallableStatement with access to the original SQL. Override this method when you need to recreate the statement (e.g., on connection failure). The default implementation ignores the SQL and delegates to AbstractProxyDriver.proxyCallableStatement(CallableStatement, Connection).

Overrides:

proxyCallableStatement in class AbstractProxyDriver

Parameters:

delegate - the delegate CallableStatement

conn - the connection

sql - the SQL used to prepare the statement

Returns:

the proxied CallableStatement

Throws:

SQLException - if an error occurs