chdb-ruby 0.1.0.rc.2 → 0.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 77408619eae7f84800fa14da51844d0180ea5d4cb7513d2f2c7f2c273f287787
-  data.tar.gz: 5cff1f1590fa5a70241d1a2e1ee1068e965487c6741ad7523921b5be0a35a8e8
+  metadata.gz: 4b53978c961a9a237f689559adad514d7b95ad435ddfa83284bd78dbf985a339
+  data.tar.gz: 4d5d284e83f4f52800739f39ed2185b629182a39e10f359f3c884e4fc27c9de5
 SHA512:
-  metadata.gz: 1a501dd7c418c3af1edd49e77e69a50b6229cd8610121d7200d5e04633c61eeafe4fc87615f24c4e6d68a99bda3daa912575a6ecf919960e1398bef253d02855
-  data.tar.gz: 07752df52ce67356c9f32b37d6444bdcdb5d49c274d61d67e26c7752694aedcd53184a682bea3408057d217152a5584e4c71c6230559b70bf289162bcaa7744e
+  metadata.gz: 05d288d130263d52120d1741351e081d05c072c992b9f7f05cc91be3454b2f423971295dfb670acee179cd1905017b24ead943fc9cc67b4747f155edc6541c41
+  data.tar.gz: 4607787c66d0f16b3a74377d1e6e43a6cf3ab7a5aac60b27b30fccfaa2fc6a5eff09f780d611e690a9805278a5a104a99eab5f458b97718949f45446b4b5ccb3

data/README.md

@@ -20,69 +20,111 @@ Note that this module is only compatible with ChDB 3.0.0 or newer.
 
 ## Quick start
 
-``` ruby
+Before using chdb-ruby, install the gem first. This will download the libchdb C++ library dependencies, so please be patient:
+```bash
+gem install chdb-ruby
+```
+
+Below are examples of common interfaces usage:
+
+```ruby
 require 'chdb'
 
 # Open a database
-db = ChDB::Database.new('test_db', results_as_hash: true)
+# Parameter explanation:
+# 1. path supports two formats:
+#    - ":memory:" in-memory temporary database (data destroyed on close)
+#    - "file:/path/to/db" file-based persistent database
+#    Configuration parameters can be appended via URL-style query (e.g. 'file:test.db?results_as_hash=true')
+# 2. options hash supports:
+#    - results_as_hash: controls whether result sets return as hashes (default: arrays)
+db = ChDB::Database.new('file:test.db', results_as_hash: true)
+
+# Create a database
+db.execute('CREATE DATABASE IF NOT EXISTS test')
 
 # Create a table
+db.execute('DROP TABLE IF EXISTS test.test_table')
 rows = db.execute <<-SQL
-  CREATE TABLE test_table(
+  CREATE TABLE test.test_table(
     id Int32,
     name String)
     ENGINE = MergeTree()
-    ORDER BY id);
+    ORDER BY id
 SQL
 
 # Execute a few inserts
 {
-      1 => 'Alice',
-      2 => 'Bob'
+  1 => 'Alice',
+  2 => 'Bob'
 }.each do |pair|
-  db.execute 'INSERT INTO test_table VALUES ( ?, ? )', pair
+  db.execute 'INSERT INTO test.test_table VALUES ( ?, ? )', pair
 end
 
 # Find a few rows
-db.execute('SELECT * FROM test_table ORDER BY id') do |row|
+db.execute('SELECT * FROM test.test_table ORDER BY id') do |row|
   p row
 end
 # [{ 'id' => '1', 'name' => 'Alice' },
 #  { 'id' => '2', 'name' => 'Bob' }]
 
+# When you need to open another database, you must first close the previous database 
+db.close()
+
 # Open another database
-db = ChDB::Database.new 'test2.db'
+db = ChDB::Database.new 'file:test.db'
 
 # Create another table
+db.execute('DROP TABLE IF EXISTS test.test2_table')
 rows = db.execute <<-SQL
-  CREATE TABLE test2_table(
+  CREATE TABLE test.test2_table(
     id Int32,
     name String)
     ENGINE = MergeTree()
-    ORDER BY id");
+    ORDER BY id
 SQL
 
 # Execute inserts with parameter markers
-db.execute('INSERT INTO test2_table (id, name)
+db.execute('INSERT INTO test.test2_table (id, name)
             VALUES (?, ?)', [3, 'Charlie'])
 
-db.execute2('SELECT * FROM test2_table') do |row|
+# Find rows with the first row displaying column names
+db.execute2('SELECT * FROM test.test2_table') do |row|
   p row
 end
-# [['id', 'name'], [3, 'Charlie']],
+# ["id", "name"]
+# ["3", "Charlie"]
+
+# Close the database
+db.close()
+
+# Use ChDB::Database.open to automatically close the database connection:
+ChDB::Database.open('file:test.db') do |db|
+  result = db.execute('SELECT 1')
+  p result.to_a # => [["1"]]
+end
+
+# Query with specific output formats (CSV, JSON, etc.):
+# See more details at https://clickhouse.com/docs/interfaces/formats.
+ChDB::Database.open(':memory:') do |db|
+  csv_data = db.query_with_format('SELECT 1 as a, 2 as b', 'CSV')
+  p csv_data
+  # "1,2\n"
+
+  json_data = db.query_with_format('SELECT 1 as a, 2 as b', 'JSON')
+  p json_data
+end
 ```
 
 ## Thread Safety
 
-When using `ChDB::Database.new` to open a session, all read/write operations within that session are thread-safe. However, currently only one active session is allowed per process. Therefore, when you need to open another session, you must first close the previous session.
-
-For example, the following code is fine because only the database
-instance is shared among threads:
+When using `ChDB::Database.new` or `ChDB::Database.open` to open a database connection, all read/write operations within that session are thread-safe. However, currently only one active database connection is allowed per process. Therefore, when you need to open another database connection, you must first close the previous connection.
+**Please note that `ChDB::Database.new`, `ChDB::Database.open`, and `ChDB::Database.close` methods themselves are not thread-safe.** If used in multi-threaded environments, external synchronization must be implemented to prevent concurrent calls to these methods, which could lead to undefined behavior.
 
 ```ruby
 require 'chdb'
 
-db = ChDB::Database.new ":memory:'
+db = ChDB::Database.new ':memory:'
 
 latch = Queue.new
 
@@ -95,6 +137,9 @@ ts = 10.times.map {
 10.times { latch << nil }
 
 p ts.map(&:value)
+# [[["1"]], [["1"]], [["1"]], [["1"]], [["1"]], [["1"]], [["1"]], [["1"]], [["1"]], [["1"]]]
+
+db.close()
 ```
 
 Other instances can be shared among threads, but they require that you provide

data/ext/chdb/chdb.c

@@ -7,17 +7,6 @@
 #include "exception.h"
 #include "local_result.h"
 
-void init_chdb_constants()
-{
-    VALUE mChDB = rb_define_module("ChDB");
-    VALUE mChDBConstants = rb_define_module_under(mChDB, "Constants");
-    VALUE mmChDBOpen = rb_define_module_under(mChDBConstants, "Open");
-
-    rb_define_const(mmChDBOpen, "READONLY", INT2FIX(CHDB_OPEN_READONLY));
-    rb_define_const(mmChDBOpen, "READWRITE", INT2FIX(CHDB_OPEN_READWRITE));
-    rb_define_const(mmChDBOpen, "CREATE", INT2FIX(CHDB_OPEN_CREATE));
-}
-
 void Init_chdb_native()
 {
     DEBUG_PRINT("Initializing chdb extension");

data/ext/chdb/chdb_handle.c

@@ -2,30 +2,43 @@
 
 #include <dlfcn.h>
 #include <ruby.h>
-
+#include "constants.h"
 #include "exception.h"
 
 void *chdb_handle = NULL;
 connect_chdb_func connect_chdb_ptr = NULL;
 close_conn_func close_conn_ptr = NULL;
 query_conn_func query_conn_ptr = NULL;
+free_result_v2_func free_result_v2_ptr = NULL;
 
-VALUE get_chdb_rb_path(void)
+VALUE get_chdb_rb_path()
 {
     VALUE chdb_module = rb_const_get(rb_cObject, rb_intern("ChDB"));
     return rb_funcall(chdb_module, rb_intern("lib_file_path"), 0);
 }
 
+void close_chdb_handle()
+{
+    if (chdb_handle)
+    {
+        dlclose(chdb_handle);
+        chdb_handle = NULL;
+        DEBUG_PRINT("Close chdb handle");
+    }
+}
+
 void init_chdb_handle()
 {
     VALUE rb_path = get_chdb_rb_path();
     VALUE lib_dir = rb_file_dirname(rb_file_dirname(rb_path));
     VALUE lib_path = rb_str_cat2(lib_dir, "/lib/chdb/lib/libchdb.so");
-    // printf("chdb.rb path from Ruby: %s\n", StringValueCStr(lib_path));
+
+    DEBUG_PRINT("chdb.rb path from Ruby: %s\n", StringValueCStr(lib_path));
 
     connect_chdb_ptr = NULL;
     close_conn_ptr = NULL;
     query_conn_ptr = NULL;
+    free_result_v2_ptr = NULL;
 
     chdb_handle = dlopen(RSTRING_PTR(lib_path), RTLD_LAZY | RTLD_GLOBAL);
     if (!chdb_handle)
@@ -37,13 +50,20 @@ void init_chdb_handle()
     connect_chdb_ptr = (connect_chdb_func)dlsym(chdb_handle, "connect_chdb");
     close_conn_ptr = (close_conn_func)dlsym(chdb_handle, "close_conn");
     query_conn_ptr = (query_conn_func)dlsym(chdb_handle, "query_conn");
+    free_result_v2_ptr = (free_result_v2_func)dlsym(chdb_handle, "free_result_v2");
 
-    if (!connect_chdb_ptr || !close_conn_ptr || !query_conn_ptr)
+    if (!connect_chdb_ptr || !close_conn_ptr || !query_conn_ptr || !free_result_v2_ptr)
     {
-        rb_raise(cChDBError, "Symbol loading failed: %s\nMissing functions: connect_chdb(%p) close_conn(%p) query_conn(%p)",
+        close_chdb_handle();
+
+        rb_raise(cChDBError,
+                 "Symbol loading failed: %s\nMissing functions: connect_chdb(%p) close_conn(%p) query_conn(%p), free_result_v2(%p)",
                  dlerror(),
                  (void*)connect_chdb_ptr,
                  (void*)close_conn_ptr,
-                 (void*)query_conn_ptr);
+                 (void*)query_conn_ptr,
+                 (void*)free_result_v2_ptr);
     }
-}
+
+    rb_set_end_proc(close_chdb_handle, 0);
+}

data/ext/chdb/chdb_handle.h

@@ -4,13 +4,15 @@
 typedef struct chdb_conn **(*connect_chdb_func)(int, char**);
 typedef void (*close_conn_func)(struct chdb_conn**);
 typedef struct local_result_v2 *(*query_conn_func)(struct chdb_conn*, const char*, const char*);
+typedef void (*free_result_v2_func)(struct local_result_v2*);
 
 extern connect_chdb_func connect_chdb_ptr;
 extern close_conn_func close_conn_ptr;
 extern query_conn_func query_conn_ptr;
+extern free_result_v2_func free_result_v2_ptr;
 
 extern void *chdb_handle;
 
 void init_chdb_handle();
 
-#endif
+#endif

data/ext/chdb/connection.c

@@ -6,10 +6,11 @@
 #include "include/chdb.h"
 #include "local_result.h"
 
-static void connection_free(void *ptr)
+void connection_free(void *ptr)
 {
     Connection *conn = (Connection *)ptr;
-    DEBUG_PRINT("Closing connection: %p", (void*)conn->c_conn);
+    DEBUG_PRINT("Closing connection in connection_free: %p", (void*)conn->c_conn);
+
     if (conn->c_conn)
     {
         close_conn_ptr(conn->c_conn);
@@ -67,7 +68,6 @@ VALUE connection_initialize(VALUE self, VALUE argc, VALUE argv)
     }
 
     xfree(c_argv);
-    rb_gc_unregister_address(&argv);
     return self;
 }
 
@@ -93,6 +93,7 @@ VALUE connection_query(VALUE self, VALUE query, VALUE format)
     if (c_result->error_message)
     {
         VALUE error_message = rb_str_new_cstr(c_result->error_message);
+        free_result_v2_ptr(c_result);
         rb_raise(cChDBError, "CHDB error: %s", StringValueCStr(error_message));
     }
 
@@ -108,8 +109,9 @@ VALUE connection_close(VALUE self)
 {
     Connection *conn;
     TypedData_Get_Struct(self, Connection, &ConnectionType, conn);
+    DEBUG_PRINT("Closing connection in connection_close: %p", (void*)conn->c_conn);
 
-    if (conn->c_conn)
+    if (conn && conn->c_conn)
     {
         close_conn_ptr(conn->c_conn);
         conn->c_conn = NULL;

data/ext/chdb/constants.c

@@ -0,0 +1,14 @@
+#include "constants.h"
+
+#include <ruby.h>
+
+void init_chdb_constants()
+{
+    VALUE mChDB = rb_define_module("ChDB");
+    VALUE mChDBConstants = rb_define_module_under(mChDB, "Constants");
+    VALUE mmChDBOpen = rb_define_module_under(mChDBConstants, "Open");
+
+    rb_define_const(mmChDBOpen, "READONLY", INT2FIX(CHDB_OPEN_READONLY));
+    rb_define_const(mmChDBOpen, "READWRITE", INT2FIX(CHDB_OPEN_READWRITE));
+    rb_define_const(mmChDBOpen, "CREATE", INT2FIX(CHDB_OPEN_CREATE));
+}

data/ext/chdb/constants.h

@@ -12,4 +12,6 @@
 #define DEBUG_PRINT(fmt, ...) ((void)0)
 #endif
 
+void init_chdb_constants();
+
 #endif

data/ext/chdb/exception.c

@@ -12,5 +12,6 @@ void init_exception()
     else
     {
         cChDBError = rb_define_class_under(mChDB, "Exception", rb_eStandardError);
+        rb_global_variable(&cChDBError);
     }
 }

data/ext/chdb/local_result.c

@@ -2,16 +2,18 @@
 
 #include "constants.h"
 #include "include/chdb.h"
+#include "chdb_handle.h"
 
 VALUE cLocalResult;
 
-static void local_result_free(void *ptr)
+void local_result_free(void *ptr)
 {
     LocalResult *result = (LocalResult *)ptr;
     DEBUG_PRINT("Freeing LocalResult: %p", (void*)result);
     if (result->c_result)
     {
-        free_result_v2(result->c_result);
+        DEBUG_PRINT("Freeing local_result_v2: %p", (void*)result->c_result);
+        free_result_v2_ptr(result->c_result);
     }
     free(result);
 }

data/lib/chdb/data_path.rb

@@ -23,7 +23,7 @@ module ChDB
 
     def generate_arguments # rubocop:disable Metrics/MethodLength
       args = ['clickhouse', "--path=#{@dir_path}"]
-      excluded_keys = %i[results_as_hash readonly readwrite flags]
+      excluded_keys = %w[results_as_hash readonly readwrite flags]
 
       @query_params.each do |key, value|
         next if excluded_keys.include?(key)
@@ -72,8 +72,7 @@ module ChDB
     end
 
     def merge_options(options)
-      @query_params = @query_params.merge(options)
-      # @query_params = @query_params.merge(options.transform_keys(&:to_s))
+      @query_params = @query_params.merge(options.transform_keys(&:to_s))
     end
 
     def directory_path(path)
@@ -87,31 +86,29 @@ module ChDB
     end
 
     def ensure_directory_exists
-      if @mode.nobits?(Constants::Open::CREATE)
-        raise DirectoryNotFoundException, "Directory #{@dir_path} required" unless Dir.exist?(@dir_path)
+      return if Dir.exist?(@dir_path)
 
-        return
-      end
+      raise DirectoryNotFoundException, "Directory #{@dir_path} required" if @mode.nobits?(Constants::Open::CREATE)
 
       FileUtils.mkdir_p(@dir_path, mode: 0o755)
     end
 
     def check_params # rubocop:disable Metrics/MethodLength
       @mode = Constants::Open::READWRITE | Constants::Open::CREATE
-      @mode = Constants::Open::READONLY if @query_params[:readonly]
+      @mode = Constants::Open::READONLY if @query_params['readonly']
 
-      if @query_params[:readwrite]
-        raise InvalidArgumentException, 'conflicting options: readonly and readwrite' if @query_params[:readonly]
+      if @query_params['readwrite']
+        raise InvalidArgumentException, 'conflicting options: readonly and readwrite' if @query_params['readonly']
 
         @mode = Constants::Open::READWRITE
       end
 
-      return unless @query_params[:flags]
-      if @query_params[:readonly] || @query_params[:readwrite]
+      return unless @query_params['flags']
+      if @query_params['readonly'] || @query_params['readwrite']
         raise InvalidArgumentException, 'conflicting options: flags with readonly and/or readwrite'
       end
 
-      @mode = @query_params[:flags]
+      @mode = @query_params['flags']
     end
 
     def remove_file_prefix(str)

data/lib/chdb/database.rb

@@ -13,6 +13,8 @@ module ChDB
   # Represents a database connection and provides methods to interact with the database.
   class Database # rubocop:disable Metrics/ClassLength
     class << self
+      @@instance = nil # rubocop:disable Style/ClassVars
+
       # Without block works exactly as new.
       # With block, like new closes the database at the end, but unlike new
       # returns the result of the block instead of the database instance.
@@ -36,16 +38,20 @@ module ChDB
     attr_accessor :results_as_hash, :conn
 
     def initialize(file, options = {}) # rubocop:disable Metrics/MethodLength
+      raise InternalException, 'Existing database instance is not closed' if @@instance
+
       file = file.to_path if file.respond_to? :to_path
 
       @data_path = DataPath.new(file, options)
-      @results_as_hash = @data_path.query_params[:results_as_hash]
+      @results_as_hash = @data_path.query_params['results_as_hash'] || false
       @readonly = @data_path.mode & Constants::Open::READONLY != 0
 
       argv = @data_path.generate_arguments
       @conn = ChDB::Connection.new(argv.size, argv)
       @closed = false
 
+      @@instance = self # rubocop:disable Style/ClassVars
+
       return unless block_given?
 
       begin
@@ -61,6 +67,8 @@ module ChDB
       @data_path.close if @data_path.respond_to?(:close)
       @conn.close if @conn.respond_to?(:close)
       @closed = true
+
+      @@instance = nil # rubocop:disable Style/ClassVars
     end
 
     def closed?
@@ -111,7 +119,7 @@ module ChDB
       end
     end
 
-    def query_with_format(sql, bind_vars = [], format = 'CSV')
+    def query_with_format(sql, format = 'CSV', bind_vars = [])
       result = prepare(sql).execute_with_format(bind_vars, format)
       if block_given?
         yield result

data/lib/chdb/parameter_binding.rb

@@ -11,14 +11,8 @@ module ChDB
     def bind_params(*bind_vars)
       index = 1
       bind_vars.flatten.each do |var|
-        if var.is_a?(Hash)
-          # TODO: Hash-style parameter binding not yet implemented
-          # Currently using positional parameters instead of named parameters
-          var.each { |key, val| bind_param key, val }
-        else
-          bind_param index, var
-          index += 1
-        end
+        bind_param index, var
+        index += 1
       end
     end
   end

data/lib/chdb/sql_processor.rb

@@ -1,10 +1,17 @@
 # frozen_string_literal: true
 
+require 'chdb/errors'
+
 module ChDB
   # This module provides functionality for processing SQL queries,
   # including binding variables and escaping values.
   module SQLProcessor
     def process_sql
+      placeholders = @sql.scan(/(?<!\\)\?/).size
+      if placeholders != @bind_vars.size
+        raise ChDB::SQLException, "Wrong number of bind variables (#{@bind_vars.size} for #{placeholders})"
+      end
+
       escaped_values = @bind_vars.map { |v| escape(v) }
       sql = @sql.dup
       sql.gsub(/(?<!\\)\?/) { escaped_values.shift or '?' }

data/lib/chdb/statement.rb

@@ -107,8 +107,8 @@ module ChDB
     private
 
     def validate_inputs(db, sql_str)
-      raise ArgumentError, 'SQL statement cannot be nil' if sql_str.nil?
-      raise ArgumentError, 'prepare called on a closed database' if db.nil? || db.closed?
+      raise InvalidArgumentException, 'SQL statement cannot be nil' if sql_str.nil?
+      raise InvalidArgumentException, 'prepare called on a closed database' if db.nil? || db.closed?
     end
 
     def encode_sql(sql_str)

data/lib/chdb/version.rb

@@ -2,5 +2,5 @@
 
 module ChDB
   # (String) the version of the chdb gem, e.g. "0.1.0"
-  VERSION = '0.1.0.rc.2'
+  VERSION = '0.1.0'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: chdb-ruby
 version: !ruby/object:Gem::Version
-  version: 0.1.0.rc.2
+  version: 0.1.0
 platform: ruby
 authors:
 - Xiaozhe Yu
 - Auxten Wang
 bindir: bin
 cert_chain: []
-date: 2025-04-01 00:00:00.000000000 Z
+date: 2025-04-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: csv
@@ -41,6 +41,7 @@ files:
 - ext/chdb/chdb_handle.h
 - ext/chdb/connection.c
 - ext/chdb/connection.h
+- ext/chdb/constants.c
 - ext/chdb/constants.h
 - ext/chdb/exception.c
 - ext/chdb/exception.h