Database.CQL.IO.Settings

Documentation

data Settings

Constructors

Settings

Fields

• _poolSettings :: PoolSettings
• _connSettings :: ConnectionSettings
• _retrySettings :: RetrySettings
• _logger :: Logger
• _protoVersion :: Version
• _portnumber :: PortNumber
• _contacts :: NonEmpty String
• _policyMaker :: IO Policy
• _prepStrategy :: PrepareStrategy

data PrepareStrategy

Strategy for the execution of PrepQuerys.

Constructors

EagerPrepare

cluster-wide preparation

LazyPrepare

on-demand per node preparation

Instances

Eq PrepareStrategy

Defined in Database.CQL.IO.Settings

Methods

(==) :: PrepareStrategy -> PrepareStrategy -> Bool

(/=) :: PrepareStrategy -> PrepareStrategy -> Bool

Ord PrepareStrategy

Defined in Database.CQL.IO.Settings

Methods

compare :: PrepareStrategy -> PrepareStrategy -> Ordering

(<) :: PrepareStrategy -> PrepareStrategy -> Bool

(<=) :: PrepareStrategy -> PrepareStrategy -> Bool

(>) :: PrepareStrategy -> PrepareStrategy -> Bool

(>=) :: PrepareStrategy -> PrepareStrategy -> Bool

max :: PrepareStrategy -> PrepareStrategy -> PrepareStrategy

min :: PrepareStrategy -> PrepareStrategy -> PrepareStrategy

Show PrepareStrategy

Defined in Database.CQL.IO.Settings

Methods

showsPrec :: Int -> PrepareStrategy -> ShowS

show :: PrepareStrategy -> String

showList :: [PrepareStrategy] -> ShowS

data RetrySettings

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.

Constructors

RetrySettings

Fields

• _retryPolicy :: forall m. Monad m => RetryPolicyM m
• _reducedConsistency :: Maybe Consistency
• _sendTimeoutChange :: Milliseconds
• _recvTimeoutChange :: Milliseconds
• _retryHandlers :: forall m. Monad m => [RetryStatus -> Handler m Bool]

sendTimeoutChange :: Lens' RetrySettings Milliseconds

retryPolicy :: forall m. Monad m => Getter RetrySettings (RetryPolicyM m)

retryHandlers :: forall m. Monad m => Getter RetrySettings [RetryStatus -> Handler m Bool]

reducedConsistency :: Lens' RetrySettings (Maybe Consistency)

recvTimeoutChange :: Lens' RetrySettings Milliseconds

retrySettings :: Lens' Settings RetrySettings

protoVersion :: Lens' Settings Version

prepStrategy :: Lens' Settings PrepareStrategy

portnumber :: Lens' Settings PortNumber

poolSettings :: Lens' Settings PoolSettings

policyMaker :: Lens' Settings (IO Policy)

logger :: Lens' Settings Logger

contacts :: Lens' Settings (NonEmpty String)

connSettings :: Lens' Settings ConnectionSettings

defSettings :: Settings

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

Set the binary protocol version to use.

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

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

addContact :: String -> Settings -> Settings

Add an additional host to the contact list.

setPortNumber :: PortNumber -> Settings -> Settings

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

setPolicy :: IO Policy -> Settings -> Settings

Set the load-balancing policy.

setPrepareStrategy :: PrepareStrategy -> Settings -> Settings

Set strategy to use for preparing statements.

setLogger :: Logger -> Settings -> Settings

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

setIdleTimeout :: NominalDiffTime -> Settings -> Settings

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

Maximum connections per pool stripe.

setPoolStripes :: Int -> Settings -> Settings

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

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

Set the compression to use for frame body compression.

setMaxStreams :: Int -> Settings -> Settings

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

Set the connect timeout of a connection.

setSendTimeout :: NominalDiffTime -> Settings -> Settings

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

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

setKeyspace :: Keyspace -> Settings -> Settings

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

setRetrySettings :: RetrySettings -> Settings -> Settings

Set the retry settings to use.

setMaxRecvBuffer :: Int -> Settings -> Settings

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

Set a fully configured SSL context.

This will make client server queries use TLS.

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

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

Never retry.

defRetrySettings :: RetrySettings

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

eagerRetrySettings :: RetrySettings

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

defRetryPolicy :: RetryPolicy

The default retry policy permits a single, immediate retry.

eagerRetryPolicy :: RetryPolicy

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]

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]

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

• Any ResponseError that is a ReadTimeout, WriteTimeout, Overloaded, Unavailable or ServerError.
• Any ConnectionError.
• Any IOException.
• Any HostError.
• Any SomeSSLException (if an SSL context is configured).

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

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

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

On retry, change the consistency to the given value.

adjustSendTimeout :: NominalDiffTime -> RetrySettings -> RetrySettings

On retry adjust the send timeout. See setSendTimeout.

adjustResponseTimeout :: NominalDiffTime -> RetrySettings -> RetrySettings

On retry adjust the response timeout. See setResponseTimeout.