chdb-ruby 0.1.0.rc.2 → 0.2.0.rc.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 77408619eae7f84800fa14da51844d0180ea5d4cb7513d2f2c7f2c273f287787
-  data.tar.gz: 5cff1f1590fa5a70241d1a2e1ee1068e965487c6741ad7523921b5be0a35a8e8
+  metadata.gz: d3dffafce42be0cf41b18bdc22e47ae17a4dfea85169a641b2068a9d0e54b306
+  data.tar.gz: e0cde6afb8872dd2a72f5dc8b90392ec0163707daa430907aa126e63a57bbf77
 SHA512:
-  metadata.gz: 1a501dd7c418c3af1edd49e77e69a50b6229cd8610121d7200d5e04633c61eeafe4fc87615f24c4e6d68a99bda3daa912575a6ecf919960e1398bef253d02855
-  data.tar.gz: 07752df52ce67356c9f32b37d6444bdcdb5d49c274d61d67e26c7752694aedcd53184a682bea3408057d217152a5584e4c71c6230559b70bf289162bcaa7744e
+  metadata.gz: d198f71a5348388d2b49eb5819014490d0300a20fb1d48c8342da35162d41b650d3c872f1d65b15777d2a73a47b9ca5438f551a066c05b59faab2f2b6148bd02
+  data.tar.gz: f73e40324a300d87849350637257a593f484ba2b8a8f7e40c671969ed9dbc2c1737437641dbe96a7a119d22b33bff753a514bd66f612453c0f9305ffea620a4a

data/README.md

@@ -20,69 +20,122 @@ 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
+
+# Execute streaming query
+ChDB::Database.open(':memory:') do |db|
+  total_rows = 0
+  collected = []
+  db.send_query('SELECT * FROM numbers(200000)') do |chunk|
+    collected << chunk.buf
+    total_rows += chunk.rows_read
+  end
+  p total_rows # => 200000
+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 +148,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/dependencies.yml

@@ -1,2 +1,2 @@
 chdb:
-  version: "3.1.2"
+  version: "3.2.0"

data/ext/chdb/chdb.c

@@ -6,17 +6,7 @@
 #include "connection.h"
 #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));
-}
+#include "streaming_result.h"
 
 void Init_chdb_native()
 {
@@ -26,6 +16,7 @@ void Init_chdb_native()
     init_chdb_handle();
     init_chdb_constants();
     init_local_result();
+    init_streaming_result();
     init_connection();
 
     DEBUG_PRINT("chdb extension initialized successfully");

data/ext/chdb/chdb_handle.c

@@ -2,30 +2,53 @@
 
 #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;
+query_conn_streaming_func query_conn_streaming_ptr = NULL;
+chdb_streaming_result_error_func chdb_streaming_result_error_ptr = NULL;
+chdb_streaming_fetch_result_func chdb_streaming_fetch_result_ptr = NULL;
+chdb_streaming_cancel_query_func chdb_streaming_cancel_query_ptr = NULL;
+chdb_destroy_result_func chdb_destroy_result_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;
+    query_conn_streaming_ptr = NULL;
+    chdb_streaming_result_error_ptr = NULL;
+    chdb_streaming_fetch_result_ptr = NULL;
+    chdb_streaming_cancel_query_ptr = NULL;
+    chdb_destroy_result_ptr = NULL;
 
     chdb_handle = dlopen(RSTRING_PTR(lib_path), RTLD_LAZY | RTLD_GLOBAL);
     if (!chdb_handle)
@@ -37,13 +60,32 @@ 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");
+    query_conn_streaming_ptr = (query_conn_streaming_func)dlsym(chdb_handle, "query_conn_streaming");
+    chdb_streaming_result_error_ptr = (chdb_streaming_result_error_func)dlsym(chdb_handle, "chdb_streaming_result_error");
+    chdb_streaming_fetch_result_ptr = (chdb_streaming_fetch_result_func)dlsym(chdb_handle, "chdb_streaming_fetch_result");
+    chdb_streaming_cancel_query_ptr = (chdb_streaming_cancel_query_func)dlsym(chdb_handle, "chdb_streaming_cancel_query");
+    chdb_destroy_result_ptr = (chdb_destroy_result_func)dlsym(chdb_handle, "chdb_destroy_result");
 
-    if (!connect_chdb_ptr || !close_conn_ptr || !query_conn_ptr)
+    if (!connect_chdb_ptr || !close_conn_ptr || !query_conn_ptr || !free_result_v2_ptr ||
+            !query_conn_streaming_ptr || !chdb_streaming_result_error_ptr || !chdb_streaming_fetch_result_ptr ||
+            !chdb_streaming_cancel_query_ptr || !chdb_destroy_result_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), query_conn_streaming(%p), chdb_streaming_result_error(%p), chdb_streaming_fetch_result(%p), chdb_streaming_cancel_query(%p), chdb_destroy_result(%p)",
                  dlerror(),
                  (void*)connect_chdb_ptr,
                  (void*)close_conn_ptr,
-                 (void*)query_conn_ptr);
+                 (void*)query_conn_ptr,
+                 (void*)free_result_v2_ptr,
+                 (void*)query_conn_streaming_ptr,
+                 (void*)chdb_streaming_result_error_ptr,
+                 (void*)chdb_streaming_fetch_result_ptr,
+                 (void*)chdb_streaming_cancel_query_ptr,
+                 (void*)chdb_destroy_result_ptr);
     }
-}
+
+    rb_set_end_proc(close_chdb_handle, 0);
+}

data/ext/chdb/chdb_handle.h

@@ -1,16 +1,30 @@
 #ifndef CHDB_HANDLE_H
 #define CHDB_HANDLE_H
 
+#include "include/chdb.h"
+
 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*);
+typedef chdb_streaming_result *(*query_conn_streaming_func)(struct chdb_conn*, const char*, const char*);
+typedef const char *(*chdb_streaming_result_error_func)(chdb_streaming_result*);
+typedef struct local_result_v2 *(*chdb_streaming_fetch_result_func)(struct chdb_conn*, chdb_streaming_result*);
+typedef void (*chdb_streaming_cancel_query_func)(struct chdb_conn*, chdb_streaming_result*);
+typedef void (*chdb_destroy_result_func)(chdb_streaming_result*);
 
 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 query_conn_streaming_func query_conn_streaming_ptr;
+extern chdb_streaming_result_error_func chdb_streaming_result_error_ptr;
+extern chdb_streaming_fetch_result_func chdb_streaming_fetch_result_ptr;
+extern chdb_streaming_cancel_query_func chdb_streaming_cancel_query_ptr;
+extern chdb_destroy_result_func chdb_destroy_result_ptr;
 
 extern void *chdb_handle;
 
 void init_chdb_handle();
 
-#endif
+#endif

data/ext/chdb/connection.c

@@ -5,11 +5,13 @@
 #include "exception.h"
 #include "include/chdb.h"
 #include "local_result.h"
+#include "streaming_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);
@@ -31,6 +33,9 @@ void init_connection()
     rb_define_alloc_func(cConnection, connection_alloc);
     rb_define_method(cConnection, "initialize", connection_initialize, 2);
     rb_define_method(cConnection, "query", connection_query, 2);
+    rb_define_method(cConnection, "send_query", connection_streaming_query, 2);
+    rb_define_method(cConnection, "fetch_streaming_result", connection_streaming_fecth_result, 1);
+    rb_define_method(cConnection, "cancel_streaming_query", connection_streaming_cancel_query, 1);
     rb_define_method(cConnection, "close", connection_close, 0);
 }
 
@@ -67,7 +72,6 @@ VALUE connection_initialize(VALUE self, VALUE argc, VALUE argv)
     }
 
     xfree(c_argv);
-    rb_gc_unregister_address(&argv);
     return self;
 }
 
@@ -93,6 +97,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));
     }
 
@@ -104,12 +109,90 @@ VALUE connection_query(VALUE self, VALUE query, VALUE format)
     return result_obj;
 }
 
+VALUE connection_streaming_query(VALUE self, VALUE query, VALUE format)
+{
+    Connection *conn;
+    TypedData_Get_Struct(self, Connection, &ConnectionType, conn);
+
+    Check_Type(query, T_STRING);
+    Check_Type(format, T_STRING);
+
+    chdb_streaming_result *c_result = query_conn_streaming_ptr(
+                                          *conn->c_conn,
+                                          StringValueCStr(query),
+                                          StringValueCStr(format)
+                                      );
+
+    if (!c_result)
+    {
+        rb_raise(cChDBError, "Query failed with nil streaming result");
+    }
+
+    const char *error = chdb_streaming_result_error_ptr(c_result);
+    if (error)
+    {
+        VALUE error_message = rb_str_new_cstr(error);
+        chdb_destroy_result_ptr(c_result);
+        rb_raise(cChDBError, "CHDB error: %s", StringValueCStr(error_message));
+    }
+
+    VALUE result_obj = rb_class_new_instance(0, NULL, cStreamingResult);
+    StreamingResult *result;
+    TypedData_Get_Struct(result_obj, StreamingResult, &StreamingResultType, result);
+    result->c_result = c_result;
+
+    return result_obj;
+}
+
+VALUE connection_streaming_fecth_result(VALUE self, VALUE streaming_result)
+{
+    Connection *conn;
+    TypedData_Get_Struct(self, Connection, &ConnectionType, conn);
+
+    StreamingResult *result;
+    TypedData_Get_Struct(streaming_result, StreamingResult, &StreamingResultType, result);
+
+    struct local_result_v2 *c_result = chdb_streaming_fetch_result_ptr(*conn->c_conn, result->c_result);
+
+    if (!c_result)
+    {
+        rb_raise(cChDBError, "Failed to fetch streaming result");
+    }
+
+    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));
+    }
+
+    VALUE result_obj = rb_class_new_instance(0, NULL, cLocalResult);
+    LocalResult *local_result;
+    TypedData_Get_Struct(result_obj, LocalResult, &LocalResultType, local_result);
+    local_result->c_result = c_result;
+
+    return result_obj;
+}
+
+VALUE connection_streaming_cancel_query(VALUE self, VALUE streaming_result)
+{
+    Connection *conn;
+    TypedData_Get_Struct(self, Connection, &ConnectionType, conn);
+
+    StreamingResult *result;
+    TypedData_Get_Struct(streaming_result, StreamingResult, &StreamingResultType, result);
+
+    chdb_streaming_cancel_query_ptr(*conn->c_conn, result->c_result);
+    return Qnil;
+}
+
 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/connection.h

@@ -18,6 +18,12 @@ VALUE connection_initialize(VALUE self, VALUE argc, VALUE argv);
 
 VALUE connection_query(VALUE self, VALUE query, VALUE format);
 
+VALUE connection_streaming_query(VALUE self, VALUE query, VALUE format);
+
+VALUE connection_streaming_fecth_result(VALUE self, VALUE streaming_result);
+
+VALUE connection_streaming_cancel_query(VALUE self, VALUE streaming_result);
+
 VALUE connection_close(VALUE self);
 
 #endif

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

@@ -1,17 +1,18 @@
 #include "local_result.h"
 
 #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/ext/chdb/local_result.h

@@ -3,6 +3,8 @@
 
 #include <ruby.h>
 
+#include "include/chdb.h"
+
 typedef struct
 {
     struct local_result_v2 *c_result;

data/ext/chdb/streaming_result.c

@@ -0,0 +1,39 @@
+#include "streaming_result.h"
+
+#include "constants.h"
+#include "chdb_handle.h"
+
+VALUE cStreamingResult;
+
+void streaming_result_free(void *ptr)
+{
+    StreamingResult *result = (StreamingResult *)ptr;
+    DEBUG_PRINT("Freeing StreamingResult: %p", (void*)result);
+    if (result->c_result)
+    {
+        DEBUG_PRINT("Freeing chdb_streaming_result: %p", (void*)result->c_result);
+        chdb_destroy_result_ptr(result->c_result);
+    }
+    free(result);
+}
+
+const rb_data_type_t StreamingResultType =
+{
+    "StreamingResult",
+    {NULL, streaming_result_free, NULL},
+};
+
+void init_streaming_result()
+{
+    VALUE mChDB = rb_define_module("ChDB");
+    cStreamingResult = rb_define_class_under(mChDB, "StreamingResult", rb_cObject);
+    rb_define_alloc_func(cStreamingResult, streaming_result_alloc);
+}
+
+VALUE streaming_result_alloc(VALUE klass)
+{
+    StreamingResult *result = ALLOC(StreamingResult);
+    DEBUG_PRINT("Allocating StreamingResult: %p", (void*)result);
+    result->c_result = NULL;
+    return rb_data_typed_object_wrap(klass, result, &StreamingResultType);
+}

data/ext/chdb/streaming_result.h

@@ -0,0 +1,20 @@
+#ifndef CHDB_STREAMING_RESULT_H
+#define CHDB_STREAMING_RESULT_H
+
+#include <ruby.h>
+
+#include "include/chdb.h"
+
+typedef struct
+{
+    chdb_streaming_result *c_result;
+} StreamingResult;
+
+extern VALUE cStreamingResult;
+extern const rb_data_type_t StreamingResultType;
+
+void init_streaming_result();
+
+VALUE streaming_result_alloc(VALUE klass);
+
+#endif

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?
@@ -86,14 +94,14 @@ module ChDB
       end
     end
 
-    def execute2(sql, *bind_vars, &) # rubocop:disable Metrics/MethodLength
+    def execute2(sql, *bind_vars, &block) # rubocop:disable Metrics/MethodLength
       prepare(sql) do |stmt|
         result = stmt.execute(*bind_vars)
         stmt.parse
 
-        if block_given?
+        if block
           yield stmt.columns
-          result.each(&)
+          result.each(&block)
         else
           return result.each_with_object([stmt.columns]) do |row, arr|
                    arr << row
@@ -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
@@ -120,6 +128,18 @@ module ChDB
       end
     end
 
+    def send_query(sql, format = 'CSV', bind_vars = [], &block)
+      prepare(sql) do |stmt|
+        result = stmt.send_query(bind_vars, format)
+
+        if block
+          result.each(&block)
+        else
+          result
+        end
+      end
+    end
+
     def get_first_row(sql, *bind_vars)
       execute(sql, *bind_vars).first
     end

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/result_set.rb

@@ -54,4 +54,44 @@ module ChDB
   class HashResultSet < ResultSet # :nodoc:
     alias next next_hash
   end
+
+  class StreamingResultSet
+    include Enumerable
+
+    def initialize(db, streaming_result)
+      @db = db
+      @streaming_result = streaming_result
+      @done = false
+    end
+
+    def eof?
+      @done
+    end
+
+    def next
+      return nil if @done
+
+      result = @db.conn.fetch_streaming_result(@streaming_result)
+
+      if result.nil? || result.rows_read.zero?
+        @done = true
+        nil
+      else
+        result
+      end
+    end
+
+    def each
+      while (node = self.next)
+        yield node
+      end
+    end
+
+    def cancel
+      return nil if @done
+
+      @db.conn.cancel_streaming_query(@streaming_result)
+      @done = true
+    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

@@ -8,6 +8,7 @@ rescue LoadError
   require 'chdb/chdb_native'
 end
 require 'chdb/local_result'
+require 'chdb/streaming_result'
 require 'chdb/result_set'
 require 'chdb/result_handler'
 require 'chdb/parameter_binding'
@@ -71,6 +72,21 @@ module ChDB
       @result.buf
     end
 
+    def send_query(*bind_vars, format)
+      reset! if @executed
+
+      bind_params(*bind_vars) unless bind_vars.empty?
+
+      my_processed_sql = process_sql
+      streaming_result = @connection.conn.send_query(my_processed_sql, format)
+      streaming_result.output_format = format
+
+      results = StreamingResultSet.new(@connection, streaming_result)
+
+      yield results if block_given?
+      results
+    end
+
     def reset!
       @executed = false
       @parsed = false
@@ -78,7 +94,7 @@ module ChDB
       @bind_vars.clear
       @parsed_data.clear
       @columns.clear
-      @results = nil
+      @result = nil
     end
 
     def step
@@ -101,14 +117,14 @@ module ChDB
       end
 
       @parsed = true
-      @results = nil
+      @result = nil
     end
 
     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/streaming_result.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module ChDB
+  # Represents the local result of a ChDB operation.
+  class StreamingResult
+    attr_accessor :output_format
+  end
+end

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.2.0.rc.1'
 end

metadata

@@ -1,14 +1,15 @@
 --- !ruby/object:Gem::Specification
 name: chdb-ruby
 version: !ruby/object:Gem::Version
-  version: 0.1.0.rc.2
+  version: 0.2.0.rc.1
 platform: ruby
 authors:
 - Xiaozhe Yu
 - Auxten Wang
+autorequire:
 bindir: bin
 cert_chain: []
-date: 2025-04-01 00:00:00.000000000 Z
+date: 2025-05-07 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: csv
@@ -27,6 +28,7 @@ dependencies:
 description: |
   Ruby library to interface with the chDB database engine (https://clickhouse.com/docs/chdb). Precompiled
   binaries are available for common platforms for recent versions of Ruby.
+email:
 executables: []
 extensions:
 - ext/chdb/extconf.rb
@@ -41,12 +43,15 @@ 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
 - ext/chdb/extconf.rb
 - ext/chdb/local_result.c
 - ext/chdb/local_result.h
+- ext/chdb/streaming_result.c
+- ext/chdb/streaming_result.h
 - lib/chdb.rb
 - lib/chdb/constants.rb
 - lib/chdb/data_path.rb
@@ -58,6 +63,7 @@ files:
 - lib/chdb/result_set.rb
 - lib/chdb/sql_processor.rb
 - lib/chdb/statement.rb
+- lib/chdb/streaming_result.rb
 - lib/chdb/version.rb
 - lib/chdb/version_info.rb
 homepage: https://github.com/chdb-io/chdb-ruby
@@ -69,6 +75,7 @@ metadata:
   changelog_uri: https://github.com/chdb-io/chdb-ruby/blob/main/CHANGELOG.md
   source_code_uri: https://github.com/chdb-io/chdb-ruby
   rubygems_mfa_required: 'true'
+post_install_message:
 rdoc_options:
 - "--main"
 - README.md
@@ -81,11 +88,12 @@ required_ruby_version: !ruby/object:Gem::Requirement
       version: '3.1'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
-  - - ">="
+  - - ">"
     - !ruby/object:Gem::Version
-      version: '0'
+      version: 1.3.1
 requirements: []
-rubygems_version: 3.6.2
+rubygems_version: 3.3.27
+signing_key:
 specification_version: 4
 summary: Ruby library to interface with the chDB database engine (https://clickhouse.com/docs/chdb).
 test_files: []