duckdb 1.2.0.0 → 1.2.2.0

data/lib/duckdb/appender.rb

@@ -203,27 +203,235 @@ module DuckDB
     end
 
     # call-seq:
-    #  appender.append_uint8(val) -> self
+    #   appender.append_uint8(val) -> self
     #
     # Appends an uint8 value to the current row in the appender.
     #
-    #  require 'duckdb'
-    #  db = DuckDB::Database.open
-    #  con = db.connect
-    #  con.query('CREATE TABLE users (id INTEGER, age UTINYINT)')
-    #  appender = con.appender('users')
-    #  appender
-    #    .append_int32(1)
-    #    .append_uint8(20)
-    #    .end_row
-    #    .flush
+    #   require 'duckdb'
+    #   db = DuckDB::Database.open
+    #   con = db.connect
+    #   con.query('CREATE TABLE users (id INTEGER, age UTINYINT)')
+    #   appender = con.appender('users')
+    #   appender
+    #     .append_int32(1)
+    #     .append_uint8(20)
+    #     .end_row
+    #     .flush
     def append_uint8(value)
       return self if _append_uint8(value)
 
       raise_appender_error('failed to append_uint8')
     end
 
-    # appends huge int value.
+    # call-seq:
+    #   appender.append_uint16(val) -> self
+    #
+    # Appends an uint16 value to the current row in the appender.
+    #
+    #   require 'duckdb'
+    #   db = DuckDB::Database.open
+    #   con = db.connect
+    #   con.query('CREATE TABLE users (id INTEGER, age USMALLINT)')
+    #   appender = con.appender('users')
+    #   appender
+    #     .append_int32(1)
+    #     .append_uint16(20)
+    #     .end_row
+    #     .flush
+    def append_uint16(value)
+      return self if _append_uint16(value)
+
+      raise_appender_error('failed to append_uint16')
+    end
+
+    # call-seq:
+    #   appender.append_uint32(val) -> self
+    #
+    # Appends an uint32 value to the current row in the appender.
+    #
+    #   require 'duckdb'
+    #   db = DuckDB::Database.open
+    #   con = db.connect
+    #   con.query('CREATE TABLE users (id INTEGER, age UINTEGER)')
+    #   appender = con.appender('users')
+    #   appender
+    #     .append_int32(1)
+    #     .append_uint32(20)
+    #     .end_row
+    #     .flush
+    def append_uint32(value)
+      return self if _append_uint32(value)
+
+      raise_appender_error('failed to append_uint32')
+    end
+
+    # call-seq:
+    #   appender.append_uint64(val) -> self
+    #
+    # Appends an uint64 value to the current row in the appender.
+    #
+    #   require 'duckdb'
+    #   db = DuckDB::Database.open
+    #   con = db.connect
+    #   con.query('CREATE TABLE users (id INTEGER, age UBIGINT)')
+    #   appender = con.appender('users')
+    #   Appender
+    #     .append_int32(1)
+    #     .append_uint64(20)
+    #     .end_row
+    #     .flush
+    def append_uint64(value)
+      return self if _append_uint64(value)
+
+      raise_appender_error('failed to append_uint64')
+    end
+
+    # call-seq:
+    #   appender.append_float(val) -> self
+    #
+    # Appends a float value to the current row in the appender.
+    #
+    #   require 'duckdb'
+    #   db = DuckDB::Database.open
+    #   con = db.connect
+    #   con.query('CREATE TABLE numbers (num FLOAT)')
+    #   appender = con.appender('numbers')
+    #   appender
+    #     .append_float(1.23)
+    #     .end_row
+    #     .flush
+    def append_float(value)
+      return self if _append_float(value)
+
+      raise_appender_error('failed to append_float')
+    end
+
+    # call-seq:
+    #   appender.append_double(val) -> self
+    #
+    # Appends a double value to the current row in the appender.
+    #
+    #   require 'duckdb'
+    #   db = DuckDB::Database.open
+    #   con = db.connect
+    #   con.query('CREATE TABLE numbers (num DOUBLE)')
+    #   appender = con.appender('numbers')
+    #   appender
+    #     .append_double(1.23)
+    #     .end_row
+    #     .flush
+    def append_double(value)
+      return self if _append_double(value)
+
+      raise_appender_error('failed to append_double')
+    end
+
+    # call-seq:
+    #   appender.append_varchar(val) -> self
+    #
+    # Appends a varchar value to the current row in the appender.
+    #
+    #   require 'duckdb'
+    #   db = DuckDB::Database.open
+    #   con = db.connect
+    #   con.query('CREATE TABLE names (name VARCHAR)')
+    #   appender = con.appender('names')
+    #   appender
+    #     .append_varchar('Alice')
+    #     .end_row
+    #     .flush
+    def append_varchar(value)
+      return self if _append_varchar(value)
+
+      raise_appender_error('failed to append_varchar')
+    end
+
+    # call-seq:
+    #   appender.append_varchar_length(val, len) -> self
+    #
+    # Appends a varchar value to the current row in the appender.
+    #
+    #   require 'duckdb'
+    #   db = DuckDB::Database.open
+    #   con = db.connect
+    #   con.query('CREATE TABLE names (name VARCHAR)')
+    #   appender = con.appender('names')
+    #   appender
+    #     .append_varchar_length('Alice', 5)
+    #     .end_row
+    #     .flush
+    def append_varchar_length(value, length)
+      return self if _append_varchar_length(value, length)
+
+      raise_appender_error('failed to append_varchar_length')
+    end
+
+    # call-seq:
+    #   appender.append_blob(val) -> self
+    #
+    # Appends a varchar value to the current row in the appender.
+    #
+    #   require 'duckdb'
+    #   db = DuckDB::Database.open
+    #   con = db.connect
+    #   con.query('CREATE TABLE values (value BLOB)')
+    #   appender = con.appender('values')
+    #   appender
+    #     .append('\0\1\2\3\4\5'.encode(Encoding::BINARY))
+    #     .end_row
+    #     .flush
+    def append_blob(value)
+      return self if _append_blob(value)
+
+      raise_appender_error('failed to append_blob')
+    end
+
+    # call-seq:
+    #   appender.append_null -> self
+    #
+    # Appends a NULL value to the current row in the appender.
+    #
+    #   require 'duckdb'
+    #   db = DuckDB::Database.open
+    #   con = db.connect
+    #   con.query('CREATE TABLE values (value INTEGER)')
+    #   appender = con.appender('values')
+    #   appender
+    #     .append_null
+    #     .end_row
+    #     .flush
+    def append_null
+      return self if _append_null
+
+      raise_appender_error('failed to append_null')
+    end
+
+    # call-seq:
+    #   appender.append_default -> self
+    #
+    # Appends a default value to the current row in the appender.
+    # If the column does not have a default value, this method
+    # appends a NULL value.
+    #
+    #   require 'duckdb'
+    #   db = DuckDB::Database.open
+    #   con = db.connect
+    #   con.query('CREATE TABLE values (value INTEGER DEFAULT 1)')
+    #   appender = con.appender('values')
+    #   appender
+    #     .append_default
+    #     .end_row
+    #     .flush
+    def append_default
+      return self if _append_default
+
+      raise_appender_error('failed to append_default')
+    end
+
+    # call-seq:
+    #   appender.append_hugeint(val) -> self
+    #
+    # Appends a huge int value to the current row in the appender.
     #
     #   require 'duckdb'
     #   db = DuckDB::Database.open
@@ -233,12 +441,19 @@ module DuckDB
     #   appender
     #     .append_hugeint(-170_141_183_460_469_231_731_687_303_715_884_105_727)
     #     .end_row
+    #     .flush
     def append_hugeint(value)
       lower, upper = integer_to_hugeint(value)
-      _append_hugeint(lower, upper)
+
+      return self if _append_hugeint(lower, upper)
+
+      raise_appender_error('failed to append_hugeint')
     end
 
-    # appends unsigned huge int value.
+    # call-seq:
+    #   appender.append_uhugeint(val) -> self
+    #
+    # Appends an unsigned huge int value to the current row in the appender.
     #
     #   require 'duckdb'
     #   db = DuckDB::Database.open
@@ -248,12 +463,19 @@ module DuckDB
     #   appender
     #     .append_hugeint(340_282_366_920_938_463_463_374_607_431_768_211_455)
     #     .end_row
+    #     .flush
     def append_uhugeint(value)
       lower, upper = integer_to_hugeint(value)
-      _append_uhugeint(lower, upper)
+
+      return self if _append_uhugeint(lower, upper)
+
+      raise_appender_error('failed to append_uhugeint')
     end
 
-    # appends date value.
+    # call-seq:
+    #   appender.append_date(val) -> self
+    #
+    # Appends a date value to the current row in the appender.
     #
     #   require 'duckdb'
     #   db = DuckDB::Database.open
@@ -269,10 +491,15 @@ module DuckDB
     def append_date(value)
       date = _parse_date(value)
 
-      _append_date(date.year, date.month, date.day)
+      return self if _append_date(date.year, date.month, date.day)
+
+      raise_appender_error('failed to append_date')
     end
 
-    # appends time value.
+    # call-seq:
+    #   appender.append_time(val) -> self
+    #
+    # Appends a time value to the current row in the appender.
     #
     #   require 'duckdb'
     #   db = DuckDB::Database.open
@@ -287,10 +514,15 @@ module DuckDB
     def append_time(value)
       time = _parse_time(value)
 
-      _append_time(time.hour, time.min, time.sec, time.usec)
+      return self if _append_time(time.hour, time.min, time.sec, time.usec)
+
+      raise_appender_error('failed to append_time')
     end
 
-    # appends timestamp value.
+    # call-seq:
+    #   appender.append_timestamp(val) -> self
+    #
+    # Appends a timestamp value to the current row in the appender.
     #
     #   require 'duckdb'
     #   db = DuckDB::Database.open
@@ -306,12 +538,16 @@ module DuckDB
     def append_timestamp(value)
       time = to_time(value)
 
-      _append_timestamp(time.year, time.month, time.day, time.hour, time.min, time.sec, time.nsec / 1000)
+      return self if _append_timestamp(time.year, time.month, time.day, time.hour, time.min, time.sec, time.nsec / 1000)
+
+      raise_appender_error('failed to append_timestamp')
     end
 
-    # appends interval.
+    # call-seq:
+    #   appender.append_interval(val) -> self
+    #
+    # Appends an interval value to the current row in the appender.
     # The argument must be ISO8601 duration format.
-    # WARNING: This method is expremental.
     #
     #   require 'duckdb'
     #   db = DuckDB::Database.open
@@ -324,7 +560,10 @@ module DuckDB
     #     .flush
     def append_interval(value)
       value = Interval.to_interval(value)
-      _append_interval(value.interval_months, value.interval_days, value.interval_micros)
+
+      return self if _append_interval(value.interval_months, value.interval_days, value.interval_micros)
+
+      raise_appender_error('failed to append_interval')
     end
 
     # appends value.

data/lib/duckdb/instance_cache.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+if defined?(DuckDB::InstanceCache)
+
+module DuckDB
+  # The DuckDB::InstanceCache is necessary if a client/program (re)opens
+  # multiple databases to the same file within the same statement.
+  #
+  #   require 'duckdb'
+  #   cache = DuckDB::InstanceCache.new
+  #   db1 = cache.get(path: 'db.duckdb')
+  #   db2 = cache.get(path: 'db.duckdb')
+  class InstanceCache
+    # :call-seq:
+    #   instance_cache.get(path:, config:) -> self
+    #
+    # Returns a DuckDB::Database object for the given path and config.
+    #   db1 = cache.get(path: 'db.duckdb')
+    #   db2 = cache.get(path: 'db.duckdb')
+    def get(path: nil, config: nil)
+      get_or_create(path, config)
+    end
+  end
+end
+
+end

data/lib/duckdb/logical_type.rb

@@ -2,6 +2,9 @@
 
 module DuckDB
   class LogicalType
+    alias :alias get_alias
+    alias :alias= set_alias
+
     # returns logical type's type symbol
     # `:unknown` means that the logical type's type is unknown/unsupported by ruby-duckdb.
     # `:invalid` means that the logical type's type is invalid in duckdb.
@@ -18,5 +21,133 @@ module DuckDB
       type_id = _type
       DuckDB::Converter::IntToSym.type_to_sym(type_id)
     end
+
+    # returns logical type's internal type symbol for Decimal or Enum types
+    # `:unknown` means that the logical type's type is unknown/unsupported by ruby-duckdb.
+    # `:invalid` means that the logical type's type is invalid in duckdb.
+    #
+    #   require 'duckdb'
+    #   db = DuckDB::Database.open
+    #   con = db.connect
+    #   con.query("CREATE TYPE mood AS ENUM ('happy', 'sad')")
+    #   con.query("CREATE TABLE emotions (id INTEGER, enum_col mood)")
+    #
+    #   users = con.query('SELECT * FROM emotions')
+    #   ernum_col = users.columns.find { |col| col.name == 'enum_col' }
+    #   enum_col.logical_type.internal_type #=> :utinyint
+    def internal_type
+      type_id = _internal_type
+      DuckDB::Converter::IntToSym.type_to_sym(type_id)
+    end
+
+    # Iterates over each union member name.
+    #
+    # When a block is provided, this method yields each union member name in
+    # order. It also returns the total number of members yielded.
+    #
+    #   union_logical_type.each_member_name do |name|
+    #     puts "Union member: #{name}"
+    #   end
+    #
+    # If no block is given, an Enumerator is returned, which can be used to
+    # retrieve all member names.
+    #
+    #   names = union_logical_type.each_member_name.to_a
+    #   # => ["member1", "member2"]
+    def each_member_name
+      return to_enum(__method__) {member_count} unless block_given?
+
+      member_count.times do |i|
+        yield member_name_at(i)
+      end
+    end
+
+    # Iterates over each union member type.
+    #
+    # When a block is provided, this method yields each union member logical
+    # type in order. It also returns the total number of members yielded.
+    #
+    #   union_logical_type.each_member_type do |logical_type|
+    #     puts "Union member: #{logical_type.type}"
+    #   end
+    #
+    # If no block is given, an Enumerator is returned, which can be used to
+    # retrieve all member logical types.
+    #
+    #   names = union_logical_type.each_member_type.map(&:type)
+    #   # => [:varchar, :integer]
+    def each_member_type
+      return to_enum(__method__) {member_count} unless block_given?
+
+      member_count.times do |i|
+        yield member_type_at(i)
+      end
+    end
+
+    # Iterates over each struct child name.
+    #
+    # When a block is provided, this method yields each struct child name in
+    # order. It also returns the total number of children yielded.
+    #
+    #   struct_logical_type.each_child_name do |name|
+    #     puts "Struct child: #{name}"
+    #   end
+    #
+    # If no block is given, an Enumerator is returned, which can be used to
+    # retrieve all child names.
+    #
+    #   names = struct_logical_type.each_child_name.to_a
+    #   # => ["child1", "child2"]
+    def each_child_name
+      return to_enum(__method__) {child_count} unless block_given?
+
+      child_count.times do |i|
+        yield child_name_at(i)
+      end
+    end
+
+    # Iterates over each struct child type.
+    #
+    # When a block is provided, this method yields each struct child type in
+    # order. It also returns the total number of children yielded.
+    #
+    #   struct_logical_type.each_child_type do |logical_type|
+    #     puts "Struct child type: #{logical_type.type}"
+    #   end
+    #
+    # If no block is given, an Enumerator is returned, which can be used to
+    # retrieve all child logical types.
+    #
+    #   types = struct_logical_type.each_child_type.map(&:type)
+    #   # => [:integer, :varchar]
+    def each_child_type
+      return to_enum(__method__) {child_count} unless block_given?
+
+      child_count.times do |i|
+        yield child_type_at(i)
+      end
+    end
+
+    # Iterates over each enum dictionary value.
+    #
+    # When a block is provided, this method yields each enum dictionary value
+    # in order. It also returns the total number of dictionary values yielded.
+    #
+    #   enum_logical_type.each_value do |value|
+    #     puts "Enum value: #{value}"
+    #   end
+    #
+    # If no block is given, an Enumerator is returned, which can be used to
+    # retrieve all enum dictionary values.
+    #
+    #   values = enum_logical_type.each_value.to_a
+    #   # => ["happy", "sad"]
+    def each_dictionary_value
+      return to_enum(__method__) {dictionary_size} unless block_given?
+
+      dictionary_size.times do |i|
+        yield dictionary_value_at(i)
+      end
+    end
   end
 end

data/lib/duckdb/prepared_statement.rb

@@ -105,6 +105,46 @@ module DuckDB
       end
     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.
+    # The second argument value is to expected Integer value between 0 to 255.
+    def bind_uint8(index, val)
+      return _bind_uint8(index, val) if val.between?(0, 255)
+
+      raise DuckDB::Error, "can't bind uint8(bind_uint8) to `#{val}`. The `#{val}` is out of range 0..255."
+    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.
+    # The second argument value is to expected Integer value between 0 to 65535.
+    def bind_uint16(index, val)
+      return _bind_uint16(index, val) if val.between?(0, 65_535)
+
+      raise DuckDB::Error, "can't bind uint16(bind_uint16) to `#{val}`. The `#{val}` is out of range 0..65535."
+    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.
+    # The second argument value is to expected Integer value between 0 to 4294967295.
+    def bind_uint32(index, val)
+      return _bind_uint32(index, val) if val.between?(0, 4_294_967_295)
+
+      raise DuckDB::Error, "can't bind uint32(bind_uint32) to `#{val}`. The `#{val}` is out of range 0..4294967295."
+    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.
+    # The second argument value is to expected Integer value between 0 to 18446744073709551615.
+    def bind_uint64(index, val)
+      return _bind_uint64(index, val) if val.between?(0, 18_446_744_073_709_551_615)
+
+      raise DuckDB::Error, "can't bind uint64(bind_uint64) to `#{val}`. The `#{val}` is out of range 0..18446744073709551615."
+    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.
@@ -135,7 +175,7 @@ module DuckDB
     #   require 'duckdb'
     #   db = DuckDB::Database.open('duckdb_database')
     #   con = db.connect
-    #   sql ='SELECT name FROM users WHERE bigint_col = ?'
+    #   sql ='SELECT name FROM users WHERE hugeint_col = ?'
     #   stmt = PreparedStatement.new(con, sql)
     #   stmt.bind_hugeint_internal(1, 1_234_567_890_123_456_789_012_345)
     def bind_hugeint_internal(index, value)
@@ -143,6 +183,23 @@ module DuckDB
       _bind_hugeint(index, lower, upper)
     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.
+    # The second argument value must be Integer value.
+    # This method uses duckdb_bind_uhugeint internally.
+    #
+    #   require 'duckdb'
+    #   db = DuckDB::Database.open('duckdb_database')
+    #   con = db.connect
+    #   sql ='SELECT name FROM users WHERE uhugeint_col = ?'
+    #   stmt = PreparedStatement.new(con, sql)
+    #   stmt.bind_uhugeint(1, (2**128) - 1)
+    def bind_uhugeint(index, value)
+      lower, upper = integer_to_hugeint(value)
+      _bind_uhugeint(index, lower, upper)
+    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/version.rb

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

data/lib/duckdb.rb

@@ -15,6 +15,7 @@ require 'duckdb/config'
 require 'duckdb/column'
 require 'duckdb/logical_type'
 require 'duckdb/infinity'
+require 'duckdb/instance_cache'
 
 # DuckDB provides Ruby interface of DuckDB.
 module DuckDB

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: duckdb
 version: !ruby/object:Gem::Version
-  version: 1.2.0.0
+  version: 1.2.2.0
 platform: ruby
 authors:
 - Masaki Suketa
 bindir: bin
 cert_chain: []
-date: 2025-02-23 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bigdecimal
@@ -132,6 +132,8 @@ files:
 - ext/duckdb/extconf.rb
 - ext/duckdb/extracted_statements.c
 - ext/duckdb/extracted_statements.h
+- ext/duckdb/instance_cache.c
+- ext/duckdb/instance_cache.h
 - ext/duckdb/logical_type.c
 - ext/duckdb/logical_type.h
 - ext/duckdb/pending_result.c
@@ -154,6 +156,7 @@ files:
 - lib/duckdb/database.rb
 - lib/duckdb/extracted_statements.rb
 - lib/duckdb/infinity.rb
+- lib/duckdb/instance_cache.rb
 - lib/duckdb/interval.rb
 - lib/duckdb/library_version.rb
 - lib/duckdb/logical_type.rb
@@ -185,7 +188,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.2
+rubygems_version: 3.6.7
 specification_version: 4
 summary: This module is Ruby binding for DuckDB database engine.
 test_files: []