clickhouse-ruby 0.1.0

data/lib/clickhouse_ruby/types/uuid.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+module ClickhouseRuby
+  module Types
+    # Type handler for ClickHouse UUID type
+    #
+    # UUIDs are stored as 16-byte values but represented as strings
+    # in the format: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
+    #
+    class UUID < Base
+      # UUID regex pattern
+      UUID_PATTERN = /\A[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}\z/i
+
+      # Converts a Ruby value to a UUID string
+      #
+      # @param value [Object] the value to convert
+      # @return [String, nil] the UUID string
+      # @raise [TypeCastError] if the value is not a valid UUID
+      def cast(value)
+        return nil if value.nil?
+
+        str = normalize_uuid(value)
+        validate_uuid!(str, value)
+        str
+      end
+
+      # Converts a value from ClickHouse to a UUID string
+      #
+      # @param value [Object] the value from ClickHouse
+      # @return [String, nil] the UUID string
+      def deserialize(value)
+        return nil if value.nil?
+
+        normalize_uuid(value)
+      end
+
+      # Converts a UUID to SQL literal
+      #
+      # @param value [String, nil] the UUID value
+      # @return [String] the SQL literal
+      def serialize(value)
+        return 'NULL' if value.nil?
+
+        "'#{normalize_uuid(value)}'"
+      end
+
+      private
+
+      # Normalizes a UUID value to the standard format
+      #
+      # @param value [Object] the value to normalize
+      # @return [String] the normalized UUID
+      def normalize_uuid(value)
+        str = value.to_s.strip.downcase
+
+        # Remove braces if present
+        str = str.gsub(/[{}]/, '')
+
+        # If no hyphens, add them
+        if str.length == 32 && !str.include?('-')
+          str = "#{str[0..7]}-#{str[8..11]}-#{str[12..15]}-#{str[16..19]}-#{str[20..31]}"
+        end
+
+        str
+      end
+
+      # Validates that a string is a valid UUID
+      #
+      # @param str [String] the normalized UUID string
+      # @param original [Object] the original value (for error messages)
+      # @raise [TypeCastError] if invalid
+      def validate_uuid!(str, original)
+        return if str.match?(UUID_PATTERN)
+
+        raise TypeCastError.new(
+          "Invalid UUID format: '#{original}'",
+          from_type: original.class.name,
+          to_type: name,
+          value: original
+        )
+      end
+    end
+  end
+end

data/lib/clickhouse_ruby/types.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+# Load base class first, then parser, then specific types, then registry last
+require_relative 'types/base'
+require_relative 'types/parser'
+require_relative 'types/integer'
+require_relative 'types/float'
+require_relative 'types/string'
+require_relative 'types/date_time'
+require_relative 'types/uuid'
+require_relative 'types/boolean'
+require_relative 'types/array'
+require_relative 'types/map'
+require_relative 'types/tuple'
+require_relative 'types/nullable'
+require_relative 'types/low_cardinality'
+require_relative 'types/registry'
+
+module ClickhouseRuby
+  # Type system for mapping between ClickHouse and Ruby types
+  #
+  # Key features:
+  # - AST-based type parser (handles nested types correctly)
+  # - Bidirectional conversion (Ruby ↔ ClickHouse)
+  # - Proper handling of complex types (Array, Map, Tuple, Nullable)
+  #
+  # @example Parse a complex type
+  #   parser = ClickhouseRuby::Types::Parser.new
+  #   ast = parser.parse('Array(Tuple(String, UInt64))')
+  #   # => { type: 'Array', args: [{ type: 'Tuple', args: [...] }] }
+  #
+  # @example Convert values
+  #   type = ClickhouseRuby::Types.lookup('UInt64')
+  #   type.cast(42)          # => 42
+  #   type.serialize(42)     # => "42"
+  #   type.deserialize("42") # => 42
+  #
+  module Types
+    class << self
+      # Returns the global type registry
+      #
+      # @return [Registry] the type registry
+      def registry
+        @registry ||= Registry.new.tap(&:register_defaults)
+      end
+
+      # Looks up a type by its ClickHouse type string
+      #
+      # @param type_string [String] the ClickHouse type (e.g., 'Array(String)')
+      # @return [Base] the type instance
+      def lookup(type_string)
+        registry.lookup(type_string)
+      end
+
+      # Parses a ClickHouse type string into an AST
+      #
+      # @param type_string [String] the ClickHouse type string
+      # @return [Hash] the parsed AST
+      def parse(type_string)
+        Parser.new.parse(type_string)
+      end
+
+      # Resets the registry (useful for testing)
+      def reset!
+        @registry = nil
+      end
+    end
+  end
+end

data/lib/clickhouse_ruby/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module ClickhouseRuby
+  VERSION = '0.1.0'
+end

data/lib/clickhouse_ruby.rb

@@ -0,0 +1,101 @@
+# frozen_string_literal: true
+
+require_relative 'clickhouse_ruby/version'
+require_relative 'clickhouse_ruby/errors'
+require_relative 'clickhouse_ruby/configuration'
+require_relative 'clickhouse_ruby/types'
+require_relative 'clickhouse_ruby/result'
+require_relative 'clickhouse_ruby/client'
+require_relative 'clickhouse_ruby/connection'
+require_relative 'clickhouse_ruby/connection_pool'
+
+# ClickhouseRuby - Ruby/ActiveRecord integration for ClickHouse
+#
+# A robust, reliable ClickHouse client for Ruby that prioritizes:
+# - No silent failures (proper error handling)
+# - Correct type handling (AST-based parser for complex types)
+# - Performance (bulk operations, connection pooling)
+# - Security (SSL verification enabled by default)
+#
+# @example Basic usage
+#   ClickhouseRuby.configure do |config|
+#     config.host = 'localhost'
+#     config.port = 8123
+#     config.database = 'analytics'
+#   end
+#
+#   client = ClickhouseRuby::Client.new
+#   result = client.execute('SELECT * FROM events LIMIT 10')
+#   result.each { |row| puts row['name'] }
+#
+# @example Bulk insert
+#   client.insert('events', [
+#     { id: 1, name: 'click', timestamp: Time.now },
+#     { id: 2, name: 'view', timestamp: Time.now }
+#   ])
+#
+module ClickhouseRuby
+  class << self
+    # Returns the global configuration instance
+    #
+    # @return [Configuration] the configuration object
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    # Allows configuration via a block
+    #
+    # @yield [Configuration] the configuration object
+    # @return [Configuration] the configuration object
+    #
+    # @example
+    #   ClickhouseRuby.configure do |config|
+    #     config.host = 'clickhouse.example.com'
+    #     config.port = 8443
+    #     config.ssl = true
+    #   end
+    def configure
+      yield(configuration)
+      configuration
+    end
+
+    # Resets the configuration to defaults
+    # Primarily useful for testing
+    #
+    # @return [Configuration] a new configuration object
+    def reset_configuration!
+      @configuration = Configuration.new
+    end
+
+    # Creates a new client with the global configuration
+    #
+    # @return [Client] a new client instance
+    def client
+      Client.new(configuration)
+    end
+
+    # Convenience method to execute a query using global configuration
+    #
+    # @param sql [String] the SQL query to execute
+    # @param options [Hash] query options
+    # @return [Result] the query result
+    def execute(sql, **options)
+      client.execute(sql, **options)
+    end
+
+    # Convenience method to insert data using global configuration
+    #
+    # @param table [String] the table name
+    # @param rows [Array<Hash>] the rows to insert
+    # @param options [Hash] insert options
+    # @return [Result] the insert result
+    def insert(table, rows, **options)
+      client.insert(table, rows, **options)
+    end
+  end
+end
+
+# Load ActiveRecord integration if ActiveRecord is available
+if defined?(ActiveRecord)
+  require_relative 'clickhouse_ruby/active_record'
+end

metadata

@@ -0,0 +1,150 @@
+--- !ruby/object:Gem::Specification
+name: clickhouse-ruby
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Mohamad Kamar
+autorequire: 
+bindir: exe
+cert_chain: []
+date: 2026-01-31 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.12'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.12'
+- !ruby/object:Gem::Dependency
+  name: simplecov
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.21.0
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.21.0
+- !ruby/object:Gem::Dependency
+  name: webmock
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 3.18.0
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 3.18.0
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+description: A lightweight Ruby client for ClickHouse with optional ActiveRecord integration.
+  Provides a simple interface for querying, inserting, and managing ClickHouse databases.
+email:
+- mohamad.kamar.dev@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- lib/clickhouse_ruby.rb
+- 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/railtie.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/result.rb
+- lib/clickhouse_ruby/types.rb
+- lib/clickhouse_ruby/types/array.rb
+- lib/clickhouse_ruby/types/base.rb
+- lib/clickhouse_ruby/types/boolean.rb
+- lib/clickhouse_ruby/types/date_time.rb
+- lib/clickhouse_ruby/types/float.rb
+- lib/clickhouse_ruby/types/integer.rb
+- lib/clickhouse_ruby/types/low_cardinality.rb
+- lib/clickhouse_ruby/types/map.rb
+- lib/clickhouse_ruby/types/nullable.rb
+- lib/clickhouse_ruby/types/parser.rb
+- lib/clickhouse_ruby/types/registry.rb
+- lib/clickhouse_ruby/types/string.rb
+- lib/clickhouse_ruby/types/tuple.rb
+- lib/clickhouse_ruby/types/uuid.rb
+- lib/clickhouse_ruby/version.rb
+homepage: https://github.com/kamardev/clickhouse-ruby
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/kamardev/clickhouse-ruby
+  source_code_uri: https://github.com/kamardev/clickhouse-ruby
+  changelog_uri: https://github.com/kamardev/clickhouse-ruby/blob/main/CHANGELOG.md
+  documentation_uri: https://rubydoc.info/gems/clickhouse-ruby
+  rubygems_mfa_required: 'true'
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.6.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.0.3.1
+signing_key: 
+specification_version: 4
+summary: Ruby/ActiveRecord integration for ClickHouse
+test_files: []