Class: ClickhouseRuby::Configuration

Inherits:
Object
  • Object
show all
Defined in:
lib/clickhouse_ruby/configuration.rb

Overview

Configuration for ClickhouseRuby client connections

Examples:

config = ClickhouseRuby::Configuration.new
config.host = 'clickhouse.example.com'
config.port = 8443
config.ssl = true

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize ⇒ Configuration

Creates a new Configuration with sensible defaults



84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
 
# File 'lib/clickhouse_ruby/configuration.rb', line 84

def initialize
  @host = "localhost"
  @port = 8123
  @database = "default"
  @username = nil
  @password = nil
  @ssl = false
  @ssl_verify = true # SECURITY: Verify certificates by default
  @ssl_ca_path = nil
  @connect_timeout = 10
  @read_timeout = 60
  @write_timeout = 60
  @pool_size = 5
  @pool_timeout = 5
  @logger = nil
  @log_level = :info
  @default_settings = {}
  @compression = nil
  @compression_threshold = 1024
  @max_retries = 3
  @initial_backoff = 1.0
  @max_backoff = 120.0
  @backoff_multiplier = 1.6
  @retry_jitter = :equal
end

Instance Attribute Details

#backoff_multiplier ⇒ Float

Returns exponential backoff multiplier (default: 1.6).

Returns:

  • (Float) —

    exponential backoff multiplier (default: 1.6)



78
79
80
 
# File 'lib/clickhouse_ruby/configuration.rb', line 78

def backoff_multiplier
  @backoff_multiplier
end

#compression ⇒ String?

Returns compression algorithm (‘gzip’ or nil to disable).

Returns:

  • (String, nil) —

    compression algorithm (‘gzip’ or nil to disable)



63
64
65
 
# File 'lib/clickhouse_ruby/configuration.rb', line 63

def compression
  @compression
end

#compression_threshold ⇒ Integer

Returns minimum body size in bytes to compress (default: 1024).

Returns:

  • (Integer) —

    minimum body size in bytes to compress (default: 1024)



66
67
68
 
# File 'lib/clickhouse_ruby/configuration.rb', line 66

def compression_threshold
  @compression_threshold
end

#connect_timeout ⇒ Integer

Returns connection timeout in seconds (default: 10).

Returns:

  • (Integer) —

    connection timeout in seconds (default: 10)



39
40
41
 
# File 'lib/clickhouse_ruby/configuration.rb', line 39

def connect_timeout
  @connect_timeout
end

#database ⇒ String

Returns the database name (default: ‘default’).

Returns:

  • (String) —

    the database name (default: ‘default’)



20
21
22
 
# File 'lib/clickhouse_ruby/configuration.rb', line 20

def database
  @database
end

#default_settings ⇒ Hash

Returns default ClickHouse settings for all queries.

Returns:

  • (Hash) —

    default ClickHouse settings for all queries



60
61
62
 
# File 'lib/clickhouse_ruby/configuration.rb', line 60

def default_settings
  @default_settings
end

#host ⇒ String

Returns the ClickHouse server hostname.

Returns:

  • (String) —

    the ClickHouse server hostname



14
15
16
 
# File 'lib/clickhouse_ruby/configuration.rb', line 14

def host
  @host
end

#initial_backoff ⇒ Float

Returns initial backoff delay in seconds (default: 1.0).

Returns:

  • (Float) —

    initial backoff delay in seconds (default: 1.0)



72
73
74
 
# File 'lib/clickhouse_ruby/configuration.rb', line 72

def initial_backoff
  @initial_backoff
end

#log_level ⇒ Symbol

Returns log level (:debug, :info, :warn, :error).

Returns:

  • (Symbol) —

    log level (:debug, :info, :warn, :error)



57
58
59
 
# File 'lib/clickhouse_ruby/configuration.rb', line 57

def log_level
  @log_level
end

#logger ⇒ Logger?

Returns logger instance for debugging.

Returns:

  • (Logger, nil) —

    logger instance for debugging



54
55
56
 
# File 'lib/clickhouse_ruby/configuration.rb', line 54

def logger
  @logger
end

#max_backoff ⇒ Float

Returns maximum backoff delay in seconds (default: 120.0).

Returns:

  • (Float) —

    maximum backoff delay in seconds (default: 120.0)



75
76
77
 
# File 'lib/clickhouse_ruby/configuration.rb', line 75

def max_backoff
  @max_backoff
end

#max_retries ⇒ Integer

Returns maximum number of retry attempts (default: 3).

Returns:

  • (Integer) —

    maximum number of retry attempts (default: 3)



69
70
71
 
# File 'lib/clickhouse_ruby/configuration.rb', line 69

def max_retries
  @max_retries
end

#password ⇒ String?

Returns the password for authentication.

Returns:

  • (String, nil) —

    the password for authentication



26
27
28
 
# File 'lib/clickhouse_ruby/configuration.rb', line 26

def password
  @password
end

#pool_size ⇒ Integer

Returns connection pool size (default: 5).

Returns:

  • (Integer) —

    connection pool size (default: 5)



48
49
50
 
# File 'lib/clickhouse_ruby/configuration.rb', line 48

def pool_size
  @pool_size
end

#pool_timeout ⇒ Integer

Returns time to wait for a pool connection in seconds (default: 5).

Returns:

  • (Integer) —

    time to wait for a pool connection in seconds (default: 5)



51
52
53
 
# File 'lib/clickhouse_ruby/configuration.rb', line 51

def pool_timeout
  @pool_timeout
end

#port ⇒ Integer

Returns the ClickHouse HTTP port (default: 8123).

Returns:

  • (Integer) —

    the ClickHouse HTTP port (default: 8123)



17
18
19
 
# File 'lib/clickhouse_ruby/configuration.rb', line 17

def port
  @port
end

#read_timeout ⇒ Integer

Returns read timeout in seconds (default: 60).

Returns:

  • (Integer) —

    read timeout in seconds (default: 60)



42
43
44
 
# File 'lib/clickhouse_ruby/configuration.rb', line 42

def read_timeout
  @read_timeout
end

#retry_jitter ⇒ Symbol

Returns jitter strategy: :full, :equal, or :none (default: :equal).

Returns:

  • (Symbol) —

    jitter strategy: :full, :equal, or :none (default: :equal)



81
82
83
 
# File 'lib/clickhouse_ruby/configuration.rb', line 81

def retry_jitter
  @retry_jitter
end

#ssl ⇒ Boolean

Returns whether to use SSL/TLS.

Returns:

  • (Boolean) —

    whether to use SSL/TLS



29
30
31
 
# File 'lib/clickhouse_ruby/configuration.rb', line 29

def ssl
  @ssl
end

#ssl_ca_path ⇒ String?

Returns path to custom CA certificate file.

Returns:

  • (String, nil) —

    path to custom CA certificate file



36
37
38
 
# File 'lib/clickhouse_ruby/configuration.rb', line 36

def ssl_ca_path
  @ssl_ca_path
end

#ssl_verify ⇒ Boolean

IMPORTANT: This defaults to true for security. Only disable in development.

Returns:

  • (Boolean) —

    whether to verify SSL certificates (default: true)



33
34
35
 
# File 'lib/clickhouse_ruby/configuration.rb', line 33

def ssl_verify
  @ssl_verify
end

#username ⇒ String?

Returns the username for authentication.

Returns:

  • (String, nil) —

    the username for authentication



23
24
25
 
# File 'lib/clickhouse_ruby/configuration.rb', line 23

def username
  @username
end

#write_timeout ⇒ Integer

Returns write timeout in seconds (default: 60).

Returns:

  • (Integer) —

    write timeout in seconds (default: 60)



45
46
47
 
# File 'lib/clickhouse_ruby/configuration.rb', line 45

def write_timeout
  @write_timeout
end

Instance Method Details

#base_url ⇒ String

Returns the base URL for HTTP connections

Returns:

  • (String) —

    the base URL



113
114
115
116
 
# File 'lib/clickhouse_ruby/configuration.rb', line 113

def base_url
  scheme = ssl ? "https" : "http"
  "#{scheme}://#{host}:#{port}"
end

#compression_enabled? ⇒ Boolean

Returns whether compression is enabled

Returns:

  • (Boolean) —

    true if compression is set to ‘gzip’



132
133
134
 
# File 'lib/clickhouse_ruby/configuration.rb', line 132

def compression_enabled?
  @compression == "gzip"
end

#dup ⇒ Configuration

Creates a duplicate configuration

Returns:



160
161
162
163
164
165
166
167
168
169
170
171
 
# File 'lib/clickhouse_ruby/configuration.rb', line 160

def dup
  new_config = Configuration.new
  instance_variables.each do |var|
    value = instance_variable_get(var)
    begin
      new_config.instance_variable_set(var, value.dup)
    rescue StandardError
      value
    end
  end
  new_config
end

#to_connection_options ⇒ Hash

Returns a hash suitable for creating HTTP connections

Returns:

  • (Hash) —

    connection options



139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
 
# File 'lib/clickhouse_ruby/configuration.rb', line 139

def to_connection_options
  {
    host: host,
    port: port,
    database: database,
    username: username,
    password: password,
    use_ssl: use_ssl?,
    ssl_verify: ssl_verify,
    ssl_ca_path: ssl_ca_path,
    connect_timeout: connect_timeout,
    read_timeout: read_timeout,
    write_timeout: write_timeout,
    compression: compression,
    compression_threshold: compression_threshold,
  }
end

#use_ssl? ⇒ Boolean

Returns whether SSL should be used based on configuration or port Automatically enables SSL for common secure ports (8443, 443)

Returns:

  • (Boolean) —

    whether to use SSL



122
123
124
125
126
127
 
# File 'lib/clickhouse_ruby/configuration.rb', line 122

def use_ssl?
  return ssl unless ssl.nil?

  # Auto-enable SSL for secure ports
  [8443, 443].include?(port)
end

#validate! ⇒ Boolean

Validates the configuration

Returns:

  • (Boolean) —

    true if valid

Raises:



177
178
179
180
181
182
183
184
 
# File 'lib/clickhouse_ruby/configuration.rb', line 177

def validate!
  raise ConfigurationError, "host is required" if host.nil? || host.empty?
  raise ConfigurationError, "port must be a positive integer" unless port.is_a?(Integer) && port.positive?
  raise ConfigurationError, "database is required" if database.nil? || database.empty?
  raise ConfigurationError, "pool_size must be at least 1" unless pool_size >= 1

  true
end