clickhouse-ruby 0.1.0 → 0.2.0

data/lib/clickhouse_ruby/types/registry.rb

@@ -36,7 +36,7 @@ module ClickhouseRuby
       # @param type_class [Class] the type class
       def register(name, type_class)
         @types[name] = type_class
-        @cache.clear  # Invalidate cache when types change
+        @cache.clear # Invalidate cache when types change
       end
 
       # Looks up a type by its ClickHouse type string
@@ -62,43 +62,55 @@ module ClickhouseRuby
       # Registers all default ClickHouse types
       def register_defaults
         # Integer types
-        register('Int8', Integer)
-        register('Int16', Integer)
-        register('Int32', Integer)
-        register('Int64', Integer)
-        register('Int128', Integer)
-        register('Int256', Integer)
-        register('UInt8', Integer)
-        register('UInt16', Integer)
-        register('UInt32', Integer)
-        register('UInt64', Integer)
-        register('UInt128', Integer)
-        register('UInt256', Integer)
+        register("Int8", Integer)
+        register("Int16", Integer)
+        register("Int32", Integer)
+        register("Int64", Integer)
+        register("Int128", Integer)
+        register("Int256", Integer)
+        register("UInt8", Integer)
+        register("UInt16", Integer)
+        register("UInt32", Integer)
+        register("UInt64", Integer)
+        register("UInt128", Integer)
+        register("UInt256", Integer)
 
         # Float types
-        register('Float32', Float)
-        register('Float64', Float)
+        register("Float32", Float)
+        register("Float64", Float)
+
+        # Decimal types
+        register("Decimal", Decimal)
+        register("Decimal32", Decimal)
+        register("Decimal64", Decimal)
+        register("Decimal128", Decimal)
+        register("Decimal256", Decimal)
 
         # String types
-        register('String', String)
-        register('FixedString', String)
+        register("String", String)
+        register("FixedString", String)
 
         # Date/Time types
-        register('Date', DateTime)
-        register('Date32', DateTime)
-        register('DateTime', DateTime)
-        register('DateTime64', DateTime)
+        register("Date", DateTime)
+        register("Date32", DateTime)
+        register("DateTime", DateTime)
+        register("DateTime64", DateTime)
 
         # Other basic types
-        register('UUID', UUID)
-        register('Bool', Boolean)
+        register("UUID", UUID)
+        register("Bool", Boolean)
 
         # Complex/wrapper types
-        register('Array', Array)
-        register('Map', Map)
-        register('Tuple', Tuple)
-        register('Nullable', Nullable)
-        register('LowCardinality', LowCardinality)
+        register("Array", Array)
+        register("Map", Map)
+        register("Tuple", Tuple)
+        register("Nullable", Nullable)
+        register("LowCardinality", LowCardinality)
+
+        # Enum types
+        register("Enum", Enum)
+        register("Enum8", Enum)
+        register("Enum16", Enum)
       end
 
       private
@@ -142,7 +154,6 @@ module ClickhouseRuby
           type_class.new(type_name)
         end
       end
-
     end
   end
 end

data/lib/clickhouse_ruby/types/string.rb

@@ -29,9 +29,7 @@ module ClickhouseRuby
         str = value.to_s
 
         # For FixedString, pad or truncate to length
-        if @length
-          str = str.ljust(@length, "\0")[0, @length]
-        end
+        str = str.ljust(@length, "\0")[0, @length] if @length
 
         str
       end
@@ -46,9 +44,7 @@ module ClickhouseRuby
         str = value.to_s
 
         # For FixedString, remove trailing null bytes
-        if @length
-          str = str.gsub(/\0+\z/, '')
-        end
+        str = str.gsub(/\0+\z/, "") if @length
 
         str
       end
@@ -58,7 +54,7 @@ module ClickhouseRuby
       # @param value [String, nil] the value to serialize
       # @return [String] the SQL literal
       def serialize(value)
-        return 'NULL' if value.nil?
+        return "NULL" if value.nil?
 
         escaped = escape_string(value.to_s)
         "'#{escaped}'"
@@ -71,12 +67,12 @@ module ClickhouseRuby
       # @param value [String] the string to escape
       # @return [String] the escaped string
       def escape_string(value)
-        value.gsub("\\", "\\\\")
-             .gsub("'", "\\'")
-             .gsub("\n", "\\n")
-             .gsub("\r", "\\r")
-             .gsub("\t", "\\t")
-             .gsub("\0", "\\0")
+        value.gsub("\\", "\\\\\\\\")
+          .gsub("'", "\\\\'")
+          .gsub("\n", "\\\\n")
+          .gsub("\r", "\\\\r")
+          .gsub("\t", "\\\\t")
+          .gsub("\0", "\\\\0")
       end
     end
   end

data/lib/clickhouse_ruby/types/string_parser.rb

@@ -0,0 +1,135 @@
+# frozen_string_literal: true
+
+module ClickhouseRuby
+  module Types
+    # Shared utilities for parsing ClickHouse string representations
+    # of complex types (arrays, tuples, maps)
+    #
+    # These methods handle the common patterns of parsing nested structures
+    # with proper handling of quotes, escape characters, and bracket depth.
+    #
+    module StringParser
+      module_function
+
+      # Parses a comma-separated list of elements, respecting nested structures and quotes
+      #
+      # @param str [String] the string to parse
+      # @param open_brackets [Array<String>] characters that increase nesting depth
+      # @param close_brackets [Array<String>] characters that decrease nesting depth
+      # @return [Array<String>] parsed elements
+      #
+      # @example
+      #   StringParser.parse_delimited("a, b, c")
+      #   # => ["a", "b", "c"]
+      #
+      #   StringParser.parse_delimited("'hello', [1, 2], 'world'")
+      #   # => ["'hello'", "[1, 2]", "'world'"]
+      #
+      def parse_delimited(str, open_brackets: ["[", "(", "{"], close_brackets: ["]", ")", "}"])
+        elements = []
+        current = +""
+        depth = 0
+        in_string = false
+        escape_next = false
+
+        str.each_char do |char|
+          if escape_next
+            current << char
+            escape_next = false
+            next
+          end
+
+          case char
+          when "\\"
+            escape_next = true
+            current << char
+          when "'"
+            in_string = !in_string
+            current << char
+          when *open_brackets
+            depth += 1 unless in_string
+            current << char
+          when *close_brackets
+            depth -= 1 unless in_string
+            current << char
+          when ","
+            if depth.zero? && !in_string
+              elements << current.strip
+              current = +""
+            else
+              current << char
+            end
+          else
+            current << char
+          end
+        end
+
+        elements << current.strip unless current.strip.empty?
+        elements
+      end
+
+      # Removes surrounding single quotes and unescapes content
+      #
+      # @param str [String] potentially quoted string
+      # @return [String] unquoted string with escapes processed
+      #
+      # @example
+      #   StringParser.unquote("'hello'")
+      #   # => "hello"
+      #
+      #   StringParser.unquote("'it\\'s'")
+      #   # => "it's"
+      #
+      #   StringParser.unquote("123")
+      #   # => "123"
+      #
+      def unquote(str)
+        str = str.strip
+        if str.start_with?("'") && str.end_with?("'") && str.length >= 2
+          str[1...-1].gsub("\\'", "'")
+        else
+          str
+        end
+      end
+
+      # Validates and extracts content from a bracketed string
+      #
+      # @param str [String] bracketed string like "[...]" or "(...)"
+      # @param open_bracket [String] expected opening bracket
+      # @param close_bracket [String] expected closing bracket
+      # @return [String] inner content (may be empty)
+      # @raise [ArgumentError] if format is invalid
+      #
+      # @example
+      #   StringParser.extract_bracketed("[1, 2, 3]", "[", "]")
+      #   # => "1, 2, 3"
+      #
+      def extract_bracketed(str, open_bracket, close_bracket)
+        str = str.strip
+        unless str.start_with?(open_bracket) && str.end_with?(close_bracket) && str.length >= 2
+          raise ArgumentError, "Expected #{open_bracket}...#{close_bracket} format, got: '#{str}'"
+        end
+
+        str[1...-1]
+      end
+
+      # Parses elements and unquotes them in one step
+      #
+      # @param str [String] the string to parse
+      # @param open_brackets [Array<String>] characters that increase nesting depth
+      # @param close_brackets [Array<String>] characters that decrease nesting depth
+      # @return [Array<String>] parsed and unquoted elements
+      #
+      def parse_and_unquote(str, open_brackets: ["[", "(", "{"], close_brackets: ["]", ")", "}"])
+        parse_delimited(str, open_brackets: open_brackets, close_brackets: close_brackets).map do |el|
+          # Only unquote simple quoted strings, preserve nested structures
+          if el.start_with?("'") && el.end_with?("'") && !el.include?("[") && !el.include?("(") && !el.include?("{")
+            unquote(el)
+          else
+            el
+          end
+        end
+      end
+    end
+  end
+end

data/lib/clickhouse_ruby/types/tuple.rb

@@ -37,12 +37,7 @@ module ClickhouseRuby
               when ::String
                 parse_tuple_string(value)
               else
-                raise TypeCastError.new(
-                  "Cannot cast #{value.class} to Tuple",
-                  from_type: value.class.name,
-                  to_type: to_s,
-                  value: value
-                )
+                raise_cast_error(value, "Cannot cast #{value.class} to Tuple")
               end
 
         cast_elements(arr)
@@ -72,21 +67,21 @@ module ClickhouseRuby
       # @param value [Array, nil] the value to serialize
       # @return [String] the SQL literal
       def serialize(value)
-        return 'NULL' if value.nil?
+        return "NULL" if value.nil?
 
         elements = value.each_with_index.map do |v, i|
-          type = @element_types[i] || Base.new('String')
+          type = @element_types[i] || Base.new("String")
           type.serialize(v)
         end
 
-        "(#{elements.join(', ')})"
+        "(#{elements.join(", ")})"
       end
 
       # Returns the full type string including element types
       #
       # @return [String] the type string
       def to_s
-        type_strs = @element_types.map(&:to_s).join(', ')
+        type_strs = @element_types.map(&:to_s).join(", ")
         "Tuple(#{type_strs})"
       end
 
@@ -98,7 +93,7 @@ module ClickhouseRuby
       # @return [Array] the cast array
       def cast_elements(arr)
         arr.each_with_index.map do |v, i|
-          type = @element_types[i] || Base.new('String')
+          type = @element_types[i] || Base.new("String")
           type.cast(v)
         end
       end
@@ -109,7 +104,7 @@ module ClickhouseRuby
       # @return [Array] the deserialized array
       def deserialize_elements(arr)
         arr.each_with_index.map do |v, i|
-          type = @element_types[i] || Base.new('String')
+          type = @element_types[i] || Base.new("String")
           type.deserialize(v)
         end
       end
@@ -122,17 +117,10 @@ module ClickhouseRuby
         stripped = value.strip
 
         # Handle empty tuple
-        return [] if stripped == '()'
+        return [] if stripped == "()"
 
         # Remove outer parentheses
-        unless stripped.start_with?('(') && stripped.end_with?(')')
-          raise TypeCastError.new(
-            "Invalid tuple format: '#{value}'",
-            from_type: 'String',
-            to_type: to_s,
-            value: value
-          )
-        end
+        raise_format_error(value, "tuple") unless stripped.start_with?("(") && stripped.end_with?(")")
 
         inner = stripped[1...-1]
         return [] if inner.strip.empty?
@@ -146,48 +134,7 @@ module ClickhouseRuby
       # @param str [String] the inner tuple string
       # @return [Array] the parsed elements
       def parse_elements(str)
-        elements = []
-        current = ''
-        depth = 0
-        in_string = false
-        escape_next = false
-
-        str.each_char do |char|
-          if escape_next
-            current += char
-            escape_next = false
-            next
-          end
-
-          case char
-          when '\\'
-            escape_next = true
-            current += char
-          when "'"
-            in_string = !in_string
-            current += char
-          when '(', '[', '{'
-            depth += 1 unless in_string
-            current += char
-          when ')', ']', '}'
-            depth -= 1 unless in_string
-            current += char
-          when ','
-            if depth.zero? && !in_string
-              elements << parse_element(current.strip)
-              current = ''
-            else
-              current += char
-            end
-          else
-            current += char
-          end
-        end
-
-        # Don't forget the last element
-        elements << parse_element(current.strip) unless current.strip.empty?
-
-        elements
+        StringParser.parse_delimited(str).map { |el| parse_element(el) }
       end
 
       # Parses a single element, removing quotes if necessary
@@ -195,11 +142,7 @@ module ClickhouseRuby
       # @param str [String] the element string
       # @return [Object] the parsed element
       def parse_element(str)
-        if str.start_with?("'") && str.end_with?("'")
-          str[1...-1].gsub("\\'", "'")
-        else
-          str
-        end
+        StringParser.unquote(str)
       end
     end
   end

data/lib/clickhouse_ruby/types/uuid.rb

@@ -8,17 +8,19 @@ module ClickhouseRuby
     # in the format: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
     #
     class UUID < Base
+      include NullSafe
+
       # 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
 
+      protected
+
       # Converts a Ruby value to a UUID string
       #
-      # @param value [Object] the value to convert
-      # @return [String, nil] the UUID string
+      # @param value [Object] the value to convert (guaranteed non-nil)
+      # @return [String] the UUID string
       # @raise [TypeCastError] if the value is not a valid UUID
-      def cast(value)
-        return nil if value.nil?
-
+      def cast_value(value)
         str = normalize_uuid(value)
         validate_uuid!(str, value)
         str
@@ -26,21 +28,17 @@ module ClickhouseRuby
 
       # 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?
-
+      # @param value [Object] the value from ClickHouse (guaranteed non-nil)
+      # @return [String] the UUID string
+      def deserialize_value(value)
         normalize_uuid(value)
       end
 
       # Converts a UUID to SQL literal
       #
-      # @param value [String, nil] the UUID value
+      # @param value [String] the UUID value (guaranteed non-nil)
       # @return [String] the SQL literal
-      def serialize(value)
-        return 'NULL' if value.nil?
-
+      def serialize_value(value)
         "'#{normalize_uuid(value)}'"
       end
 
@@ -54,10 +52,10 @@ module ClickhouseRuby
         str = value.to_s.strip.downcase
 
         # Remove braces if present
-        str = str.gsub(/[{}]/, '')
+        str = str.gsub(/[{}]/, "")
 
         # If no hyphens, add them
-        if str.length == 32 && !str.include?('-')
+        if str.length == 32 && !str.include?("-")
           str = "#{str[0..7]}-#{str[8..11]}-#{str[12..15]}-#{str[16..19]}-#{str[20..31]}"
         end
 
@@ -72,12 +70,7 @@ module ClickhouseRuby
       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
-        )
+        raise_format_error(original, "UUID")
       end
     end
   end

data/lib/clickhouse_ruby/types.rb

@@ -1,20 +1,24 @@
 # 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'
+# Load base class first, then modules, then parser, then specific types, then registry last
+require_relative "types/base"
+require_relative "types/null_safe"
+require_relative "types/string_parser"
+require_relative "types/parser"
+require_relative "types/integer"
+require_relative "types/float"
+require_relative "types/decimal"
+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/enum"
+require_relative "types/registry"
 
 module ClickhouseRuby
   # Type system for mapping between ClickHouse and Ruby types

data/lib/clickhouse_ruby/version.rb

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

data/lib/clickhouse_ruby.rb

@@ -1,13 +1,15 @@
 # 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'
+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/retry_handler"
+require_relative "clickhouse_ruby/streaming_result"
+require_relative "clickhouse_ruby/client"
+require_relative "clickhouse_ruby/connection"
+require_relative "clickhouse_ruby/connection_pool"
 
 # ClickhouseRuby - Ruby/ActiveRecord integration for ClickHouse
 #
@@ -96,6 +98,4 @@ module ClickhouseRuby
 end
 
 # Load ActiveRecord integration if ActiveRecord is available
-if defined?(ActiveRecord)
-  require_relative 'clickhouse_ruby/active_record'
-end
+require_relative "clickhouse_ruby/active_record" if defined?(ActiveRecord)