Retry policies

Retry polices allow the driver to automatically handle server-side failures when Cassandra is unable to fulfill the consistency requirement of a request.

Important: Retry policies do not handle client-side failures such as client-side timeouts or client-side connection issues. In these cases application code must handle the failure and retry the request. The driver will automatically recover requests that haven’t been written, but once a request is written the driver will return an error for in-flight requests and will not try to automatically recover. This is done because not all operations are idempotent and the driver is unable to distinguish which requests can automatically retried without side effect. It’s up to application code to make this distinction.

Setting Retry Policy

By default, the driver uses the default retry policy for all requests unless it is overridden. The retry policy can be set globally using cass_cluster_set_retry_policy() or it can be set per statement or batch using cass_statement_set_retry_policy() or cass_batch_set_retry_policy(), respectively.

Default Retry Policy

The default retry policy will only retry a request when it is safe to do so while preserving the consistency level of the request and it is likely to succeed. In all other cases, this policy will return an error.

Failure Type Action
Read Timeout Retry if the number of received responses is greater than or equal to the number of required responses, but the data was not received. Returns and error in all other cases.
Write Timeout Retry only if the request is a logged batch request and the request failed to write the batch log. Returns an error in all other cases.
Unavailable Retries the request using the next host in the query plan.
CassRetryPolicy* default_policy = cass_retry_policy_default_new();

/* ... */

/* Retry policies must be freed */
cass_retry_policy_free(default_policy);

Downgrading Consistency Retry Policy

Deprecated: Please do not use this policy in new applications. The use of this policy can lead to unexpected behavior. Application errors can happen when the consistency level is unexpectedly changed because the cluster is in a degraded state. The assumptions made at the normal operating consistency level may no longer apply when the consistency level is downgraded. Instead, applications should always use the lowest consistency that can be tolerated by a specific use case. The consistency level can be set per cluster using cass_cluster_set_consistency(), per execution profile using cass_execution_profile_set_consistency(), or per statement using cass_statement_set_consistency()`.

Fallthrough Retry Policy

This policy never retries or ignores a server-side failures. Errors are always returned. This policy is useful for application that want to handle retries directly.

Failure Type Action
Read Timeout Return error
Write Timeout Return error
Unavailable Return error
CassRetryPolicy* fallthrough_policy =
cass_retry_policy_fallthrough_new();

/* ... */

/* Retry policies must be freed */
cass_retry_policy_free(fallthrough_policy);

Logging

This policy can be added as a parent policy to all the other polices. It logs the retry decision of its child policy. The log messages created by this policy are done using the CASS_LOG_INFO level.

CassCluster* cluster = cass_cluster_new();

CassRetryPolicy* default_policy = cass_retry_policy_default_new();
CassRetryPolicy* logging_policy = cass_retry_policy_logging_new(default_policy);

cass_cluster_set_retry_policy(cluster, logging_policy);

/* ... */

/* Retry policies must be freed */
cass_retry_policy_free(default_policy);
cass_retry_policy_free(logging_policy);

cass_cluster_free(cluster);