duckdb 1.5.3.0 → 1.5.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4226fa5e46b5d23fec1fd817577faa2329dced7fa67cedacaa75140849c2de16
-  data.tar.gz: 931c46acf582c8d01057c7a5b81f8356d430d1ed44cfad85ff79fd16a1935664
+  metadata.gz: 534e22d8df0424b7551b9ca68678d4da9f2e7a8055272dabe7c31d9f63c7b5b4
+  data.tar.gz: 5a1a9289dd5b20de755dd2c5c17242a353fe695ff27e47e5c862bc62004d1875
 SHA512:
-  metadata.gz: e41cee0179f52dab024e361a69725468a7f088a6e5314df76b1d4d5d2b216b687f075c6873a4d294026e29466e99223b79653c6391a8ddf44a574dc0ec1e633e
-  data.tar.gz: 49c1f2218424af2b13009fff358de4ace4050385323d5a6e06dee4c3b301fe8ee4855abbcbd944593b1ada48ec59eabd6af1e963aed3e70085da7f74b9257fd6
+  metadata.gz: 5afc359f5b6f5c972a34f0662e0f94360d91a12fd6a3db3e116f54eea486436c2855e0ee8f1949d8aff42c7b171e2efbeded84989b5bf335b57c7b9e7d5ee497
+  data.tar.gz: 7f5d628c60766814253cf9971b90f3fc1911d63d376cbce414dcff92f8e550dbccc676832435349b925c26449aa18d2dff394bd0e33d300ee1e57cc8ff8f5f5f

data/CHANGELOG.md

@@ -4,6 +4,53 @@ All notable changes to this project will be documented in this file.
 
 # Unreleased
 
+# 1.5.5.0 - 2026-07-27
+
+- bump up DuckDB 1.5.5 on CI.
+- support TIME_NS columns in `DuckDB::ScalarFunction` and `DuckDB::AggregateFunction`: TIME_NS can now be used as parameter and return type (with `DuckDB::LogicalType::TIME_NS`). Requires DuckDB >= 1.5.0 for full TIME_NS support in the C API.
+- bump Ruby to 3.4.10 on CI.
+- add `DuckDB::Connection#table_names(sql, qualified: false)` returning the table names referenced by a SQL query without executing it (binds `duckdb_get_table_names`). With `qualified: true`, names are returned as written in the query (including schema/catalog prefixes and aliases). Result order is unspecified.
+- add `DuckDB::Value.create_list(child_type, values)` and `DuckDB::Value.create_array(child_type, values)` to create LIST/ARRAY values from an element type (a Symbol like `:integer` or a `DuckDB::LogicalType`) and an Array of `DuckDB::Value` elements. The created values can be bound to prepared statements with `#bind_value`.
+- add `DuckDB::Value#list_size` and `DuckDB::Value#list_child(index)` to read LIST value elements as `DuckDB::Value`.
+- add `DuckDB::Value#to_ruby` converting a `DuckDB::Value` to a Ruby object. LIST/ARRAY values are converted to Ruby Arrays recursively; NULL becomes `nil`.
+- add `DuckDB::Value.create_struct(struct_type, values)` to create STRUCT values from a field spec (a Hash like `{ a: :integer, b: :varchar }` or a STRUCT `DuckDB::LogicalType`) and an Array of `DuckDB::Value` field values (positional, matching field order).
+- add `DuckDB::Value#struct_child(index)` to read STRUCT fields as `DuckDB::Value`. `DuckDB::Value#to_ruby` converts STRUCT values to a Hash with Symbol keys recursively.
+- add `DuckDB::Value.create_map(map_type, entries)` to create MAP values from a type spec (a one-pair Hash like `{ varchar: :integer }` or a MAP `DuckDB::LogicalType`) and a Hash of `DuckDB::Value` keys to `DuckDB::Value` values.
+- add `DuckDB::Value#map_size`, `#map_key(index)` and `#map_value(index)` to read MAP entries as `DuckDB::Value`. `DuckDB::Value#to_ruby` converts MAP values to a Hash recursively (keys keep their natural Ruby type).
+- add `DuckDB::PreparedStatement#column_count`, `#column_name(col_index)`, `#column_type(col_index)` and `#column_logical_type(col_index)` to get the result-set column metadata of a prepared statement without executing it (column index is 0-based). Useful for PG-style statement caching where column types must be known before execution.
+- add `DuckDB::Error#error_type` returning the DuckDB error category as a Symbol (e.g. `:constraint`, `:catalog`, `:parser`), or `nil` for errors not originating from a query result. Helps the ActiveRecord adapter map failures to `RecordNotUnique` / `NotNullViolation` etc. without parsing error messages.
+- add `DuckDB::PreparedStatement#param_logical_type(param_index)` returning the `DuckDB::LogicalType` of a bind parameter (1-based index), giving richer type information than `#param_type` (e.g. decimal width/scale, nested types).
+- add `DuckDB::Value.create_date(value)` to create DATE values from a Date, a Time, or a parseable String (same lenient input as `Appender#append_date`).
+- add `DuckDB::Value.create_time(value)` to create TIME values (microsecond precision) from a Time or a parseable String.
+- add `DuckDB::Value.create_time_ns(value)` to create TIME_NS values (nanosecond precision) from a Time or a parseable String. TIME_NS values are now converted to Ruby Time with full nanosecond precision (previously truncated to microseconds).
+- add `DuckDB::Value.create_time_tz(value)` to create TIMETZ values from a Time (the UTC offset is taken from the Time) or a parseable String with offset.
+- add `DuckDB::Value.create_timestamp(value)` to create TIMESTAMP values (microsecond precision) from a Time, a Date, or a parseable String (same lenient input as `Appender#append_timestamp`).
+- add `DuckDB::Value.create_timestamp_s(value)` to create TIMESTAMP_S values (second precision; sub-second input is truncated).
+- add `DuckDB::Value.create_timestamp_ms(value)` to create TIMESTAMP_MS values (millisecond precision).
+- add `DuckDB::Value.create_timestamp_ns(value)` to create TIMESTAMP_NS values (nanosecond precision). TIMESTAMP_NS values (including query results) are now converted to Ruby Time with full nanosecond precision (previously truncated to microseconds).
+- add `DuckDB::Value.create_timestamp_tz(value)` to create TIMESTAMP WITH TIME ZONE values; the instant is stored correctly regardless of the input UTC offset.
+- add `DuckDB::Value.create_interval(value)` to create INTERVAL values from a `DuckDB::Interval`.
+- add `DuckDB::Value.create_enum(enum_type, member)` to create ENUM values from an Array of member names (or an ENUM `DuckDB::LogicalType`) and a member name or 0-based index.
+- `DuckDB::Value#to_ruby` converts ENUM values to the member String.
+- add `DuckDB::Value.create_union(union_type, tag, value)` to create UNION values from a member spec Hash like `{ num: :integer, str: :varchar }` (or a UNION `DuckDB::LogicalType`), a member tag, and a `DuckDB::Value`. `DuckDB::Value#to_ruby` converts UNION values to the member value.
+- add `DuckDB::Value.create_bit(value)` to create BIT values from a String of '0'/'1' characters.
+- `DuckDB::Value#to_ruby` converts BIT values to a String of '0'/'1' characters.
+- add `DuckDB::Value.create_bignum(value)` to create BIGNUM (arbitrary-precision integer) values from a Ruby Integer.
+- `DuckDB::Value#to_ruby` converts BIGNUM values to a Ruby Integer.
+- `DuckDB::Value#to_ruby` converts BLOB values to a BINARY-encoded String.
+- `DuckDB::Value#to_ruby` converts DECIMAL values to a BigDecimal.
+
+# 1.5.4.0 - 2026-06-20
+- bump up DuckDB 1.5.4 and 1.4.5 on CI.
+- add experimental `DuckDB::Result#arrow_c_stream` returning `DuckDB::ArrowArrayStream` to export a query result as an Arrow C stream (Arrow C Data Interface). The stream can be consumed directly by ruby-polars (`Polars::DataFrame.new(result)`) and red-arrow (`Arrow::RecordBatchReader.import(stream.to_i)`).
+- add experimental `DuckDB::Connection#append_arrow(table, producer)` to import an Arrow producer (any object responding to `#arrow_c_stream`, such as a Polars `DataFrame` or a `DuckDB::Result`) into an existing table, returning the number of rows appended.
+- drop Ruby 3.2.
+- add `DuckDB::TableFunction::InitInfo#max_threads=` (and `#set_max_threads`) to hint DuckDB how many worker threads can execute a custom table function concurrently.
+- add `DuckDB::TableFunction::InitInfo#column_count` to get the number of projected result columns of a custom table function scan.
+- add `DuckDB::TableFunction::InitInfo#column_index` to get the source column index of a given projected result column of a custom table function scan.
+- add `DuckDB::Appender#append_uuid(value)` to append a UUID value to a `UUID` column. `value` must be a String in canonical UUID format (`xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx`).
+- add `DuckDB::PreparedStatement#bind_uuid(index, value)` to bind a UUID parameter. `value` must be a String in canonical UUID format.
+
 # 1.5.3.0 - 2026-05-24
 - bump up DuckDB 1.5.3 on CI.
 - add `DuckDB::AggregateFunctionSet` class and `DuckDB::Connection#register_aggregate_function_set` to register multiple overloads of a custom aggregate function under one SQL name.

data/CLAUDE.md

@@ -0,0 +1,4 @@
+## Orchestration workflow
+You (Fable) are the orchestrator. Plan, decompose, synthesize.
+Reasoning-heavy phases → deep-reasoner
+Mechanical work → fast-worker

data/README.md

@@ -266,6 +266,58 @@ res.first.first # => 4
 
 Set `DuckDB.default_timezone` to control how TIMESTAMP and TIME values without time zone are converted to Ruby `Time` objects. The default is `:local`, but you can use `:utc` for UTC conversion.
 
+### Arrow interop (experimental)
+
+`DuckDB::Result#arrow_c_stream` exports a query result as an Arrow C stream
+([Arrow C Data Interface](https://arrow.apache.org/docs/format/CDataInterface.html)).
+The returned `DuckDB::ArrowArrayStream` satisfies the Ruby Arrow C stream
+protocol (`#arrow_c_stream` / `#to_i`), so query results can be handed to
+Arrow consumers in columnar form, without converting each row to Ruby objects.
+
+With [ruby-polars](https://github.com/ankane/ruby-polars), no glue code is needed:
+
+```ruby
+result = con.query('SELECT * FROM users')
+df = Polars::DataFrame.new(result)
+```
+
+With [red-arrow](https://github.com/apache/arrow/tree/main/ruby/red-arrow),
+pass the stream address to `Arrow::RecordBatchReader.import`:
+
+```ruby
+result = con.query('SELECT * FROM users')
+reader = Arrow::RecordBatchReader.import(result.arrow_c_stream.to_i)
+```
+
+The consumer takes ownership of the stream's contents, so a result can be
+exported only once; exporting the same result again raises `DuckDB::Error`.
+
+In the other direction, `DuckDB::Connection#append_arrow` imports an Arrow
+producer into an existing table. Any object responding to `#arrow_c_stream`
+works as the producer — for example a Polars `DataFrame`, or another
+`DuckDB::Result`:
+
+```ruby
+con.query('CREATE TABLE users (id BIGINT, name VARCHAR)')
+rows = con.append_arrow('users', polars_df) # => number of rows appended
+con.query('SELECT * FROM users').to_a
+```
+
+The producer's columns must line up with the table's columns by count and
+position. DuckDB casts compatible column types (e.g. INTEGER into a BIGINT
+column); a type that cannot be cast raises `DuckDB::Error`. `append_arrow` is
+not transactional — wrap it in your own transaction if you need all-or-nothing.
+
+These features are **experimental**: they are built on DuckDB's unstable Arrow
+C API and may change in any minor release.
+
+Note: [red-arrow-format](https://github.com/apache/arrow/tree/main/ruby/red-arrow-format)
+(the pure-Ruby Arrow implementation) supports only the Arrow IPC
+serialization format, not the C Data Interface. To exchange data with it,
+write/read Arrow IPC files through DuckDB's
+[arrow community extension](https://duckdb.org/community_extensions/extensions/arrow.html)
+(`COPY ... TO 'data.arrows'` / `read_arrow(...)`).
+
 ## Versioning and DuckDB support
 
 The first three digits of the gem version track the DuckDB release that the

data/duckdb.gemspec

@@ -32,6 +32,6 @@ Gem::Specification.new do |spec|
 
   spec.require_paths = ['lib']
   spec.extensions = ['ext/duckdb/extconf.rb']
-  spec.required_ruby_version = '>= 3.2.0'
+  spec.required_ruby_version = '>= 3.3.0'
   spec.add_dependency 'bigdecimal', '>= 3.1.4'
 end

data/ext/duckdb/aggregate_function.c

@@ -737,7 +737,6 @@ void rbduckdb_init_aggregate_function(void) {
     rb_define_alloc_func(cDuckDBAggregateFunction, allocate);
     rb_define_method(cDuckDBAggregateFunction, "initialize", aggregate_function_initialize, 0);
     rb_define_method(cDuckDBAggregateFunction, "set_name", aggregate_function_set_name, 1);
-    rb_define_method(cDuckDBAggregateFunction, "name=", aggregate_function_set_name, 1);
     rb_define_private_method(cDuckDBAggregateFunction, "_set_return_type", aggregate_function__set_return_type, 1);
     rb_define_private_method(cDuckDBAggregateFunction, "_add_parameter", aggregate_function__add_parameter, 1);
     rb_define_private_method(cDuckDBAggregateFunction, "_set_init", aggregate_function__set_init, 0);

data/ext/duckdb/appender.c

@@ -35,6 +35,7 @@ static VALUE appender__append_time(VALUE self, VALUE hour, VALUE min, VALUE sec,
 static VALUE appender__append_timestamp(VALUE self, VALUE year, VALUE month, VALUE day, VALUE hour, VALUE min, VALUE sec, VALUE micros);
 static VALUE appender__append_hugeint(VALUE self, VALUE lower, VALUE upper);
 static VALUE appender__append_uhugeint(VALUE self, VALUE lower, VALUE upper);
+static VALUE appender__append_uuid(VALUE self, VALUE val);
 static VALUE appender__append_value(VALUE self, VALUE val);
 static VALUE appender__append_data_chunk(VALUE self, VALUE chunk);
 static VALUE appender__append_default_to_chunk(VALUE self, VALUE chunk, VALUE col, VALUE row);
@@ -453,6 +454,21 @@ static VALUE appender__append_uhugeint(VALUE self, VALUE lower, VALUE upper) {
     return state_to_rbool(duckdb_append_uhugeint(ctx->appender, uhugeint));
 }
 
+/* :nodoc: */
+static VALUE appender__append_uuid(VALUE self, VALUE val) {
+    rubyDuckDBAppender *ctx;
+    duckdb_uhugeint uhugeint;
+    duckdb_value uuid_val;
+    duckdb_state state;
+
+    TypedData_Get_Struct(self, rubyDuckDBAppender, &appender_data_type, ctx);
+    rbduckdb_uuid_str_to_uhugeint(val, &uhugeint);
+    uuid_val = duckdb_create_uuid(uhugeint);
+    state = duckdb_append_value(ctx->appender, uuid_val);
+    duckdb_destroy_value(&uuid_val);
+    return state_to_rbool(state);
+}
+
 /* :nodoc: */
 static VALUE appender__append_value(VALUE self, VALUE val) {
     rubyDuckDBAppender *ctx;
@@ -578,6 +594,7 @@ void rbduckdb_init_appender(void) {
     rb_define_private_method(cDuckDBAppender, "_append_timestamp", appender__append_timestamp, 7);
     rb_define_private_method(cDuckDBAppender, "_append_hugeint", appender__append_hugeint, 2);
     rb_define_private_method(cDuckDBAppender, "_append_uhugeint", appender__append_uhugeint, 2);
+    rb_define_private_method(cDuckDBAppender, "_append_uuid", appender__append_uuid, 1);
     rb_define_private_method(cDuckDBAppender, "_append_value", appender__append_value, 1);
     rb_define_private_method(cDuckDBAppender, "_append_data_chunk", appender__append_data_chunk, 1);
     rb_define_private_method(cDuckDBAppender, "_append_default_to_chunk", appender__append_default_to_chunk, 3);

data/ext/duckdb/arrow_array_stream.c

@@ -0,0 +1,226 @@
+#include "ruby-duckdb.h"
+#include <errno.h>
+
+static VALUE cDuckDBArrowArrayStream;
+
+typedef struct {
+    struct ArrowArrayStream stream;
+} rubyDuckDBArrowArrayStream;
+
+/*
+ * Heap-allocated context referenced by stream.private_data. Consumers may
+ * move the stream struct contents out and keep using the callbacks after
+ * the Ruby DuckDB::ArrowArrayStream object is gone, so this context is
+ * freed only by the stream release callback, and it holds a reference on
+ * the result struct (rbduckdb_result_ref) until then. The release callback
+ * must not call any Ruby API: it can run during GC sweep (via deallocate
+ * of an unconsumed stream) or from a non-Ruby thread.
+ */
+typedef struct {
+    rubyDuckDBResult *presult_ctx;
+    duckdb_arrow_options arrow_options;
+    char *last_error;
+} arrowArrayStreamContext;
+
+static void deallocate(void *ctx);
+static VALUE allocate(VALUE klass);
+static size_t memsize(const void *p);
+static VALUE arrow_array_stream_to_i(VALUE self);
+static VALUE arrow_array_stream_arrow_c_stream(VALUE self);
+static void stream_set_error(arrowArrayStreamContext *ctx, const char *msg);
+static int stream_check_error(arrowArrayStreamContext *ctx, duckdb_error_data error_data);
+static int stream_get_schema(struct ArrowArrayStream *stream, struct ArrowSchema *out);
+static int stream_get_next(struct ArrowArrayStream *stream, struct ArrowArray *out);
+static const char *stream_get_last_error(struct ArrowArrayStream *stream);
+static void stream_release(struct ArrowArrayStream *stream);
+
+static const rb_data_type_t arrow_array_stream_data_type = {
+    "DuckDB/ArrowArrayStream",
+    {NULL, deallocate, memsize,},
+    0, 0, RUBY_TYPED_FREE_IMMEDIATELY
+};
+
+static void deallocate(void *ctx) {
+    rubyDuckDBArrowArrayStream *p = (rubyDuckDBArrowArrayStream *)ctx;
+
+    if (p->stream.release != NULL) {
+        p->stream.release(&(p->stream));
+    }
+    xfree(p);
+}
+
+static VALUE allocate(VALUE klass) {
+    rubyDuckDBArrowArrayStream *ctx = xcalloc((size_t)1, sizeof(rubyDuckDBArrowArrayStream));
+    return TypedData_Wrap_Struct(klass, &arrow_array_stream_data_type, ctx);
+}
+
+static size_t memsize(const void *p) {
+    return sizeof(rubyDuckDBArrowArrayStream);
+}
+
+/* Context memory is managed with plain malloc/free because the release
+ * callback may run outside Ruby's memory bookkeeping. */
+static void stream_set_error(arrowArrayStreamContext *ctx, const char *msg) {
+    size_t len = strlen(msg) + 1;
+
+    free(ctx->last_error);
+    ctx->last_error = malloc(len);
+    if (ctx->last_error != NULL) {
+        memcpy(ctx->last_error, msg, len);
+    }
+}
+
+static int stream_check_error(arrowArrayStreamContext *ctx, duckdb_error_data error_data) {
+    if (error_data == NULL) {
+        return 0;
+    }
+    if (!duckdb_error_data_has_error(error_data)) {
+        duckdb_destroy_error_data(&error_data);
+        return 0;
+    }
+    stream_set_error(ctx, duckdb_error_data_message(error_data));
+    duckdb_destroy_error_data(&error_data);
+    return EIO;
+}
+
+static int stream_get_schema(struct ArrowArrayStream *stream, struct ArrowSchema *out) {
+    arrowArrayStreamContext *ctx = (arrowArrayStreamContext *)stream->private_data;
+    duckdb_error_data error_data;
+    duckdb_logical_type *types;
+    const char **names;
+    idx_t column_count;
+    idx_t i;
+
+    column_count = duckdb_column_count(&(ctx->presult_ctx->result));
+    types = calloc((size_t)column_count, sizeof(duckdb_logical_type));
+    names = calloc((size_t)column_count, sizeof(const char *));
+    if (column_count > 0 && (types == NULL || names == NULL)) {
+        free(types);
+        free(names);
+        stream_set_error(ctx, "failed to allocate memory for Arrow schema conversion");
+        return ENOMEM;
+    }
+    for (i = 0; i < column_count; i++) {
+        types[i] = duckdb_column_logical_type(&(ctx->presult_ctx->result), i);
+        names[i] = duckdb_column_name(&(ctx->presult_ctx->result), i);
+    }
+
+    error_data = duckdb_to_arrow_schema(ctx->arrow_options, types, names, column_count, out);
+
+    for (i = 0; i < column_count; i++) {
+        duckdb_destroy_logical_type(&types[i]);
+    }
+    free(types);
+    free(names);
+    return stream_check_error(ctx, error_data);
+}
+
+static int stream_get_next(struct ArrowArrayStream *stream, struct ArrowArray *out) {
+    arrowArrayStreamContext *ctx = (arrowArrayStreamContext *)stream->private_data;
+    duckdb_data_chunk chunk;
+    duckdb_error_data error_data;
+
+    chunk = duckdb_fetch_chunk(ctx->presult_ctx->result);
+    if (chunk == NULL) {
+        /* End of stream: a released (release == NULL) array. */
+        memset(out, 0, sizeof(struct ArrowArray));
+        return 0;
+    }
+    /* duckdb_data_chunk_to_arrow copies the chunk into Arrow-owned buffers,
+     * so the chunk can be destroyed right after conversion. */
+    error_data = duckdb_data_chunk_to_arrow(ctx->arrow_options, chunk, out);
+    duckdb_destroy_data_chunk(&chunk);
+    return stream_check_error(ctx, error_data);
+}
+
+static const char *stream_get_last_error(struct ArrowArrayStream *stream) {
+    arrowArrayStreamContext *ctx = (arrowArrayStreamContext *)stream->private_data;
+
+    return ctx == NULL ? NULL : ctx->last_error;
+}
+
+static void stream_release(struct ArrowArrayStream *stream) {
+    arrowArrayStreamContext *ctx;
+
+    if (stream == NULL || stream->release == NULL) {
+        return;
+    }
+    ctx = (arrowArrayStreamContext *)stream->private_data;
+    if (ctx != NULL) {
+        rbduckdb_result_unref(ctx->presult_ctx);
+        if (ctx->arrow_options != NULL) {
+            duckdb_destroy_arrow_options(&(ctx->arrow_options));
+        }
+        free(ctx->last_error);
+        free(ctx);
+    }
+    stream->private_data = NULL;
+    stream->release = NULL;
+}
+
+VALUE rbduckdb_create_arrow_array_stream(VALUE oDuckDBResult) {
+    VALUE obj;
+    rubyDuckDBArrowArrayStream *p;
+    rubyDuckDBResult *presult_ctx;
+    arrowArrayStreamContext *ctx;
+
+    obj = allocate(cDuckDBArrowArrayStream);
+    TypedData_Get_Struct(obj, rubyDuckDBArrowArrayStream, &arrow_array_stream_data_type, p);
+    presult_ctx = rbduckdb_get_struct_result(oDuckDBResult);
+
+    ctx = calloc((size_t)1, sizeof(arrowArrayStreamContext));
+    if (ctx == NULL) {
+        rb_raise(rb_eNoMemError, "failed to allocate ArrowArrayStream context");
+    }
+
+    rbduckdb_result_ref(presult_ctx);
+    ctx->presult_ctx = presult_ctx;
+    ctx->arrow_options = duckdb_result_get_arrow_options(&(presult_ctx->result));
+
+    p->stream.get_schema = stream_get_schema;
+    p->stream.get_next = stream_get_next;
+    p->stream.get_last_error = stream_get_last_error;
+    p->stream.release = stream_release;
+    p->stream.private_data = ctx;
+
+    return obj;
+}
+
+/*
+ *  call-seq:
+ *    stream.to_i -> Integer
+ *
+ *  Returns the address of the underlying C <code>struct ArrowArrayStream</code>.
+ *  Arrow consumers such as red-arrow accept this address directly:
+ *
+ *    reader = Arrow::RecordBatchReader.import(stream.to_i)
+ */
+static VALUE arrow_array_stream_to_i(VALUE self) {
+    rubyDuckDBArrowArrayStream *p;
+
+    TypedData_Get_Struct(self, rubyDuckDBArrowArrayStream, &arrow_array_stream_data_type, p);
+    return ULL2NUM((unsigned long long)(uintptr_t)&(p->stream));
+}
+
+/*
+ *  call-seq:
+ *    stream.arrow_c_stream -> self
+ *
+ *  Returns self. Defined so that the stream object itself satisfies the
+ *  Arrow C stream protocol used by ruby-polars and others.
+ */
+static VALUE arrow_array_stream_arrow_c_stream(VALUE self) {
+    return self;
+}
+
+void rbduckdb_init_arrow_array_stream(void) {
+#if 0
+    VALUE mDuckDB = rb_define_module("DuckDB");
+#endif
+    cDuckDBArrowArrayStream = rb_define_class_under(mDuckDB, "ArrowArrayStream", rb_cObject);
+
+    rb_define_alloc_func(cDuckDBArrowArrayStream, allocate);
+
+    rb_define_method(cDuckDBArrowArrayStream, "to_i", arrow_array_stream_to_i, 0);
+    rb_define_method(cDuckDBArrowArrayStream, "arrow_c_stream", arrow_array_stream_arrow_c_stream, 0);
+}

data/ext/duckdb/arrow_array_stream.h

@@ -0,0 +1,61 @@
+#ifndef RUBY_DUCKDB_ARROW_ARRAY_STREAM_H
+#define RUBY_DUCKDB_ARROW_ARRAY_STREAM_H
+
+/*
+ * Canonical Arrow C Data Interface and Arrow C Stream Interface definitions.
+ * https://arrow.apache.org/docs/format/CDataInterface.html
+ * duckdb.h only forward-declares these structs.
+ */
+#ifndef ARROW_C_DATA_INTERFACE
+#define ARROW_C_DATA_INTERFACE
+
+#define ARROW_FLAG_DICTIONARY_ORDERED 1
+#define ARROW_FLAG_NULLABLE 2
+#define ARROW_FLAG_MAP_KEYS_SORTED 4
+
+struct ArrowSchema {
+    const char *format;
+    const char *name;
+    const char *metadata;
+    int64_t flags;
+    int64_t n_children;
+    struct ArrowSchema **children;
+    struct ArrowSchema *dictionary;
+
+    void (*release)(struct ArrowSchema *);
+    void *private_data;
+};
+
+struct ArrowArray {
+    int64_t length;
+    int64_t null_count;
+    int64_t offset;
+    int64_t n_buffers;
+    int64_t n_children;
+    const void **buffers;
+    struct ArrowArray **children;
+    struct ArrowArray *dictionary;
+
+    void (*release)(struct ArrowArray *);
+    void *private_data;
+};
+
+#endif /* ARROW_C_DATA_INTERFACE */
+
+#ifndef ARROW_C_STREAM_INTERFACE
+#define ARROW_C_STREAM_INTERFACE
+
+struct ArrowArrayStream {
+    int (*get_schema)(struct ArrowArrayStream *, struct ArrowSchema *out);
+    int (*get_next)(struct ArrowArrayStream *, struct ArrowArray *out);
+    const char *(*get_last_error)(struct ArrowArrayStream *);
+    void (*release)(struct ArrowArrayStream *);
+    void *private_data;
+};
+
+#endif /* ARROW_C_STREAM_INTERFACE */
+
+void rbduckdb_init_arrow_array_stream(void);
+VALUE rbduckdb_create_arrow_array_stream(VALUE oDuckDBResult);
+
+#endif

data/ext/duckdb/arrow_import.c

@@ -0,0 +1,165 @@
+#include "ruby-duckdb.h"
+
+/*
+ * Internal helpers backing DuckDB::Connection#append_arrow. They consume an
+ * Arrow producer's struct ArrowArrayStream (given by its address) and convert
+ * each chunk into a DuckDB::DataChunk using DuckDB's unstable Arrow C API. The
+ * Ruby layer owns the loop, the appender lifecycle, and error handling; these
+ * primitives only do the raw-pointer / C-API work.
+ */
+
+static VALUE cDuckDBArrowConvertedSchema;
+
+typedef struct {
+    duckdb_arrow_converted_schema converted_schema;
+} rubyDuckDBArrowConvertedSchema;
+
+static void deallocate(void *ctx);
+static VALUE allocate(VALUE klass);
+static size_t memsize(const void *p);
+static void raise_error_data(duckdb_error_data error_data);
+
+static VALUE connection__arrow_converted_schema(VALUE self, VALUE address);
+static VALUE connection__arrow_next_chunk(VALUE self, VALUE address, VALUE converted);
+static VALUE connection__arrow_release(VALUE self, VALUE address);
+
+static const rb_data_type_t arrow_converted_schema_data_type = {
+    "DuckDB/ArrowConvertedSchema",
+    {NULL, deallocate, memsize,},
+    0, 0, RUBY_TYPED_FREE_IMMEDIATELY
+};
+
+static void deallocate(void *ctx) {
+    rubyDuckDBArrowConvertedSchema *p = (rubyDuckDBArrowConvertedSchema *)ctx;
+
+    if (p->converted_schema) {
+        duckdb_destroy_arrow_converted_schema(&(p->converted_schema));
+    }
+    xfree(p);
+}
+
+static VALUE allocate(VALUE klass) {
+    rubyDuckDBArrowConvertedSchema *ctx = xcalloc((size_t)1, sizeof(rubyDuckDBArrowConvertedSchema));
+    return TypedData_Wrap_Struct(klass, &arrow_converted_schema_data_type, ctx);
+}
+
+static size_t memsize(const void *p) {
+    return sizeof(rubyDuckDBArrowConvertedSchema);
+}
+
+static void raise_error_data(duckdb_error_data error_data) {
+    VALUE message;
+
+    if (error_data == NULL) {
+        return;
+    }
+    if (!duckdb_error_data_has_error(error_data)) {
+        duckdb_destroy_error_data(&error_data);
+        return;
+    }
+    message = rb_str_new_cstr(duckdb_error_data_message(error_data));
+    duckdb_destroy_error_data(&error_data);
+    rb_raise(eDuckDBError, "%s", StringValueCStr(message));
+}
+
+static struct ArrowArrayStream *stream_from_address(VALUE address) {
+    return (struct ArrowArrayStream *)(uintptr_t)NUM2ULL(address);
+}
+
+/* :nodoc: */
+static VALUE connection__arrow_converted_schema(VALUE self, VALUE address) {
+    rubyDuckDBConnection *ctx;
+    struct ArrowArrayStream *stream;
+    struct ArrowSchema schema;
+    duckdb_arrow_converted_schema converted_schema = NULL;
+    duckdb_error_data error_data;
+    VALUE obj;
+    rubyDuckDBArrowConvertedSchema *schema_ctx;
+    int rc;
+
+    ctx = rbduckdb_get_struct_connection(self);
+    stream = stream_from_address(address);
+    if (stream == NULL) {
+        rb_raise(eDuckDBError, "Arrow producer returned a NULL stream");
+    }
+
+    memset(&schema, 0, sizeof(schema));
+    rc = stream->get_schema(stream, &schema);
+    if (rc != 0) {
+        const char *err = stream->get_last_error(stream);
+        rb_raise(eDuckDBError, "failed to get Arrow schema: %s", err ? err : "unknown error");
+    }
+
+    error_data = duckdb_schema_from_arrow(ctx->con, &schema, &converted_schema);
+    if (schema.release != NULL) {
+        schema.release(&schema);
+    }
+    raise_error_data(error_data);
+
+    obj = allocate(cDuckDBArrowConvertedSchema);
+    TypedData_Get_Struct(obj, rubyDuckDBArrowConvertedSchema, &arrow_converted_schema_data_type, schema_ctx);
+    schema_ctx->converted_schema = converted_schema;
+    return obj;
+}
+
+/* :nodoc: */
+static VALUE connection__arrow_next_chunk(VALUE self, VALUE address, VALUE converted) {
+    rubyDuckDBConnection *ctx;
+    rubyDuckDBArrowConvertedSchema *schema_ctx;
+    struct ArrowArrayStream *stream;
+    struct ArrowArray array;
+    duckdb_data_chunk chunk = NULL;
+    duckdb_error_data error_data;
+    int rc;
+
+    ctx = rbduckdb_get_struct_connection(self);
+    TypedData_Get_Struct(converted, rubyDuckDBArrowConvertedSchema, &arrow_converted_schema_data_type, schema_ctx);
+    stream = stream_from_address(address);
+
+    memset(&array, 0, sizeof(array));
+    rc = stream->get_next(stream, &array);
+    if (rc != 0) {
+        const char *err = stream->get_last_error(stream);
+        rb_raise(eDuckDBError, "failed to get next Arrow chunk: %s", err ? err : "unknown error");
+    }
+    /* End of stream: a released array (release == NULL). */
+    if (array.release == NULL) {
+        return Qnil;
+    }
+
+    /* duckdb_data_chunk_from_arrow takes ownership of the array (nulls its
+     * release). On error before that, we still own it and must release it. */
+    error_data = duckdb_data_chunk_from_arrow(ctx->con, &array, schema_ctx->converted_schema, &chunk);
+    if (error_data != NULL && duckdb_error_data_has_error(error_data)) {
+        if (array.release != NULL) {
+            array.release(&array);
+        }
+        raise_error_data(error_data);
+    } else if (error_data != NULL) {
+        duckdb_destroy_error_data(&error_data);
+    }
+
+    return rbduckdb_create_data_chunk(chunk, true);
+}
+
+/* :nodoc: */
+static VALUE connection__arrow_release(VALUE self, VALUE address) {
+    struct ArrowArrayStream *stream = stream_from_address(address);
+
+    if (stream != NULL && stream->release != NULL) {
+        stream->release(stream);
+    }
+    return Qnil;
+}
+
+void rbduckdb_init_arrow_import(void) {
+#if 0
+    VALUE mDuckDB = rb_define_module("DuckDB");
+#endif
+    cDuckDBArrowConvertedSchema = rb_define_class_under(mDuckDB, "ArrowConvertedSchema", rb_cObject);
+    rb_define_alloc_func(cDuckDBArrowConvertedSchema, allocate);
+
+    rb_define_private_method(cDuckDBConnection, "_arrow_converted_schema", connection__arrow_converted_schema, 1);
+    rb_define_private_method(cDuckDBConnection, "_arrow_next_chunk", connection__arrow_next_chunk, 2);
+    rb_define_private_method(cDuckDBConnection, "_arrow_release", connection__arrow_release, 1);
+}

data/ext/duckdb/arrow_import.h

@@ -0,0 +1,6 @@
+#ifndef RUBY_DUCKDB_ARROW_IMPORT_H
+#define RUBY_DUCKDB_ARROW_IMPORT_H
+
+void rbduckdb_init_arrow_import(void);
+
+#endif

data/ext/duckdb/blob.c

@@ -2,7 +2,7 @@
 
 VALUE cDuckDBBlob;
 
-void rbduckdb_init_duckdb_blob(void) {
+void rbduckdb_init_blob(void) {
 #if 0
     VALUE mDuckDB = rb_define_module("DuckDB");
 #endif

data/ext/duckdb/blob.h

@@ -1,7 +1,6 @@
 #ifndef RUBY_DUCKDB_BLOB_H
 #define RUBY_DUCKDB_BLOB_H
 
-void rbduckdb_init_duckdb_blob(void);
+void rbduckdb_init_blob(void);
 
 #endif
-