clickhouse-ruby 0.1.0

data/lib/clickhouse_ruby/connection_pool.rb

@@ -0,0 +1,301 @@
+# frozen_string_literal: true
+
+require 'thread'
+require 'timeout'
+
+module ClickhouseRuby
+  # Thread-safe connection pool for managing multiple ClickHouse connections
+  #
+  # Features:
+  # - Thread-safe checkout/checkin with mutex
+  # - Configurable pool size and timeout
+  # - Automatic health checks before returning connections
+  # - with_connection block pattern for safe usage
+  # - Idle connection cleanup
+  #
+  # @example Basic usage with block (recommended)
+  #   pool = ClickhouseRuby::ConnectionPool.new(config)
+  #   pool.with_connection do |conn|
+  #     response = conn.post('/query', 'SELECT 1')
+  #   end
+  #
+  # @example Manual checkout/checkin (use with caution)
+  #   conn = pool.checkout
+  #   begin
+  #     response = conn.post('/query', 'SELECT 1')
+  #   ensure
+  #     pool.checkin(conn)
+  #   end
+  #
+  class ConnectionPool
+    # @return [Integer] maximum number of connections in the pool
+    attr_reader :size
+
+    # @return [Integer] timeout in seconds when waiting for a connection
+    attr_reader :timeout
+
+    # Creates a new connection pool
+    #
+    # @param config [Configuration] connection configuration
+    # @param size [Integer] maximum pool size (default from config)
+    # @param timeout [Integer] wait timeout in seconds (default from config)
+    def initialize(config, size: nil, timeout: nil)
+      @config = config
+      @size = size || config.pool_size
+      @timeout = timeout || config.pool_timeout
+      @connection_options = config.to_connection_options
+
+      # Pool state
+      @available = []           # Connections available for checkout
+      @in_use = []             # Connections currently checked out
+      @all_connections = []    # All connections ever created
+
+      # Synchronization
+      @mutex = Mutex.new
+      @condition = ConditionVariable.new
+
+      # Stats
+      @total_checkouts = 0
+      @total_timeouts = 0
+      @created_at = Time.now
+    end
+
+    # Executes a block with a checked-out connection
+    #
+    # This is the recommended way to use the pool. The connection is
+    # automatically returned to the pool when the block completes,
+    # even if an exception is raised.
+    #
+    # @yield [Connection] the checked-out connection
+    # @return [Object] the block's return value
+    # @raise [PoolTimeout] if no connection becomes available
+    def with_connection
+      conn = checkout
+      begin
+        yield conn
+      ensure
+        checkin(conn)
+      end
+    end
+
+    # Checks out a connection from the pool
+    #
+    # If no connections are available and the pool is at capacity,
+    # waits up to @timeout seconds for one to become available.
+    #
+    # @return [Connection] a healthy connection
+    # @raise [PoolTimeout] if no connection available within timeout
+    # @raise [PoolExhausted] if pool is exhausted and timeout is 0
+    def checkout
+      deadline = Time.now + @timeout
+
+      @mutex.synchronize do
+        loop do
+          # Try to get an available connection
+          if (conn = get_available_connection)
+            @in_use << conn
+            @total_checkouts += 1
+            return conn
+          end
+
+          # Try to create a new connection if under capacity
+          if @all_connections.size < @size
+            conn = create_connection
+            @in_use << conn
+            @total_checkouts += 1
+            return conn
+          end
+
+          # Wait for a connection to be returned
+          remaining = deadline - Time.now
+          if remaining <= 0
+            @total_timeouts += 1
+            raise PoolTimeout.new(
+              "Could not obtain a connection from the pool within #{@timeout} seconds " \
+              "(pool size: #{@size}, in use: #{@in_use.size})"
+            )
+          end
+
+          @condition.wait(@mutex, remaining)
+        end
+      end
+    end
+
+    # Returns a connection to the pool
+    #
+    # @param connection [Connection] the connection to return
+    # @return [void]
+    def checkin(connection)
+      return unless connection
+
+      @mutex.synchronize do
+        @in_use.delete(connection)
+
+        # Only return healthy connections to the available pool
+        if connection.healthy? && !connection.stale?
+          @available << connection
+        else
+          # Disconnect unhealthy connections
+          connection.disconnect rescue nil
+          @all_connections.delete(connection)
+        end
+
+        @condition.signal
+      end
+    end
+
+    # Returns the number of currently available connections
+    #
+    # @return [Integer]
+    def available_count
+      @mutex.synchronize { @available.size }
+    end
+
+    # Returns the number of connections currently in use
+    #
+    # @return [Integer]
+    def in_use_count
+      @mutex.synchronize { @in_use.size }
+    end
+
+    # Returns the total number of connections (available + in use)
+    #
+    # @return [Integer]
+    def total_count
+      @mutex.synchronize { @all_connections.size }
+    end
+
+    # Checks if all connections are currently in use
+    #
+    # @return [Boolean]
+    def exhausted?
+      @mutex.synchronize do
+        @available.empty? && @all_connections.size >= @size
+      end
+    end
+
+    # Closes all connections and resets the pool
+    #
+    # This should be called when shutting down the application.
+    #
+    # @return [void]
+    def shutdown
+      @mutex.synchronize do
+        (@available + @in_use).each do |conn|
+          conn.disconnect rescue nil
+        end
+
+        @available.clear
+        @in_use.clear
+        @all_connections.clear
+      end
+    end
+
+    # Removes idle/unhealthy connections from the pool
+    #
+    # @param max_idle_seconds [Integer] maximum idle time before removal
+    # @return [Integer] number of connections removed
+    def cleanup(max_idle_seconds = 300)
+      removed = 0
+
+      @mutex.synchronize do
+        @available.reject! do |conn|
+          if conn.stale?(max_idle_seconds) || !conn.healthy?
+            conn.disconnect rescue nil
+            @all_connections.delete(conn)
+            removed += 1
+            true
+          else
+            false
+          end
+        end
+      end
+
+      removed
+    end
+
+    # Pings all available connections to check health
+    #
+    # @return [Hash] status report
+    def health_check
+      @mutex.synchronize do
+        healthy = 0
+        unhealthy = 0
+
+        @available.each do |conn|
+          if conn.ping
+            healthy += 1
+          else
+            unhealthy += 1
+          end
+        end
+
+        {
+          available: @available.size,
+          in_use: @in_use.size,
+          total: @all_connections.size,
+          capacity: @size,
+          healthy: healthy,
+          unhealthy: unhealthy
+        }
+      end
+    end
+
+    # Returns pool statistics
+    #
+    # @return [Hash] pool statistics
+    def stats
+      @mutex.synchronize do
+        {
+          size: @size,
+          available: @available.size,
+          in_use: @in_use.size,
+          total_connections: @all_connections.size,
+          total_checkouts: @total_checkouts,
+          total_timeouts: @total_timeouts,
+          uptime_seconds: Time.now - @created_at
+        }
+      end
+    end
+
+    # Returns a string representation of the pool
+    #
+    # @return [String]
+    def inspect
+      @mutex.synchronize do
+        "#<#{self.class.name} size=#{@size} available=#{@available.size} in_use=#{@in_use.size}>"
+      end
+    end
+
+    private
+
+    # Gets an available connection from the pool
+    #
+    # @return [Connection, nil] a healthy connection or nil
+    def get_available_connection
+      while (conn = @available.pop)
+        # Verify the connection is still healthy
+        if conn.healthy? && !conn.stale?
+          return conn
+        else
+          # Remove unhealthy connections
+          conn.disconnect rescue nil
+          @all_connections.delete(conn)
+        end
+      end
+
+      nil
+    end
+
+    # Creates a new connection
+    #
+    # @return [Connection] the new connection
+    # @raise [ConnectionNotEstablished] if connection fails
+    def create_connection
+      conn = Connection.new(**@connection_options)
+      conn.connect
+      @all_connections << conn
+      conn
+    end
+  end
+end

data/lib/clickhouse_ruby/errors.rb

@@ -0,0 +1,144 @@
+# frozen_string_literal: true
+
+module ClickhouseRuby
+  # Base error class for all ClickhouseRuby errors
+  # All errors include context information to aid debugging
+  class Error < StandardError
+    # @return [Exception, nil] the original exception that caused this error
+    attr_reader :original_error
+
+    # @param message [String] the error message
+    # @param original_error [Exception, nil] the underlying exception
+    def initialize(message = nil, original_error: nil)
+      @original_error = original_error
+      super(message)
+    end
+  end
+
+  # Connection-related errors
+  # Raised when there are issues establishing or maintaining a connection
+  class ConnectionError < Error; end
+
+  # Raised when a connection cannot be established
+  # Common causes: wrong host/port, network issues, authentication failure
+  class ConnectionNotEstablished < ConnectionError; end
+
+  # Raised when a connection or query times out
+  class ConnectionTimeout < ConnectionError; end
+
+  # Raised for SSL/TLS related errors
+  # Common causes: certificate verification failure, SSL protocol mismatch
+  class SSLError < ConnectionError; end
+
+  # Query execution errors
+  # Raised when there are issues executing a query
+  class QueryError < Error
+    # @return [Integer, nil] ClickHouse error code
+    attr_reader :code
+
+    # @return [String, nil] HTTP status code from the response
+    attr_reader :http_status
+
+    # @return [String, nil] the SQL that caused the error
+    attr_reader :sql
+
+    # @param message [String] the error message
+    # @param code [Integer, nil] ClickHouse error code
+    # @param http_status [String, nil] HTTP response status
+    # @param sql [String, nil] the SQL query that failed
+    # @param original_error [Exception, nil] the underlying exception
+    def initialize(message = nil, code: nil, http_status: nil, sql: nil, original_error: nil)
+      @code = code
+      @http_status = http_status
+      @sql = sql
+      super(message, original_error: original_error)
+    end
+
+    # Returns a detailed error message including context
+    #
+    # @return [String] the detailed error message
+    def detailed_message
+      parts = [message]
+      parts << "Code: #{code}" if code
+      parts << "HTTP Status: #{http_status}" if http_status
+      parts << "SQL: #{sql}" if sql
+      parts.join(' | ')
+    end
+  end
+
+  # Raised for SQL syntax errors
+  class SyntaxError < QueryError; end
+
+  # Raised when a query is invalid (e.g., unknown table, column)
+  class StatementInvalid < QueryError; end
+
+  # Raised when a query exceeds its time limit
+  class QueryTimeout < QueryError; end
+
+  # Raised when a table doesn't exist
+  class UnknownTable < QueryError; end
+
+  # Raised when a column doesn't exist
+  class UnknownColumn < QueryError; end
+
+  # Raised when a database doesn't exist
+  class UnknownDatabase < QueryError; end
+
+  # Type conversion errors
+  # Raised when there are issues converting between Ruby and ClickHouse types
+  class TypeCastError < Error
+    # @return [String, nil] the source type
+    attr_reader :from_type
+
+    # @return [String, nil] the target type
+    attr_reader :to_type
+
+    # @return [Object, nil] the value that couldn't be converted
+    attr_reader :value
+
+    # @param message [String] the error message
+    # @param from_type [String, nil] the source type
+    # @param to_type [String, nil] the target type
+    # @param value [Object, nil] the value that failed conversion
+    def initialize(message = nil, from_type: nil, to_type: nil, value: nil)
+      @from_type = from_type
+      @to_type = to_type
+      @value = value
+      super(message)
+    end
+  end
+
+  # Configuration errors
+  # Raised when there are issues with configuration
+  class ConfigurationError < Error; end
+
+  # Pool errors
+  # Raised when there are issues with the connection pool
+  class PoolError < Error; end
+
+  # Raised when no connections are available in the pool
+  class PoolExhausted < PoolError; end
+
+  # Raised when waiting for a connection times out
+  class PoolTimeout < PoolError; end
+
+  # Maps ClickHouse error codes to exception classes
+  # See: https://github.com/ClickHouse/ClickHouse/blob/master/src/Common/ErrorCodes.cpp
+  ERROR_CODE_MAPPING = {
+    60 => UnknownTable,        # UNKNOWN_TABLE
+    16 => UnknownColumn,       # NO_SUCH_COLUMN_IN_TABLE
+    81 => UnknownDatabase,     # UNKNOWN_DATABASE
+    62 => SyntaxError,         # SYNTAX_ERROR
+    159 => QueryTimeout,       # TIMEOUT_EXCEEDED
+  }.freeze
+
+  class << self
+    # Maps a ClickHouse error code to the appropriate exception class
+    #
+    # @param code [Integer] the ClickHouse error code
+    # @return [Class] the exception class to use
+    def error_class_for_code(code)
+      ERROR_CODE_MAPPING.fetch(code, QueryError)
+    end
+  end
+end

data/lib/clickhouse_ruby/result.rb

@@ -0,0 +1,189 @@
+# frozen_string_literal: true
+
+module ClickhouseRuby
+  # Query result container that provides access to columns, types, and rows
+  #
+  # Result implements Enumerable for easy iteration over rows.
+  # Each row is returned as a Hash with column names as keys and
+  # properly deserialized values.
+  #
+  # @example Iterating over results
+  #   result = client.execute('SELECT id, name FROM users')
+  #   result.columns  # => ['id', 'name']
+  #   result.types    # => ['UInt64', 'String']
+  #
+  #   result.each do |row|
+  #     puts "#{row['id']}: #{row['name']}"
+  #   end
+  #
+  # @example Array-like access
+  #   result.rows[0]       # => { 'id' => 1, 'name' => 'Alice' }
+  #   result.first         # => { 'id' => 1, 'name' => 'Alice' }
+  #   result.to_a          # => [{ 'id' => 1, 'name' => 'Alice' }, ...]
+  #
+  # @example Metadata access
+  #   result.count         # => 100
+  #   result.empty?        # => false
+  #   result.elapsed_time  # => 0.023 (seconds)
+  #
+  class Result
+    include Enumerable
+
+    # @return [Array<String>] column names in order
+    attr_reader :columns
+
+    # @return [Array<String>] ClickHouse type strings for each column
+    attr_reader :types
+
+    # @return [Array<Hash>] rows as hashes with column names as keys
+    attr_reader :rows
+
+    # @return [Float, nil] query execution time in seconds (from ClickHouse)
+    attr_reader :elapsed_time
+
+    # @return [Integer, nil] number of rows read by ClickHouse
+    attr_reader :rows_read
+
+    # @return [Integer, nil] bytes read by ClickHouse
+    attr_reader :bytes_read
+
+    # Creates a new Result from parsed response data
+    #
+    # @param columns [Array<String>] column names
+    # @param types [Array<String>] ClickHouse type strings
+    # @param data [Array<Array>] raw row data (values in column order)
+    # @param statistics [Hash] optional query statistics from ClickHouse
+    # @param deserialize [Boolean] whether to deserialize values using type system
+    def initialize(columns:, types:, data:, statistics: {}, deserialize: true)
+      @columns = columns.freeze
+      @types = types.freeze
+      @elapsed_time = statistics['elapsed']
+      @rows_read = statistics['rows_read']
+      @bytes_read = statistics['bytes_read']
+
+      # Build type instances for deserialization
+      @type_instances = if deserialize
+                          types.map { |t| Types.lookup(t) }
+                        else
+                          nil
+                        end
+
+      # Convert raw data to row hashes
+      @rows = build_rows(data).freeze
+    end
+
+    # Iterates over each row
+    #
+    # @yield [Hash] each row as a hash
+    # @return [Enumerator] if no block given
+    def each(&block)
+      @rows.each(&block)
+    end
+
+    # Returns the number of rows
+    #
+    # @return [Integer] row count
+    def count
+      @rows.length
+    end
+    alias size count
+    alias length count
+
+    # Returns whether there are no rows
+    #
+    # @return [Boolean] true if no rows
+    def empty?
+      @rows.empty?
+    end
+
+    # Returns the first row
+    #
+    # @return [Hash, nil] the first row or nil
+    def first
+      @rows.first
+    end
+
+    # Returns the last row
+    #
+    # @return [Hash, nil] the last row or nil
+    def last
+      @rows.last
+    end
+
+    # Access a row by index
+    #
+    # @param index [Integer] row index
+    # @return [Hash, nil] the row or nil
+    def [](index)
+      @rows[index]
+    end
+
+    # Returns a specific column's values across all rows
+    #
+    # @param column_name [String] the column name
+    # @return [Array] values for that column
+    # @raise [ArgumentError] if column doesn't exist
+    def column_values(column_name)
+      index = @columns.index(column_name)
+      raise ArgumentError, "Unknown column: #{column_name}" if index.nil?
+
+      @rows.map { |row| row[column_name] }
+    end
+
+    # Returns column names mapped to their types
+    #
+    # @return [Hash<String, String>] column name => type mapping
+    def column_types
+      @columns.zip(@types).to_h
+    end
+
+    # Creates an empty result (for commands that don't return data)
+    #
+    # @return [Result] an empty result
+    def self.empty
+      new(columns: [], types: [], data: [])
+    end
+
+    # Creates a result from JSONCompact format response
+    #
+    # @param response_data [Hash] parsed JSON response
+    # @return [Result] the result
+    def self.from_json_compact(response_data)
+      meta = response_data['meta'] || []
+      columns = meta.map { |m| m['name'] }
+      types = meta.map { |m| m['type'] }
+      data = response_data['data'] || []
+      statistics = response_data['statistics'] || {}
+
+      new(columns: columns, types: types, data: data, statistics: statistics)
+    end
+
+    # Returns a human-readable string representation
+    #
+    # @return [String] string representation
+    def inspect
+      "#<#{self.class.name} columns=#{@columns.inspect} rows=#{count}>"
+    end
+
+    private
+
+    # Builds row hashes from raw data
+    #
+    # @param data [Array<Array>] raw row data
+    # @return [Array<Hash>] rows as hashes
+    def build_rows(data)
+      data.map do |row_values|
+        row = {}
+        @columns.each_with_index do |col, i|
+          value = row_values[i]
+          # Deserialize if we have type instances
+          if @type_instances
+            value = @type_instances[i].deserialize(value)
+          end
+          row[col] = value
+        end
+        row
+      end
+    end
+  end
+end