chdb 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 0bfc7331198cabffa295674625f913fb6092c9ede2a263aa9a95794c055e0179
+  data.tar.gz: 10ec8acedb049d14a45077ad2fee6b877ce6575719019b49ce0e06ea75e83aa6
+SHA512:
+  metadata.gz: d09ffbf109f543df962ea69135e7d75749abb480f9b2c331b80ab7eb0ae6371b2eb239c11d2ab64a807f30cf0b8c0f117880197b2ec8e0a08bec3adce0c1b00e
+  data.tar.gz: 3c6f26c064a6a512afbd11d5755c5c4d569d0909434f67474e18e7256caf1dc6547d0ccfce4d142f02afde60916911704b9293310b54de37f16336bf9de25190

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2024 Gerardo Ortega
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,178 @@
+# Chdb Ruby Gem
+
+Chdb is a Ruby gem that provides a direct interface to the [chDB](https://clickhouse.com/docs/en/chdb), an in-process SQL OLAP Engine powered by ClickHouse. It allows you to execute SQL queries and manage database sessions directly from your Ruby applications.
+
+## Status
+
+This gem is under development and the API is not stable yet.
+
+## Installation
+
+First of all, you need to install the chDB engine.
+
+**Install libchdb**
+
+```bash
+curl -sL https://lib.chdb.io | bash
+```
+
+**Install the gem**
+
+To install the gem, add the following line to your application's Gemfile:
+
+```ruby
+gem 'chdb'
+```
+
+Then, execute:
+
+```bash
+bundle install
+```
+
+If you are not using bundler, you can install the gem by running:
+
+```bash
+gem install chdb
+```
+
+Make sure you have the `chdb` C library installed on your system.
+
+## Usage
+
+The `Chdb` gem provides two main ways to interact with the chDB engine:
+
+1.  **Direct Query Execution:** Execute queries directly against the engine.
+2.  **Session-based Query Execution:** Execute queries within a session, providing temporary storage and resource cleanup.
+
+### Direct Query Execution
+
+The `Chdb.query` method allows you to execute SQL queries and get results.
+
+```ruby
+require 'chdb'
+
+# Execute a simple query
+result = Chdb.query("SELECT 1")
+puts result.buf # => The result as a string
+
+# Execute a query with CSV output
+result = Chdb.query("SELECT 1 AS a, 'test' AS b", "CSV")
+puts result.rows # => An array of hashes with the data
+puts result.columns # => The columns of the result
+
+# Execute a query with JSON output
+result = Chdb.query("SELECT 1 AS a, 'test' AS b", "JSON")
+puts result.rows # => An array of hashes with the data
+puts result.columns # => The columns of the result
+
+# Handle errors
+begin
+    Chdb.query("SELECT invalid syntax")
+rescue Chdb::Error => e
+    puts "Error executing query: #{e.message}"
+end
+```
+
+**Parameters:**
+
+*   `query_str` (String): The SQL query to be executed.
+*   `output_format` (String, optional): The output format for the query results, can be `"CSV"`, `"JSON"`, or `"debug"`. The default value is `"CSV"`.
+
+**Returns:**
+
+*   A `Chdb::LocalResult` object, containing the query results, buffer, elapsed time, rows and columns.
+
+**Output Formats:**
+
+*   **CSV:** Results are returned as CSV strings, parsed into an array of hashes.
+*   **JSON:** Results are returned as JSON strings, parsed into an array of hashes.
+*   **debug:** Results are returned as CSV format, with debug information.
+
+### Session-based Query Execution
+
+The `Chdb::Session` class allows you to execute queries within a session, enabling creation of temporary tables and other resources. Temporary sessions are automatically cleaned up when the session object is closed.
+
+```ruby
+require 'chdb'
+
+# Create a new session
+session = Chdb::Session.new
+
+# Create a table
+session.query("CREATE TABLE IF NOT EXISTS my_table (a Int, b String) ENGINE = Memory")
+
+# Insert some values
+session.query("INSERT INTO my_table VALUES (1, 'one'), (2, 'two')")
+
+# Query the created table
+result = session.query("SELECT * FROM my_table")
+puts result.rows # => An array of hashes with the data
+
+# Close the session. The temporary directory is cleaned
+session.close
+
+# Using a presistent path
+session = Chdb::Session.new("my_persistent_db")
+# ...
+session.close
+```
+
+**Parameters:**
+
+*   `path` (String, optional): The path to the database. If `nil` or empty, a temporary directory will be used, which is cleaned up when the session is closed.
+
+**Methods:**
+
+*   `query(query_str, output_format = "CSV")`: Executes an SQL query within the session.
+    *   `query_str` (String): The SQL query to be executed.
+    *   `output_format` (String, optional): The output format for the query results, can be `"CSV"`, `"JSON"`, or `"debug"`. The default value is `"CSV"`.
+*   `close`: Closes the session. Cleans up the temporary directory if it was created by the session.
+*   `cleanup`: Removes the session directory, it's called automatically if the session is temporal
+
+## LocalResult Class
+
+The `Chdb::LocalResult` class represents the result of a chDB query.
+
+**Attributes:**
+
+*   `buf`: The raw result buffer as a string.
+*   `elapsed`: The time elapsed for the query execution.
+*   `rows`: An array of hashes, representing the result rows.
+*   `columns`: An array of strings representing the column names in the result.
+*   `output_format`: The output format used for the query.
+
+**Methods:**
+
+*   `each(&block)`: Allows iteration over the rows.
+*   `to_s`: Returns the buffer as a string
+
+## Error Handling
+
+The gem defines a custom error class `Chdb::Error`, that is raised when the chDB engine returns an error.
+
+```ruby
+begin
+  Chdb.query("SELECT invalid syntax")
+rescue Chdb::Error => e
+  puts "Error: #{e.message}"
+end
+```
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at [https://github.com/g3ortega/chdb](https://github.com/g3ortega/chdb). This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/g3ortega/chdb/blob/main/CODE_OF_CONDUCT.md).
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+
+## Code of Conduct
+
+Everyone interacting in the Chdb project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/g3ortega/chdb/blob/main/CODE_OF_CONDUCT.md).

data/Rakefile

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+require "rubocop/rake_task"
+
+RuboCop::RakeTask.new
+
+task default: %i[spec rubocop]

data/chdb.gemspec

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+require_relative "lib/chdb/version"
+
+Gem::Specification.new do |spec|
+  spec.name = "chdb"
+  spec.version = Chdb::VERSION
+  spec.authors = ["Gerardo Ortega"]
+  spec.email = ["g3ortega@gmail.com"]
+
+  spec.summary = "Chdb implementation in Ruby"
+  spec.description = "Ruby interface for the chDB in-process SQL OLAP Engine, " \
+                    "providing direct query execution and session management capabilities."
+  spec.homepage = "https://github.com/g3ortega/chdb"
+  spec.license = "MIT"
+  spec.required_ruby_version = ">= 3.0.0"
+
+  spec.metadata["allowed_push_host"] = "https://rubygems.org"
+
+  spec.metadata["homepage_uri"] = spec.homepage
+  spec.metadata["source_code_uri"] = "https://github.com/g3ortega/chdb"
+  spec.metadata["changelog_uri"] = "https://github.com/g3ortega/chdb/blob/main/CHANGELOG.md"
+
+  # Specify which files should be added to the gem when it is released.
+  # The `git ls-files -z` loads the files in the RubyGem that have been added into git.
+  spec.files = Dir["lib/**/*.rb", "ext/**/*.{c,h}", "ext/**/Makefile", "README.md", "LICENSE.txt", "Rakefile",
+                   "chdb.gemspec"]
+
+  spec.bindir = "exe"
+  spec.executables = spec.files.grep(%r{\Aexe/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+
+  spec.extensions = ["ext/chdb/extconf.rb"]
+  # Uncomment to register a new dependency of your gem
+  # spec.add_dependency "example-gem", "~> 1.0"
+
+  # For more information and examples about making a new gem, check out our
+  # guide at: https://bundler.io/guides/creating_gem.html
+end

data/ext/chdb/chdb.c

@@ -0,0 +1,123 @@
+#include <ruby.h>
+#include "chdb.h"
+
+// Debug configuration
+#define CHDB_DEBUG 0
+#if CHDB_DEBUG
+#define DEBUG_PRINT(fmt, ...) fprintf(stderr, fmt "\n", ##__VA_ARGS__)
+#else
+#define DEBUG_PRINT(fmt, ...) ((void)0)
+#endif
+
+// Constants
+#define CHDB_MAX_ARGS 256
+
+VALUE cChdbError;
+
+// Define a Ruby wrapper for `local_result_v2`
+typedef struct {
+    struct local_result_v2 *c_result;
+} LocalResult;
+
+static 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);
+    }
+    free(result);
+}
+
+static VALUE local_result_alloc(VALUE klass) {
+    LocalResult *result = ALLOC(LocalResult);
+    DEBUG_PRINT("Allocating LocalResult: %p", (void*)result);
+    result->c_result = NULL;
+    return Data_Wrap_Struct(klass, NULL, local_result_free, result);
+}
+
+static VALUE local_result_initialize(VALUE self, VALUE argc, VALUE argv) {
+    DEBUG_PRINT("Initializing LocalResult with %d arguments", NUM2INT(argc));
+
+    // Type checking
+    Check_Type(argc, T_FIXNUM);
+    Check_Type(argv, T_ARRAY);
+
+    int c_argc = NUM2INT(argc);
+    if (c_argc < 0) {
+        rb_raise(rb_eArgError, "Argument count cannot be negative");
+    }
+    if (c_argc > CHDB_MAX_ARGS) {
+        rb_raise(rb_eArgError, "Too many arguments (max: %d)", CHDB_MAX_ARGS);
+    }
+
+    char **c_argv = ALLOC_N(char *, c_argc);
+
+    for (int i = 0; i < c_argc; i++) {
+        VALUE arg = rb_ary_entry(argv, i);
+        c_argv[i] = StringValueCStr(arg);
+    }
+
+    LocalResult *result;
+    Data_Get_Struct(self, LocalResult, result);
+
+    // Execute query
+    result->c_result = query_stable_v2(c_argc, c_argv);
+
+    if (!result->c_result) {
+        xfree(c_argv);
+        rb_gc_unregister_address(&argv);
+        rb_raise(cChdbError, "chDB query returned nil");
+    }
+
+    if (result->c_result->error_message) {
+        VALUE error_message = rb_str_new_cstr(result->c_result->error_message);
+        // Create error context
+        VALUE context = rb_hash_new();
+        rb_hash_aset(context, ID2SYM(rb_intern("args")), argv);
+        rb_hash_aset(context, ID2SYM(rb_intern("error")), error_message);
+
+        xfree(c_argv);
+        rb_gc_unregister_address(&argv);
+        rb_raise(cChdbError, "chDB error: %s", StringValueCStr(error_message));
+    }
+
+    xfree(c_argv);
+    rb_gc_unregister_address(&argv);
+    DEBUG_PRINT("LocalResult initialization complete");
+    return self;
+}
+
+static VALUE local_result_buf(VALUE self) {
+    LocalResult *result;
+    Data_Get_Struct(self, LocalResult, result);
+
+    if (!result->c_result || !result->c_result->buf) {
+        DEBUG_PRINT("Buffer access attempted on empty result");
+        return Qnil;
+    }
+
+    DEBUG_PRINT("Returning buffer of length %zu", result->c_result->len);
+    return rb_str_new(result->c_result->buf, result->c_result->len);
+}
+
+static VALUE local_result_elapsed(VALUE self) {
+    LocalResult *result;
+    Data_Get_Struct(self, LocalResult, result);
+    DEBUG_PRINT("Query elapsed time: %f", result->c_result->elapsed);
+    return DBL2NUM(result->c_result->elapsed);
+}
+
+void Init_chdb() {
+    DEBUG_PRINT("Initializing chdb extension");
+
+    VALUE mChdb = rb_define_module("Chdb");
+    cChdbError = rb_define_class_under(mChdb, "Error", rb_eStandardError);
+
+    VALUE cLocalResult = rb_define_class_under(mChdb, "LocalResult", rb_cObject);
+    rb_define_alloc_func(cLocalResult, local_result_alloc);
+    rb_define_method(cLocalResult, "initialize", local_result_initialize, 2);
+    rb_define_method(cLocalResult, "buf", local_result_buf, 0);
+    rb_define_method(cLocalResult, "elapsed", local_result_elapsed, 0);
+
+    DEBUG_PRINT("chdb extension initialized successfully");
+}

data/ext/chdb/extconf.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+require "mkmf"
+
+# First try to find system-wide installations
+system_found = have_library("chdb") && have_header("chdb.h")
+
+unless system_found
+  # Abort if not found
+  abort "chdb.h or chdb library not found! Please install chdb development files"
+end
+
+# Create Makefile
+create_makefile("chdb/chdb")

data/lib/chdb/local_result.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+require "csv"
+require "json"
+
+module Chdb
+  # Handles ClickHouse query results with support for CSV and JSON formats,
+  # providing enumerable access to result rows and column information
+  class LocalResult
+    include Enumerable
+
+    attr_accessor :output_format
+
+    def to_s
+      buf
+    end
+
+    def rows
+      @rows ||= parse_buffer
+    end
+
+    def columns
+      @columns ||= extract_columns
+    end
+
+    def each(&block)
+      rows.each(&block)
+    end
+
+    private
+
+    def parse_buffer
+      return [] if buf.nil? || buf.empty?
+
+      case output_format&.downcase
+      when "csv" then parse_csv
+      when "json" then parse_json
+      else
+        raise Chdb::Error, "Unsupported output format: #{output_format}"
+      end
+    end
+
+    def parse_csv
+      csv_options = { headers: true }
+      CSV.parse(buf, **csv_options).map(&:to_h)
+    end
+
+    def parse_json
+      parsed = JSON.parse(buf)
+      parsed["data"] || []
+    end
+
+    def extract_columns
+      return [] if buf.nil? || buf.empty?
+
+      case output_format&.downcase
+      when "csv" then extract_csv_columns
+      when "json" then extract_json_columns
+      else
+        raise Chdb::Error, "Unsupported output format: #{output_format}"
+      end
+    end
+
+    def extract_csv_columns
+      csv_options = { headers: true }
+      CSV.parse(buf, **csv_options).headers
+    end
+
+    def extract_json_columns
+      first_row = parse_buffer.first
+      first_row ? first_row.keys : []
+    end
+  end
+end

data/lib/chdb/session.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+require "tempfile"
+require "fileutils"
+
+module Chdb
+  # Manages ClickHouse database sessions, handling temporary and permanent paths
+  # for query execution and resource cleanup
+  class Session
+    attr_reader :path, :is_temp
+
+    def initialize(path = nil)
+      if path.nil? || path.empty?
+        @path = Dir.mktmpdir("chdb_")
+        @is_temp = true
+      else
+        @path = path
+        @is_temp = false
+      end
+    end
+
+    def query(query_str, output_format = "CSV")
+      output_format ||= "CSV" # Default value
+      query_to_buffer(query_str, output_format, @path, "")
+    end
+
+    def close
+      cleanup if @is_temp && File.basename(@path).start_with?("chdb_")
+    end
+
+    def cleanup
+      FileUtils.remove_entry(@path) if Dir.exist?(@path)
+    end
+
+    private
+
+    def query_to_buffer(query_str, output_format, path, udf_path)
+      argv = ["clickhouse", "--multiquery"]
+      argv += format_options(output_format)
+      argv << "--path=#{path}" unless path.empty?
+      argv << "--query=#{query_str}"
+      argv += udf_options(udf_path) unless udf_path.empty?
+
+      create_result(argv, output_format)
+    end
+
+    def format_options(output_format)
+      if output_format.casecmp("debug").zero?
+        ["--verbose", "--log-level=trace", "--output-format=CSV"]
+      else
+        ["--output-format=#{output_format}"]
+      end
+    end
+
+    def udf_options(udf_path)
+      ["--", "--user_scripts_path=#{udf_path}",
+       "--user_defined_executable_functions_config=#{udf_path}/*.xml"]
+    end
+
+    def create_result(argv, output_format)
+      result = Chdb::LocalResult.new(argv.length, argv)
+      result.output_format = output_format
+      result
+    end
+  end
+end

data/lib/chdb/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Chdb
+  VERSION = "0.1.0"
+end

data/lib/chdb.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+require_relative "chdb/version"
+require "chdb/chdb"
+require "chdb/local_result"
+require "chdb/session"
+
+# Ruby interface for ClickHouse database, providing direct query execution
+# and session management capabilities
+module Chdb
+  class << self
+    def query(query_str, output_format = "CSV")
+      output_format ||= "CSV" # Default value
+      query_to_buffer(query_str, output_format, "", "")
+    end
+
+    private
+
+    def query_to_buffer(query_str, output_format, path, udf_path)
+      argv = ["clickhouse", "--multiquery"]
+      argv << "--path=#{path}" unless path.empty?
+      argv << "--query=#{build_query_string(query_str, output_format)}"
+      argv += udf_options(udf_path) unless udf_path.empty?
+
+      create_result(argv, output_format)
+    end
+
+    def build_query_string(query_str, output_format)
+      format_suffix = case output_format.downcase
+                      when "csv" then " FORMAT CSVWithNames"
+                      when "json" then " FORMAT JSON"
+                      else ""
+                      end
+      query_str + format_suffix
+    end
+
+    def udf_options(udf_path)
+      ["--", "--user_scripts_path=#{udf_path}",
+       "--user_defined_executable_functions_config=#{udf_path}/*.xml"]
+    end
+
+    def create_result(argv, output_format)
+      result = LocalResult.new(argv.length, argv)
+      result.output_format = output_format
+      result
+    end
+  end
+end

metadata

@@ -0,0 +1,59 @@
+--- !ruby/object:Gem::Specification
+name: chdb
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Gerardo Ortega
+autorequire:
+bindir: exe
+cert_chain: []
+date: 2024-12-20 00:00:00.000000000 Z
+dependencies: []
+description: Ruby interface for the chDB in-process SQL OLAP Engine, providing direct
+  query execution and session management capabilities.
+email:
+- g3ortega@gmail.com
+executables: []
+extensions:
+- ext/chdb/extconf.rb
+extra_rdoc_files: []
+files:
+- LICENSE.txt
+- README.md
+- Rakefile
+- chdb.gemspec
+- ext/chdb/chdb.c
+- ext/chdb/extconf.rb
+- lib/chdb.rb
+- lib/chdb/local_result.rb
+- lib/chdb/session.rb
+- lib/chdb/version.rb
+homepage: https://github.com/g3ortega/chdb
+licenses:
+- MIT
+metadata:
+  allowed_push_host: https://rubygems.org
+  homepage_uri: https://github.com/g3ortega/chdb
+  source_code_uri: https://github.com/g3ortega/chdb
+  changelog_uri: https://github.com/g3ortega/chdb/blob/main/CHANGELOG.md
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.0.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.9
+signing_key:
+specification_version: 4
+summary: Chdb implementation in Ruby
+test_files: []