quack-ruby 0.1.0-x86_64-darwin

data/lib/quack/logical_types.rb

@@ -0,0 +1,72 @@
+module Quack
+  # Preserve the SQL timestamp kind as well as Ruby's nanosecond-precision instant.
+  # Time equality/arithmetic continue to use Ruby's standard behavior.
+  class Timestamp < Time
+    attr_reader :duckdb_type
+
+    def self.from(value, type)
+      seconds = value.is_a?(DateTime) ? (value.new_offset(0) - DateTime.new(1970, 1, 1)) * 86_400 : value.to_r
+      at(seconds).utc.tap { |time| time.instance_variable_set(:@duckdb_type, String(type).freeze) }
+    end
+
+    def getutc
+      super.tap { |time| time.instance_variable_set(:@duckdb_type, duckdb_type) }
+    end
+
+    def getlocal(*args)
+      super.tap { |time| time.instance_variable_set(:@duckdb_type, duckdb_type) }
+    end
+
+    def +(seconds) = self.class.from(super, duckdb_type)
+    def -(other)
+      result = super
+      result.is_a?(Time) ? self.class.from(result, duckdb_type) : result
+    end
+  end
+
+  BitString = Data.define(:bits) do
+    def initialize(bits:)
+      bits = String(bits)
+      raise ArgumentError, "BIT values need at least one 0 or 1 bit" unless bits.match?(/\A[01]+\z/)
+      super(bits: bits.dup.freeze)
+    end
+    def to_s = bits
+  end
+
+  # Standard WKB is a lossless geometry value, including empty/Z/M geometries.
+  Geometry = Data.define(:wkb, :crs) do
+    def initialize(wkb:, crs: nil)
+      super(wkb: String(wkb).b.freeze, crs: crs&.dup&.freeze)
+    end
+  end
+
+  Map = Data.define(:entries, :key_type, :value_type) do
+    include Enumerable
+    def initialize(entries:, key_type: nil, value_type: nil)
+      super(entries: entries.to_h.freeze, key_type: key_type, value_type: value_type)
+    end
+    def each(&block) = entries.each(&block)
+    def [](key) = entries[key]
+    def to_h = entries.dup
+    def ==(other) = other.is_a?(Map) && entries == other.entries
+    alias eql? ==
+    def hash = [self.class, entries].hash
+  end
+
+  Union = Data.define(:tag, :value, :members) do
+    def initialize(tag:, value:, members: nil)
+      super(tag: String(tag).freeze, value: value, members: members)
+    end
+    def ==(other) = other.is_a?(Union) && tag == other.tag && value == other.value
+    alias eql? ==
+    def hash = [self.class, tag, value].hash
+  end
+
+  Tuple = Data.define(:values) do
+    def initialize(values:)
+      super(values: values.to_a.freeze)
+    end
+    def [](index) = values[index]
+    def to_a = values.dup
+  end
+end

data/lib/quack/result.rb

@@ -0,0 +1,64 @@
+module Quack
+  class Result
+    include Enumerable
+    attr_reader :columns, :rows, :column_metadata
+
+    def initialize(metadata, rows)
+      @column_metadata = metadata.freeze
+      @columns = metadata.map { |col| col.fetch("name") }.freeze
+      @rows = rows
+    end
+    def each
+      return enum_for(__method__) unless block_given?
+      rows.each { |row| yield columns.zip(row).to_h }
+      self
+    end
+    def affected_rows
+      columns == ["Count"] && rows.first&.first.is_a?(Integer) ? rows.first.first : 0
+    end
+  end
+
+  class Stream
+    include Enumerable
+    attr_reader :column_metadata, :columns
+
+    def initialize(native)
+      @native = native
+      @column_metadata = native.columns.freeze
+      @columns = column_metadata.map { |col| col.fetch("name") }.freeze
+      @closed = false
+    end
+    def each_batch
+      return enum_for(__method__) unless block_given?
+      begin
+        while (batch = @native.next_batch)
+          batch.each do |row|
+            row.each_index { |index| row[index] = Codec.decode(row[index], column_metadata[index].fetch("duckdb_type")) }
+          end
+          yield batch
+        end
+      ensure
+        close
+      end
+      self
+    end
+    def each_row
+      return enum_for(__method__) unless block_given?
+      each_batch { |batch| batch.each { |row| yield row } }
+      self
+    end
+    def each
+      return enum_for(__method__) unless block_given?
+      each_row { |row| yield columns.zip(row).to_h }
+      self
+    end
+    def close
+      return if @closed
+      @native.close
+      @closed = true
+      nil
+    end
+    def closed? = @closed
+    def to_result = Result.new(column_metadata, each_row.to_a)
+  end
+end

data/lib/quack/sql.rb

@@ -0,0 +1,183 @@
+require "strscan"
+
+module Quack
+  module SQL
+    module_function
+
+    def identifier(name)
+      '"' + String(name).gsub('"', '""') + '"'
+    end
+
+    def identifier_parts(name)
+      scanner = StringScanner.new(String(name))
+      parts = []
+      until scanner.eos?
+        if scanner.scan(/"/)
+          part = +""
+          closed = false
+          until scanner.eos?
+            char = scanner.getch
+            if char == '"'
+              if scanner.scan(/"/) then part << '"'
+              else closed = true; break
+              end
+            else part << char
+            end
+          end
+          raise ArgumentError, "unterminated quoted identifier" unless closed
+        else
+          part = scanner.scan(/[^."]+/)
+        end
+        raise ArgumentError, "invalid qualified identifier" if part.nil? || part.empty?
+        parts << part
+        break if scanner.eos?
+        raise ArgumentError, "invalid qualified identifier" unless scanner.scan(/\./) && !scanner.eos?
+      end
+      raise ArgumentError, "expected one to three identifier parts" unless (1..3).cover?(parts.length)
+      parts
+    end
+
+    def literal(value)
+      case value
+      when nil then "NULL"
+      when true then "TRUE"
+      when false then "FALSE"
+      when Integer
+        return "'#{value}'::BIGNUM" unless (-(2**127)...2**128).cover?(value)
+        value.negative? ? "(#{value})" : value.to_s
+      when BigDecimal
+        raise ArgumentError, "non-finite decimal parameter" unless value.finite?
+        text = value.to_s("F").sub(/\.0\z/, "")
+        integer, fraction = text.delete_prefix("-").split(".")
+        scale = fraction.to_s.length
+        width = [integer.sub(/\A0+/, "").length + scale, 1].max
+        raise RangeError, "DuckDB decimals support at most 38 digits" if width > 38
+        "'#{text}'::DECIMAL(#{width},#{scale})"
+      when Float
+        return "'NaN'::DOUBLE" if value.nan?
+        return value.positive? ? "'Infinity'::DOUBLE" : "'-Infinity'::DOUBLE" if value.infinite?
+        "'#{value}'::DOUBLE"
+      when String
+        if value.encoding == Encoding::BINARY
+          "from_hex('#{value.unpack1('H*')}')"
+        else
+          text = value.encode(Encoding::UTF_8)
+          text.include?("\0") ? "decode(from_hex('#{text.unpack1('H*')}'))" : "'#{text.gsub("'", "''")}'"
+        end
+      when Timestamp then timestamp_literal(value, value.duckdb_type)
+      when Time, DateTime
+        fraction = value.is_a?(DateTime) ? value.sec_fraction : value.to_r % 1
+        timestamp_literal(value, ((fraction * 1_000_000) % 1).zero? ? "TIMESTAMPTZ" : "TIMESTAMP_NS")
+      when Date then "DATE '#{value.iso8601}'"
+      when TimeOfDay
+        type = if value.utc_offset
+          "TIMETZ"
+        elsif (value.nanoseconds % 1000).zero?
+          "TIME"
+        else
+          "TIME_NS"
+        end
+        "#{type} '#{value}'"
+      when Interval then "INTERVAL '#{Integer(value.months)} months #{Integer(value.days)} days #{Integer(value.microseconds)} microseconds'"
+      when InfiniteTemporal
+        type = (%w[DATE] + TIMESTAMP_TYPES).include?(value.type) ? value.type : raise(ArgumentError, "invalid temporal type")
+        "#{type} '#{value.sign.negative? ? '-' : ''}infinity'"
+      when BitString then "#{literal(value.bits)}::BIT"
+      when Geometry
+        geometry = "ST_GeomFromWKB(#{literal(value.wkb)})"
+        value.crs ? "#{geometry}::GEOMETRY(#{literal(value.crs)})" : geometry
+      when Map
+        expression = "map([#{value.entries.keys.map { |key| literal(key) }.join(', ')}], [#{value.entries.values.map { |item| literal(item) }.join(', ')}])"
+        if value.key_type && value.value_type
+          seed = "map([#{Codec.type_expression(value.key_type)}][0:0], [#{Codec.type_expression(value.value_type)}][0:0])"
+          "cast_to_type(#{expression}, #{seed})"
+        else expression
+        end
+      when Union
+        active = literal(value.value)
+        active = "(#{active})::#{Codec.sql_type(value.members.fetch(value.tag))}" if value.members
+        expression = "union_value(#{identifier(value.tag)} := #{active})"
+        if value.members
+          "#{expression}::UNION(#{value.members.map { |name, type| "#{identifier(name)} #{Codec.sql_type(type)}" }.join(', ')})"
+        else expression
+        end
+      when Tuple then "row(#{value.values.map { |item| literal(item) }.join(', ')})"
+      when Variant then value.to_sql
+      when Array then "[#{value.map { |v| literal(v) }.join(', ')}]"
+      when Hash then "{#{value.map { |key, v| "#{literal(String(key))}: #{literal(v)}" }.join(', ')}}"
+      else raise TypeError, "unsupported Quack parameter type: #{value.class}"
+      end
+    end
+
+    TIMESTAMP_TYPES = %w[TIMESTAMP_S TIMESTAMP_MS TIMESTAMP TIMESTAMP_NS TIMESTAMPTZ TIMESTAMPTZ_NS].freeze
+
+    def timestamp_literal(value, type)
+      raise ArgumentError, "invalid timestamp type" unless TIMESTAMP_TYPES.include?(type)
+      return "#{type} '#{value.sign.negative? ? '-' : ''}infinity'" if value.is_a?(InfiniteTemporal)
+      Codec.pack(value, {"id" => Codec::SQL_NAMES.key(type) || "Timestamp"})
+      utc = value.is_a?(DateTime) ? value.new_offset(0).new_start(Date::GREGORIAN) : value.getutc
+      suffix = type.start_with?("TIMESTAMPTZ") ? "+00" : ""
+      "#{type} '#{utc.strftime('%Y-%m-%d %H:%M:%S.%N')}#{suffix}'"
+    end
+
+    # Parameter substitution is client-side. The lexer preserves UTF-8, quoted
+    # identifiers/strings, dollar strings, and nested comments verbatim.
+    def bind(sql, parameters = nil)
+      return String(sql) if parameters.nil?
+      unless parameters.is_a?(Array) || parameters.is_a?(Hash)
+        raise ArgumentError, "parameters must be an Array or Hash"
+      end
+      named = parameters.is_a?(Hash)
+      parameters = parameters.transform_keys(&:to_s) if named
+      scanner = StringScanner.new(String(sql))
+      output = +""
+      index = 0
+      until scanner.eos?
+        if (token = scanner.scan(/--[^\n]*(?:\n|\z)/))
+          output << token
+        elsif scanner.scan(%r{/\*})
+          output << "/*"
+          depth = 1
+          until scanner.eos? || depth.zero?
+            if scanner.scan(%r{/\*}) then output << "/*"; depth += 1
+            elsif scanner.scan(%r{\*/}) then output << "*/"; depth -= 1
+            else output << scanner.getch
+            end
+          end
+        elsif (start = scanner.scan(/(?:\b[Ee])?'|"/))
+          output << start
+          quote = start[-1]
+          escaped = start.length > 1
+          until scanner.eos?
+            char = scanner.getch
+            output << char
+            if escaped && char == "\\"
+              output << scanner.getch unless scanner.eos?
+            elsif char == quote
+              if scanner.peek(1) == quote then output << scanner.getch
+              else break
+              end
+            end
+          end
+        elsif (delimiter = scanner.scan(/\$(?:[A-Za-z_][A-Za-z_0-9]*)?\$/))
+          output << delimiter
+          output << (scanner.scan_until(/#{Regexp.escape(delimiter)}/) || scanner.rest.tap { scanner.terminate })
+        elsif (cast = scanner.scan(/::/))
+          output << cast
+        elsif named && (placeholder = scanner.scan(/:[A-Za-z_][A-Za-z_0-9]*/))
+          name = placeholder.delete_prefix(":")
+          raise ArgumentError, "missing parameter :#{name}" unless parameters.key?(name)
+          output << literal(parameters.fetch(name))
+        elsif !named && scanner.scan(/\?/)
+          raise ArgumentError, "more placeholders than parameters" if index >= parameters.length
+          output << literal(parameters[index])
+          index += 1
+        else
+          output << scanner.getch
+        end
+      end
+      raise ArgumentError, "#{index} placeholders for #{parameters.length} parameters" if !named && index != parameters.length
+      output
+    end
+  end
+end

data/lib/quack/types.rb

@@ -0,0 +1,40 @@
+module Quack
+  # Time-of-day can represent 24:00:00 and nanoseconds without inventing a date.
+  TimeOfDay = Data.define(:nanoseconds, :utc_offset) do
+    def to_s
+      seconds, fraction = nanoseconds.divmod(1_000_000_000)
+      hours, seconds = seconds.divmod(3600)
+      minutes, seconds = seconds.divmod(60)
+      text = format("%02d:%02d:%02d", hours, minutes, seconds)
+      text += ".#{format('%09d', fraction).sub(/0+\z/, '')}" unless fraction.zero?
+      unless utc_offset.nil?
+        offset = utc_offset.abs
+        text += format("%s%02d:%02d:%02d", utc_offset.negative? ? "-" : "+", offset / 3600, offset / 60 % 60, offset % 60)
+      end
+      text
+    end
+  end
+  Interval = Data.define(:months, :days, :microseconds)
+  InfiniteTemporal = Data.define(:type, :sign)
+
+  def self.__decimal(text) = BigDecimal(text)
+  def self.__date(days)
+    return InfiniteTemporal.new("DATE", days.negative? ? -1 : 1) if [2**31 - 1, -(2**31 - 1)].include?(days)
+    Date.new(1970, 1, 1, Date::GREGORIAN) + days
+  end
+  def self.__time(value, unit) = TimeOfDay.new(unit == "Micros" ? value * 1000 : value, nil)
+  def self.__time_tz(bits)
+    unsigned = bits & ((1 << 64) - 1)
+    # DuckDB packs microseconds into the high 40 bits and a biased UTC offset
+    # (16 hours minus one second minus offset seconds) into the low 24 bits.
+    TimeOfDay.new((unsigned >> 24) * 1000, 57_599 - (unsigned & 0xffffff))
+  end
+  def self.__timestamp(value, unit, timezone_utc)
+    return InfiniteTemporal.new(timezone_utc ? "TIMESTAMPTZ" : "TIMESTAMP", value.negative? ? -1 : 1) if [2**63 - 1, -(2**63 - 1)].include?(value)
+    divisor = {"Seconds" => 1, "Millis" => 1000, "Micros" => 1_000_000, "Nanos" => 1_000_000_000}.fetch(unit)
+    Time.at(Rational(value, divisor)).utc
+  end
+  def self.__interval(months, days, micros) = Interval.new(months, days, micros)
+
+  def self.__pack(value, type) = Codec.pack(value, type)
+end

data/lib/quack/variant.rb

@@ -0,0 +1,298 @@
+module Quack
+  # A logical, typed tree. Node types preserve distinctions such as UBIGINT,
+  # BLOB versus VARCHAR, and timestamp units inside heterogeneous containers.
+  class Variant
+    Node = Data.define(:type, :value)
+    attr_reader :node
+
+    INTEGER_TYPES = {3 => ["TINYINT", 1], 4 => ["SMALLINT", 2], 5 => ["INTEGER", 4], 6 => ["BIGINT", 8], 7 => ["HUGEINT", 16],
+                     8 => ["UTINYINT", 1], 9 => ["USMALLINT", 2], 10 => ["UINTEGER", 4], 11 => ["UBIGINT", 8], 12 => ["UHUGEINT", 16]}.freeze
+    TEMPORAL_TYPES = {20 => ["TIME", "Micros"], 21 => ["TIME_NS", "Nanos"],
+                      22 => ["TIMESTAMP_S", "Seconds"], 23 => ["TIMESTAMP_MS", "Millis"],
+                      24 => ["TIMESTAMP", "Micros"], 25 => ["TIMESTAMP_NS", "Nanos"],
+                      27 => ["TIMESTAMPTZ", "Micros"], 34 => ["TIMESTAMPTZ_NS", "Nanos"]}.freeze
+    STRING_TYPES = {16 => "VARCHAR", 17 => "BLOB", 31 => "BIGNUM", 32 => "BIT", 33 => "GEOMETRY"}.freeze
+
+    def initialize(value, type: nil)
+      @node = value.is_a?(Node) ? value : self.class.make_node(value, type)
+      self.class.validate_node(@node)
+      freeze
+    end
+
+    def type = node.type
+    def value = self.class.unwrap(node)
+    def ==(other) = other.is_a?(Variant) && node == other.node
+    alias eql? ==
+    def hash = [self.class, node].hash
+
+    def self.unwrap(node)
+      case node.type
+      when "OBJECT" then node.value.transform_values { |child| unwrap(child) }
+      when "ARRAY" then node.value.map { |child| unwrap(child) }
+      else node.value
+      end
+    end
+
+    def self.make_node(value, type = nil)
+      return value.node if value.is_a?(Variant)
+      return value if value.is_a?(Node)
+      type ||= case value
+      when nil then "NULL"
+      when true, false then "BOOLEAN"
+      when Integer then (-(2**63)...2**63).cover?(value) ? "BIGINT" : "BIGNUM"
+      when Float then "DOUBLE"
+      when BigDecimal
+        text = value.to_s("F").sub(/\.0\z/, "")
+        integer, fraction = text.delete_prefix("-").split(".")
+        scale = fraction.to_s.length
+        "DECIMAL(#{[integer.sub(/\A0+/, '').length + scale, 1].max},#{scale})"
+      when String then value.encoding == Encoding::BINARY ? "BLOB" : "VARCHAR"
+      when Timestamp then value.duckdb_type
+      when Time, DateTime then "TIMESTAMP_NS"
+      when Date then "DATE"
+      when TimeOfDay then value.utc_offset.nil? ? "TIME_NS" : "TIMETZ"
+      when Interval then "INTERVAL"
+      when InfiniteTemporal then value.type
+      when BitString then "BIT"
+      when Geometry then "GEOMETRY"
+      when Array, Tuple then "ARRAY"
+      when Hash then "OBJECT"
+      else raise TypeError, "unsupported VARIANT value #{value.class}"
+      end
+      type = String(type).upcase.freeze
+      children = case type
+      when "ARRAY" then (value.is_a?(Tuple) ? value.values : value).map { |child| make_node(child) }.freeze
+      when "OBJECT" then value.to_h.to_h { |key, child| [String(key).freeze, make_node(child)] }.freeze
+      else value
+      end
+      Node.new(type, children)
+    end
+
+    def self.validate_node(node, depth = 0)
+      raise ArgumentError, "VARIANT nesting exceeds 256 levels" if depth > 256
+      type = node.type
+      # Node is public; validate its names even when constructed directly.
+      valid = ["NULL", "BOOLEAN", "FLOAT", "DOUBLE", "UUID", "DATE", "TIMETZ", "INTERVAL", "OBJECT", "ARRAY"] + INTEGER_TYPES.values.map(&:first) + TEMPORAL_TYPES.values.map(&:first) + STRING_TYPES.values
+      unless valid.include?(type) || type.match?(/\ADECIMAL\((?:[1-9]|[12][0-9]|3[0-8]),(?:[0-9]|[12][0-9]|3[0-8])\)\z/)
+        raise ArgumentError, "unsupported VARIANT type #{type}"
+      end
+      case type
+      when "ARRAY" then node.value.each { |child| validate_node(child, depth + 1) }
+      when "OBJECT" then node.value.each_value { |child| validate_node(child, depth + 1) }
+      when "BOOLEAN"
+        raise TypeError, "VARIANT BOOLEAN must be true or false" unless node.value == true || node.value == false
+      end
+    end
+
+    class Reader
+      def initialize(data, offset)
+        @data, @offset = data, Integer(offset)
+        raise ProtocolError, "invalid VARIANT byte offset" unless (0..data.bytesize).cover?(@offset)
+      end
+      def bytes(count)
+        raise ProtocolError, "truncated VARIANT payload" if count.negative? || @offset + count > @data.bytesize
+        result = @data.byteslice(@offset, count)
+        @offset += count
+        result
+      end
+      def uint(count) = bytes(count).bytes.reverse.reduce(0) { |value, byte| (value << 8) | byte }
+      def int(count)
+        value = uint(count)
+        value >= 2**(count * 8 - 1) ? value - 2**(count * 8) : value
+      end
+      def varint
+        result = 0
+        5.times do |index|
+          byte = uint(1)
+          result |= (byte & 127) << (index * 7)
+          return result if byte < 128 && result < 2**32
+        end
+        raise ProtocolError, "invalid VARIANT varint"
+      end
+    end
+
+    def self.from_physical(physical)
+      decode_node = lambda do |index, ancestors|
+        raise ProtocolError, "cyclic or excessively nested VARIANT" if ancestors.include?(index) || ancestors.length > 256
+        item = physical.fetch("values").fetch(index)
+        id = item.fetch("type_id")
+        reader = Reader.new(physical.fetch("data"), item.fetch("byte_offset"))
+        type, value = if INTEGER_TYPES.key?(id)
+          name, size = INTEGER_TYPES.fetch(id)
+          [name, name.start_with?("U") ? reader.uint(size) : reader.int(size)]
+        elsif TEMPORAL_TYPES.key?(id)
+          name, unit = TEMPORAL_TYPES.fetch(id)
+          raw = reader.int(8)
+          converted = if name.start_with?("TIME") && !name.start_with?("TIMESTAMP") && !name.start_with?("TIMESTAMPTZ")
+            Quack.__time(raw, unit)
+          else
+            timestamp = Quack.__timestamp(raw, unit, name.start_with?("TIMESTAMPTZ"))
+            timestamp.is_a?(InfiniteTemporal) ? timestamp : Timestamp.from(timestamp, name)
+          end
+          [name, converted]
+        elsif STRING_TYPES.key?(id)
+          name = STRING_TYPES.fetch(id)
+          data = reader.bytes(reader.varint)
+          converted = case name
+          when "VARCHAR"
+            text = data.dup.force_encoding(Encoding::UTF_8)
+            raise ProtocolError, "invalid VARIANT UTF-8" unless text.valid_encoding?
+            text
+          when "BIGNUM" then Codec.decode_bignum(data)
+          when "BIT" then Codec.decode_bit(data)
+          when "GEOMETRY" then Geometry.new(data)
+          else data.b
+          end
+          [name, converted]
+        else
+          case id
+          when 0 then ["NULL", nil]
+          when 1, 2 then ["BOOLEAN", id == 1]
+          when 13 then ["FLOAT", reader.bytes(4).unpack1("e")]
+          when 14 then ["DOUBLE", reader.bytes(8).unpack1("E")]
+          when 15
+            width, scale = reader.varint, reader.varint
+            raise ProtocolError, "invalid VARIANT decimal metadata" unless (1..38).cover?(width) && scale <= width
+            size = width <= 4 ? 2 : width <= 9 ? 4 : width <= 18 ? 8 : 16
+            integer = reader.int(size)
+            digits = integer.abs.to_s.rjust(scale + 1, "0")
+            text = scale.zero? ? digits : "#{digits[0...-scale]}.#{digits[-scale..]}"
+            ["DECIMAL(#{width},#{scale})", BigDecimal(integer.negative? ? "-#{text}" : text)]
+          when 18
+            hex = (reader.uint(16) ^ (1 << 127)).to_s(16).rjust(32, "0")
+            ["UUID", [hex[0, 8], hex[8, 4], hex[12, 4], hex[16, 4], hex[20, 12]].join("-")]
+          when 19 then ["DATE", Quack.__date(reader.int(4))]
+          when 26 then ["TIMETZ", Quack.__time_tz(reader.int(8))]
+          when 28 then ["INTERVAL", Interval.new(reader.int(4), reader.int(4), reader.int(8))]
+          when 29, 30
+            count = reader.varint
+            first = count.zero? ? 0 : reader.varint
+            children = physical.fetch("children")
+            raise ProtocolError, "invalid VARIANT child range" if first + count > children.length
+            items = children.slice(first, count).map do |child|
+              node = decode_node.call(child.fetch("values_index"), ancestors + [index])
+              id == 29 ? [physical.fetch("keys").fetch(child.fetch("keys_index")), node] : node
+            end
+            [id == 29 ? "OBJECT" : "ARRAY", id == 29 ? items.to_h.freeze : items.freeze]
+          else raise UnsupportedTypeError, "unsupported VARIANT logical type #{id}"
+          end
+        end
+        Node.new(type, value)
+      end
+      node = decode_node.call(0, [])
+      node.type == "NULL" ? nil : new(node)
+    rescue KeyError, IndexError, TypeError => error
+      raise ProtocolError, "invalid VARIANT structure: #{error.message}"
+    end
+
+    def to_sql
+      self.class.validate_node(node)
+      self.class.node_sql(node)
+    end
+
+    def self.node_sql(node)
+      case node.type
+      when "NULL" then "('null'::JSON)::VARIANT"
+      when "ARRAY" then "[#{node.value.map { |child| node_sql(child) }.join(', ')}]::VARIANT"
+      when "OBJECT"
+        return "('{}'::JSON)::VARIANT" if node.value.empty?
+        "{#{node.value.map { |key, child| "#{SQL.literal(key)}: #{node_sql(child)}" }.join(', ')}}::VARIANT"
+      else
+        literal = node.type.start_with?("TIMESTAMP") || node.type.start_with?("TIMESTAMPTZ") ? SQL.timestamp_literal(node.value, node.type) : SQL.literal(node.value)
+        "((#{literal})::#{node.type})::VARIANT"
+      end
+    end
+
+    def self.varint(value)
+      raise RangeError, "VARIANT length out of range" unless (0...2**32).cover?(value)
+      bytes = []
+      loop do
+        byte = value & 127
+        value >>= 7
+        bytes << (value.zero? ? byte : byte | 128)
+        break if value.zero?
+      end
+      bytes.pack("C*")
+    end
+
+    def self.integer_bytes(value, size, signed: true)
+      range = signed ? (-(2**(size * 8 - 1))...2**(size * 8 - 1)) : (0...2**(size * 8))
+      raise RangeError, "VARIANT integer out of range" unless value.is_a?(Integer) && range.cover?(value)
+      Array.new(size) { |index| (value >> (index * 8)) & 255 }.pack("C*")
+    end
+
+    def to_physical
+      keys = []
+      visit_keys = lambda do |node|
+        case node.type
+        when "OBJECT"
+          keys.concat(node.value.keys)
+          node.value.each_value { |child| visit_keys.call(child) }
+        when "ARRAY" then node.value.each { |child| visit_keys.call(child) }
+        end
+      end
+      visit_keys.call(node)
+      keys = keys.uniq.sort
+      key_indices = keys.each_with_index.to_h
+      physical = {"keys" => keys, "children" => [], "values" => [], "data" => +"".b}
+      encode = lambda do |node|
+        index = physical.fetch("values").length
+        physical.fetch("values") << nil
+        type, value = node.type, node.value
+        id, bytes = if (entry = INTEGER_TYPES.find { |_id, (name, _size)| name == type })
+          [entry.first, self.class.integer_bytes(value, entry.last.last, signed: !type.start_with?("U"))]
+        elsif (entry = TEMPORAL_TYPES.find { |_id, (name, _unit)| name == type })
+          spec = {"id" => Codec::SQL_NAMES.key(type) || type.capitalize}
+          spec["id"] = "Timestamp" if type == "TIMESTAMP"
+          packed = Codec.pack(value, spec)
+          [entry.first, self.class.integer_bytes(packed[1], 8)]
+        elsif (entry = STRING_TYPES.find { |_id, name| name == type })
+          payload = case type
+          when "BIGNUM" then Codec.encode_bignum(value)
+          when "BIT" then Codec.encode_bit(value)
+          when "GEOMETRY" then value.wkb
+          else String(value).b
+          end
+          [entry.first, self.class.varint(payload.bytesize) + payload]
+        else
+          case type
+          when "NULL" then [0, "".b]
+          when "BOOLEAN" then [value ? 1 : 2, "".b]
+          when "FLOAT" then [13, [value].pack("e")]
+          when "DOUBLE" then [14, [value].pack("E")]
+          when /\ADECIMAL\((\d+),(\d+)\)\z/
+            width, scale = Regexp.last_match.captures.map(&:to_i)
+            packed = Codec.pack(value, {"id" => "Decimal", "width" => width, "scale" => scale})
+            integer = (BigDecimal(packed[1]) * 10**scale).to_i
+            size = width <= 4 ? 2 : width <= 9 ? 4 : width <= 18 ? 8 : 16
+            [15, self.class.varint(width) + self.class.varint(scale) + self.class.integer_bytes(integer, size)]
+          when "UUID"
+            hex = String(value).delete("-")
+            raise ArgumentError, "invalid VARIANT UUID" unless hex.match?(/\A[0-9a-fA-F]{32}\z/)
+            [18, self.class.integer_bytes(hex.to_i(16) ^ (1 << 127), 16, signed: false)]
+          when "DATE"
+            [19, self.class.integer_bytes(Codec.pack(value, {"id" => "Date"})[1], 4)]
+          when "TIMETZ"
+            [26, self.class.integer_bytes(Codec.pack(value, {"id" => "TimeTz"})[1], 8)]
+          when "INTERVAL"
+            [28, self.class.integer_bytes(value.months, 4) + self.class.integer_bytes(value.days, 4) + self.class.integer_bytes(value.microseconds, 8)]
+          when "OBJECT", "ARRAY"
+            children = type == "OBJECT" ? value.to_a : value.map { |child| [nil, child] }
+            first = physical.fetch("children").length
+            physical.fetch("children").concat(Array.new(children.length))
+            children.each_with_index do |(key, child), offset|
+              physical.fetch("children")[first + offset] = {"keys_index" => key && key_indices.fetch(key), "values_index" => encode.call(child)}
+            end
+            [type == "OBJECT" ? 29 : 30, self.class.varint(children.length) + (children.empty? ? "".b : self.class.varint(first))]
+          else raise ArgumentError, "unsupported VARIANT type #{type}"
+          end
+        end
+        physical.fetch("values")[index] = {"type_id" => id, "byte_offset" => physical.fetch("data").bytesize}
+        physical.fetch("data") << bytes
+        index
+      end
+      encode.call(node)
+      physical
+    end
+  end
+end