|
4 | 4 |
|
5 | 5 | [](https://github.com/chdb-io/chdb-ruby/actions/workflows/chdb.yml) |
6 | 6 |
|
7 | | -# chdb-ruby |
8 | | -[chDB](https://github.com/chdb-io/chdb) ruby bindings and chDB cli. |
| 7 | +# Ruby Interface for chdb |
| 8 | + |
| 9 | +## Overview |
| 10 | + |
| 11 | +This library allows Ruby programs to use the chDB embedded analytical database (https://github.com/chdb-io/chdb). |
| 12 | + |
| 13 | +**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. |
| 14 | + |
| 15 | +Note that this module is only compatible with ChDB 3.0.0 or newer. |
| 16 | + |
| 17 | +* Source code: https://github.com/chdb-io/chdb-ruby |
| 18 | +* Download: http://rubygems.org/gems/chdb-ruby |
| 19 | +* Documentation: https://clickhouse.com/docs/chdb |
| 20 | + |
| 21 | +## Quick start |
| 22 | + |
| 23 | +``` ruby |
| 24 | +require 'chdb' |
| 25 | + |
| 26 | +# Open a database |
| 27 | +db = ChDB::Database.new('test_db', results_as_hash: true) |
| 28 | + |
| 29 | +# Create a table |
| 30 | +rows = db.execute <<-SQL |
| 31 | + CREATE TABLE test_table( |
| 32 | + id Int32, |
| 33 | + name String) |
| 34 | + ENGINE = MergeTree() |
| 35 | + ORDER BY id); |
| 36 | +SQL |
| 37 | + |
| 38 | +# Execute a few inserts |
| 39 | +{ |
| 40 | + 1 => 'Alice', |
| 41 | + 2 => 'Bob' |
| 42 | +}.each do |pair| |
| 43 | + db.execute 'INSERT INTO test_table VALUES ( ?, ? )', pair |
| 44 | +end |
| 45 | + |
| 46 | +# Find a few rows |
| 47 | +db.execute('SELECT * FROM test_table ORDER BY id') do |row| |
| 48 | + p row |
| 49 | +end |
| 50 | +# [{ 'id' => '1', 'name' => 'Alice' }, |
| 51 | +# { 'id' => '2', 'name' => 'Bob' }] |
| 52 | + |
| 53 | +# Open another database |
| 54 | +db = ChDB::Database.new 'test2.db' |
| 55 | + |
| 56 | +# Create another table |
| 57 | +rows = db.execute <<-SQL |
| 58 | + CREATE TABLE test2_table( |
| 59 | + id Int32, |
| 60 | + name String) |
| 61 | + ENGINE = MergeTree() |
| 62 | + ORDER BY id"); |
| 63 | +SQL |
| 64 | +
|
| 65 | +# Execute inserts with parameter markers |
| 66 | +db.execute('INSERT INTO test2_table (id, name) |
| 67 | + VALUES (?, ?)', [3, 'Charlie']) |
| 68 | +
|
| 69 | +db.execute2('SELECT * FROM test2_table') do |row| |
| 70 | + p row |
| 71 | +end |
| 72 | +# [['id', 'name'], [3, 'Charlie']], |
| 73 | +``` |
| 74 | +
|
| 75 | +## Thread Safety |
| 76 | +
|
| 77 | +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. |
| 78 | +
|
| 79 | +For example, the following code is fine because only the database |
| 80 | +instance is shared among threads: |
| 81 | +
|
| 82 | +```ruby |
| 83 | +require 'chdb' |
| 84 | +
|
| 85 | +db = ChDB::Database.new ":memory:' |
| 86 | +
|
| 87 | +latch = Queue.new |
| 88 | +
|
| 89 | +ts = 10.times.map { |
| 90 | + Thread.new { |
| 91 | + latch.pop |
| 92 | + db.execute 'SELECT 1' |
| 93 | + } |
| 94 | +} |
| 95 | +10.times { latch << nil } |
| 96 | +
|
| 97 | +p ts.map(&:value) |
| 98 | +``` |
| 99 | +
|
| 100 | +Other instances can be shared among threads, but they require that you provide |
| 101 | +your own locking for thread safety. For example, `ChDB::Statement` objects |
| 102 | +(prepared statements) are mutable, so applications must take care to add |
| 103 | +appropriate locks to avoid data race conditions when sharing these objects |
| 104 | +among threads. |
| 105 | +
|
| 106 | +It is generally recommended that if applications want to share a database among |
| 107 | +threads, they _only_ share the database instance object. Other objects are |
| 108 | +fine to share, but may require manual locking for thread safety. |
| 109 | +
|
| 110 | +## Support |
| 111 | +
|
| 112 | +### Installation |
| 113 | +
|
| 114 | +If you're having trouble with installation, please first read [`INSTALLATION.md`](./INSTALLATION.md). |
| 115 | +
|
| 116 | +### Bug reports |
| 117 | +
|
| 118 | +You can file the bug at the [github issues page](https://github.com/chdb-io/chdb-ruby/issues). |
| 119 | +
|
| 120 | +## License |
| 121 | +
|
| 122 | +This library is licensed under `Apache License 2.0`, see [`LICENSE`](./LICENSE). |
0 commit comments