cql-io-1.1.0: Cassandra CQL client.

Safe HaskellNone
LanguageHaskell2010

Database.CQL.IO.Settings

Synopsis

Documentation

data RetrySettings Source #

Retry settings control if and how retries are performed by the client upon encountering errors during query execution.

There are three aspects to the retry settings:

  1. What to retry. Determined by the retry handlers (setRetryHandlers).
  2. How to perform the retries. Determined by the retry policy (setRetryPolicy).
  3. Configuration adjustments to be performed before retrying. Determined by adjustConsistency, adjustSendTimeout and adjustResponseTimeout. These adjustments are performed once before the first retry and are scoped to the retries only.

Retry settings can be scoped to a client action by retry, thus locally overriding the "global" retry settings configured by setRetrySettings.

defSettings :: Settings Source #

Default settings:

  • The initial contact point is "localhost" on port 9042.
  • The load-balancing policy is random.
  • The binary protocol version is 3.
  • The connection idle timeout is 60s.
  • The connection pool uses 4 stripes to mitigate thread contention.
  • Connections use a connect timeout of 5s, a send timeout of 3s and a receive timeout of 10s.
  • 128 streams per connection are used.
  • 16k receive buffer size.
  • No compression is applied to frame bodies.
  • No default keyspace is used.
  • A single, immediate retry is performed for errors that are always safe to retry and are known to have good chances of succeeding on a retry. See defRetrySettings.
  • Query preparation is done lazily. See PrepareStrategy.

setProtocolVersion :: Version -> Settings -> Settings Source #

Set the binary protocol version to use.

setContacts :: String -> [String] -> Settings -> Settings Source #

Set the initial contact points (hosts) from which node discovery will start.

addContact :: String -> Settings -> Settings Source #

Add an additional host to the contact list.

setPortNumber :: PortNumber -> Settings -> Settings Source #

Set the portnumber to use to connect on every node of the cluster.

setPolicy :: IO Policy -> Settings -> Settings Source #

Set the load-balancing policy.

setPrepareStrategy :: PrepareStrategy -> Settings -> Settings Source #

Set strategy to use for preparing statements.

setLogger :: Logger -> Settings -> Settings Source #

Set the Logger to use for processing log messages emitted by the client.

setIdleTimeout :: NominalDiffTime -> Settings -> Settings Source #

Set the connection idle timeout. Connections in a pool will be closed if not in use for longer than this timeout.

setMaxConnections :: Int -> Settings -> Settings Source #

Maximum connections per pool stripe.

setPoolStripes :: Int -> Settings -> Settings Source #

Set the number of pool stripes to use. A good setting is equal to the number of CPU cores this codes is running on.

setMaxTimeouts :: Int -> Settings -> Settings Source #

When receiving a response times out, we can no longer use the stream of the connection that was used to make the request as it is uncertain if a response will arrive later. Thus the bandwith of a connection will be decreased. This settings defines a threshold after which we close the connection to get a new one with all streams available.

setCompression :: Compression -> Settings -> Settings Source #

Set the compression to use for frame body compression.

setMaxStreams :: Int -> Settings -> Settings Source #

Set the maximum number of streams per connection. In version 2 of the binary protocol at most 128 streams can be used. Version 3 supports up to 32768 streams.

setConnectTimeout :: NominalDiffTime -> Settings -> Settings Source #

Set the connect timeout of a connection.

setSendTimeout :: NominalDiffTime -> Settings -> Settings Source #

Set the send timeout of a connection. Requests exceeding the send timeout will cause the connection to be closed and fail with a ConnectionClosed exception.

setResponseTimeout :: NominalDiffTime -> Settings -> Settings Source #

Set the response timeout of a connection. Requests exceeding the response timeout will fail with a ResponseTimeout exception.

setKeyspace :: Keyspace -> Settings -> Settings Source #

Set the default keyspace to use. Every new connection will be initialised to use this keyspace.

setRetrySettings :: RetrySettings -> Settings -> Settings Source #

Set the retry settings to use.

setMaxRecvBuffer :: Int -> Settings -> Settings Source #

Set maximum receive buffer size.

The actual buffer size used will be the minimum of the CQL response size and the value set here.

setSSLContext :: SSLContext -> Settings -> Settings Source #

Set a fully configured SSL context.

This will make client server queries use TLS.

setAuthentication :: [Authenticator] -> Settings -> Settings Source #

Set the supported authentication mechanisms.

When a Cassandra server requests authentication on a connection, it specifies the requested AuthMechanism. The client Authenticator is chosen based that name. If no authenticator with a matching name is configured, an AuthenticationError is thrown.

noRetry :: RetrySettings Source #

Never retry.

defRetrySettings :: RetrySettings Source #

Default retry settings, combining defRetryHandlers with defRetryPolicy. Consistency is never reduced on retries and timeout values remain unchanged.

eagerRetrySettings :: RetrySettings Source #

Eager retry settings, combining eagerRetryHandlers with eagerRetryPolicy. Consistency is never reduced on retries and timeout values remain unchanged.

defRetryPolicy :: RetryPolicy Source #

The default retry policy permits a single, immediate retry.

eagerRetryPolicy :: RetryPolicy Source #

The eager retry policy permits 5 retries with exponential backoff (base-2) with an initial delay of 100ms, i.e. the retries will be performed with 100ms, 200ms, 400ms, 800ms and 1.6s delay, respectively, for a maximum delay of ~3s.

defRetryHandlers :: Monad m => [RetryStatus -> Handler m Bool] Source #

The default retry handlers permit a retry for the following errors:

  • A HostError, since it always occurs before a query has been sent to the server.
  • A ConnectionError that is a ConnectTimeout, since it always occurs before a query has been sent to the server.
  • A ResponseError that is one of the following:

    • Unavailable, since that is an error response from a coordinator before the query is actually executed.
    • A ReadTimeout that indicates that the required consistency level could be achieved but the data was unfortunately chosen by the coordinator to be returned from a replica that turned out to be unavailable. A retry has a good chance of getting the data from one of the other replicas.
    • A WriteTimeout for a write to the batch log failed. The batch log is written prior to execution of the statements of the batch and hence these errors are safe to retry.

eagerRetryHandlers :: Monad m => [RetryStatus -> Handler m Bool] Source #

The eager retry handlers permit a superset of the errors of defRetryHandlers, namely:

Notably, these retry handlers are only safe to use for idempotent queries, or if a duplicate write has no severe consequences in the context of the application's data model.

setRetryPolicy :: RetryPolicy -> RetrySettings -> RetrySettings Source #

Set the RetryPolicy to apply on retryable exceptions, which determines the number and distribution of retries over time, i.e. how retries are performed. Configuring a retry policy does not specify what errors should actually be retried. See setRetryHandlers.

setRetryHandlers :: (forall m. Monad m => [RetryStatus -> Handler m Bool]) -> RetrySettings -> RetrySettings Source #

Set the exception handlers that decide whether a request can be retried by the client, i.e. what errors are permissible to retry. For configuring how the retries are performed, see setRetryPolicy.

adjustConsistency :: Consistency -> RetrySettings -> RetrySettings Source #

On retry, change the consistency to the given value.

adjustSendTimeout :: NominalDiffTime -> RetrySettings -> RetrySettings Source #

On retry adjust the send timeout. See setSendTimeout.