duckdb 1.5.2.1 → 1.5.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4c7c57e0282ec2213b1efb3844445804e5fbbc09e03496f2ba71c1bd24152843
-  data.tar.gz: 9057fa45fafeba0dc2110562f98cd49eecf53ec0f0a48a989756742525c82b4a
+  metadata.gz: 4226fa5e46b5d23fec1fd817577faa2329dced7fa67cedacaa75140849c2de16
+  data.tar.gz: 931c46acf582c8d01057c7a5b81f8356d430d1ed44cfad85ff79fd16a1935664
 SHA512:
-  metadata.gz: 78bbd166f587491085267791ffca949f2b310597f802424b7e0525c8c4f35f345c2362b17b33401bee374601d5f52746d10ac21f60ea8344bd3bf08e28d7f4b5
-  data.tar.gz: 6fc88b5e289ef3451691f57cb404c390b9deabbafddf81e8aedd300121276a9df62b0492559f2602eb4aeaa57ed2a83cc98ccfbef3a728771c34a565a022f78a
+  metadata.gz: e41cee0179f52dab024e361a69725468a7f088a6e5314df76b1d4d5d2b216b687f075c6873a4d294026e29466e99223b79653c6391a8ddf44a574dc0ec1e633e
+  data.tar.gz: 49c1f2218424af2b13009fff358de4ace4050385323d5a6e06dee4c3b301fe8ee4855abbcbd944593b1ada48ec59eabd6af1e963aed3e70085da7f74b9257fd6

data/CHANGELOG.md

@@ -4,6 +4,35 @@ All notable changes to this project will be documented in this file.
 
 # Unreleased
 
+# 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.
+- add `DuckDB::Appender#append_default_to_chunk`.
+- add `DuckDB::TableNameParser` module with shared table name parsing logic (quoting and dot-notation), included by `DuckDB::Appender` and `DuckDB::TableDescription`.
+- add `DuckDB::PreparedStatement#bind_timestamp_tz` to bind a `TIMESTAMP WITH TIME ZONE` (TIMESTAMPTZ) parameter from a `Time` or timestamp string.
+- `DuckDB::AggregateFunction#name=` and `DuckDB::ScalarFunction#name=` now accept Symbol arguments (coerced to String).
+## Breaking Changes
+- `DuckDB::ScalarFunction.create`: `name:` is now a required keyword argument (previously optional with `nil` default). Parameter order changed to `name:, return_type:, ...`.
+- `DuckDB::ScalarFunctionSet#add`: no longer overrides the scalar function's name with the set's name. The individual function must have its own name set before being added to the set.
+- `DuckDB::TableDescription.new`: the 2nd argument now parses dot-notation and quoting:
+  - `'schema.table'` is interpreted as schema-qualified (deprecated; use `schema:` keyword instead).
+  - `'"schema.table"'` or `"'schema.table'"` — quotes are stripped and the name is treated as a literal table name containing a dot.
+- `DuckDB::Appender.new`: the 2nd argument now parses dot-notation and quoting (previously only `Connection#appender` did this):
+  - `'schema.table'` is interpreted as schema-qualified (deprecated; use `schema:` keyword instead).
+  - `'"schema.table"'` or `"'schema.table'"` — quotes are stripped and the name is treated as a literal table name containing a dot.
+- `DuckDB::Connection#appender`: table name parsing (dot-notation, quoting) is now delegated to `DuckDB::Appender.new` internally. Behavior is unchanged — `'schema.table'` has always split on dot in `Connection#appender`. No deprecation warning is emitted.
+- `DuckDB::Connection#appender`: table names surrounded by double or single quotes (e.g. `'"a.b"'` or `"'a.b'"`) are treated as literal table names — the quotes are stripped and no dot-splitting is performed.
+- fix: `Connection#appender('a.b')` no longer emits a misleading deprecation warning (the behavior was not deprecated — it was already the correct behavior).
+- add `DuckDB::Appender.new(con, table, schema: nil, catalog: nil)` keyword argument form.
+- add `DuckDB::Connection#appender(table, schema: nil, catalog: nil)` keyword argument form.
+- deprecate `DuckDB::Result#_column_type(i)` private method. use `columns[i].send(:_type)` instead.
+- `DuckDB::Result#enum_dictionary_values` checks invalid column index.
+- deprecate `DuckDB::Result#_enum_dictionary_size` private method.
+- deprecate `DuckDB::Result#_enum_dictionary_value` private method.
+## Deprecations
+- deprecate `DuckDB::Appender.new(con, schema, table)` 3-positional-argument form. Use `DuckDB::Appender.new(con, table, schema: schema)` instead.
+- deprecate passing dot-notation string (e.g. `'schema.table'`) directly to `DuckDB::Appender.new`. Use `DuckDB::Appender.new(con, table, schema: schema)` instead.
+
 # 1.5.2.1 - 2026-04-24
 
 - add `DuckDB::AggregateFunction.create`.

data/ext/duckdb/aggregate_function.c

@@ -736,6 +736,7 @@ void rbduckdb_init_aggregate_function(void) {
     cDuckDBAggregateFunction = rb_define_class_under(mDuckDB, "AggregateFunction", rb_cObject);
     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);

data/ext/duckdb/aggregate_function_set.c

@@ -0,0 +1,86 @@
+#include "ruby-duckdb.h"
+
+VALUE cDuckDBAggregateFunctionSet;
+
+static void mark(void *);
+static void deallocate(void *);
+static VALUE allocate(VALUE klass);
+static size_t memsize(const void *p);
+static void compact(void *);
+static VALUE aggregate_function_set__initialize(VALUE self, VALUE name);
+static VALUE aggregate_function_set__add(VALUE self, VALUE aggregate_function);
+
+static const rb_data_type_t aggregate_function_set_data_type = {
+    "DuckDB/AggregateFunctionSet",
+    {mark, deallocate, memsize, compact},
+    0, 0, RUBY_TYPED_FREE_IMMEDIATELY
+};
+
+static void mark(void *ctx) {
+    rubyDuckDBAggregateFunctionSet *p = (rubyDuckDBAggregateFunctionSet *)ctx;
+    rb_gc_mark(p->functions);
+}
+
+static void deallocate(void *ctx) {
+    rubyDuckDBAggregateFunctionSet *p = (rubyDuckDBAggregateFunctionSet *)ctx;
+    duckdb_destroy_aggregate_function_set(&(p->aggregate_function_set));
+    xfree(p);
+}
+
+static void compact(void *ctx) {
+    rubyDuckDBAggregateFunctionSet *p = (rubyDuckDBAggregateFunctionSet *)ctx;
+    p->functions = rb_gc_location(p->functions);
+}
+
+static VALUE allocate(VALUE klass) {
+    rubyDuckDBAggregateFunctionSet *ctx = xcalloc((size_t)1, sizeof(rubyDuckDBAggregateFunctionSet));
+    VALUE obj = TypedData_Wrap_Struct(klass, &aggregate_function_set_data_type, ctx);
+    ctx->functions = rb_ary_new();
+    RB_GC_GUARD(ctx->functions);
+    return obj;
+}
+
+static size_t memsize(const void *p) {
+    return sizeof(rubyDuckDBAggregateFunctionSet);
+}
+
+rubyDuckDBAggregateFunctionSet *rbduckdb_get_struct_aggregate_function_set(VALUE obj) {
+    rubyDuckDBAggregateFunctionSet *ctx;
+    TypedData_Get_Struct(obj, rubyDuckDBAggregateFunctionSet, &aggregate_function_set_data_type, ctx);
+    return ctx;
+}
+
+/* :nodoc: */
+static VALUE aggregate_function_set__initialize(VALUE self, VALUE name) {
+    rubyDuckDBAggregateFunctionSet *p;
+
+    TypedData_Get_Struct(self, rubyDuckDBAggregateFunctionSet, &aggregate_function_set_data_type, p);
+    p->aggregate_function_set = duckdb_create_aggregate_function_set(StringValueCStr(name));
+    return self;
+}
+
+/* :nodoc: */
+static VALUE aggregate_function_set__add(VALUE self, VALUE aggregate_function) {
+    rubyDuckDBAggregateFunctionSet *p;
+    rubyDuckDBAggregateFunction *af;
+
+    TypedData_Get_Struct(self, rubyDuckDBAggregateFunctionSet, &aggregate_function_set_data_type, p);
+    af = rbduckdb_get_struct_aggregate_function(aggregate_function);
+
+    if (duckdb_add_aggregate_function_to_set(p->aggregate_function_set, af->aggregate_function) == DuckDBError) {
+        rb_raise(eDuckDBError, "failed to add aggregate function to set (duplicate overload?)");
+    }
+
+    rb_ary_push(p->functions, aggregate_function);
+    return self;
+}
+
+void rbduckdb_init_aggregate_function_set(void) {
+#if 0
+    VALUE mDuckDB = rb_define_module("DuckDB");
+#endif
+    cDuckDBAggregateFunctionSet = rb_define_class_under(mDuckDB, "AggregateFunctionSet", rb_cObject);
+    rb_define_alloc_func(cDuckDBAggregateFunctionSet, allocate);
+    rb_define_private_method(cDuckDBAggregateFunctionSet, "_initialize", aggregate_function_set__initialize, 1);
+    rb_define_private_method(cDuckDBAggregateFunctionSet, "_add", aggregate_function_set__add, 1);
+}

data/ext/duckdb/aggregate_function_set.h

@@ -0,0 +1,14 @@
+#ifndef RUBY_DUCKDB_AGGREGATE_FUNCTION_SET_H
+#define RUBY_DUCKDB_AGGREGATE_FUNCTION_SET_H
+
+struct _rubyDuckDBAggregateFunctionSet {
+    duckdb_aggregate_function_set aggregate_function_set;
+    VALUE functions; /* Ruby Array of AggregateFunction objects — prevents GC collection */
+};
+
+typedef struct _rubyDuckDBAggregateFunctionSet rubyDuckDBAggregateFunctionSet;
+
+void rbduckdb_init_aggregate_function_set(void);
+rubyDuckDBAggregateFunctionSet *rbduckdb_get_struct_aggregate_function_set(VALUE obj);
+
+#endif

data/ext/duckdb/appender.c

@@ -9,7 +9,8 @@ static size_t memsize(const void *p);
 
 static VALUE appender_s_create_query(VALUE klass, VALUE con, VALUE query, VALUE types, VALUE table, VALUE columns);
 
-static VALUE appender_initialize(VALUE klass, VALUE con, VALUE schema, VALUE table);
+static VALUE appender__initialize(VALUE self, VALUE con, VALUE schema, VALUE table);
+static VALUE appender__initialize_ext(VALUE self, VALUE con, VALUE catalog, VALUE schema, VALUE table);
 static VALUE appender_error_message(VALUE self);
 static VALUE appender__append_bool(VALUE self, VALUE val);
 static VALUE appender__append_int8(VALUE self, VALUE val);
@@ -36,6 +37,7 @@ 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_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);
 static VALUE appender__flush(VALUE self);
 
 #ifdef HAVE_DUCKDB_H_GE_V1_5_0
@@ -130,14 +132,14 @@ static VALUE appender_s_create_query(VALUE klass, VALUE con, VALUE query, VALUE
     return appender;
 }
 
-static VALUE appender_initialize(VALUE self, VALUE con, VALUE schema, VALUE table) {
+static VALUE appender__initialize(VALUE self, VALUE con, VALUE schema, VALUE table) {
 
     rubyDuckDBConnection *ctxcon;
     rubyDuckDBAppender *ctx;
     char *pschema = 0;
 
     if (!rb_obj_is_kind_of(con, cDuckDBConnection)) {
-        rb_raise(rb_eTypeError, "1st argument should be instance of DackDB::Connection");
+        rb_raise(rb_eTypeError, "1st argument should be instance of DuckDB::Connection");
     }
 
     TypedData_Get_Struct(self, rubyDuckDBAppender, &appender_data_type, ctx);
@@ -153,6 +155,32 @@ static VALUE appender_initialize(VALUE self, VALUE con, VALUE schema, VALUE tabl
     return self;
 }
 
+static VALUE appender__initialize_ext(VALUE self, VALUE con, VALUE catalog, VALUE schema, VALUE table) {
+    rubyDuckDBConnection *ctxcon;
+    rubyDuckDBAppender *ctx;
+    char *pcatalog = 0;
+    char *pschema = 0;
+
+    if (!rb_obj_is_kind_of(con, cDuckDBConnection)) {
+        rb_raise(rb_eTypeError, "1st argument should be instance of DuckDB::Connection");
+    }
+
+    TypedData_Get_Struct(self, rubyDuckDBAppender, &appender_data_type, ctx);
+    ctxcon = rbduckdb_get_struct_connection(con);
+
+    if (catalog != Qnil) {
+        pcatalog = StringValuePtr(catalog);
+    }
+    if (schema != Qnil) {
+        pschema = StringValuePtr(schema);
+    }
+
+    if (duckdb_appender_create_ext(ctxcon->con, pcatalog, pschema, StringValuePtr(table), &(ctx->appender)) == DuckDBError) {
+        rb_raise(eDuckDBError, "failed to create appender");
+    }
+    return self;
+}
+
 /* call-seq:
  *   appender.error_message -> String
  *
@@ -447,6 +475,17 @@ static VALUE appender__append_data_chunk(VALUE self, VALUE chunk) {
     return state_to_rbool(duckdb_append_data_chunk(ctx->appender, chunk_ctx->data_chunk));
 }
 
+/* :nodoc: */
+static VALUE appender__append_default_to_chunk(VALUE self, VALUE chunk, VALUE col, VALUE row) {
+    rubyDuckDBAppender *ctx;
+    rubyDuckDBDataChunk *chunk_ctx;
+
+    TypedData_Get_Struct(self, rubyDuckDBAppender, &appender_data_type, ctx);
+    chunk_ctx = rbduckdb_get_struct_data_chunk(chunk);
+
+    return state_to_rbool(duckdb_append_default_to_chunk(ctx->appender, chunk_ctx->data_chunk, NUM2ULL(col), NUM2ULL(row)));
+}
+
 /* :nodoc: */
 static VALUE appender__flush(VALUE self) {
     rubyDuckDBAppender *ctx;
@@ -504,7 +543,8 @@ void rbduckdb_init_appender(void) {
     cDuckDBAppender = rb_define_class_under(mDuckDB, "Appender", rb_cObject);
     rb_define_alloc_func(cDuckDBAppender, allocate);
     rb_define_singleton_method(cDuckDBAppender, "create_query", appender_s_create_query, 5);
-    rb_define_method(cDuckDBAppender, "initialize", appender_initialize, 3);
+    rb_define_private_method(cDuckDBAppender, "_initialize", appender__initialize, 3);
+    rb_define_private_method(cDuckDBAppender, "_initialize_ext", appender__initialize_ext, 4);
     rb_define_method(cDuckDBAppender, "error_message", appender_error_message, 0);
     rb_define_private_method(cDuckDBAppender, "_end_row", appender__end_row, 0);
     rb_define_private_method(cDuckDBAppender, "_flush", appender__flush, 0);
@@ -540,4 +580,5 @@ void rbduckdb_init_appender(void) {
     rb_define_private_method(cDuckDBAppender, "_append_uhugeint", appender__append_uhugeint, 2);
     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/connection.c

@@ -15,6 +15,7 @@ static VALUE connection__register_logical_type(VALUE self, VALUE logical_type);
 static VALUE connection__register_scalar_function(VALUE self, VALUE scalar_function);
 static VALUE connection__register_scalar_function_set(VALUE self, VALUE scalar_function_set);
 static VALUE connection__register_aggregate_function(VALUE self, VALUE aggregate_function);
+static VALUE connection__register_aggregate_function_set(VALUE self, VALUE aggregate_function_set);
 static VALUE connection__register_table_function(VALUE self, VALUE table_function);
 
 static const rb_data_type_t connection_data_type = {
@@ -286,6 +287,27 @@ static VALUE connection__register_aggregate_function(VALUE self, VALUE aggregate
     return self;
 }
 
+/* :nodoc: */
+static VALUE connection__register_aggregate_function_set(VALUE self, VALUE aggregate_function_set) {
+    rubyDuckDBConnection *ctxcon;
+    rubyDuckDBAggregateFunctionSet *ctxafs;
+    duckdb_state state;
+
+    ctxcon = rbduckdb_get_struct_connection(self);
+    ctxafs = rbduckdb_get_struct_aggregate_function_set(aggregate_function_set);
+
+    state = duckdb_register_aggregate_function_set(ctxcon->con, ctxafs->aggregate_function_set);
+
+    if (state == DuckDBError) {
+        rb_raise(eDuckDBError, "Failed to register aggregate function set");
+    }
+
+    /* Keep reference to prevent GC while connection is alive */
+    rb_ary_push(ctxcon->registered_functions, aggregate_function_set);
+
+    return self;
+}
+
 static VALUE connection__register_table_function(VALUE self, VALUE table_function) {
     rubyDuckDBConnection *ctxcon;
     rubyDuckDBTableFunction *ctxtf;
@@ -320,6 +342,7 @@ void rbduckdb_init_connection(void) {
     rb_define_private_method(cDuckDBConnection, "_register_scalar_function", connection__register_scalar_function, 1);
     rb_define_private_method(cDuckDBConnection, "_register_scalar_function_set", connection__register_scalar_function_set, 1);
     rb_define_private_method(cDuckDBConnection, "_register_aggregate_function", connection__register_aggregate_function, 1);
+    rb_define_private_method(cDuckDBConnection, "_register_aggregate_function_set", connection__register_aggregate_function_set, 1);
     rb_define_private_method(cDuckDBConnection, "_register_table_function", connection__register_table_function, 1);
     rb_define_private_method(cDuckDBConnection, "_connect", connection__connect, 1);
     rb_define_private_method(cDuckDBConnection, "_query_sql", connection__query_sql, 1);

data/ext/duckdb/duckdb.c

@@ -59,6 +59,7 @@ Init_duckdb_native(void) {
     rbduckdb_init_duckdb_scalar_function();
     rbduckdb_init_duckdb_scalar_function_set();
     rbduckdb_init_aggregate_function();
+    rbduckdb_init_aggregate_function_set();
     rbduckdb_init_expression();
     rbduckdb_init_client_context();
     rbduckdb_init_duckdb_scalar_function_bind_info();

data/ext/duckdb/extconf.rb

@@ -4,13 +4,34 @@ require 'mkmf'
 
 DUCKDB_REQUIRED_VERSION = '1.4.0'
 
+def brew_prefix(formula = nil)
+  cmd = formula ? "brew --prefix #{formula} 2>/dev/null" : 'brew --prefix 2>/dev/null'
+  prefix = `#{cmd}`.chomp
+  prefix.empty? ? nil : prefix
+end
+
+FALLBACK_PREFIXES = %w[/opt/homebrew /opt/homebrew/opt/duckdb /opt/local].freeze
+
+def brew_dirs(subdir)
+  dirs = []
+  dirs << "#{brew_prefix('duckdb')}/#{subdir}" if brew_prefix('duckdb')
+  if (prefix = brew_prefix)
+    dirs << "#{prefix}/#{subdir}"
+    dirs << "#{prefix}/opt/duckdb/#{subdir}"
+  end
+  dirs
+end
+
+def homebrew_include_dirs
+  (brew_dirs('include') + FALLBACK_PREFIXES.map { |p| "#{p}/include" }).uniq
+end
+
+def homebrew_lib_dirs
+  (brew_dirs('lib') + FALLBACK_PREFIXES.map { |p| "#{p}/lib" }).uniq
+end
+
 def check_duckdb_header(header, version)
-  found = find_header(
-    header,
-    '/opt/homebrew/include',
-    '/opt/homebrew/opt/duckdb/include',
-    '/opt/local/include'
-  )
+  found = find_header(header, *homebrew_include_dirs)
   return if found
 
   msg = "#{header} is not found. Install #{header} of duckdb >= #{version}."
@@ -19,13 +40,7 @@ def check_duckdb_header(header, version)
 end
 
 def check_duckdb_library(library, func, version)
-  found = find_library(
-    library,
-    func,
-    '/opt/homebrew/lib',
-    '/opt/homebrew/opt/duckdb/lib',
-    '/opt/local/lib'
-  )
+  found = find_library(library, func, *homebrew_lib_dirs)
   have_func(func, 'duckdb.h')
   return if found
 

data/ext/duckdb/prepared_statement.c

@@ -34,6 +34,7 @@ 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);
@@ -471,6 +472,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;
@@ -597,6 +613,7 @@ 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);

data/ext/duckdb/result.c

@@ -17,12 +17,9 @@ static VALUE destroy_data_chunk(VALUE arg);
 
 static VALUE result__chunk_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);
@@ -198,13 +195,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 +224,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 +240,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]);
 }
@@ -718,11 +671,8 @@ 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_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/ruby-duckdb.h

@@ -38,6 +38,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"

data/lib/duckdb/aggregate_function.rb

@@ -57,6 +57,12 @@ module DuckDB
   class AggregateFunction
     include FunctionTypeValidation
 
+    def name=(value)
+      set_name(value.to_s)
+    end
+
+    private :set_name
+
     class << self
       # Creates a new AggregateFunction in a single call.
       #
@@ -64,7 +70,7 @@ module DuckDB
       # AggregateFunction without requiring you to set each attribute
       # separately.
       #
-      # @param name [String] the SQL function name
+      # @param name [String, Symbol] the SQL function name
       # @param return_type [DuckDB::LogicalType | Symbol] the SQL return type
       # @param params [Array<DuckDB::LogicalType | Symbol>] input parameter types
       #   (empty array for a zero-argument aggregate)

data/lib/duckdb/aggregate_function_set.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module DuckDB
+  # DuckDB::AggregateFunctionSet encapsulates DuckDB's aggregate function set,
+  # which allows registering multiple overloads of an aggregate function under one name.
+  #
+  # @note DuckDB::AggregateFunctionSet is experimental.
+  class AggregateFunctionSet
+    # @param name [String, Symbol] the function set name shared by all overloads
+    # @raise [TypeError] if name is not a String or Symbol
+    def initialize(name)
+      raise TypeError, "#{name.class} is not a String or Symbol" unless name.is_a?(String) || name.is_a?(Symbol)
+
+      _initialize(name.to_s)
+    end
+
+    # @param aggregate_function [DuckDB::AggregateFunction] the overload to add
+    # @return [self]
+    # @raise [TypeError] if aggregate_function is not a DuckDB::AggregateFunction
+    # @raise [DuckDB::Error] if the overload already exists in the set
+    def add(aggregate_function)
+      unless aggregate_function.is_a?(DuckDB::AggregateFunction)
+        raise TypeError, "#{aggregate_function.class} is not a DuckDB::AggregateFunction"
+      end
+
+      _add(aggregate_function)
+    end
+  end
+end

data/lib/duckdb/appender.rb

@@ -7,6 +7,11 @@ require_relative 'converter'
 module DuckDB
   # The DuckDB::Appender encapsulates DuckDB Appender.
   #
+  # The +table+ argument (2nd positional argument) supports dot-notation and quoting:
+  #
+  # - <tt>'schema.table'</tt> — interpreted as schema-qualified (deprecated; use +schema:+ instead)
+  # - <tt>'"schema.table"'</tt> or <tt>"'schema.table'"</tt> — treated as a literal table name containing a dot
+  #
   #   require 'duckdb'
   #   db = DuckDB::Database.open
   #   con = db.connect
@@ -15,11 +20,21 @@ module DuckDB
   #   appender.append_row(1, 'Alice')
   class Appender
     include DuckDB::Converter
+    include DuckDB::TableNameParser
 
     class << self
       alias from_query create_query
     end
 
+    def initialize(con, table_or_schema, table = nil, schema: nil, catalog: nil)
+      if table
+        warn_deprecated_3arg
+        _initialize(con, table_or_schema, table)
+      else
+        initialize_with_parsed_table(con, table_or_schema, schema: schema, catalog: catalog)
+      end
+    end
+
     # :call-seq:
     #   appender.begin_row -> self
     # A nop method, provided for backwards compatibility reasons.
@@ -661,6 +676,20 @@ module DuckDB
 
     # call-seq:
     #   appender.append_data_chunk(chunk) -> self
+    #
+    # Appends a pre-filled DuckDB::DataChunk to the appender.
+    #
+    #   require 'duckdb'
+    #   db = DuckDB::Database.open
+    #   con = db.connect
+    #   con.query('CREATE TABLE users (id INTEGER, name VARCHAR)')
+    #   appender = con.appender('users')
+    #   chunk = DuckDB::DataChunk.new([DuckDB::LogicalType::INTEGER, DuckDB::LogicalType::VARCHAR])
+    #   chunk.set_value(0, 0, 1)
+    #   chunk.set_value(1, 0, 'Alice')
+    #   chunk.size = 1
+    #   appender.append_data_chunk(chunk)
+    #   appender.flush
     def append_data_chunk(chunk)
       raise ArgumentError, "expected DuckDB::DataChunk, got #{chunk.class}" unless chunk.is_a?(DuckDB::DataChunk)
 
@@ -669,6 +698,34 @@ module DuckDB
       raise_appender_error('failed to append_data_chunk')
     end
 
+    # call-seq:
+    #   appender.append_default_to_chunk(chunk, col, row) -> self
+    #
+    # Appends the DEFAULT value for the column at +col+ and +row+ in +chunk+.
+    # If no DEFAULT is defined for the column, NULL is used.
+    # Call this before appending the chunk via #append_data_chunk.
+    #
+    #   require 'duckdb'
+    #   db = DuckDB::Database.open
+    #   con = db.connect
+    #   con.query('CREATE TABLE users (name VARCHAR, enabled BOOLEAN DEFAULT TRUE)')
+    #   appender = con.appender('users')
+    #   chunk = DuckDB::DataChunk.new([DuckDB::LogicalType::VARCHAR, DuckDB::LogicalType::BOOLEAN])
+    #   appender.append_default_to_chunk(chunk, 1, 0)  # enabled DEFAULT for row 0
+    #   appender.append_default_to_chunk(chunk, 1, 1)  # enabled DEFAULT for row 1
+    #   chunk.set_value(0, 0, 'Alice')
+    #   chunk.set_value(0, 1, 'Bob')
+    #   chunk.size = 2
+    #   appender.append_data_chunk(chunk)
+    #   appender.flush
+    def append_default_to_chunk(chunk, col, row)
+      raise ArgumentError, "expected DuckDB::DataChunk, got #{chunk.class}" unless chunk.is_a?(DuckDB::DataChunk)
+
+      return self if _append_default_to_chunk(chunk, col, row)
+
+      raise_appender_error('failed to append_default_to_chunk')
+    end
+
     # appends value.
     #
     #   require 'duckdb'
@@ -722,6 +779,23 @@ module DuckDB
 
     private
 
+    def warn_deprecated_3arg # :nodoc:
+      warn(
+        'DuckDB::Appender.new(con, schema, table) is deprecated. ' \
+        'Use DuckDB::Appender.new(con, table, schema: schema) instead.',
+        category: :deprecated
+      )
+    end
+
+    def initialize_with_parsed_table(con, table_name, schema:, catalog:) # :nodoc:
+      table_name, schema, catalog = parse_table_name(table_name, schema, catalog)
+      if catalog
+        _initialize_ext(con, catalog, schema, table_name)
+      else
+        _initialize(con, schema, table_name)
+      end
+    end
+
     def raise_appender_error(default_message) # :nodoc:
       message = error_message
       raise DuckDB::Error, message || default_message

data/lib/duckdb/connection.rb

@@ -8,6 +8,8 @@ module DuckDB
   #   con = db.connect
   #   con.query(sql)
   class Connection
+    include DuckDB::TableNameParser
+
     # executes sql with args.
     # The first argument sql must be SQL string.
     # The rest arguments are parameters of SQL string.
@@ -127,11 +129,43 @@ module DuckDB
       PreparedStatement.prepare(self, str, &)
     end
 
-    # returns Appender object.
-    # The first argument is table name
-    def appender(table, &)
-      appender = create_appender(table)
-      run_appender_block(appender, &)
+    # :call-seq:
+    #   connection.appender(table, schema: nil, catalog: nil) -> DuckDB::Appender
+    #   connection.appender(table, schema: nil, catalog: nil) { |appender| ... } -> self
+    #
+    # Returns a DuckDB::Appender for bulk-inserting rows into +table+.
+    # If a block is given, the appender is flushed and closed automatically after the block.
+    #
+    # +schema:+ and +catalog:+ optionally qualify the table.
+    #
+    # Raises DuckDB::Error if the table (or schema/catalog) does not exist.
+    #
+    # Table name parsing (quoting, dot-notation) is handled by DuckDB::Appender.new.
+    # See DuckDB::Appender.new for details on quoting and dot-notation.
+    #
+    #   require 'duckdb'
+    #   db = DuckDB::Database.open
+    #   con = db.connect
+    #   con.query('CREATE TABLE users (id INTEGER, name VARCHAR)')
+    #
+    #   # block form (recommended) — flushes and closes automatically
+    #   con.appender('users') do |a|
+    #     a.append_row(1, 'Alice')
+    #     a.append_row(2, 'Bob')
+    #   end
+    #
+    #   # with schema
+    #   con.appender('users', schema: 'main') do |a|
+    #     a.append_row(3, 'Carol')
+    #   end
+    #
+    #   # manual form
+    #   appender = con.appender('users')
+    #   appender.append_row(4, 'Dave')
+    #   appender.close
+    def appender(table, schema: nil, catalog: nil, &)
+      table, schema, catalog = parse_connection_appender_table(table, schema, catalog)
+      run_appender_block(Appender.new(self, table, schema: schema, catalog: catalog), &)
     end
 
     if Appender.respond_to?(:create_query)
@@ -234,7 +268,7 @@ module DuckDB
     # allowing DuckDB to dispatch to the correct implementation based on argument types.
     #
     # @param scalar_function_set [DuckDB::ScalarFunctionSet] the function set to register
-    # @return [void]
+    # @return [self]
     # @raise [TypeError] if argument is not a DuckDB::ScalarFunctionSet
     #
     # @example Register multiple overloads under one name
@@ -251,6 +285,42 @@ module DuckDB
       _register_scalar_function_set(scalar_function_set)
     end
 
+    # Registers an aggregate function set with the connection.
+    # An aggregate function set groups multiple overloads of an aggregate function under one name,
+    # allowing DuckDB to dispatch to the correct implementation based on argument types.
+    #
+    # @param aggregate_function_set [DuckDB::AggregateFunctionSet] the function set to register
+    # @return [self]
+    # @raise [TypeError] if argument is not a DuckDB::AggregateFunctionSet
+    #
+    # @example Register multiple overloads under one name
+    #   af_bigint = DuckDB::AggregateFunction.new
+    #   af_bigint.name = 'my_sum'
+    #   af_bigint.return_type = DuckDB::LogicalType::BIGINT
+    #   af_bigint.add_parameter(DuckDB::LogicalType::BIGINT)
+    #   af_bigint.set_init   { 0 }
+    #   af_bigint.set_update  { |state, val| state + val }
+    #   af_bigint.set_combine { |s1, s2| s1 + s2 }
+    #
+    #   af_double = DuckDB::AggregateFunction.new
+    #   af_double.name = 'my_sum'
+    #   af_double.return_type = DuckDB::LogicalType::DOUBLE
+    #   af_double.add_parameter(DuckDB::LogicalType::DOUBLE)
+    #   af_double.set_init   { 0.0 }
+    #   af_double.set_update  { |state, val| state + val }
+    #   af_double.set_combine { |s1, s2| s1 + s2 }
+    #
+    #   set = DuckDB::AggregateFunctionSet.new(:my_sum)
+    #   set.add(af_bigint).add(af_double)
+    #   con.register_aggregate_function_set(set)
+    def register_aggregate_function_set(aggregate_function_set)
+      unless aggregate_function_set.is_a?(AggregateFunctionSet)
+        raise TypeError, "#{aggregate_function_set.class} is not a DuckDB::AggregateFunctionSet"
+      end
+
+      _register_aggregate_function_set(aggregate_function_set)
+    end
+
     # Registers an aggregate function with the connection.
     #
     # @param aggregate_function [DuckDB::AggregateFunction] the aggregate function to register
@@ -323,9 +393,15 @@ module DuckDB
       appender.close
     end
 
-    def create_appender(table)
-      t1, t2 = table.split('.')
-      t2 ? Appender.new(self, t1, t2) : Appender.new(self, t2, t1)
+    # Silently pre-parses dot-notation so Appender.new receives clean values
+    # and does not emit a misleading "DuckDB::Appender.new" warning.
+    # con.appender('a.b') has always split on dot — no warning needed.
+    # Quoted table names pass through unchanged for Appender.new to handle.
+    def parse_connection_appender_table(table, schema, catalog)
+      return [table, schema, catalog] if quoted_table_name?(table)
+      return [table, schema, catalog] unless table.include?('.')
+
+      dot_notation_split(table, schema, catalog)
     end
 
     alias execute query

data/lib/duckdb/prepared_statement.rb

@@ -250,6 +250,24 @@ module DuckDB
       _bind_timestamp(index, time.year, time.month, time.day, time.hour, time.min, time.sec, time.usec)
     end
 
+    # binds i-th parameter of TIMESTAMP WITH TIME ZONE (TIMESTAMPTZ) type with SQL prepared statement.
+    # The first argument is index of parameter.
+    # The index of first parameter is 1 not 0.
+    # The second argument value is to expected time value.
+    #
+    #   require 'duckdb'
+    #   db = DuckDB::Database.open('duckdb_database')
+    #   con = db.connect
+    #   sql ='SELECT name FROM users WHERE created_at = ?'
+    #   stmt = PreparedStatement.new(con, sql)
+    #   stmt.bind_timestamp_tz(1, Time.now)
+    #   #  or you can specify timestamp string.
+    #   # stmt.bind_timestamp_tz(1, '2022-02-23 07:39:45+00')
+    def bind_timestamp_tz(index, value)
+      time = _parse_time(value).utc
+      _bind_timestamp_tz(index, time.year, time.month, time.day, time.hour, time.min, time.sec, time.usec)
+    end
+
     # binds i-th parameter with SQL prepared statement.
     # The first argument is index of parameter.
     # The index of first parameter is 1 not 0.

data/lib/duckdb/result.rb

@@ -81,11 +81,48 @@ module DuckDB
     #   result = con.query('SELECT * FROM enums')
     #   result.enum_dictionary_values(1) # => ['sad', 'ok', 'happy', '𝘾𝝾օɭ 😎']
     def enum_dictionary_values(col_index)
+      column = columns[col_index]
+
+      raise ArgumentError, "Invalid index: #{col_index}" if column.nil? || col_index.negative?
+
+      lt = column.logical_type
+
+      raise DuckDB::Error, "Column[#{col_index}] type is not enum" if lt.type != :enum
+
       values = []
-      _enum_dictionary_size(col_index).times do |i|
-        values << _enum_dictionary_value(col_index, i)
+      lt.dictionary_size.times do |i|
+        values << lt.dictionary_value_at(i)
       end
       values
     end
+
+    private
+
+    def _enum_dictionary_size(idx)
+      warn(":_enum_dictionary_size is deprecated. use columns[#{idx}].logical_type.dictionary_size instead.")
+
+      raise ArgumentError, "Invalid index: #{idx}" if idx.negative?
+
+      columns[idx]&.logical_type&.dictionary_size
+    end
+
+    def _enum_dictionary_value(col_index, idx)
+      warn(":_enum_dictionary_value is deprecated.\
+           use columns[#{col_index}].logical_type.dictionary_value_at(#{idx}) instead.")
+
+      raise ArgumentError, "Invalid index: #{col_index}" if col_index.negative?
+
+      lt = columns[col_index]&.logical_type
+
+      raise DuckDB::Error, "Column[#{col_index}] type is not enum" if lt&.type != :enum
+
+      lt.dictionary_value_at(idx)
+    end
+
+    def _column_type(idx)
+      warn(":_column_type is deprecated. use columns[#{idx}].send(:_type) instead.")
+
+      columns[idx].send(:_type)
+    end
   end
 end

data/lib/duckdb/scalar_function.rb

@@ -7,8 +7,7 @@ module DuckDB
   class ScalarFunction
     # Create and configure a scalar function in one call
     #
-    # @param name [String, Symbol, nil] the function name; use +nil+ when creating overloads
-    #   intended for use in a +DuckDB::ScalarFunctionSet+ (the set provides the name)
+    # @param name [String, Symbol] the function name (required)
     # @param return_type [DuckDB::LogicalType|:logical_type_symbol] the return type
     # @param parameter_type [DuckDB::LogicalType|:logical_type_symbol, nil] single fixed parameter type
     # @param parameter_types [Array<DuckDB::LogicalType|:logical_type_symbol>, nil] multiple fixed parameter types
@@ -64,7 +63,7 @@ module DuckDB
     #     null_handling: true
     #   ) { |v| v.nil? ? 0 : v }
     def self.create( # rubocop:disable Metrics/MethodLength,Metrics/CyclomaticComplexity,Metrics/PerceivedComplexity,Metrics/ParameterLists
-      return_type:, name: nil, parameter_type: nil, parameter_types: nil, varargs_type: nil, null_handling: false, &
+      name:, return_type:, parameter_type: nil, parameter_types: nil, varargs_type: nil, null_handling: false, &
     )
       raise ArgumentError, 'Block required' unless block_given?
       raise ArgumentError, 'Cannot specify both parameter_type and parameter_types' if parameter_type && parameter_types
@@ -78,7 +77,7 @@ module DuckDB
                end
 
       sf = new
-      sf.name = name.to_s if name
+      sf.name = name
       sf.return_type = return_type
       params.each { |type| sf.add_parameter(type) }
       sf.varargs_type = varargs_type if varargs_type
@@ -87,6 +86,12 @@ module DuckDB
       sf
     end
 
+    def name=(value)
+      set_name(value.to_s)
+    end
+
+    private :set_name
+
     include FunctionTypeValidation
 
     # Adds a parameter to the scalar function.

data/lib/duckdb/scalar_function_set.rb

@@ -24,7 +24,6 @@ module DuckDB
         raise TypeError, "#{scalar_function.class} is not a DuckDB::ScalarFunction"
       end
 
-      scalar_function.name = @name
       _add(scalar_function)
     end
   end

data/lib/duckdb/table_description.rb

@@ -21,11 +21,17 @@ module DuckDB
     #   # id: integer, default=false
     #   # name: varchar, default=true
     class TableDescription
+      include DuckDB::TableNameParser
+
       # Creates a new TableDescription for the given table.
       #
       # +con+ must be a DuckDB::Connection. +table+ is the table name (String).
       # Optionally pass +schema:+ and/or +catalog:+ to qualify the table.
       #
+      # The +table+ argument supports dot-notation and quoting:
+      # - <tt>'schema.table'</tt> — interpreted as schema-qualified (deprecated; use +schema:+ instead)
+      # - <tt>'"a.b"'</tt> or <tt>"'a.b'"</tt> — treated as a literal table name containing a dot
+      #
       # Raises DuckDB::Error if the connection is invalid, the table name is nil,
       # or the table (or schema/catalog) does not exist.
       #
@@ -40,6 +46,7 @@ module DuckDB
         raise DuckDB::Error, '1st argument must be DuckDB::Connection object.' unless con.is_a?(DuckDB::Connection)
         raise DuckDB::Error, '2nd argument must be table name.' if table.nil?
 
+        table, schema, catalog = parse_table_name(table, schema, catalog)
         raise DuckDB::Error, error_message unless _initialize(con, catalog, schema, table)
       end
 

data/lib/duckdb/table_name_parser.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module DuckDB
+  # DuckDB::TableNameParser provides shared table name parsing for classes that
+  # accept a table name argument, such as DuckDB::Appender and DuckDB::TableDescription.
+  #
+  # It handles:
+  # - Dot-notation: <tt>'schema.table'</tt> is split into schema and table (deprecated).
+  # - Quoting: <tt>'"a.b"'</tt> or <tt>"'a.b'"</tt> strips the quotes and treats the name literally.
+  module TableNameParser
+    private
+
+    # Parses +table+, +schema+, and +catalog+, handling quoting and dot-notation.
+    # Returns <tt>[table, schema, catalog]</tt>.
+    def parse_table_name(table, schema, catalog)
+      if quoted_table_name?(table)
+        [unquote_table_name(table), schema, catalog]
+      elsif table.include?('.')
+        warn_dot_notation_deprecated(table)
+        dot_notation_split(table, schema, catalog)
+      else
+        [table, schema, catalog]
+      end
+    end
+
+    def quoted_table_name?(name) # :nodoc:
+      name.match?(/\A(["']).*\1\z/)
+    end
+
+    def unquote_table_name(name) # :nodoc:
+      name[1..-2]
+    end
+
+    # Splits a dot-notation string into [table, schema, catalog].
+    # Explicit keyword args take precedence over dot-notation parts.
+    def dot_notation_split(table, schema, catalog) # :nodoc:
+      parts = table.split('.')
+      raise ArgumentError, "Too many dot-separated segments in '#{table}'" if parts.length > 3
+
+      case parts.length
+      when 2 then [parts[1], schema || parts[0], catalog]
+      when 3 then [parts[2], schema || parts[1], catalog || parts[0]]
+      else raise ArgumentError, "Unexpected segment count in '#{table}'"
+      end
+    end
+
+    def warn_dot_notation_deprecated(table) # :nodoc:
+      class_name = self.class.name
+      warn(
+        "Passing dot-notation '#{table}' to #{class_name}.new is deprecated. " \
+        "If '#{table}' is a schema-qualified table, use #{class_name}.new(con, table, schema: schema) instead. " \
+        "If '#{table}' is a literal table name containing a dot, " \
+        "use #{class_name}.new(con, '\"#{table}\"') instead.",
+        category: :deprecated
+      )
+    end
+  end
+end

data/lib/duckdb/version.rb

@@ -3,5 +3,5 @@
 module DuckDB
   # The version string of ruby-duckdb.
   # Currently, ruby-duckdb is NOT semantic versioning.
-  VERSION = '1.5.2.1'
+  VERSION = '1.5.3.0'
 end

data/lib/duckdb.rb

@@ -4,6 +4,7 @@ require 'duckdb/duckdb_native'
 require 'duckdb/library_version'
 require 'duckdb/version'
 require 'duckdb/converter'
+require 'duckdb/table_name_parser'
 require 'duckdb/database'
 require 'duckdb/connection'
 require 'duckdb/extracted_statements'
@@ -18,6 +19,7 @@ require 'duckdb/function_type_validation'
 require 'duckdb/scalar_function'
 require 'duckdb/scalar_function_set'
 require 'duckdb/aggregate_function'
+require 'duckdb/aggregate_function_set'
 require 'duckdb/expression'
 require 'duckdb/client_context'
 require 'duckdb/scalar_function/bind_info'

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: duckdb
 version: !ruby/object:Gem::Version
-  version: 1.5.2.1
+  version: 1.5.3.0
 platform: ruby
 authors:
 - Masaki Suketa
@@ -43,6 +43,8 @@ files:
 - duckdb.gemspec
 - ext/duckdb/aggregate_function.c
 - ext/duckdb/aggregate_function.h
+- ext/duckdb/aggregate_function_set.c
+- ext/duckdb/aggregate_function_set.h
 - ext/duckdb/appender.c
 - ext/duckdb/appender.h
 - ext/duckdb/blob.c
@@ -110,6 +112,7 @@ files:
 - ext/duckdb/vector.h
 - lib/duckdb.rb
 - lib/duckdb/aggregate_function.rb
+- lib/duckdb/aggregate_function_set.rb
 - lib/duckdb/appender.rb
 - lib/duckdb/casting.rb
 - lib/duckdb/client_context.rb
@@ -140,6 +143,7 @@ files:
 - lib/duckdb/table_function/bind_info.rb
 - lib/duckdb/table_function/function_info.rb
 - lib/duckdb/table_function/init_info.rb
+- lib/duckdb/table_name_parser.rb
 - lib/duckdb/value.rb
 - lib/duckdb/vector.rb
 - lib/duckdb/version.rb
@@ -165,7 +169,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.6
+rubygems_version: 4.0.10
 specification_version: 4
 summary: Ruby bindings for the DuckDB database engine.
 test_files: []