duckdb 1.5.2.1 → 1.5.4.0

data/ext/duckdb/function_executor.c

@@ -68,6 +68,14 @@ static struct callback_request *g_request_list = NULL;
 static VALUE g_executor_thread = Qnil;
 static int g_executor_started = 0;
 
+/*
+ * GC-protection array holding every live per-worker proxy Ruby thread.
+ * Proxies are created from non-Ruby init hooks (via the global executor) and
+ * are not reachable from any marked object, so without this array the GC could
+ * collect a proxy thread while DuckDB still dispatches callbacks to it.
+ */
+static VALUE g_proxy_threads = Qnil;
+
 /* Data passed to the executor wait function */
 struct executor_wait_data {
     struct callback_request *request;
@@ -166,6 +174,11 @@ void rbduckdb_function_executor_ensure_started(void) {
     }
 #endif
 
+    if (g_proxy_threads == Qnil) {
+        g_proxy_threads = rb_ary_new();
+        rb_global_variable(&g_proxy_threads);
+    }
+
     g_executor_thread = rb_thread_create(executor_thread_func, NULL);
     rb_global_variable(&g_executor_thread);
     g_executor_started = 1;
@@ -242,7 +255,293 @@ static void *callback_with_gvl(void *data) {
     return NULL;
 }
 
-void rbduckdb_function_executor_dispatch(rbduckdb_function_callback_t cb, void *user_data) {
+/*
+ * ============================================================================
+ * Per-worker proxy thread
+ * ============================================================================
+ *
+ * One dedicated Ruby thread per DuckDB worker thread. Same hand-off protocol as
+ * the global executor (mutex + condvars), but private to a single worker so
+ * that callbacks from different workers no longer serialize through one queue.
+ *
+ * Pattern follows the FFI gem's async callback dispatcher:
+ *   https://github.com/ffi/ffi/blob/master/ext/ffi_c/Function.c
+ */
+struct worker_proxy {
+    VALUE ruby_thread;
+    volatile int stop_requested;
+    rbduckdb_function_callback_t cb;
+    void *user_data;
+    volatile int has_request;
+    volatile int request_done;
+    volatile int thread_exited;
+#ifdef _MSC_VER
+    CRITICAL_SECTION lock;
+    CONDITION_VARIABLE request_cond;
+    CONDITION_VARIABLE request_done_cond;
+    CONDITION_VARIABLE thread_exit_cond;
+#else
+    pthread_mutex_t lock;
+    pthread_cond_t request_cond;
+    pthread_cond_t request_done_cond;
+    pthread_cond_t thread_exit_cond;
+#endif
+};
+
+/* Runs without GVL: the proxy waits for a callback request */
+static void *proxy_wait_func(void *data) {
+    struct worker_proxy *proxy = (struct worker_proxy *)data;
+
+#ifdef _MSC_VER
+    EnterCriticalSection(&proxy->lock);
+    while (!proxy->stop_requested && !proxy->has_request) {
+        SleepConditionVariableCS(&proxy->request_cond, &proxy->lock, INFINITE);
+    }
+    LeaveCriticalSection(&proxy->lock);
+#else
+    pthread_mutex_lock(&proxy->lock);
+    while (!proxy->stop_requested && !proxy->has_request) {
+        pthread_cond_wait(&proxy->request_cond, &proxy->lock);
+    }
+    pthread_mutex_unlock(&proxy->lock);
+#endif
+
+    return NULL;
+}
+
+/* Unblock function for the proxy thread (VM shutdown or Thread#kill) */
+static void proxy_stop_func(void *data) {
+    struct worker_proxy *proxy = (struct worker_proxy *)data;
+
+#ifdef _MSC_VER
+    EnterCriticalSection(&proxy->lock);
+    proxy->stop_requested = 1;
+    WakeConditionVariable(&proxy->request_cond);
+    LeaveCriticalSection(&proxy->lock);
+#else
+    pthread_mutex_lock(&proxy->lock);
+    proxy->stop_requested = 1;
+    pthread_cond_signal(&proxy->request_cond);
+    pthread_mutex_unlock(&proxy->lock);
+#endif
+}
+
+/* The proxy thread main loop. Runs as the body of rb_ensure (see below). */
+static VALUE proxy_loop_body(VALUE data) {
+    struct worker_proxy *proxy = (struct worker_proxy *)data;
+
+    while (!proxy->stop_requested) {
+        /* Release the GVL and wait for a request */
+        rb_thread_call_without_gvl(proxy_wait_func, proxy, proxy_stop_func, proxy);
+
+        if (proxy->stop_requested) break;
+
+        if (proxy->has_request) {
+            /* Execute the callback with the GVL held */
+            proxy->cb(proxy->user_data);
+
+            /* Signal completion to the DuckDB worker thread */
+#ifdef _MSC_VER
+            EnterCriticalSection(&proxy->lock);
+            proxy->has_request = 0;
+            proxy->request_done = 1;
+            WakeConditionVariable(&proxy->request_done_cond);
+            LeaveCriticalSection(&proxy->lock);
+#else
+            pthread_mutex_lock(&proxy->lock);
+            proxy->has_request = 0;
+            proxy->request_done = 1;
+            pthread_cond_signal(&proxy->request_done_cond);
+            pthread_mutex_unlock(&proxy->lock);
+#endif
+        }
+    }
+
+    return Qnil;
+}
+
+/*
+ * Teardown for the proxy thread. Run via rb_ensure so it executes even if an
+ * async exception (Thread#kill, VM shutdown via rb_thread_terminate_all)
+ * unwinds proxy_loop_body. If it were skipped, thread_exited would stay 0
+ * forever and rbduckdb_worker_proxy_destroy's join would deadlock.
+ */
+static VALUE proxy_cleanup(VALUE data) {
+    struct worker_proxy *proxy = (struct worker_proxy *)data;
+
+    /* Stop being GC-protected now that we are about to exit */
+    if (g_proxy_threads != Qnil) {
+        rb_ary_delete(g_proxy_threads, proxy->ruby_thread);
+    }
+
+    /*
+     * Signal that this thread has finished and no longer touches the proxy
+     * struct. Only after this may rbduckdb_worker_proxy_destroy free it.
+     */
+#ifdef _MSC_VER
+    EnterCriticalSection(&proxy->lock);
+    proxy->thread_exited = 1;
+    WakeConditionVariable(&proxy->thread_exit_cond);
+    LeaveCriticalSection(&proxy->lock);
+#else
+    pthread_mutex_lock(&proxy->lock);
+    proxy->thread_exited = 1;
+    pthread_cond_signal(&proxy->thread_exit_cond);
+    pthread_mutex_unlock(&proxy->lock);
+#endif
+
+    return Qnil;
+}
+
+/* The proxy thread entry point (Ruby thread). */
+static VALUE proxy_thread_func(void *data) {
+    return rb_ensure(proxy_loop_body, (VALUE)data, proxy_cleanup, (VALUE)data);
+}
+
+struct worker_proxy *rbduckdb_worker_proxy_create(void) {
+    /*
+     * Use calloc (not xcalloc): rbduckdb_worker_proxy_destroy frees the struct
+     * from a non-Ruby thread where xfree is unsafe.
+     */
+    struct worker_proxy *proxy = calloc(1, sizeof(struct worker_proxy));
+    if (proxy == NULL) {
+        rb_raise(rb_eNoMemError, "failed to allocate worker_proxy");
+    }
+
+    proxy->stop_requested = 0;
+    proxy->has_request = 0;
+    proxy->request_done = 0;
+    proxy->thread_exited = 0;
+
+#ifdef _MSC_VER
+    InitializeCriticalSection(&proxy->lock);
+    InitializeConditionVariable(&proxy->request_cond);
+    InitializeConditionVariable(&proxy->request_done_cond);
+    InitializeConditionVariable(&proxy->thread_exit_cond);
+#else
+    pthread_mutex_init(&proxy->lock, NULL);
+    pthread_cond_init(&proxy->request_cond, NULL);
+    pthread_cond_init(&proxy->request_done_cond, NULL);
+    pthread_cond_init(&proxy->thread_exit_cond, NULL);
+#endif
+
+    /*
+     * Lazy-init the GC-protection array so create never silently skips it (see
+     * the g_proxy_threads comment above); create runs with the GVL, so safe.
+     */
+    if (g_proxy_threads == Qnil) {
+        g_proxy_threads = rb_ary_new();
+        rb_global_variable(&g_proxy_threads);
+    }
+
+    proxy->ruby_thread = rb_thread_create(proxy_thread_func, proxy);
+    rb_ary_push(g_proxy_threads, proxy->ruby_thread);
+
+    return proxy;
+}
+
+/*
+ * Hand a callback to a proxy and block until it completes.
+ * Called from the DuckDB worker thread (non-Ruby thread) that owns this proxy.
+ */
+static void dispatch_callback_to_proxy(struct worker_proxy *proxy, rbduckdb_function_callback_t cb, void *user_data) {
+#ifdef _MSC_VER
+    EnterCriticalSection(&proxy->lock);
+    proxy->cb = cb;
+    proxy->user_data = user_data;
+    proxy->request_done = 0;
+    proxy->has_request = 1;
+    WakeConditionVariable(&proxy->request_cond);
+    LeaveCriticalSection(&proxy->lock);
+
+    EnterCriticalSection(&proxy->lock);
+    while (!proxy->request_done) {
+        SleepConditionVariableCS(&proxy->request_done_cond, &proxy->lock, INFINITE);
+    }
+    LeaveCriticalSection(&proxy->lock);
+#else
+    pthread_mutex_lock(&proxy->lock);
+    proxy->cb = cb;
+    proxy->user_data = user_data;
+    proxy->request_done = 0;
+    proxy->has_request = 1;
+    pthread_cond_signal(&proxy->request_cond);
+    pthread_mutex_unlock(&proxy->lock);
+
+    pthread_mutex_lock(&proxy->lock);
+    while (!proxy->request_done) {
+        pthread_cond_wait(&proxy->request_done_cond, &proxy->lock);
+    }
+    pthread_mutex_unlock(&proxy->lock);
+#endif
+}
+
+/* Blocks until the proxy thread has fully exited. Runs without the GVL. */
+static void *proxy_join_func(void *data) {
+    struct worker_proxy *proxy = (struct worker_proxy *)data;
+
+#ifdef _MSC_VER
+    EnterCriticalSection(&proxy->lock);
+    while (!proxy->thread_exited) {
+        SleepConditionVariableCS(&proxy->thread_exit_cond, &proxy->lock, INFINITE);
+    }
+    LeaveCriticalSection(&proxy->lock);
+#else
+    pthread_mutex_lock(&proxy->lock);
+    while (!proxy->thread_exited) {
+        pthread_cond_wait(&proxy->thread_exit_cond, &proxy->lock);
+    }
+    pthread_mutex_unlock(&proxy->lock);
+#endif
+
+    return NULL;
+}
+
+void rbduckdb_worker_proxy_destroy(void *data) {
+    struct worker_proxy *proxy = (struct worker_proxy *)data;
+    if (proxy == NULL) return;
+
+    /* Ask the proxy thread to stop. */
+#ifdef _MSC_VER
+    EnterCriticalSection(&proxy->lock);
+    proxy->stop_requested = 1;
+    WakeConditionVariable(&proxy->request_cond);
+    LeaveCriticalSection(&proxy->lock);
+#else
+    pthread_mutex_lock(&proxy->lock);
+    proxy->stop_requested = 1;
+    pthread_cond_signal(&proxy->request_cond);
+    pthread_mutex_unlock(&proxy->lock);
+#endif
+
+    /*
+     * Wait until the proxy thread has fully exited. Before exiting it runs Ruby
+     * code (removing itself from the GC-protection array), which needs the GVL.
+     * DuckDB may invoke this destructor either from a worker thread (no GVL) or
+     * — depending on when it tears down the local state — from a Ruby thread
+     * that holds the GVL. In the latter case we must release the GVL while
+     * waiting, or the proxy thread could never acquire it and we would deadlock.
+     */
+    if (ruby_native_thread_p() && ruby_thread_has_gvl_p()) {
+        rb_thread_call_without_gvl(proxy_join_func, proxy, NULL, NULL);
+    } else {
+        proxy_join_func(proxy);
+    }
+
+    /* The proxy thread is gone; tear down OS primitives and free the struct. */
+#ifdef _MSC_VER
+    DeleteCriticalSection(&proxy->lock);
+#else
+    pthread_cond_destroy(&proxy->thread_exit_cond);
+    pthread_cond_destroy(&proxy->request_done_cond);
+    pthread_cond_destroy(&proxy->request_cond);
+    pthread_mutex_destroy(&proxy->lock);
+#endif
+
+    free(proxy);
+}
+
+void rbduckdb_function_executor_dispatch_via_proxy(rbduckdb_function_callback_t cb, void *user_data, struct worker_proxy *proxy) {
     if (ruby_native_thread_p()) {
         if (ruby_thread_has_gvl_p()) {
             /* Case 1: Ruby thread with GVL - call directly */
@@ -254,8 +553,15 @@ void rbduckdb_function_executor_dispatch(rbduckdb_function_callback_t cb, void *
             arg.user_data = user_data;
             rb_thread_call_with_gvl(callback_with_gvl, &arg);
         }
+    } else if (proxy != NULL) {
+        /* Case 3a: Non-Ruby thread with a per-worker proxy */
+        dispatch_callback_to_proxy(proxy, cb, user_data);
     } else {
-        /* Case 3: Non-Ruby thread - dispatch to executor */
+        /* Case 3b: Non-Ruby thread - dispatch to the global executor */
         dispatch_callback_to_executor(cb, user_data);
     }
 }
+
+void rbduckdb_function_executor_dispatch(rbduckdb_function_callback_t cb, void *user_data) {
+    rbduckdb_function_executor_dispatch_via_proxy(cb, user_data, NULL);
+}

data/ext/duckdb/function_executor.h

@@ -43,4 +43,48 @@ void rbduckdb_function_executor_ensure_started(void);
  */
 void rbduckdb_function_executor_dispatch(rbduckdb_function_callback_t cb, void *user_data);
 
+/*
+ * ============================================================================
+ * Per-worker proxy threads (DuckDB >= 1.5.0)
+ * ============================================================================
+ *
+ * The global executor above serializes every non-Ruby-thread callback through
+ * a single Ruby thread. A per-worker proxy instead gives each DuckDB worker
+ * thread its own dedicated Ruby thread, so callbacks from different workers can
+ * run concurrently — they compete for the GVL in round-robin fashion, which
+ * helps when callbacks release the GVL (e.g. on I/O).
+ *
+ * Proxies are created lazily from DuckDB's per-worker init hook and stored in
+ * DuckDB's thread-local state; the global executor remains the fallback.
+ */
+
+/* Opaque per-worker proxy handle. */
+struct worker_proxy;
+
+/*
+ * Create a per-worker proxy thread. Must be called with the GVL held
+ * (typically by dispatching this through the global executor from a per-worker
+ * init callback, which itself runs on a non-Ruby thread).
+ *
+ * May raise (NoMemError, Thread.new failure). The executor runs callbacks
+ * unprotected, so a wrapper dispatched to it must rb_protect this call —
+ * otherwise a raise longjmps past the executor's done-signaling and the
+ * waiting DuckDB worker blocks forever.
+ */
+struct worker_proxy *rbduckdb_worker_proxy_create(void);
+
+/*
+ * Destroy a per-worker proxy. The signature matches duckdb_delete_callback_t so
+ * it can be handed directly to DuckDB. Safe to call from a non-Ruby thread: it
+ * touches only OS primitives and frees memory allocated with calloc.
+ */
+void rbduckdb_worker_proxy_destroy(void *proxy);
+
+/*
+ * Like rbduckdb_function_executor_dispatch, but on the non-Ruby-thread path
+ * (Case 3) it routes through the given per-worker proxy when non-NULL, falling
+ * back to the global executor when NULL. Cases 1 and 2 are unchanged.
+ */
+void rbduckdb_function_executor_dispatch_via_proxy(rbduckdb_function_callback_t cb, void *user_data, struct worker_proxy *proxy);
+
 #endif

data/ext/duckdb/prepared_statement.c

@@ -34,9 +34,11 @@ static VALUE prepared_statement__bind_uint64(VALUE self, VALUE vidx, VALUE val);
 static VALUE prepared_statement__bind_date(VALUE self, VALUE vidx, VALUE year, VALUE month, VALUE day);
 static VALUE prepared_statement__bind_time(VALUE self, VALUE vidx, VALUE hour, VALUE min, VALUE sec, VALUE micros);
 static VALUE prepared_statement__bind_timestamp(VALUE self, VALUE vidx, VALUE year, VALUE month, VALUE day, VALUE hour, VALUE min, VALUE sec, VALUE micros);
+static VALUE prepared_statement__bind_timestamp_tz(VALUE self, VALUE vidx, VALUE year, VALUE month, VALUE day, VALUE hour, VALUE min, VALUE sec, VALUE micros);
 static VALUE prepared_statement__bind_interval(VALUE self, VALUE vidx, VALUE months, VALUE days, VALUE micros);
 static VALUE prepared_statement__bind_hugeint(VALUE self, VALUE vidx, VALUE lower, VALUE upper);
 static VALUE prepared_statement__bind_uhugeint(VALUE self, VALUE vidx, VALUE lower, VALUE upper);
+static VALUE prepared_statement__bind_uuid(VALUE self, VALUE vidx, VALUE val);
 static VALUE prepared_statement__bind_decimal(VALUE self, VALUE vidx, VALUE lower, VALUE upper, VALUE width, VALUE scale);
 static VALUE prepared_statement__bind_value(VALUE self, VALUE vidx, VALUE val);
 
@@ -471,6 +473,21 @@ static VALUE prepared_statement__bind_timestamp(VALUE self, VALUE vidx, VALUE ye
     return self;
 }
 
+/* :nodoc: */
+static VALUE prepared_statement__bind_timestamp_tz(VALUE self, VALUE vidx, VALUE year, VALUE month, VALUE day, VALUE hour, VALUE min, VALUE sec, VALUE micros) {
+    duckdb_timestamp timestamp_tz;
+    rubyDuckDBPreparedStatement *ctx;
+    idx_t idx = check_index(vidx);
+
+    timestamp_tz = rbduckdb_to_duckdb_timestamp_from_value(year, month, day, hour, min, sec, micros);
+    TypedData_Get_Struct(self, rubyDuckDBPreparedStatement, &prepared_statement_data_type, ctx);
+
+    if (duckdb_bind_timestamp_tz(ctx->prepared_statement, idx, timestamp_tz) == DuckDBError) {
+        rb_raise(eDuckDBError, "fail to bind %llu parameter", (unsigned long long)idx);
+    }
+    return self;
+}
+
 /* :nodoc: */
 static VALUE prepared_statement__bind_interval(VALUE self, VALUE vidx, VALUE months, VALUE days, VALUE micros) {
     duckdb_interval interval;
@@ -542,6 +559,25 @@ static VALUE prepared_statement__bind_decimal(VALUE self, VALUE vidx, VALUE lowe
     return self;
 }
 
+/* :nodoc: */
+static VALUE prepared_statement__bind_uuid(VALUE self, VALUE vidx, VALUE val) {
+    rubyDuckDBPreparedStatement *ctx;
+    duckdb_uhugeint uhugeint;
+    duckdb_value uuid_val;
+    duckdb_state state;
+    idx_t idx = check_index(vidx);
+
+    TypedData_Get_Struct(self, rubyDuckDBPreparedStatement, &prepared_statement_data_type, ctx);
+    rbduckdb_uuid_str_to_uhugeint(val, &uhugeint);
+    uuid_val = duckdb_create_uuid(uhugeint);
+    state = duckdb_bind_value(ctx->prepared_statement, idx, uuid_val);
+    duckdb_destroy_value(&uuid_val);
+    if (state == DuckDBError) {
+        rb_raise(eDuckDBError, "fail to bind %llu parameter", (unsigned long long)idx);
+    }
+    return self;
+}
+
 /* :nodoc: */
 static VALUE prepared_statement__bind_value(VALUE self, VALUE vidx, VALUE val) {
     rubyDuckDBPreparedStatement *ctx;
@@ -597,9 +633,11 @@ void rbduckdb_init_prepared_statement(void) {
     rb_define_private_method(cDuckDBPreparedStatement, "_bind_date", prepared_statement__bind_date, 4);
     rb_define_private_method(cDuckDBPreparedStatement, "_bind_time", prepared_statement__bind_time, 5);
     rb_define_private_method(cDuckDBPreparedStatement, "_bind_timestamp", prepared_statement__bind_timestamp, 8);
+    rb_define_private_method(cDuckDBPreparedStatement, "_bind_timestamp_tz", prepared_statement__bind_timestamp_tz, 8);
     rb_define_private_method(cDuckDBPreparedStatement, "_bind_interval", prepared_statement__bind_interval, 4);
     rb_define_private_method(cDuckDBPreparedStatement, "_bind_hugeint", prepared_statement__bind_hugeint, 3);
     rb_define_private_method(cDuckDBPreparedStatement, "_bind_uhugeint", prepared_statement__bind_uhugeint, 3);
+    rb_define_private_method(cDuckDBPreparedStatement, "_bind_uuid", prepared_statement__bind_uuid, 2);
     rb_define_private_method(cDuckDBPreparedStatement, "_bind_decimal", prepared_statement__bind_decimal, 5);
     rb_define_private_method(cDuckDBPreparedStatement, "_bind_value", prepared_statement__bind_value, 2);
 }

data/ext/duckdb/result.c

@@ -16,13 +16,11 @@ static VALUE result_columns(VALUE oDuckDBResult);
 static VALUE destroy_data_chunk(VALUE arg);
 
 static VALUE result__chunk_stream(VALUE oDuckDBResult);
+static VALUE result_arrow_c_stream(VALUE oDuckDBResult);
 static VALUE yield_rows(VALUE arg);
-static VALUE result__column_type(VALUE oDuckDBResult, VALUE col_idx);
 static VALUE result__return_type(VALUE oDuckDBResult);
 static VALUE result__statement_type(VALUE oDuckDBResult);
 static VALUE result__enum_internal_type(VALUE oDuckDBResult, VALUE col_idx);
-static VALUE result__enum_dictionary_size(VALUE oDuckDBResult, VALUE col_idx);
-static VALUE result__enum_dictionary_value(VALUE oDuckDBResult, VALUE col_idx, VALUE idx);
 
 static VALUE vector_date(void *vector_data, idx_t row_idx);
 static VALUE vector_timestamp(void* vector_data, idx_t row_idx);
@@ -59,15 +57,30 @@ static const rb_data_type_t result_data_type = {
 static void deallocate(void *ctx) {
     rubyDuckDBResult *p = (rubyDuckDBResult *)ctx;
 
-    duckdb_destroy_result(&(p->result));
-    xfree(p);
+    rbduckdb_result_unref(p);
 }
 
 static VALUE allocate(VALUE klass) {
-    rubyDuckDBResult *ctx = xcalloc((size_t)1, sizeof(rubyDuckDBResult));
+    rubyDuckDBResult *ctx = calloc((size_t)1, sizeof(rubyDuckDBResult));
+
+    if (ctx == NULL) {
+        rb_raise(rb_eNoMemError, "failed to allocate DuckDB::Result");
+    }
+    ctx->refcount = 1;
     return TypedData_Wrap_Struct(klass, &result_data_type, ctx);
 }
 
+void rbduckdb_result_ref(rubyDuckDBResult *ctx) {
+    RUBY_ATOMIC_FETCH_ADD(ctx->refcount, 1);
+}
+
+void rbduckdb_result_unref(rubyDuckDBResult *ctx) {
+    if (RUBY_ATOMIC_FETCH_SUB(ctx->refcount, 1) == 1) {
+        duckdb_destroy_result(&(ctx->result));
+        free(ctx);
+    }
+}
+
 static size_t memsize(const void *p) {
     return sizeof(rubyDuckDBResult);
 }
@@ -198,13 +211,6 @@ static VALUE yield_rows(VALUE arg) {
     return Qnil;
 }
 
-/* :nodoc: */
-static VALUE result__column_type(VALUE oDuckDBResult, VALUE col_idx) {
-    rubyDuckDBResult *ctx;
-    TypedData_Get_Struct(oDuckDBResult, rubyDuckDBResult, &result_data_type, ctx);
-    return LL2NUM(duckdb_column_type(&(ctx->result), NUM2LL(col_idx)));
-}
-
 /* :nodoc: */
 static VALUE result__return_type(VALUE oDuckDBResult) {
     rubyDuckDBResult *ctx;
@@ -234,46 +240,10 @@ static VALUE result__enum_internal_type(VALUE oDuckDBResult, VALUE col_idx) {
     return type;
 }
 
-/* :nodoc: */
-static VALUE result__enum_dictionary_size(VALUE oDuckDBResult, VALUE col_idx) {
-    rubyDuckDBResult *ctx;
-    VALUE size = Qnil;
-    duckdb_logical_type logical_type;
-
-    TypedData_Get_Struct(oDuckDBResult, rubyDuckDBResult, &result_data_type, ctx);
-    logical_type = duckdb_column_logical_type(&(ctx->result), NUM2LL(col_idx));
-    if (logical_type) {
-        size = UINT2NUM(duckdb_enum_dictionary_size(logical_type));
-    }
-    duckdb_destroy_logical_type(&logical_type);
-    return size;
-}
-
-/* :nodoc: */
-static VALUE result__enum_dictionary_value(VALUE oDuckDBResult, VALUE col_idx, VALUE idx) {
-    rubyDuckDBResult *ctx;
-    VALUE value = Qnil;
-    duckdb_logical_type logical_type;
-    char *p;
-
-    TypedData_Get_Struct(oDuckDBResult, rubyDuckDBResult, &result_data_type, ctx);
-    logical_type = duckdb_column_logical_type(&(ctx->result), NUM2LL(col_idx));
-    if (logical_type) {
-        p = duckdb_enum_dictionary_value(logical_type, NUM2LL(idx));
-        if (p) {
-            value = rb_utf8_str_new_cstr(p);
-            duckdb_free(p);
-        }
-    }
-    duckdb_destroy_logical_type(&logical_type);
-    return value;
-}
-
 VALUE rbduckdb_create_result(void) {
     return allocate(cDuckDBResult);
 }
 
-
 static VALUE vector_date(void *vector_data, idx_t row_idx) {
     return rbduckdb_date_to_ruby(((duckdb_date *)vector_data)[row_idx]);
 }
@@ -286,7 +256,6 @@ static VALUE vector_time(void* vector_data, idx_t row_idx) {
     return rbduckdb_time_to_ruby(((duckdb_time *)vector_data)[row_idx]);
 }
 
-
 static VALUE vector_interval(void* vector_data, idx_t row_idx) {
     return rbduckdb_interval_to_ruby(((duckdb_interval *)vector_data)[row_idx]);
 }
@@ -694,6 +663,35 @@ static VALUE vector_uuid(void* vector_data, idx_t row_idx) {
     return rbduckdb_uuid_to_ruby(((duckdb_hugeint *)vector_data)[row_idx]);
 }
 
+/*
+ *  call-seq:
+ *    result.arrow_c_stream -> DuckDB::ArrowArrayStream
+ *
+ *  [EXPERIMENTAL] Exports the result as an Arrow C stream
+ *  (Arrow C Data Interface). The returned stream object satisfies the
+ *  Ruby Arrow C stream protocol, so it can be consumed directly by
+ *  ruby-polars, red-arrow and other Arrow consumers:
+ *
+ *    result = con.query('SELECT * FROM users')
+ *    df = Polars::DataFrame.new(result)
+ *
+ *  The stream consumes the result's chunks; a result can be exported
+ *  only once. This API is built on DuckDB's unstable Arrow C API and
+ *  may change in any minor release.
+ */
+static VALUE result_arrow_c_stream(VALUE oDuckDBResult) {
+    rubyDuckDBResult *ctx;
+    VALUE stream;
+
+    TypedData_Get_Struct(oDuckDBResult, rubyDuckDBResult, &result_data_type, ctx);
+    if (ctx->arrow_exported) {
+        rb_raise(eDuckDBError, "result is already exported as an Arrow stream");
+    }
+    stream = rbduckdb_create_arrow_array_stream(oDuckDBResult);
+    ctx->arrow_exported = true;
+    return stream;
+}
+
 static VALUE vector_value(duckdb_vector vector, idx_t row_idx) {
     duckdb_logical_type ty;
     VALUE obj = Qnil;
@@ -718,11 +716,9 @@ void rbduckdb_init_result(void) {
     rb_define_method(cDuckDBResult, "rows_changed", result_rows_changed, 0);
     rb_define_method(cDuckDBResult, "columns", result_columns, 0);
     rb_define_private_method(cDuckDBResult, "_chunk_stream", result__chunk_stream, 0);
-    rb_define_private_method(cDuckDBResult, "_column_type", result__column_type, 1);
+    rb_define_method(cDuckDBResult, "arrow_c_stream", result_arrow_c_stream, 0);
     rb_define_private_method(cDuckDBResult, "_return_type", result__return_type, 0);
     rb_define_private_method(cDuckDBResult, "_statement_type", result__statement_type, 0);
 
     rb_define_private_method(cDuckDBResult, "_enum_internal_type", result__enum_internal_type, 1);
-    rb_define_private_method(cDuckDBResult, "_enum_dictionary_size", result__enum_dictionary_size, 1);
-    rb_define_private_method(cDuckDBResult, "_enum_dictionary_value", result__enum_dictionary_value, 2);
 }

data/ext/duckdb/result.h

@@ -1,13 +1,24 @@
 #ifndef RUBY_DUCKDB_RESULT_H
 #define RUBY_DUCKDB_RESULT_H
 
+/*
+ * Allocated with plain calloc/free and reference-counted: the Ruby Result
+ * object holds one reference, and each exported Arrow stream holds another,
+ * so the duckdb_result stays valid for consumers that outlive the Ruby
+ * objects. rbduckdb_result_unref() must not call any Ruby API: it runs from
+ * GC sweep (deallocate) and from Arrow stream release callbacks.
+ */
 struct _rubyDuckDBResult {
     duckdb_result result;
+    bool arrow_exported;
+    rb_atomic_t refcount;
 };
 
 typedef struct _rubyDuckDBResult rubyDuckDBResult;
 
 rubyDuckDBResult *rbduckdb_get_struct_result(VALUE obj);
+void rbduckdb_result_ref(rubyDuckDBResult *ctx);
+void rbduckdb_result_unref(rubyDuckDBResult *ctx);
 void rbduckdb_init_result(void);
 VALUE rbduckdb_create_result(void);
 VALUE rbduckdb_vector_value_at(duckdb_vector vector, duckdb_logical_type element_type, idx_t index);

data/ext/duckdb/ruby-duckdb.h

@@ -6,6 +6,7 @@
 
 #include "ruby.h"
 #include "ruby/thread.h"
+#include "ruby/atomic.h"
 #include <duckdb.h>
 
 #ifdef HAVE_DUCKDB_UNSAFE_VECTOR_ASSIGN_STRING_ELEMENT_LEN
@@ -38,6 +39,7 @@
 #include "./scalar_function.h"
 #include "./scalar_function_set.h"
 #include "./aggregate_function.h"
+#include "./aggregate_function_set.h"
 #include "./expression.h"
 #include "./client_context.h"
 #include "./scalar_function_bind_info.h"
@@ -49,6 +51,8 @@
 #include "./memory_helper.h"
 #include "./table_function.h"
 #include "./table_description.h"
+#include "./arrow_array_stream.h"
+#include "./arrow_import.h"
 
 extern VALUE mDuckDB;
 extern VALUE cDuckDBDatabase;