duckdb 1.5.2.0 → 1.5.3.0

data/lib/duckdb/aggregate_function.rb

@@ -1,13 +1,159 @@
 # frozen_string_literal: true
 
 module DuckDB
-  # DuckDB::AggregateFunction encapsulates DuckDB's aggregate function.
+  # DuckDB::AggregateFunction lets you register a custom aggregate function
+  # written in Ruby and call it from SQL.
   #
-  # @note DuckDB::AggregateFunction is experimental. Phase 1.0 only supports
-  #   +set_init+ and +set_finalize+; +update+ and +combine+ are internal no-ops.
+  # An aggregate function folds many rows into a single value. You define its
+  # behaviour with four callbacks:
+  #
+  # * +set_init+    — called once per group; returns the initial state.
+  # * +set_update+  — called once per row; receives the current state and the
+  #                   input value(s), returns the new state.
+  # * +set_combine+ — merges two partial states (required for parallel
+  #                   execution); receives source and target states, returns the
+  #                   merged state.
+  # * +set_finalize+ — converts the final state into the SQL result value.
+  #
+  # Only +set_init+ is required. The other three have sensible defaults:
+  # * +set_update+   defaults to +{ |state, *| state }+ (ignore inputs)
+  # * +set_combine+  defaults to +{ |s1, _s2| s1 }+ (keep source state)
+  # * +set_finalize+ defaults to +{ |x| x }+ (return state as-is)
+  #
+  # @note The default +set_combine+ keeps the source state and discards the
+  #   target, which is only correct for single-threaded (single-partition)
+  #   execution. If DuckDB runs the aggregate in parallel it will produce
+  #   wrong results. Always supply an explicit +set_combine+ when the
+  #   aggregate must be parallel-safe.
+  #
+  # == Basic example: custom SUM
+  #
+  #   af = DuckDB::AggregateFunction.new
+  #   af.name        = 'my_sum'
+  #   af.return_type = DuckDB::LogicalType::BIGINT
+  #   af.add_parameter(DuckDB::LogicalType::BIGINT)
+  #
+  #   af.set_init    { 0 }
+  #   af.set_update  { |state, value| state + value }
+  #   af.set_combine { |s1, s2| s1 + s2 }
+  #
+  #   con.register_aggregate_function(af)
+  #   con.query('SELECT my_sum(i) FROM range(100) t(i)').first.first  # => 4950
+  #
+  # == Example: weighted average with Hash state
+  #
+  #   af = DuckDB::AggregateFunction.new
+  #   af.name        = 'weighted_avg'
+  #   af.return_type = DuckDB::LogicalType::DOUBLE
+  #   af.add_parameter(DuckDB::LogicalType::DOUBLE)  # value
+  #   af.add_parameter(DuckDB::LogicalType::DOUBLE)  # weight
+  #
+  #   af.set_init    { { sum: 0.0, weight: 0.0 } }
+  #   af.set_update  { |state, value, weight| { sum: state[:sum] + value * weight, weight: state[:weight] + weight } }
+  #   af.set_combine { |s1, s2| { sum: s1[:sum] + s2[:sum], weight: s1[:weight] + s2[:weight] } }
+  #   af.set_finalize { |state| state[:weight].zero? ? nil : state[:sum] / state[:weight] }
+  #
+  #   con.register_aggregate_function(af)
   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.
+      #
+      # This is a convenience factory that builds and configures an
+      # AggregateFunction without requiring you to set each attribute
+      # separately.
+      #
+      # @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)
+      # @param init [#call] callable that returns the initial per-group state
+      # @param update [#call] callable that folds one row into the state;
+      #   receives +state, *inputs+ and must return the updated state.
+      #   Default: +->( state, *) { state }+ (ignore inputs)
+      # @param combine [#call] callable that merges two partial states;
+      #   receives +source_state, target_state+ and must return the merged
+      #   state. Default: +->(state, _other) { state }+ (keep source only —
+      #   only correct for single-threaded execution)
+      # @param finalize [#call] callable that converts the final state into the
+      #   SQL result value; receives +state+ and must return a value compatible
+      #   with +return_type+.
+      #   Default: +->(state) { state }+ (return state as-is)
+      # @param null_handling [Boolean] when +true+, enables special NULL
+      #   handling so that rows with NULL inputs are passed to +update+ as
+      #   +nil+ instead of being skipped (default: +false+)
+      # @return [DuckDB::AggregateFunction] the configured aggregate function,
+      #   ready to be passed to +Connection#register_aggregate_function+
+      # @raise [ArgumentError] if any of +init+, +update+, +combine+, or
+      #   +finalize+ does not respond to +call+
+      #
+      # == Example: custom SUM
+      #
+      #   af = DuckDB::AggregateFunction.create(
+      #     name:        'my_sum',
+      #     return_type: :bigint,
+      #     params:      [:bigint],
+      #     init:        -> { 0 },
+      #     update:      ->(state, value) { state + value },
+      #     combine:     ->(state, other) { state + other }
+      #   )
+      #   con.register_aggregate_function(af)
+      #   con.query('SELECT my_sum(i) FROM range(100) t(i)').first.first  # => 4950
+      #
+      # == Example: count including NULL values
+      #
+      #   af = DuckDB::AggregateFunction.create(
+      #     name:         'count_with_nulls',
+      #     return_type:  :bigint,
+      #     params:       [:bigint],
+      #     init:         -> { 0 },
+      #     update:       ->(state, _value) { state + 1 },
+      #     combine:      ->(state, other) { state + other },
+      #     null_handling: true
+      #   )
+      def create( # rubocop:disable Metrics/MethodLength, Metrics/ParameterLists, Metrics/AbcSize
+        name:,
+        return_type:,
+        params: [], # rubocop:disable Style/KeywordParametersOrder
+        init:,
+        update: ->(state, *_inputs) { state },
+        combine: ->(state, _other_state) { state },
+        finalize: ->(state) { state },
+        null_handling: false
+      )
+        callable!(:init, init)
+        callable!(:update, update)
+        callable!(:combine, combine)
+        callable!(:finalize, finalize)
+
+        af = AggregateFunction.new
+        af.name = name
+        af.return_type = return_type
+        params.each do |param|
+          af.add_parameter(param)
+        end
+        af.set_init { init.call }
+        af.set_update { |state, *inputs| update.call(state, *inputs) }
+        af.set_combine { |state, other_state| combine.call(state, other_state) }
+        af.set_finalize { |state| finalize.call(state) }
+        af.set_special_handling if null_handling
+        af
+      end
+
+      private
+
+      def callable!(name, arg)
+        raise ArgumentError, "#{name} must respond to `call`" unless arg.respond_to?(:call)
+      end
+    end
+
     # Sets the return type for the aggregate function.
     #
     # @param logical_type [DuckDB::LogicalType | :logical_type_symbol] the return type
@@ -30,6 +176,65 @@ module DuckDB
       _add_parameter(logical_type)
     end
 
+    # Sets the block that initialises the per-group state.
+    # The block takes no arguments and returns the initial state value.
+    # This is the only required callback; defaults for +set_update+,
+    # +set_combine+, and +set_finalize+ are injected automatically on the
+    # first call if those methods have not been called explicitly.
+    #
+    # @note The injected default for +set_combine+ is +{ |s1, _s2| s1 }+, which
+    #   is only correct for single-threaded execution. Always call +set_combine+
+    #   explicitly when the aggregate must be parallel-safe.
+    #
+    # @return [DuckDB::AggregateFunction] self
+    def set_init(&)
+      unless @init_set
+        _set_update { |state, *| state } unless @update_set
+        _set_combine { |s1, _s2| s1 } unless @combine_set
+        _set_finalize { |x| x } unless @finalize_set
+      end
+      _set_init(&)
+      @init_set = true
+    end
+
+    # Sets the block that accumulates one row into the state.
+    # The block receives the current state followed by the input column
+    # value(s) for that row, and must return the updated state.
+    # Default: +{ |state, *| state }+ (ignore inputs, keep state unchanged).
+    # May be called after +set_init+ to override the injected default.
+    #
+    # @return [DuckDB::AggregateFunction] self
+    def set_update(&)
+      @update_set = true
+      _set_update(&)
+    end
+
+    # Sets the block that merges two partial states during parallel execution.
+    # The block receives the source and target states and must return the
+    # merged state.
+    # May be called after +set_init+ to override the injected default.
+    #
+    # @note The default +{ |s1, _s2| s1 }+ is only correct for single-threaded
+    #   execution. Supply an explicit combine block for parallel-safe aggregates.
+    #
+    # @return [DuckDB::AggregateFunction] self
+    def set_combine(&)
+      @combine_set = true
+      _set_combine(&)
+    end
+
+    # Sets the block that converts the final state into the SQL result value.
+    # The block receives the accumulated state and must return a value
+    # compatible with the declared +return_type+.
+    # Default: +{ |x| x }+ (return the state as-is).
+    # May be called after +set_init+ to override the injected default.
+    #
+    # @return [DuckDB::AggregateFunction] self
+    def set_finalize(&)
+      @finalize_set = true
+      _set_finalize(&)
+    end
+
     # Sets special NULL handling for the aggregate function.
     # By default DuckDB skips rows with NULL input values.  Calling this
     # method disables that behaviour so the update callback is invoked even

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.
@@ -93,6 +108,80 @@ module DuckDB
       raise_appender_error('failed to close')
     end
 
+    # :call-seq:
+    #   appender.add_column(column_name) -> self
+    #
+    # Specifies a column to append to, allowing selective column insertion.
+    # Columns not added will use their default values or be computed from
+    # generated column expressions.
+    # Raises DuckDB::Error if the column does not exist in the table.
+    #
+    #   require 'duckdb'
+    #   db = DuckDB::Database.open
+    #   con = db.connect
+    #   con.query('CREATE TABLE t (id UUID PRIMARY KEY DEFAULT uuidv4(), name VARCHAR)')
+    #   appender = con.appender('t')
+    #   appender.add_column('name')
+    #   appender
+    #     .append_varchar('Alice')
+    #     .end_row
+    #     .flush
+    def add_column(column)
+      return self if _add_column(column)
+
+      raise_appender_error('failed to add_column')
+    end
+
+    # :call-seq:
+    #   appender.clear_columns -> self
+    #
+    # Clears the list of columns previously set by #add_column, so that all
+    # columns of the table become active again. Any previously appended rows
+    # are flushed before the column list is reset; if the flush fails (e.g.
+    # a constraint violation), this method raises DuckDB::Error.
+    #
+    #   require 'duckdb'
+    #   db = DuckDB::Database.open
+    #   con = db.connect
+    #   con.query('CREATE TABLE t (id UUID PRIMARY KEY DEFAULT uuidv4(), name VARCHAR)')
+    #   appender = con.appender('t')
+    #   appender.add_column('name')
+    #   appender
+    #     .append_varchar('Alice')
+    #     .end_row
+    #     .flush
+    #   appender.clear_columns
+    #   # all table columns are active again
+    def clear_columns
+      return self if _clear_columns
+
+      raise_appender_error('failed to clear_columns')
+    end
+
+    if DuckDB::Appender.private_method_defined?(:_clear)
+      # :call-seq:
+      #   appender.clear -> self
+      #
+      # Clears all unflushed data from the appender, discarding any appended rows
+      # that have not yet been flushed to the table.
+      #
+      #   require 'duckdb'
+      #   db = DuckDB::Database.open
+      #   con = db.connect
+      #   con.query('CREATE TABLE users (id INTEGER, name VARCHAR)')
+      #   appender = con.appender('users')
+      #   appender
+      #     .append_int32(1)
+      #     .append_varchar('Alice')
+      #     .end_row
+      #     .clear # discards the row above without flushing to the table
+      def clear
+        return self if _clear
+
+        raise_appender_error('failed to clear')
+      end
+    end
+
     # call-seq:
     #   appender.append_bool(val) -> self
     #
@@ -587,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)
 
@@ -595,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'
@@ -648,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.
@@ -34,7 +36,7 @@ module DuckDB
 
     def query_multi_sql(sql)
       stmts = ExtractedStatements.new(self, sql)
-      return query_sql(sql) if stmts.size == 1
+      return _query_sql(sql) if stmts.size == 1
 
       result = nil
       stmts.each do |stmt|
@@ -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
@@ -276,7 +346,6 @@ module DuckDB
     def register_table_function(table_function)
       raise ArgumentError, 'table_function must be a TableFunction' unless table_function.is_a?(TableFunction)
 
-      check_threads
       _register_table_function(table_function)
     end
 
@@ -291,12 +360,10 @@ module DuckDB
     # @param columns [Hash{String => DuckDB::LogicalType}, nil] optional column schema override;
     #   if omitted, the adapter determines the columns (e.g. from headers or inference)
     # @raise [ArgumentError] if no adapter is registered for the object's class
-    # @raise [DuckDB::Error] if threads setting is not 1
     # @return [void]
     #
     # @example Expose a CSV as a table
     #   require 'csv'
-    #   con.execute('SET threads=1')
     #   DuckDB::TableFunction.add_table_adapter(CSV, CSVTableAdapter.new)
     #   csv = CSV.new(File.read('data.csv'), headers: true)
     #   con.expose_as_table(csv, 'csv_table')
@@ -318,18 +385,6 @@ module DuckDB
 
     private
 
-    def check_threads
-      result = execute("SELECT current_setting('threads')")
-      thread_count = result.first.first.to_i
-
-      return unless thread_count > 1
-
-      raise DuckDB::Error,
-            'Functions with Ruby callbacks require single-threaded execution. ' \
-            "Current threads setting: #{thread_count}. " \
-            "Execute 'SET threads=1' before registering functions."
-    end
-
     def run_appender_block(appender, &)
       return appender unless block_given?
 
@@ -338,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/converter.rb

@@ -18,6 +18,7 @@ module DuckDB
     RANGE_UINT64 = 0..18_446_744_073_709_551_615
     RANGE_HUGEINT = (-(1 << 127)..((1 << 127) - 1))
     RANGE_UHUGEINT = (0..((1 << 128) - 1))
+    RANGE_DECIMAL_WIDTH = 1..38
 
     HALF_HUGEINT_BIT = 64
     HALF_HUGEINT = 1 << HALF_HUGEINT_BIT
@@ -122,6 +123,10 @@ module DuckDB
       value >> HALF_HUGEINT_BIT
     end
 
+    def _decimal_width(value)
+      value.to_s('F').gsub(/[^0-9]/, '').length
+    end
+
     def _to_decimal_from_hugeint(width, scale, upper, lower = nil)
       v = lower.nil? ? upper : _to_hugeint_from_vector(lower, upper)
       _to_decimal_from_value(width, scale, v)

data/lib/duckdb/logical_type.rb

@@ -2,8 +2,6 @@
 
 module DuckDB
   class LogicalType # rubocop:disable Metrics/ClassLength
-    RANGE_DECIMAL_WIDTH = 1..38
-
     alias :alias get_alias
     alias :alias= set_alias
 
@@ -171,7 +169,7 @@ module DuckDB
       #   decimal_type.width #=> 18
       #   decimal_type.scale #=> 3
       def create_decimal(width, scale)
-        raise DuckDB::Error, 'width must be between 1 and 38' unless RANGE_DECIMAL_WIDTH.cover?(width)
+        raise DuckDB::Error, 'width must be between 1 and 38' unless Converter::RANGE_DECIMAL_WIDTH.cover?(width)
         raise DuckDB::Error, "scale must be between 0 and width(#{width})" unless (0..width).cover?(scale)
 
         _create_decimal_type(width, scale)