Package com.clickhouse.client.api

Class Client.Builder

java.lang.Object
com.clickhouse.client.api.Client.Builder
Enclosing class:
Client
public static class Client.Builder extends Object

  • Field Details

    • DEFAULT_BUFFER_SIZE

      public static final int DEFAULT_BUFFER_SIZE
      Default size for a buffers used in networking.
      See Also:

    • DEFAULT_SOCKET_BUFFER_SIZE

      public static final int DEFAULT_SOCKET_BUFFER_SIZE
      See Also:

  • Constructor Details

    • Builder

      public Builder()

  • Method Details

    • addEndpoint

      public Client.Builder addEndpoint(String endpoint)
      Server address to which client may connect. If there are multiple endpoints then client will connect to one of them. Acceptable formats are:
      • http://localhost:8123
      • https://localhost:8443
      Parameters:
      endpoint - - URL formatted string with protocol, host and port.

    • addEndpoint

      public Client.Builder addEndpoint(Protocol protocol, String host, int port, boolean secure)
      Server address to which client may connect. If there are multiple endpoints then client will connect to one of them.
      Parameters:
      protocol - - Endpoint protocol
      host - - Endpoint host
      port - - Endpoint port

    • setOption

      public Client.Builder setOption(String key, String value)
      Sets a configuration option. This method can be used to set any configuration option. There is no specific validation is done on the key or value.
      Parameters:
      key - - configuration option name
      value - - configuration option value

    • setUsername

      public Client.Builder setUsername(String username)
      Username for authentication with server. Required for all operations. Same username will be used for all endpoints.
      Parameters:
      username - - a valid username

    • setPassword

      public Client.Builder setPassword(String password)
      Password for authentication with server. Required for all operations. Same password will be used for all endpoints.
      Parameters:
      password - - plain text password

    • setAccessToken

      public Client.Builder setAccessToken(String accessToken)
      Access token for authentication with server. Required for all operations. Same access token will be used for all endpoints.
      Parameters:
      accessToken - - plain text access token

    • useSSLAuthentication

      public Client.Builder useSSLAuthentication(boolean useSSLAuthentication)
      Makes client to use SSL Client Certificate to authenticate with server. Client certificate should be set as well. setClientCertificate(String)
      Parameters:
      useSSLAuthentication -
      Returns:

    • enableConnectionPool

      public Client.Builder enableConnectionPool(boolean enable)
      Configures client to use build-in connection pool
      Parameters:
      enable - - if connection pool should be enabled
      Returns:

    • setConnectTimeout

      public Client.Builder setConnectTimeout(long timeout)
      Default connection timeout in milliseconds. Timeout is applied to establish a connection.
      Parameters:
      timeout - - connection timeout in milliseconds

    • setConnectTimeout

      public Client.Builder setConnectTimeout(long timeout, ChronoUnit unit)
      Default connection timeout in milliseconds. Timeout is applied to establish a connection.
      Parameters:
      timeout - - connection timeout value
      unit - - time unit

    • setConnectionRequestTimeout

      public Client.Builder setConnectionRequestTimeout(long timeout, ChronoUnit unit)
      Set timeout for waiting a free connection from a pool when all connections are leased. This configuration is important when need to fail fast in high concurrent scenarios. Default is 10 s.
      Parameters:
      timeout - - connection timeout in milliseconds
      unit - - time unit

    • setMaxConnections

      public Client.Builder setMaxConnections(int maxConnections)
      Sets the maximum number of connections that can be opened at the same time to a single server. Limit is not a hard stop. It is done to prevent threads stuck inside a connection pool waiting for a connection. Default is 10. It is recommended to set a higher value for a high concurrent applications. It will let more threads to get a connection and execute a query.
      Parameters:
      maxConnections - - maximum number of connections

    • setConnectionTTL

      public Client.Builder setConnectionTTL(long timeout, ChronoUnit unit)
      Sets how long any connection would be considered as active and able for a lease. After this time connection will be marked for sweep and will not be returned from a pool. Has more effect than keep-alive timeout.
      Parameters:
      timeout - - time in unit
      unit - - time unit
      Returns:

    • setKeepAliveTimeout

      public Client.Builder setKeepAliveTimeout(long timeout, ChronoUnit unit)
      Sets keep alive timeout for a connection to override server value. If set to -1 then server value will be used. Default is -1. Doesn't override connection TTL value.
      Parameters:
      timeout - - time in unit
      unit - - time unit
      Returns:

    • setConnectionReuseStrategy

      public Client.Builder setConnectionReuseStrategy(ConnectionReuseStrategy strategy)
      Sets strategy of how connections are reuse. Default is ConnectionReuseStrategy.FIFO to evenly distribute load between them.
      Parameters:
      strategy - - strategy for connection reuse
      Returns:

    • setSocketTimeout

      public Client.Builder setSocketTimeout(long timeout)
      Default socket timeout in milliseconds. Timeout is applied to read and write operations.
      Parameters:
      timeout - - socket timeout in milliseconds

    • setSocketTimeout

      public Client.Builder setSocketTimeout(long timeout, ChronoUnit unit)
      Default socket timeout in milliseconds. Timeout is applied to read and write operations. Default is 0.
      Parameters:
      timeout - - socket timeout value
      unit - - time unit

    • setSocketRcvbuf

      public Client.Builder setSocketRcvbuf(long size)
      Default socket receive buffer size in bytes.
      Parameters:
      size - - socket receive buffer size in bytes

    • setSocketSndbuf

      public Client.Builder setSocketSndbuf(long size)
      Default socket send buffer size in bytes.
      Parameters:
      size - - socket send buffer size in bytes

    • setSocketReuseAddress

      public Client.Builder setSocketReuseAddress(boolean value)
      Default socket reuse address option.
      Parameters:
      value - - socket reuse address option

    • setSocketKeepAlive

      public Client.Builder setSocketKeepAlive(boolean value)
      Default socket keep alive option.If set to true socket will be kept alive until terminated by one of the parties.
      Parameters:
      value - - socket keep alive option

    • setSocketTcpNodelay

      public Client.Builder setSocketTcpNodelay(boolean value)
      Default socket tcp_no_delay option. If set to true, disables Nagle's algorithm.
      Parameters:
      value - - socket tcp no delay option

    • setSocketLinger

      public Client.Builder setSocketLinger(int secondsToWait)
      Default socket linger option. If set to true, socket will linger for the specified time.
      Parameters:
      secondsToWait - - socket linger time in seconds

    • compressServerResponse

      public Client.Builder compressServerResponse(boolean enabled)
      Server response compression. If set to true server will compress the response. Has most effect for read operations. Default is true.
      Parameters:
      enabled - - indicates if server response compression is enabled

    • compressClientRequest

      public Client.Builder compressClientRequest(boolean enabled)
      Client request compression. If set to true client will compress the request. Has most effect for write operations. Default is false.
      Parameters:
      enabled - - indicates if client request compression is enabled

    • useHttpCompression

      public Client.Builder useHttpCompression(boolean enabled)
      Configures the client to use HTTP compression. In this case compression is controlled by http headers. Client compression will set Content-Encoding: lz4 header and server compression will set Accept-Encoding: lz4 header. Default is false.
      Parameters:
      enabled - - indicates if http compression is enabled
      Returns:

    • appCompressedData

      public Client.Builder appCompressedData(boolean enabled)

    • setLZ4UncompressedBufferSize

      public Client.Builder setLZ4UncompressedBufferSize(int size)
      Sets buffer size for uncompressed data in LZ4 compression. For outgoing data it is the size of a buffer that will be compressed. For incoming data it is the size of a buffer that will be decompressed.
      Parameters:
      size - - size of the buffer in bytes
      Returns:

    • setDefaultDatabase

      public Client.Builder setDefaultDatabase(String database)
      Sets the default database name that will be used by operations if not specified.
      Parameters:
      database - - actual default database name.

    • addProxy

      public Client.Builder addProxy(ProxyType type, String host, int port)

    • setProxyCredentials

      public Client.Builder setProxyCredentials(String user, String pass)

    • setExecutionTimeout

      public Client.Builder setExecutionTimeout(long timeout, ChronoUnit timeUnit)
      Sets the maximum time for operation to complete. By default, it is set to 3 hours.
      Parameters:
      timeout -
      timeUnit -
      Returns:

    • useNewImplementation

      public Client.Builder useNewImplementation(boolean useNewImplementation)
      Deprecated.
      Switches to new implementation of the client. Default is true. Throws exception if useNewImplementation == false

    • setHttpCookiesEnabled

      public Client.Builder setHttpCookiesEnabled(boolean enabled)

    • setSSLTrustStore

      public Client.Builder setSSLTrustStore(String path)
      Defines path to the trust store file. It cannot be combined with certificates. Either trust store or certificates should be used. and
      Parameters:
      path -
      Returns:

    • setSSLTrustStorePassword

      public Client.Builder setSSLTrustStorePassword(String password)
      Password for the SSL Trust Store.
      Parameters:
      password -
      Returns:

    • setSSLTrustStoreType

      public Client.Builder setSSLTrustStoreType(String type)
      Type of the SSL Trust Store. Usually JKS
      Parameters:
      type -
      Returns:

    • setRootCertificate

      public Client.Builder setRootCertificate(String path)
      Defines path to the key store file. It cannot be combined with certificates. Either key store or certificates should be used. and
      Parameters:
      path -
      Returns:

    • setClientCertificate

      public Client.Builder setClientCertificate(String path)
      Client certificate for mTLS.
      Parameters:
      path -
      Returns:

    • setClientKey

      public Client.Builder setClientKey(String path)
      Client key for mTLS.
      Parameters:
      path -
      Returns:

    • useServerTimeZone

      public Client.Builder useServerTimeZone(boolean useServerTimeZone)
      Configure client to use server timezone for date/datetime columns. Default is true. If this options is selected then server timezone should be set as well.
      Parameters:
      useServerTimeZone - - if to use server timezone
      Returns:

    • useTimeZone

      public Client.Builder useTimeZone(String timeZone)
      Configure client to use specified timezone. If set using server TimeZone should be set to false
      Parameters:
      timeZone -
      Returns:

    • setServerTimeZone

      public Client.Builder setServerTimeZone(String timeZone)
      Specify server timezone to use. If not set then UTC will be used.
      Parameters:
      timeZone - - server timezone
      Returns:

    • useAsyncRequests

      public Client.Builder useAsyncRequests(boolean async)
      Configures client to execute requests in a separate thread. By default, operations (query, insert) are executed in the same thread as the caller. It is possible to set a shared executor for all operations. See setSharedOperationExecutor(ExecutorService) Note: Async operations a using executor what expects having a queue of tasks for a pool of executors. The queue size limit is small it may quickly become a problem for scheduling new tasks.
      Parameters:
      async - - if to use async requests
      Returns:

    • setSharedOperationExecutor

      public Client.Builder setSharedOperationExecutor(ExecutorService executorService)
      Sets an executor for running operations. If async operations are enabled and no executor is specified client will create a default executor. Executor will stay running after Client#close() is called. It is application responsibility to close the executor.
      Parameters:
      executorService - - executor service for async operations
      Returns:

    • setClientNetworkBufferSize

      public Client.Builder setClientNetworkBufferSize(int size)
      Set size of a buffers that are used to read/write data from the server. It is mainly used to copy data from a socket to application memory and visa-versa. Setting is applied for both read and write operations. Default is 300,000 bytes.
      Parameters:
      size - - size in bytes
      Returns:

    • retryOnFailures

      public Client.Builder retryOnFailures(ClientFaultCause... causes)
      Sets list of causes that should be retried on. Default [NoHttpResponse, ConnectTimeout, ConnectionRequestTimeout] Use ClientFaultCause.None to disable retries.
      Parameters:
      causes - - list of causes
      Returns:

    • setMaxRetries

      public Client.Builder setMaxRetries(int maxRetries)

    • allowBinaryReaderToReuseBuffers

      public Client.Builder allowBinaryReaderToReuseBuffers(boolean reuse)
      Configures client to reuse allocated byte buffers for numbers. It affects how binary format reader is working. If set to 'true' then Client.newBinaryFormatReader(QueryResponse) will construct reader that will reuse buffers for numbers. It improves performance for large datasets by reducing number of allocations (therefore GC pressure). Enabling this feature is safe because each reader suppose to be used by a single thread and readers are not reused. Default is false.
      Parameters:
      reuse - - if to reuse buffers
      Returns:

    • httpHeader

      public Client.Builder httpHeader(String key, String value)
      Defines list of headers that should be sent with each request. The Client will use a header value defined in headers instead of any other. Operation settings may override these headers.
      Parameters:
      key - - a name of the header.
      value - - a value of the header.
      Returns:
      same instance of the builder
      See Also:

    • httpHeader

      public Client.Builder httpHeader(String key, Collection<String> values)
      but for multiple values.
      Parameters:
      key - - name of the header
      values - - collection of values
      Returns:
      same instance of the builder

    • httpHeaders

      public Client.Builder httpHeaders(Map<String,String> headers)
      but for multiple headers.
      Parameters:
      headers - - map of headers
      Returns:
      same instance of the builder

    • serverSetting

      public Client.Builder serverSetting(String name, String value)
      Defines list of server settings that should be sent with each request. The Client will use a setting value defined in settings instead of any other. Operation settings may override these values.
      Parameters:
      name - - name of the setting without special prefix
      value - - value of the setting
      Returns:
      same instance of the builder
      See Also:

    • serverSetting

      public Client.Builder serverSetting(String name, Collection<String> values)
      but for multiple values.
      Parameters:
      name - - name of the setting without special prefix
      values - - collection of values
      Returns:
      same instance of the builder

    • columnToMethodMatchingStrategy

      public Client.Builder columnToMethodMatchingStrategy(ColumnToMethodMatchingStrategy strategy)
      Sets column to method matching strategy. It is used while registering POJO serializers and deserializers. Default is DefaultColumnToMethodMatchingStrategy.
      Parameters:
      strategy - - matching strategy
      Returns:
      same instance of the builder

    • useHTTPBasicAuth

      public Client.Builder useHTTPBasicAuth(boolean useBasicAuth)
      Whether to use HTTP basic authentication. Default value is true. Password that contain UTF8 characters may not be passed through http headers and BASIC authentication is the only option here.
      Parameters:
      useBasicAuth - - indicates if basic authentication should be used
      Returns:
      same instance of the builder

    • setClientName

      public Client.Builder setClientName(String clientName)
      Sets additional information about calling application. This string will be passed to server as a client name. In case of HTTP protocol it will be passed as a User-Agent header. Warn: If custom value of User-Agent header is set it will override this value for HTTP transport Client name is used by server to identify client application when investigating system.query_log. In case of HTTP transport this value will be in the system.query_log.http_user_agent column. Currently only HTTP transport is used.
      Parameters:
      clientName - - client application display name.
      Returns:
      same instance of the builder

    • setOptions

      public Client.Builder setOptions(Map<String,String> options)
      Sets client options from provided map. Values are copied as is
      Parameters:
      options - - map of client options
      Returns:
      same instance of the builder

    • useBearerTokenAuth

      public Client.Builder useBearerTokenAuth(String bearerToken)
      Specifies whether to use Bearer Authentication and what token to use. The token will be sent as is, so it should be encoded before passing to this method.
      Parameters:
      bearerToken - - token to use
      Returns:
      same instance of the builder

    • registerClientMetrics

      public Client.Builder registerClientMetrics(Object registry, String name)
      Registers http client metrics with MeterRegistry.
      Parameters:
      registry - - metrics registry
      name - - name of metrics group
      Returns:
      same instance of the builder

    • build

      public Client build()