{"id":27111866,"url":"https://github.com/chdb-io/chdb-ruby","last_synced_at":"2025-04-07T01:25:06.456Z","repository":{"id":284324404,"uuid":"954540140","full_name":"chdb-io/chdb-ruby","owner":"chdb-io","description":"chdb-ruby is a Ruby library for accessing chDB embedded analytical database with SQLite3-compatible API design.","archived":false,"fork":false,"pushed_at":"2025-04-01T10:32:44.000Z","size":65,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-04-01T11:31:22.387Z","etag":null,"topics":["chdb","ruby","ruby-gem"],"latest_commit_sha":null,"homepage":"https://clickhouse.com/chdb","language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/chdb-io.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":["chdb-io"]}},"created_at":"2025-03-25T08:38:06.000Z","updated_at":"2025-04-01T10:32:48.000Z","dependencies_parsed_at":"2025-03-25T10:32:18.504Z","dependency_job_id":"0944c83e-d3e7-40aa-8391-178121501187","html_url":"https://github.com/chdb-io/chdb-ruby","commit_stats":null,"previous_names":["chdb-io/chdb-ruby"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chdb-io%2Fchdb-ruby","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chdb-io%2Fchdb-ruby/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chdb-io%2Fchdb-ruby/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chdb-io%2Fchdb-ruby/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/chdb-io","download_url":"https://codeload.github.com/chdb-io/chdb-ruby/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247575567,"owners_count":20960798,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["chdb","ruby","ruby-gem"],"created_at":"2025-04-07T01:25:05.788Z","updated_at":"2025-04-07T01:25:06.440Z","avatar_url":"https://github.com/chdb-io.png","language":"Ruby","funding_links":["https://github.com/sponsors/chdb-io"],"categories":["Language bindings"],"sub_categories":[],"readme":"\u003ca href=\"https://chdb.io\" target=\"_blank\"\u003e\n  \u003cimg src=\"https://avatars.githubusercontent.com/u/132536224\" width=130 /\u003e\n\u003c/a\u003e\n\n[![chDB-ruby](https://github.com/chdb-io/chdb-ruby/actions/workflows/chdb.yml/badge.svg)](https://github.com/chdb-io/chdb-ruby/actions/workflows/chdb.yml)\n\n# Ruby Interface for chdb\n\n## Overview\n\nThis library allows Ruby programs to use the chDB embedded analytical database (https://github.com/chdb-io/chdb).\n\n**Designed with SQLite3-compatible API style** - If you're familiar with Ruby's sqlite3 gem, you'll feel right at home with chdb-ruby's similar interface design.\n\nNote that this module is only compatible with ChDB 3.0.0 or newer.\n\n* Source code: https://github.com/chdb-io/chdb-ruby\n* Download: http://rubygems.org/gems/chdb-ruby\n* Documentation: https://clickhouse.com/docs/chdb\n\n## Quick start\n\nBefore using chdb-ruby, install the gem first. This will download the libchdb C++ library dependencies, so please be patient:\n```bash\ngem install chdb-ruby\n```\n\nBelow are examples of common interfaces usage:\n\n```ruby\nrequire 'chdb'\n\n# Open a database\n# Parameter explanation:\n# 1. path supports two formats:\n#    - \":memory:\" in-memory temporary database (data destroyed on close)\n#    - \"file:/path/to/db\" file-based persistent database\n#    Configuration parameters can be appended via URL-style query (e.g. 'file:test.db?results_as_hash=true')\n# 2. options hash supports:\n#    - results_as_hash: controls whether result sets return as hashes (default: arrays)\ndb = ChDB::Database.new('file:test.db', results_as_hash: true)\n\n# Create a database\ndb.execute('CREATE DATABASE IF NOT EXISTS test')\n\n# Create a table\ndb.execute('DROP TABLE IF EXISTS test.test_table')\nrows = db.execute \u003c\u003c-SQL\n  CREATE TABLE test.test_table(\n    id Int32,\n    name String)\n    ENGINE = MergeTree()\n    ORDER BY id\nSQL\n\n# Execute a few inserts\n{\n  1 =\u003e 'Alice',\n  2 =\u003e 'Bob'\n}.each do |pair|\n  db.execute 'INSERT INTO test.test_table VALUES ( ?, ? )', pair\nend\n\n# Find a few rows\ndb.execute('SELECT * FROM test.test_table ORDER BY id') do |row|\n  p row\nend\n# [{ 'id' =\u003e '1', 'name' =\u003e 'Alice' },\n#  { 'id' =\u003e '2', 'name' =\u003e 'Bob' }]\n\n# When you need to open another database, you must first close the previous database \ndb.close()\n\n# Open another database\ndb = ChDB::Database.new 'file:test.db'\n\n# Create another table\ndb.execute('DROP TABLE IF EXISTS test.test2_table')\nrows = db.execute \u003c\u003c-SQL\n  CREATE TABLE test.test2_table(\n    id Int32,\n    name String)\n    ENGINE = MergeTree()\n    ORDER BY id\nSQL\n\n# Execute inserts with parameter markers\ndb.execute('INSERT INTO test.test2_table (id, name)\n            VALUES (?, ?)', [3, 'Charlie'])\n\n# Find rows with the first row displaying column names\ndb.execute2('SELECT * FROM test.test2_table') do |row|\n  p row\nend\n# [\"id\", \"name\"]\n# [\"3\", \"Charlie\"]\n\n# Close the database\ndb.close()\n\n# Use ChDB::Database.open to automatically close the database connection:\nChDB::Database.open('file:test.db') do |db|\n  result = db.execute('SELECT 1')\n  p result.to_a # =\u003e [[\"1\"]]\nend\n\n# Query with specific output formats (CSV, JSON, etc.):\n# See more details at https://clickhouse.com/docs/interfaces/formats.\nChDB::Database.open(':memory:') do |db|\n  csv_data = db.query_with_format('SELECT 1 as a, 2 as b', 'CSV')\n  p csv_data\n  # \"1,2\\n\"\n\n  json_data = db.query_with_format('SELECT 1 as a, 2 as b', 'JSON')\n  p json_data\nend\n```\n\n## Thread Safety\n\nWhen 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.\n**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.\n\n```ruby\nrequire 'chdb'\n\ndb = ChDB::Database.new ':memory:'\n\nlatch = Queue.new\n\nts = 10.times.map {\n  Thread.new {\n    latch.pop\n    db.execute 'SELECT 1'\n  }\n}\n10.times { latch \u003c\u003c nil }\n\np ts.map(\u0026:value)\n# [[[\"1\"]], [[\"1\"]], [[\"1\"]], [[\"1\"]], [[\"1\"]], [[\"1\"]], [[\"1\"]], [[\"1\"]], [[\"1\"]], [[\"1\"]]]\n\ndb.close()\n```\n\nOther instances can be shared among threads, but they require that you provide\nyour own locking for thread safety.  For example, `ChDB::Statement` objects\n(prepared statements) are mutable, so applications must take care to add\nappropriate locks to avoid data race conditions when sharing these objects\namong threads.\n\nIt is generally recommended that if applications want to share a database among\nthreads, they _only_ share the database instance object. Other objects are\nfine to share, but may require manual locking for thread safety.\n\n## Support\n\n### Installation\n\nIf you're having trouble with installation, please first read [`INSTALLATION.md`](./INSTALLATION.md).\n\n### Bug reports\n\nYou can file the bug at the [github issues page](https://github.com/chdb-io/chdb-ruby/issues).\n\n## License\n\nThis library is licensed under `Apache License 2.0`, see [`LICENSE`](./LICENSE).\n\n## Acknowledgments\nSpecial thanks to the following projects:\n\n* [chDB 2.0 Ruby client](https://github.com/g3ortega/chdb) – As the foundational work for chDB 2.0, its design and architecture inspired this chDB 3.0 Ruby client.\n* [SQLite3](https://github.com/sparklemotion/sqlite3-ruby) – We adopted patterns from its elegant Ruby API design.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fchdb-io%2Fchdb-ruby","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fchdb-io%2Fchdb-ruby","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fchdb-io%2Fchdb-ruby/lists"}