clickhouse-ruby 0.2.0 → 0.3.0

data/lib/clickhouse_ruby/client.rb

@@ -167,6 +167,91 @@ module ClickhouseRuby
       result.first["version"]
     end
 
+    # Returns the query execution plan for a SQL query
+    #
+    # Uses EXPLAIN to show how ClickHouse will execute the query.
+    #
+    # @param sql [String] the SQL query to explain
+    # @param type [Symbol] type of explain (:plan, :pipeline, :estimate, :ast, :syntax)
+    # @param settings [Hash] ClickHouse settings
+    # @return [Array<Hash>] the query plan rows
+    #
+    # @example Basic explain
+    #   client.explain('SELECT * FROM events WHERE date > today()')
+    #   # => [{"explain" => "Expression ..."}]
+    #
+    # @example Pipeline explain
+    #   client.explain('SELECT count() FROM events', type: :pipeline)
+    #
+    # @example Estimate query cost
+    #   client.explain('SELECT * FROM events', type: :estimate)
+    def explain(sql, type: :plan, settings: {})
+      explain_keyword = case type
+                        when :plan then "EXPLAIN"
+                        when :pipeline then "EXPLAIN PIPELINE"
+                        when :estimate then "EXPLAIN ESTIMATE"
+                        when :ast then "EXPLAIN AST"
+                        when :syntax then "EXPLAIN SYNTAX"
+                        else
+                          raise ArgumentError, "Unknown explain type: #{type}. Valid types: :plan, :pipeline, :estimate, :ast, :syntax"
+                        end
+
+      explain_sql = "#{explain_keyword} #{sql.strip}"
+      execute(explain_sql, settings: settings).to_a
+    end
+
+    # Returns detailed health status of the client and server
+    #
+    # Provides comprehensive health information including server status,
+    # connection pool state, and server metrics.
+    #
+    # @return [Hash] health status
+    #
+    # @example
+    #   client.health_check
+    #   # => {
+    #   #   status: :healthy,
+    #   #   server_reachable: true,
+    #   #   server_version: "24.1.0",
+    #   #   pool: { available: 3, in_use: 2, total: 5 },
+    #   #   uptime_seconds: 3600
+    #   # }
+    def health_check
+      started_at = Instrumentation.monotonic_time
+      server_reachable = ping
+      version = nil
+      server_metrics = {}
+
+      if server_reachable
+        begin
+          version = server_version
+
+          # Get server uptime and metrics
+          metrics_result = execute(<<~SQL, settings: { max_execution_time: 5 })
+            SELECT
+              uptime() AS uptime_seconds,
+              currentDatabase() AS current_database
+          SQL
+          server_metrics = metrics_result.first if metrics_result.any?
+        rescue StandardError
+          # Ignore errors fetching extended info
+        end
+      end
+
+      pool_health = @pool.health_check
+      check_duration_ms = Instrumentation.duration_ms(started_at)
+
+      {
+        status: server_reachable ? :healthy : :unhealthy,
+        server_reachable: server_reachable,
+        server_version: version,
+        current_database: server_metrics["current_database"],
+        server_uptime_seconds: server_metrics["uptime_seconds"],
+        pool: pool_health,
+        check_duration_ms: check_duration_ms.round(2),
+      }
+    end
+
     # Closes all connections in the pool
     #
     # Call this when shutting down to clean up resources.
@@ -258,6 +343,9 @@ module ClickhouseRuby
     # @param format [String] response format (default: JSONCompact)
     # @return [Result] query results
     def execute_internal(sql, settings: {}, format: DEFAULT_FORMAT)
+      started_at = Instrumentation.monotonic_time
+      row_count = 0
+
       # Build the query with format
       query_with_format = "#{sql.strip} FORMAT #{format}"
 
@@ -268,7 +356,16 @@ module ClickhouseRuby
       response = execute_request(query_with_format, params)
 
       # Parse response based on format
-      parse_response(response, sql, format)
+      result = parse_response(response, sql, format)
+      row_count = result.size
+
+      # Instrument successful query
+      instrument_query_complete(sql, settings, started_at, row_count)
+
+      result
+    rescue StandardError => e
+      instrument_query_error(sql, settings, started_at, e)
+      raise
     end
 
     # Internal insert without retry wrapper
@@ -280,6 +377,9 @@ module ClickhouseRuby
     # @param format [Symbol] insert format
     # @return [Boolean] true if successful
     def insert_internal(table, rows, columns: nil, settings: {}, format: :json_each_row)
+      started_at = Instrumentation.monotonic_time
+      row_count = rows.size
+
       # Determine columns from first row if not specified
       columns ||= rows.first.keys.map(&:to_s)
 
@@ -312,7 +412,13 @@ module ClickhouseRuby
         handle_response(response, sql)
       end
 
+      # Instrument successful insert
+      instrument_insert_complete(table, row_count, settings, started_at)
+
       true
+    rescue StandardError => e
+      instrument_insert_error(table, row_count, settings, started_at, e)
+      raise
     end
 
     # Builds query parameters including database and settings
@@ -574,5 +680,110 @@ module ClickhouseRuby
         "(code: #{code || "unknown"}, http: #{http_status}, sql: #{truncate_sql(sql, 200)})",
       )
     end
+
+    # ========================================================================
+    # Instrumentation helpers
+    # ========================================================================
+
+    # Instruments a successful query completion
+    #
+    # @param sql [String] the SQL query
+    # @param settings [Hash] query settings
+    # @param started_at [Float] monotonic start time
+    # @param row_count [Integer] number of rows returned
+    def instrument_query_complete(sql, settings, started_at, row_count)
+      duration_ms = Instrumentation.duration_ms(started_at)
+
+      payload = {
+        sql: truncate_sql(sql, 500),
+        settings: settings,
+        row_count: row_count,
+        duration_ms: duration_ms,
+      }
+
+      Instrumentation.publish(Instrumentation::EVENTS[:query_complete], payload)
+      log_query_timing(sql, duration_ms) if @logger && @config.log_level == :debug
+    end
+
+    # Instruments a query error
+    #
+    # @param sql [String] the SQL query
+    # @param settings [Hash] query settings
+    # @param started_at [Float] monotonic start time
+    # @param error [StandardError] the error
+    def instrument_query_error(sql, settings, started_at, error)
+      duration_ms = Instrumentation.duration_ms(started_at)
+
+      payload = {
+        sql: truncate_sql(sql, 500),
+        settings: settings,
+        duration_ms: duration_ms,
+        exception: [error.class.name, error.message],
+      }
+
+      Instrumentation.publish(Instrumentation::EVENTS[:query_error], payload)
+    end
+
+    # Instruments a successful insert completion
+    #
+    # @param table [String] the table name
+    # @param row_count [Integer] number of rows inserted
+    # @param settings [Hash] query settings
+    # @param started_at [Float] monotonic start time
+    def instrument_insert_complete(table, row_count, settings, started_at)
+      duration_ms = Instrumentation.duration_ms(started_at)
+
+      payload = {
+        table: table,
+        row_count: row_count,
+        settings: settings,
+        duration_ms: duration_ms,
+      }
+
+      Instrumentation.publish(Instrumentation::EVENTS[:insert_complete], payload)
+      log_insert_timing(table, row_count, duration_ms) if @logger && @config.log_level == :debug
+    end
+
+    # Instruments an insert error
+    #
+    # @param table [String] the table name
+    # @param row_count [Integer] number of rows attempted
+    # @param settings [Hash] query settings
+    # @param started_at [Float] monotonic start time
+    # @param error [StandardError] the error
+    def instrument_insert_error(table, row_count, settings, started_at, error)
+      duration_ms = Instrumentation.duration_ms(started_at)
+
+      payload = {
+        table: table,
+        row_count: row_count,
+        settings: settings,
+        duration_ms: duration_ms,
+        exception: [error.class.name, error.message],
+      }
+
+      Instrumentation.publish(Instrumentation::EVENTS[:insert_complete], payload)
+    end
+
+    # Logs query timing at debug level
+    #
+    # @param sql [String] the SQL query
+    # @param duration_ms [Float] duration in milliseconds
+    def log_query_timing(sql, duration_ms)
+      @logger.debug(
+        "[ClickhouseRuby] Query completed in #{duration_ms.round(2)}ms: #{truncate_sql(sql, 100)}",
+      )
+    end
+
+    # Logs insert timing at debug level
+    #
+    # @param table [String] the table name
+    # @param row_count [Integer] number of rows
+    # @param duration_ms [Float] duration in milliseconds
+    def log_insert_timing(table, row_count, duration_ms)
+      @logger.debug(
+        "[ClickhouseRuby] Insert #{row_count} rows into #{table} in #{duration_ms.round(2)}ms",
+      )
+    end
   end
 end

data/lib/clickhouse_ruby/connection_pool.rb

@@ -69,11 +69,26 @@ module ClickhouseRuby
     # @return [Object] the block's return value
     # @raise [PoolTimeout] if no connection becomes available
     def with_connection
+      started_at = Instrumentation.monotonic_time
       conn = checkout
+      wait_time_ms = Instrumentation.duration_ms(started_at)
+
+      # Publish pool checkout event
+      Instrumentation.publish(Instrumentation::EVENTS[:pool_checkout], {
+        pool_id: object_id,
+        wait_time_ms: wait_time_ms,
+        connection_id: conn.object_id,
+      },)
+
       begin
         yield conn
       ensure
         checkin(conn)
+        # Publish pool checkin event
+        Instrumentation.publish(Instrumentation::EVENTS[:pool_checkin], {
+          pool_id: object_id,
+          connection_id: conn.object_id,
+        },)
       end
     end
 
@@ -109,6 +124,13 @@ module ClickhouseRuby
           remaining = deadline - Time.now
           if remaining <= 0
             @total_timeouts += 1
+            # Publish pool timeout event
+            Instrumentation.publish(Instrumentation::EVENTS[:pool_timeout], {
+              pool_id: object_id,
+              wait_time_ms: @timeout * 1000,
+              pool_size: @size,
+              in_use: @in_use.size,
+            },)
             raise PoolTimeout, "Could not obtain a connection from the pool within #{@timeout} seconds " \
                                "(pool size: #{@size}, in use: #{@in_use.size})"
           end
@@ -250,7 +272,57 @@ module ClickhouseRuby
           total_connections: @all_connections.size,
           total_checkouts: @total_checkouts,
           total_timeouts: @total_timeouts,
-          uptime_seconds: Time.now - @created_at,
+          uptime_seconds: (Time.now - @created_at).round(2),
+        }
+      end
+    end
+
+    # Returns detailed pool statistics for monitoring
+    #
+    # Provides comprehensive metrics suitable for Prometheus/StatsD export.
+    #
+    # @return [Hash] detailed pool statistics
+    #
+    # @example
+    #   pool.detailed_stats
+    #   # => {
+    #   #   capacity: 5,
+    #   #   connections: { total: 5, available: 3, in_use: 2 },
+    #   #   utilization_percent: 40.0,
+    #   #   checkouts: { total: 1000, rate_per_minute: 16.7 },
+    #   #   timeouts: { total: 5, rate_per_minute: 0.08 },
+    #   #   uptime_seconds: 3600
+    #   # }
+    def detailed_stats
+      @mutex.synchronize do
+        uptime = Time.now - @created_at
+        uptime_minutes = uptime / 60.0
+
+        in_use = @in_use.size
+        available = @available.size
+        total = @all_connections.size
+        utilization = total.positive? ? (in_use.to_f / total * 100).round(2) : 0.0
+
+        checkout_rate = uptime_minutes.positive? ? (@total_checkouts / uptime_minutes).round(2) : 0.0
+        timeout_rate = uptime_minutes.positive? ? (@total_timeouts / uptime_minutes).round(4) : 0.0
+
+        {
+          capacity: @size,
+          connections: {
+            total: total,
+            available: available,
+            in_use: in_use,
+          },
+          utilization_percent: utilization,
+          checkouts: {
+            total: @total_checkouts,
+            rate_per_minute: checkout_rate,
+          },
+          timeouts: {
+            total: @total_timeouts,
+            rate_per_minute: timeout_rate,
+          },
+          uptime_seconds: uptime.round(2),
         }
       end
     end

data/lib/clickhouse_ruby/instrumentation.rb

@@ -0,0 +1,176 @@
+# frozen_string_literal: true
+
+module ClickhouseRuby
+  # Instrumentation module for observability and monitoring
+  #
+  # Provides ActiveSupport::Notifications integration when available,
+  # with graceful fallback for non-Rails applications.
+  #
+  # @example Subscribe to events (with ActiveSupport)
+  #   ActiveSupport::Notifications.subscribe(/clickhouse_ruby/) do |name, start, finish, id, payload|
+  #     duration = finish - start
+  #     Rails.logger.info "#{name} took #{duration}s"
+  #   end
+  #
+  # @example Subscribe to specific events
+  #   ActiveSupport::Notifications.subscribe('clickhouse_ruby.query.complete') do |*args|
+  #     event = ActiveSupport::Notifications::Event.new(*args)
+  #     puts "Query: #{event.payload[:sql]} took #{event.duration}ms"
+  #   end
+  #
+  module Instrumentation
+    # Event names for instrumentation
+    EVENTS = {
+      query_start: "clickhouse_ruby.query.start",
+      query_complete: "clickhouse_ruby.query.complete",
+      query_error: "clickhouse_ruby.query.error",
+      insert_start: "clickhouse_ruby.insert.start",
+      insert_complete: "clickhouse_ruby.insert.complete",
+      pool_checkout: "clickhouse_ruby.pool.checkout",
+      pool_checkin: "clickhouse_ruby.pool.checkin",
+      pool_timeout: "clickhouse_ruby.pool.timeout",
+    }.freeze
+
+    class << self
+      # Check if ActiveSupport::Notifications is available
+      #
+      # @return [Boolean] true if ActiveSupport::Notifications is available
+      def available?
+        defined?(ActiveSupport::Notifications)
+      end
+
+      # Instrument a block of code with timing and event notification
+      #
+      # When ActiveSupport::Notifications is available, publishes an event
+      # with the given name and payload. Otherwise, still tracks timing
+      # for logging purposes.
+      #
+      # @param event_name [String] the event name to publish
+      # @param payload [Hash] additional payload data
+      # @yield the block to instrument
+      # @return [Object] the result of the block
+      #
+      # @example
+      #   Instrumentation.instrument('clickhouse_ruby.query.complete', sql: 'SELECT 1') do
+      #     execute_query
+      #   end
+      def instrument(event_name, payload = {})
+        if available?
+          ActiveSupport::Notifications.instrument(event_name, payload) { yield }
+        else
+          instrument_without_as(event_name, payload) { yield }
+        end
+      end
+
+      # Publish an event without a block (for start/error events)
+      #
+      # @param event_name [String] the event name to publish
+      # @param payload [Hash] the event payload
+      # @return [void]
+      def publish(event_name, payload = {})
+        return unless available?
+
+        ActiveSupport::Notifications.publish(event_name, payload)
+      end
+
+      # Returns a monotonic timestamp for duration calculation
+      #
+      # Uses Process.clock_gettime for accurate timing that isn't
+      # affected by system clock changes.
+      #
+      # @return [Float] monotonic timestamp in seconds
+      def monotonic_time
+        Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      end
+
+      # Calculate duration in milliseconds from a start time
+      #
+      # @param started_at [Float] monotonic start time
+      # @return [Float] duration in milliseconds
+      def duration_ms(started_at)
+        (monotonic_time - started_at) * 1000
+      end
+
+      private
+
+      # Fallback instrumentation when ActiveSupport is not available
+      #
+      # Still tracks timing so it can be used for logging.
+      #
+      # @param event_name [String] the event name
+      # @param payload [Hash] the payload
+      # @yield the block to execute
+      # @return [Object] the result of the block
+      def instrument_without_as(_event_name, payload)
+        started_at = monotonic_time
+        result = yield
+        payload[:duration_ms] = duration_ms(started_at)
+        result
+      rescue StandardError => e
+        payload[:duration_ms] = duration_ms(started_at)
+        payload[:exception] = [e.class.name, e.message]
+        raise
+      end
+    end
+
+    # Helper module for including instrumentation in classes
+    module Helpers
+      private
+
+      # Instrument a query operation
+      #
+      # @param sql [String] the SQL query
+      # @param settings [Hash] query settings
+      # @yield the block to execute
+      # @return [Object] the result
+      def instrument_query(sql, settings: {})
+        payload = {
+          sql: sql,
+          settings: settings,
+          connection_id: object_id,
+        }
+
+        Instrumentation.instrument(EVENTS[:query_complete], payload) { yield }
+      end
+
+      # Instrument an insert operation
+      #
+      # @param table [String] the table name
+      # @param row_count [Integer] number of rows
+      # @param settings [Hash] query settings
+      # @yield the block to execute
+      # @return [Object] the result
+      def instrument_insert(table, row_count:, settings: {})
+        payload = {
+          table: table,
+          row_count: row_count,
+          settings: settings,
+          connection_id: object_id,
+        }
+
+        Instrumentation.instrument(EVENTS[:insert_complete], payload) { yield }
+      end
+
+      # Instrument a pool checkout operation
+      #
+      # @yield the block to execute
+      # @return [Object] the result
+      def instrument_pool_checkout
+        payload = { pool_id: object_id }
+
+        Instrumentation.instrument(EVENTS[:pool_checkout], payload) { yield }
+      end
+
+      # Publish a pool timeout event
+      #
+      # @param wait_time [Float] how long we waited before timeout
+      # @return [void]
+      def publish_pool_timeout(wait_time:)
+        Instrumentation.publish(EVENTS[:pool_timeout], {
+          pool_id: object_id,
+          wait_time_ms: wait_time * 1000,
+        },)
+      end
+    end
+  end
+end

data/lib/clickhouse_ruby/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module ClickhouseRuby
-  VERSION = "0.2.0"
+  VERSION = "0.3.0"
 end

data/lib/clickhouse_ruby.rb

@@ -3,6 +3,7 @@
 require_relative "clickhouse_ruby/version"
 require_relative "clickhouse_ruby/errors"
 require_relative "clickhouse_ruby/configuration"
+require_relative "clickhouse_ruby/instrumentation"
 require_relative "clickhouse_ruby/types"
 require_relative "clickhouse_ruby/result"
 require_relative "clickhouse_ruby/retry_handler"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: clickhouse-ruby
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Mohamad Kamar
@@ -108,6 +108,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '2.20'
+- !ruby/object:Gem::Dependency
+  name: benchmark-ips
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.12'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.12'
 description: A lightweight Ruby client for ClickHouse with optional ActiveRecord integration.
   Provides a simple interface for querying, inserting, and managing ClickHouse databases.
 email:
@@ -123,14 +137,19 @@ files:
 - lib/clickhouse_ruby/active_record.rb
 - lib/clickhouse_ruby/active_record/arel_visitor.rb
 - lib/clickhouse_ruby/active_record/connection_adapter.rb
+- lib/clickhouse_ruby/active_record/generators/migration_generator.rb
+- lib/clickhouse_ruby/active_record/generators/templates/create_table.rb.tt
+- lib/clickhouse_ruby/active_record/generators/templates/migration.rb.tt
 - lib/clickhouse_ruby/active_record/railtie.rb
 - lib/clickhouse_ruby/active_record/relation_extensions.rb
+- lib/clickhouse_ruby/active_record/schema_dumper.rb
 - lib/clickhouse_ruby/active_record/schema_statements.rb
 - lib/clickhouse_ruby/client.rb
 - lib/clickhouse_ruby/configuration.rb
 - lib/clickhouse_ruby/connection.rb
 - lib/clickhouse_ruby/connection_pool.rb
 - lib/clickhouse_ruby/errors.rb
+- lib/clickhouse_ruby/instrumentation.rb
 - lib/clickhouse_ruby/result.rb
 - lib/clickhouse_ruby/retry_handler.rb
 - lib/clickhouse_ruby/streaming_result.rb