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

This policy will retry in all the same scenarios as the default policy, and it will also retry in cases where there is a chance to save the request at the cost of lower the consistency. The goal of this policy is to be robust in the face of transient failures. Read requests will succeed as long as there’s a single copy available and write wills succeed if there’s at least a single copy persisted.

Important: This policy may attempt to retry request with a lower consistency level. Using this policy can break consistency guarantees and shouldn’t not be used in application that required strong consistency.

Failure Type Action
Read Timeout Retry with a lower consistency if some at least some replicas responded.
Write Timeout Retry unlogged batches at a lower consistency level if at least one replica responded. For single queries and other batch types if any replicas responded then consider the request successful and ignore the error.
Unavailable Retry with a lower consistency if some at least some replicas responded.
CassRetryPolicy* downgrading_policy =
cass_retry_policy_downgrading_consistency_new();

/* ... */

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

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);