quack-ruby 0.1.0-aarch64-linux-gnu

data/README.md

@@ -0,0 +1,229 @@
+# quack-ruby
+
+A direct Ruby client for DuckDB's Quack remote protocol. It uses Magnus and a
+packaged, patched [quack_protocol 0.4.1](https://github.com/bnjjj/quack_protocol_rs)
+over HTTP(S). The client does not embed DuckDB or use ADBC.
+
+Supports DuckDB 1.5.5 / protocol v1 and DuckDB 2.0.0 / protocol v3. For Rails,
+use [activerecord-quack-adapter](https://github.com/sidequery/activerecord-quack-adapter).
+
+## Install
+
+Add to your Gemfile:
+
+```ruby
+gem "quack-ruby", "~> 0.1.0"
+```
+
+Precompiled gems cover Ruby 3.2, 3.3 and 3.4 on macOS (Apple Silicon and Intel)
+and Linux glibc (ARM64 and x86-64). Bundler selects the matching platform gem;
+the Quack extension installs without running Cargo or a compiler. The package
+is named `quack-ruby`; its Ruby entry point remains `require "quack"`.
+
+Linux binaries target glibc, not Alpine/musl. A source gem is also available
+for other platforms and Ruby versions. Building that extension requires Rust,
+a C toolchain, Ruby development headers and libclang. Installing directly from
+Git also builds from source. To select the source package explicitly, use
+`gem install quack-ruby --platform ruby`.
+
+For a checkout:
+
+```sh
+bundle install
+CARGO="$PWD/script/cached-cargo" bundle exec rake compile
+```
+
+A Quack server must already be running. Provision databases on that server.
+The client initializes its session timezone to UTC, also after reconnect.
+
+## Usage
+
+```ruby
+require "quack"
+
+Quack.connect(ENV.fetch("QUACK_URI"), auth_token: ENV.fetch("QUACK_TOKEN"), timeout: 30) do |connection|
+  result = connection.query("select 42 as answer")
+end
+```
+
+For a parameterized query, choose positional or named parameters:
+
+```ruby
+connection = Quack.connect(ENV.fetch("QUACK_URI"), auth_token: ENV.fetch("QUACK_TOKEN"))
+begin
+  result = connection.query("select ?::bigint as answer", [42])
+  result.columns # => ["answer"]
+  result.rows    # => [[42]]
+  result.to_a    # => [{"answer" => 42}]
+
+  connection.first("select :answer::bigint as answer", answer: 42)
+  connection.one("select 42 as answer") # Requires exactly one row.
+  connection.values("select 42")      # => [42]
+  connection.execute("create temp table scratch (id integer)")
+
+  connection.stream("select i from range(1000000) t(i)") do |stream|
+    stream.each { |row| puts row.fetch("i") }
+    # each_row yields arrays; each_batch yields arrays of row arrays.
+  end
+
+  statement = connection.prepare("select ?::bigint as answer")
+  statement.query([42])
+  connection.transaction { |c| c.execute("insert into scratch values (?)", [1]) }
+  connection.info # Negotiated protocol version and server metadata.
+ensure
+  connection.close
+end
+```
+
+Parameters/templates use client-side SQL substitution, not server-side bind
+messages or a server statement cache. Quoting supports Unicode, binary strings,
+NUL text, exact decimals/integers, temporal values, lists and structs. The lexer
+preserves SQL strings, quoted identifiers, escaped strings, dollar-quoted
+strings and nested comments. Identifiers must be quoted separately with
+`Quack::SQL.identifier`.
+
+`query` materializes all rows. `stream` fetches chunks on demand; block iteration
+closes results even on early exit or exceptions. When keeping an unconsumed
+stream, close it explicitly. A session permits one active result; an overlapping
+operation raises `Quack::BusyError` rather than waiting indefinitely. Use a
+connection per concurrent worker or an ordinary Ruby connection pool.
+Duplicate result column names are preserved in `rows`; hash enumeration keeps
+the last value for a repeated name.
+
+Result conversions:
+
+| DuckDB value | Ruby value |
+| --- | --- |
+| Signed/unsigned integers, including 128-bit and BIGNUM | `Integer`, without precision loss |
+| Decimal | `BigDecimal` |
+| Boolean, floating point, text, NULL | `true`/`false`, `Float`, `String`, `nil` |
+| BLOB / other byte payloads | Binary-encoded `String` |
+| Date | Proleptic Gregorian `Date` |
+| Timestamp | `Quack::Timestamp < Time`, retaining SQL units, timezone kind and nanoseconds |
+| Time / time with offset | `Quack::TimeOfDay` (supports `24:00:00`) |
+| Interval | `Quack::Interval(months, days, microseconds)` |
+| Infinite date/timestamp | `Quack::InfiniteTemporal` |
+| List/array, struct | `Array`, string-keyed `Hash` |
+| JSON, UUID, ENUM | `String` (Rails casts JSON to Ruby objects) |
+| MAP | `Quack::Map`, with `entries`, `[]`, `each`, `to_h` |
+| BIT | `Quack::BitString(bits)`, a string of logical 0/1 bits |
+| GEOMETRY | `Quack::Geometry(wkb, crs)`, standard WKB and optional CRS |
+| UNION | `Quack::Union(tag, value, members)`; tag distinguishes a NULL member from SQL NULL |
+| VARIANT | `Quack::Variant`, with a typed `node` tree and logical Ruby `value` |
+| TUPLE / unnamed STRUCT | `Quack::Tuple(values)`, preserving every ordinal field |
+
+These logical values support SQL parameters, model assignment and native v1
+append, including values nested in lists, arrays and structs. BIGNUM decoding,
+DuckDB 2.0 type IDs and unnamed field handling are fixed in the packaged crate;
+no separate fork download is needed to build the gem.
+
+Read timestamps retain their SQL kind when rebound. Construct one explicitly
+with `Quack::Timestamp.from(time, "TIMESTAMP_NS")` or, on DuckDB 2.0,
+`Quack::Timestamp.from(time, "TIMESTAMPTZ_NS")`. Plain `Time`/`DateTime` values
+use TIMESTAMPTZ when microseconds suffice and TIMESTAMP_NS when nanoseconds are
+needed. Connections initialize `TimeZone = 'UTC'`, including after reconnect.
+Subsequent explicit timezone changes follow DuckDB's normal cast semantics.
+Values beyond a destination's precision are rejected by native append rather
+than silently truncated. Rails writes preserve nine fractional digits.
+
+`Quack::Variant.new({"items" => [1, nil, "é"]})` builds a heterogeneous value.
+Use `Quack::Variant.new(value, type: "UBIGINT")` to specify a scalar type.
+`variant.value` returns a Ruby tree; `variant.node` preserves each nested scalar
+type. Assign a new Variant to edit it. DuckDB normalizes a root VARIANT null to
+SQL NULL (`nil`); nulls inside containers remain nested nodes. Geometry uses
+standard WKB rather than a client geometry engine, preserving Z/M, empty values,
+collections and CRS metadata.
+
+All storable public type families are exercised on the supported server versions.
+DuckDB 1.5 cannot persist unnamed STRUCT/ROW tuples (even regular SQL INSERT fails);
+their query/parameter roundtrips work, and tuple persistence is tested on 2.0.
+TIMESTAMPTZ_NS is a DuckDB 2.0 type and is unavailable on 1.5. Internal/binder-only
+types and types supplied by optional server extensions are not universal targets.
+
+For protocol v1 only, the native append path is exposed:
+
+```ruby
+connection.append_rows("events", [{id: 1, name: "signup"}],
+  columns: {id: "BIGINT", name: "VARCHAR"}, batch_size: 1024)
+```
+
+Append resolves destination metadata from the server, including nested types,
+all-null columns, empty lists, ENUM dictionaries, case-sensitive field names and
+array sizes. Optional `columns` accepts full DuckDB SQL type declarations and
+must name every destination column; hash order does not change column placement.
+Rows must have exactly those names. Values are checked against destination
+integer ranges, decimal scale/precision and temporal units before sending any
+batch. Native SEND_DATA carries the values; append does not fall back to INSERT.
+Schema-qualified table names and a `schema:` option are supported in the current
+catalog. Select another catalog with `USE` before appending.
+Append batches are separate operations; wrap them in a transaction if atomicity
+is required.
+
+## Lifecycle and protocol limits
+
+- v3 is preferred, with v1 fallback on a rejected handshake. Require v3 by
+  setting both protocol-version bounds to 3.
+- Native v3 SEND_DATA is unavailable in the underlying transport. `append_rows`
+  raises `Quack::UnsupportedTypeError` on v3; SQL INSERT works on both versions.
+- Sessions retain temp tables, settings and transactions. Statements are never
+  replayed after a failure. Reconnect explicitly; session state is lost.
+- Native network waits release the GVL but block the calling thread. They do
+  not integrate with a Fiber scheduler. HTTP timeouts bound waits; there is no
+  server-side cancellation API. Thread interrupts arrive when a call returns.
+- Connections cannot cross forks. Create them after forking, or explicitly
+  reconnect in the child. Close explicitly for deterministic cleanup; GC
+  performs a bounded best-effort disconnect.
+- One session permits one active result. Close or consume it before another
+  operation. Use a connection per concurrent worker.
+- Nested transactions/savepoints are unavailable. Append batches are separate
+  operations; wrap them in a transaction when atomicity is needed.
+- Errors inherit from `Quack::Error`: ConnectionError, TimeoutError, ServerError,
+  ProtocolError, UnsupportedTypeError, ProxyError, BusyError and ForkError.
+
+## Development
+
+```sh
+CARGO="$PWD/script/cached-cargo" bundle exec rake compile
+script/test
+cargo fmt --manifest-path ext/quack/Cargo.toml --check
+cargo fmt --manifest-path ext/quack/vendor/quack_protocol/Cargo.toml --check
+mbx clippy --manifest-path ext/quack/Cargo.toml -- -D warnings
+bundle exec rake package
+```
+
+`script/test` uses uv to start disposable DuckDB 1.5.5 and 2.0.0 servers, run
+the integration suite and stop them. Use `DUCKDB_TEST_VERSIONS=2.0.0 script/test`
+for one server version. `bundle exec rake test` without a server runs local
+checks and explicitly skips integration cases.
+
+Tests cover all storable public type families, nested logical values, exact
+integers/decimals, nonfinite floats and negative zero, timestamp units/TZ,
+geometry dimensions/CRS, typed NULLs, empty results, parameter rebinding,
+streaming, auth/TLS, timeouts, GVL release, fork/reconnect and native v1 append.
+The append matrix includes batches, all-null/empty nested values, column
+ordering and rejection of invalid values before any batch is written. VARIANT
+leaf families also run through SQL and native v1 append. Tests distinguish
+server-version restrictions from client support.
+
+Development CI covers Linux/macOS and Ruby 3.2, 3.3 and 3.4 using Boxington.
+The `Native gems` workflow builds fresh release binaries with rb-sys-dock,
+packages all three Ruby ABIs into each platform gem, and runs the live suite
+on all twelve OS/architecture/Ruby combinations with build tools blocked.
+Release builds do not restore or publish compiler caches.
+
+To release, dispatch `Release` from main and choose a patch, minor or major
+bump. It updates the Ruby/Rust versions and locks, commits and tags the release,
+builds all five packages, and runs the twelve installed-binary test combinations.
+Only after every check passes does it publish those exact artifacts through
+RubyGems Trusted Publishing and create a GitHub Release with the gem assets.
+An optional `release_tag` publishes an existing tag without another bump; its
+source version must match the tag. Source and binary gems use the same version.
+
+## License
+
+MIT. The vendored Rust crate retains its own license and provenance in
+`ext/quack/vendor/quack_protocol/`. The type codecs follow DuckDB's public
+[BIGNUM](https://github.com/duckdb/duckdb/blob/v2.0.0/src/common/types/bignum.cpp),
+[BIT](https://github.com/duckdb/duckdb/blob/v2.0.0/src/common/types/bit.cpp) and
+[VARIANT](https://github.com/duckdb/duckdb/blob/v2.0.0/src/include/duckdb/common/types/variant_visitor.hpp)
+formats; DuckDB's MIT notice is included in LICENSE-DuckDB.

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