quack-ruby 0.1.0

data/lib/quack/codec.rb

@@ -0,0 +1,263 @@
+module Quack
+  # DuckDB's logical metadata drives both directions, including nested values.
+  module Codec
+    module_function
+
+    SQL_NAMES = {
+      "TimestampSec" => "TIMESTAMP_S", "TimestampMs" => "TIMESTAMP_MS",
+      "TimestampNs" => "TIMESTAMP_NS", "TimestampTz" => "TIMESTAMPTZ",
+      "TimestampTzNs" => "TIMESTAMPTZ_NS", "TimeNs" => "TIME_NS",
+      "TimeTz" => "TIMETZ", "SqlNull" => "INTEGER"
+    }.freeze
+    INTEGER_BITS = {"TinyInt" => 8, "SmallInt" => 16, "Integer" => 32, "BigInt" => 64, "HugeInt" => 128,
+                    "UTinyInt" => 8, "USmallInt" => 16, "UInteger" => 32, "UBigInt" => 64, "UHugeInt" => 128}.freeze
+
+    def copy(value)
+      case value
+      when Array then value.map { |item| copy(item) }
+      when Hash then value.to_h { |key, item| [copy(key), copy(item)] }
+      when Map then Map.new(copy(value.entries), value.key_type, value.value_type)
+      when Union then Union.new(value.tag, copy(value.value), value.members)
+      when Tuple then Tuple.new(copy(value.values))
+      when Variant then Variant.new(copy(value.node))
+      when Variant::Node then Variant::Node.new(value.type.dup, copy(value.value))
+      when String, Time then value.dup
+      else value
+      end
+    end
+
+    def sql_type(type)
+      id = type.fetch("id")
+      return "JSON" if type["alias"]&.casecmp?("JSON")
+      case id
+      when "Decimal" then "DECIMAL(#{type.fetch('width')},#{type.fetch('scale')})"
+      when "List" then "#{sql_type(type.fetch('child'))}[]"
+      when "Array" then "#{sql_type(type.fetch('child'))}[#{type.fetch('size')}]"
+      when "Map"
+        children = type.fetch("child").fetch("children")
+        "MAP(#{children.map { |child| sql_type(child.fetch('type')) }.join(', ')})"
+      when "Struct", "Tuple", "Union"
+        children = type.fetch("children")
+        children = children.drop(1) if id == "Union"
+        fields = children.map do |child|
+          name = child.fetch("name")
+          "#{name.empty? ? '' : SQL.identifier(name) + ' '}#{sql_type(child.fetch('type'))}"
+        end
+        "#{id.upcase}(#{fields.join(', ')})"
+      when "Enum" then "ENUM (#{type.fetch('values').map { |value| SQL.literal(value) }.join(', ')})"
+      when "Geometry"
+        type["crs"] ? "GEOMETRY(#{SQL.literal(type.fetch('crs'))})" : "GEOMETRY"
+      else SQL_NAMES.fetch(id, id.upcase)
+      end
+    end
+
+    # cast_to_type binds its second argument's type without evaluating it. A
+    # typed expression also represents query-only unnamed v1 STRUCTs, whose
+    # typeof() spelling cannot be parsed as an explicit SQL type declaration.
+    def type_expression(type)
+      case type.fetch("id")
+      when "Struct", "Tuple"
+        children = type.fetch("children")
+        if type.fetch("id") == "Tuple" || children.all? { |child| child.fetch("name").empty? }
+          "row(#{children.map { |child| type_expression(child.fetch('type')) }.join(', ')})"
+        else
+          "{#{children.map { |child| "#{SQL.literal(child.fetch('name'))}: #{type_expression(child.fetch('type'))}" }.join(', ')}}"
+        end
+      when "List" then "[#{type_expression(type.fetch('child'))}]"
+      when "Array" then "array_value(#{Array.new(type.fetch('size'), type_expression(type.fetch('child'))).join(', ')})"
+      when "Map"
+        key_type, value_type = type.fetch("child").fetch("children").map { |child| child.fetch("type") }
+        "map([#{type_expression(key_type)}][0:0], [#{type_expression(value_type)}][0:0])"
+      else "NULL::#{sql_type(type)}"
+      end
+    end
+
+    def decode(value, type)
+      return nil if value.nil?
+      id = type.fetch("id")
+      case id
+      when "BigNum" then decode_bignum(value)
+      when "Bit" then decode_bit(value)
+      when "Geometry" then Geometry.new(value, type["crs"])
+      when "List", "Array" then value.map { |item| decode(item, type.fetch("child")) }
+      when "Map"
+        fields = type.fetch("child").fetch("children")
+        Map.new(value.to_h { |pair| [decode(pair.fetch('key'), fields[0].fetch('type')), decode(pair.fetch('value'), fields[1].fetch('type'))] }, fields[0].fetch("type"), fields[1].fetch("type"))
+      when "Union"
+        members = type.fetch("children").drop(1).to_h { |child| [child.fetch("name"), child.fetch("type")] }
+        tag = members.keys.fetch(value.fetch(""))
+        Union.new(tag, decode(value.fetch(tag), members.fetch(tag)), members)
+      when "Variant" then Variant.from_physical(value)
+      when "Struct", "Tuple"
+        children = type.fetch("children")
+        if id == "Tuple" || children.all? { |child| child.fetch("name").empty? }
+          Tuple.new(children.each_with_index.map { |child, index| decode(value.fetch(index.to_s), child.fetch("type")) })
+        else
+          children.to_h { |child| [child.fetch("name"), decode(value.fetch(child.fetch("name")), child.fetch("type"))] }
+        end
+      when /\ATimestamp/
+        value.is_a?(InfiniteTemporal) ? InfiniteTemporal.new(sql_type(type), value.sign) : Timestamp.from(value, sql_type(type))
+      else value
+      end
+    end
+
+    def pack(value, type)
+      return ["null"] if value.nil?
+      id = type.fetch("id")
+      if type["alias"]&.casecmp?("JSON")
+        text = value.is_a?(String) ? value : JSON.generate(value)
+        JSON.parse(text) # Validate without changing whitespace or numeric text.
+        return ["string", text]
+      end
+      if INTEGER_BITS.key?(id)
+        raise TypeError, "#{id} append value must be an Integer" unless value.is_a?(Integer)
+        bits = INTEGER_BITS.fetch(id)
+        unsigned = id.start_with?("U")
+        range = unsigned ? (0...2**bits) : (-(2**(bits - 1))...2**(bits - 1))
+        raise RangeError, "#{value} is out of range for #{id}" unless range.cover?(value)
+        return ["int", value.to_s]
+      end
+      case id
+      when "BigNum" then ["bytes", encode_bignum(value)]
+      when "Bit" then ["bytes", encode_bit(value)]
+      when "Geometry"
+        raise TypeError, "GEOMETRY append value must be a Quack::Geometry" unless value.is_a?(Geometry)
+        ["bytes", value.wkb]
+      when "Decimal"
+        number = BigDecimal(value.to_s)
+        raise ArgumentError, "non-finite decimal append value" unless number.finite?
+        scale = type.fetch("scale")
+        scaled = number * 10**scale
+        raise RangeError, "decimal exceeds destination scale" unless scaled.frac.zero?
+        raise RangeError, "decimal exceeds destination precision" unless scaled.abs < 10**type.fetch("width")
+        ["decimal", number.to_s("F"), type.fetch("width"), scale]
+      when "Time", "TimeNs", "TimeTz"
+        raise TypeError, "#{id} append value must be a Quack::TimeOfDay" unless value.is_a?(TimeOfDay)
+        raise RangeError, "time of day out of range" unless (0..86_400_000_000_000).cover?(value.nanoseconds)
+        if id == "TimeTz"
+          raise ArgumentError, "TIMETZ needs a UTC offset" if value.utc_offset.nil?
+          raise RangeError, "TIMETZ offset out of range" unless (-57_599..57_599).cover?(value.utc_offset)
+          require_microseconds(value.nanoseconds)
+          bits = (value.nanoseconds / 1000 << 24) | (57_599 - value.utc_offset)
+          ["timetz", bits >= 2**63 ? bits - 2**64 : bits]
+        else
+          raise ArgumentError, "timezone offset requires a TIMETZ column" unless value.utc_offset.nil?
+          require_microseconds(value.nanoseconds) if id == "Time"
+          ["time", id == "Time" ? value.nanoseconds / 1000 : value.nanoseconds, id == "Time" ? "Micros" : "Nanos"]
+        end
+      when /\ATimestamp/
+        units = {"TimestampSec" => [1, "Seconds"], "TimestampMs" => [1000, "Millis"], "TimestampNs" => [1_000_000_000, "Nanos"], "TimestampTzNs" => [1_000_000_000, "Nanos"]}
+        divisor, unit = units.fetch(id, [1_000_000, "Micros"])
+        count = if value.is_a?(InfiniteTemporal)
+          value.sign.negative? ? -(2**63 - 1) : 2**63 - 1
+        else
+          seconds = value.is_a?(DateTime) ? (value.new_offset(0) - DateTime.new(1970, 1, 1)) * 86_400 : value.to_r
+          scaled = seconds * divisor
+          raise RangeError, "timestamp exceeds destination precision" unless scaled.denominator == 1
+          raise RangeError, "timestamp out of range" unless (-(2**63 - 2)..2**63 - 2).cover?(scaled)
+          scaled.to_i
+        end
+        ["timestamp", count, unit, %w[TimestampTz TimestampTzNs].include?(id)]
+      when "Date"
+        days = value.is_a?(InfiniteTemporal) ? value.sign * (2**31 - 1) : (Date.iso8601(value.iso8601, Date::GREGORIAN) - Date.new(1970, 1, 1, Date::GREGORIAN)).to_i
+        raise RangeError, "date out of range" unless (-(2**31 - 1)..2**31 - 1).cover?(days)
+        ["date", days]
+      when "List", "Array"
+        raise TypeError, "#{id} append value must be an Array" unless value.is_a?(Array)
+        raise ArgumentError, "fixed array length mismatch" if id == "Array" && value.length != type.fetch("size")
+        ["list", value.map { |item| pack(item, type.fetch("child")) }]
+      when "Map"
+        entries = value.is_a?(Map) ? value.entries : value
+        raise TypeError, "MAP append value must be a Quack::Map or Hash" unless entries.is_a?(Hash)
+        raise ArgumentError, "MAP keys cannot be NULL" if entries.key?(nil)
+        fields = type.fetch("child").fetch("children")
+        ["list", entries.map { |key, item| ["struct", {"key" => pack(key, fields[0].fetch("type")), "value" => pack(item, fields[1].fetch("type"))}] }]
+      when "Union"
+        raise TypeError, "UNION append value must be a Quack::Union" unless value.is_a?(Union)
+        children = type.fetch("children").drop(1)
+        index = children.index { |child| child.fetch("name") == value.tag }
+        raise ArgumentError, "unknown UNION member #{value.tag}" unless index
+        fields = {"" => ["int", index.to_s]}
+        children.each { |child| fields[child.fetch("name")] = child.fetch("name") == value.tag ? pack(value.value, child.fetch("type")) : ["null"] }
+        ["struct", fields]
+      when "Variant"
+        variant = value.is_a?(Variant) ? value : Variant.new(value)
+        pack(variant.to_physical, {"id" => "Struct", "children" => type.fetch("children")})
+      when "Struct", "Tuple"
+        children = type.fetch("children")
+        unnamed = id == "Tuple" || children.all? { |child| child.fetch("name").empty? }
+        if unnamed
+          values = value.is_a?(Tuple) ? value.values : value
+          raise ArgumentError, "tuple length mismatch" unless values.is_a?(Array) && values.length == children.length
+          ["struct", children.each_with_index.to_h { |child, index| [index.to_s, pack(values[index], child.fetch("type"))] }]
+        else
+          raise TypeError, "STRUCT append value must be a Hash" unless value.is_a?(Hash)
+          fields = value.transform_keys(&:to_s)
+          raise ArgumentError, "STRUCT field names mismatch" unless fields.keys.sort == children.map { |child| child.fetch("name") }.sort
+          ["struct", children.to_h { |child| [child.fetch("name"), pack(fields.fetch(child.fetch("name")), child.fetch("type"))] }]
+        end
+      when "Boolean"
+        raise TypeError, "BOOLEAN append value must be true or false" unless value == true || value == false
+        ["bool", value]
+      when "Float", "Double"
+        number = Float(value)
+        raise RangeError, "value exceeds #{id} range" if number.infinite? && value.respond_to?(:finite?) && value.finite?
+        raise RangeError, "value exceeds FLOAT range" if id == "Float" && number.finite? && number.abs > 3.4028234663852886e38
+        ["double", number]
+      when "Enum"
+        raise ArgumentError, "unknown ENUM value" unless type.fetch("values").include?(value)
+        ["string", value]
+      when "Varchar", "Char", "Uuid"
+        raise TypeError, "#{id} append value must be a String" unless value.is_a?(String)
+        text = value.encode(Encoding::UTF_8)
+        raise EncodingError, "invalid UTF-8 text" unless text.valid_encoding?
+        ["string", text]
+      when "Blob"
+        raise TypeError, "BLOB append value must be a String" unless value.is_a?(String)
+        ["bytes", value.b]
+      when "Interval"
+        raise TypeError, "INTERVAL append value must be a Quack::Interval" unless value.is_a?(Interval)
+        ["interval", value.months, value.days, value.microseconds]
+      else raise UnsupportedTypeError, "unsupported append logical type #{id}"
+      end
+    end
+
+    def require_microseconds(nanoseconds)
+      raise RangeError, "value exceeds microsecond precision" unless (nanoseconds % 1000).zero?
+    end
+
+    def decode_bignum(bytes)
+      # DuckDB stores a three-byte length header and big-endian magnitude;
+      # negative values complement every byte, including the header.
+      bytes = bytes.bytes
+      raise ProtocolError, "invalid BIGNUM payload" if bytes.length < 4
+      negative = bytes[0] < 128
+      bytes.map! { |byte| byte ^ 255 } if negative
+      length = ((bytes[0] & 127) << 16) | (bytes[1] << 8) | bytes[2]
+      raise ProtocolError, "invalid BIGNUM length" unless length == bytes.length - 3
+      magnitude = bytes.drop(3).pack("C*").unpack1("H*").to_i(16)
+      negative ? -magnitude : magnitude
+    end
+
+    def encode_bignum(value)
+      raise TypeError, "BIGNUM append value must be an Integer" unless value.is_a?(Integer)
+      hex = value.abs.to_s(16)
+      bytes = [hex.length.odd? ? "0#{hex}" : hex].pack("H*")
+      raise RangeError, "BIGNUM payload exceeds 23-bit length" if bytes.bytesize >= 2**23
+      bytes = [bytes.bytesize | 0x800000].pack("N").byteslice(1, 3) + bytes
+      value.negative? ? bytes.bytes.map { |byte| byte ^ 255 }.pack("C*") : bytes
+    end
+
+    def decode_bit(bytes)
+      padding = bytes.getbyte(0)
+      raise ProtocolError, "invalid BIT payload" unless padding && padding < 8 && bytes.bytesize > 1
+      BitString.new(bytes.byteslice(1..).unpack1("B*").byteslice(padding..))
+    end
+
+    def encode_bit(value)
+      value = BitString.new(value) unless value.is_a?(BitString)
+      padding = (8 - value.bits.length % 8) % 8
+      [padding].pack("C") + ["1" * padding + value.bits].pack("B*")
+    end
+  end
+end

data/lib/quack/connection.rb

@@ -0,0 +1,131 @@
+module Quack
+  class Connection
+    OPTIONS = %w[auth_token ssl ssl_fingerprint timeout heartbeat_timeout headers client_id client_platform client_duckdb_version min_supported_quack_version max_supported_quack_version].freeze
+
+    def initialize(uri, **options)
+      @uri = String(uri).dup.freeze
+      @options = options.transform_keys(&:to_s)
+      unknown = @options.keys - OPTIONS
+      raise ArgumentError, "unknown connection options: #{unknown.join(', ')}" unless unknown.empty?
+      @options = @options.reject { |_key, value| value.nil? }
+      open_native
+      @pid = Process.pid
+      @in_transaction = false
+    end
+    def inspect = "#<#{self.class} connected=#{connected?}>"
+    def info = @native.info
+    def connected? = @native.connected?
+    def stream(sql, parameters = nil)
+      result = Stream.new(@native.query(SQL.bind(sql, parameters)))
+      return result unless block_given?
+      begin
+        yield result
+      ensure
+        result.close
+      end
+    end
+    def query(sql, parameters = nil) = stream(sql, parameters) { |result| result.to_result }
+    def execute(sql, parameters = nil) = query(sql, parameters).affected_rows
+    def first(sql, parameters = nil) = query(sql, parameters).first
+    def one(sql, parameters = nil)
+      result = query(sql, parameters)
+      raise Error, "expected one row, got #{result.rows.length}" unless result.rows.length == 1
+      result.first
+    end
+    def values(sql, parameters = nil) = query(sql, parameters).rows.map(&:first)
+    def prepare(sql) = Statement.new(self, String(sql).dup.freeze)
+    def append_rows(table, rows, schema: nil, columns: nil, batch_size: 1024)
+      raise ArgumentError, "batch_size must be a positive Integer" unless batch_size.is_a?(Integer) && batch_size.positive?
+      unless info.fetch("quack_version") == 1
+        raise UnsupportedTypeError, "Quack v3 SEND_DATA is not implemented by quack_protocol; use SQL INSERT or insert_all"
+      end
+      return nil if rows.empty?
+      table_parts = SQL.identifier_parts(table)
+      raise UnsupportedTypeError, "v1 append uses the current catalog; select it with USE before appending" if table_parts.length == 3
+      if table_parts.length == 2 && schema && String(schema) != table_parts[0]
+        raise ArgumentError, "conflicting append schema names"
+      end
+      table_parts.unshift(String(schema)) if schema && table_parts.length == 1
+      target = table_parts.map { |part| SQL.identifier(part) }.join(".")
+      destination_sql = "select * from #{target} where false"
+      destination = query(destination_sql).column_metadata
+      schema_sql = if columns
+        definitions = columns.transform_keys(&:to_s)
+        unless definitions.keys.sort == destination.map { |column| column.fetch("name") }.sort
+          raise ArgumentError, "explicit append types must name every destination column"
+        end
+        "select #{destination.map { |column| name = column.fetch('name'); "NULL::#{definitions.fetch(name)} AS #{SQL.identifier(name)}" }.join(', ')} where false"
+      else
+        destination_sql
+      end
+      metadata = columns ? query(schema_sql).column_metadata : destination
+      expected = metadata.map { |column| column.fetch("name") }.sort
+      packed = rows.map do |row|
+        raise ArgumentError, "each row must be a Hash" unless row.is_a?(Hash)
+        values = row.transform_keys(&:to_s)
+        raise ArgumentError, "append rows must have the destination column names: #{expected.join(', ')}" unless values.keys.sort == expected
+        metadata.to_h { |column| [column.fetch("name"), Quack.__pack(values.fetch(column.fetch("name")), column.fetch("duckdb_type"))] }
+      end
+      @native.append_rows(table_parts.last, table_parts.length == 2 ? table_parts.first : nil, packed, schema_sql, batch_size)
+      nil
+    end
+    def close = @native.close
+    alias disconnect close
+    def reconnect
+      close if @pid == Process.pid && connected?
+      open_native
+      @pid = Process.pid
+      @in_transaction = false
+      self
+    end
+    def transaction
+      raise Error, "nested transactions/savepoints are not supported" if @in_transaction
+      execute("BEGIN TRANSACTION")
+      @in_transaction = true
+      committed = false
+      begin
+        value = yield self
+        execute("COMMIT")
+        committed = true
+        value
+      ensure
+        unless committed
+          begin
+            execute("ROLLBACK") if connected?
+          rescue Error
+            # Preserve the original failure; a transport failure never authorizes replay.
+          end
+        end
+        @in_transaction = false
+      end
+    end
+
+    private
+
+    def open_native
+      @native = NativeConnection.new(@uri, @options)
+      begin
+        # Ruby timestamps are UTC values. Make implicit timestamp/TZ casts
+        # consistent with Rails and independent of the server host timezone.
+        @native.query("SET TimeZone = 'UTC'").close
+      rescue Exception
+        begin
+          @native.close
+        rescue Error
+          # Preserve the configuration failure rather than a cleanup failure.
+        end
+        raise
+      end
+    end
+  end
+
+  # Reusable client-side SQL template; Quack's prepare request carries SQL text.
+  class Statement
+    def initialize(connection, sql)
+      @connection, @sql = connection, sql
+    end
+    def query(parameters = nil) = @connection.query(@sql, parameters)
+    def execute(parameters = nil) = @connection.execute(@sql, parameters)
+    def stream(parameters = nil, &block) = @connection.stream(@sql, parameters, &block)
+  end
+end

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