clickhouse-ruby 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: d7855eb261fe694066b665b2d1408b837a751d257c26d88f74d29847869fe652
+  data.tar.gz: 524b169428f84ab3f24c26433b4b57ead1f41e6147551c412e0f0a1840a8f7c9
+SHA512:
+  metadata.gz: 76da6aa320dabde964561304404eecfba2f500437ffc763f1bb15f6c5917c1cf703b1c14f2ec76024f7a585749993cd047dd7e6576dc2e33c2754e9677865556
+  data.tar.gz: 7bba509232194cef0a8dd560a08434d16a6ba3fd04a96d7868e1b00080d0421834e1a88c07f76c592589aadf2b473703ae6f3b5dd3cc692fcae6f3798843a446

data/CHANGELOG.md

@@ -0,0 +1,80 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-01-31
+
+### Added
+
+#### Core Features
+- HTTP client with connection pooling for ClickHouse communication
+- SSL/TLS support with certificate verification **enabled by default** (security fix vs existing gems)
+- Configurable timeouts (connect, read, write)
+- Basic authentication (username/password via headers)
+- Connection health checks (ping)
+
+#### Error Handling (Critical Fix)
+- Proper HTTP status code checking - **never silently ignores errors**
+- Clear exception hierarchy (`ClickhouseRuby::Error` → `QueryError`, `ConnectionError`, etc.)
+- ClickHouse error code extraction and mapping to specific exception classes
+- Actionable error messages with full context (SQL, error code, HTTP status)
+
+#### Type System (Critical Fix)
+- **AST-based type parser** - properly handles nested types (fixes regex-based parsing issues)
+- Support for all basic types: String, Int8-256, UInt8-256, Float32/64, Bool
+- Date/DateTime/DateTime64 with timezone awareness
+- UUID with format validation
+- Complex types: Array(T), Map(K,V), Tuple(T1,T2,...), Nullable(T), LowCardinality(T)
+- Bidirectional type conversion (Ruby ↔ ClickHouse)
+
+#### Query Execution
+- SELECT queries with JSONCompact format
+- Result object with Enumerable interface
+- Column type information in results
+- Query-level SETTINGS support
+
+#### Bulk Insert
+- JSONEachRow format support (5x faster than VALUES syntax)
+- INSERT with SETTINGS support (async_insert, etc.)
+- Batch insert API with proper error handling
+
+#### ActiveRecord Integration
+- Connection adapter registration (`adapter: clickhouse`)
+- Basic CRUD operations with proper error propagation
+- Schema introspection (tables, columns via system tables)
+- Arel visitor for ClickHouse SQL dialect
+- ALTER TABLE DELETE/UPDATE syntax for mutations
+- Rails integration via Railtie
+
+#### Project Infrastructure
+- RSpec test suite with unit and integration tests
+- VCR for HTTP interaction recording
+- Docker Compose setup for ClickHouse testing
+- GitHub Actions CI workflow
+- RuboCop configuration
+
+### Security
+- SSL certificate verification is ON by default (unlike existing gems)
+- Passwords not logged
+
+### Known Limitations
+- HTTP protocol only (native TCP protocol planned for future)
+- No PREWHERE support yet (planned for v0.2.0)
+- No streaming results yet (planned for v0.2.0)
+- No migration DSL for table engines/partitions yet (planned for v0.2.0)
+
+## Comparison with Existing Solutions
+
+This gem addresses critical issues found in existing ClickHouse Ruby gems:
+
+| Issue | clickhouse-activerecord | ClickhouseRuby |
+|-------|------------------------|--------|
+| Silent DELETE failures (#230) | ❌ Fails silently | ✅ Always raises errors |
+| Type parsing (#210) | ❌ Regex breaks nested | ✅ AST-based parser |
+| SSL verification | ❌ Disabled by default | ✅ Enabled by default |
+| PREWHERE support (#228) | ❌ Missing | 🔜 Planned v0.2.0 |

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Your Name
+
+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,251 @@
+# ClickhouseRuby
+
+A lightweight Ruby client for ClickHouse with optional ActiveRecord integration.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'clickhouse-ruby'
+```
+
+And then execute:
+
+```bash
+bundle install
+```
+
+Or install it yourself as:
+
+```bash
+gem install clickhouse-ruby
+```
+
+## Quick Start
+
+```ruby
+require 'clickhouse-ruby'
+
+# Create a client
+client = ClickhouseRuby::Client.new(
+  host: 'localhost',
+  port: 8123,
+  database: 'default'
+)
+
+# Execute a query
+result = client.query('SELECT 1 + 1 AS result')
+puts result.first['result'] # => 2
+
+# Insert data
+client.insert('events', [
+  { date: '2024-01-01', event_type: 'click', count: 100 },
+  { date: '2024-01-02', event_type: 'view', count: 250 }
+])
+```
+
+## Configuration
+
+### Basic Configuration
+
+```ruby
+ClickhouseRuby.configure do |config|
+  config.host = 'localhost'
+  config.port = 8123
+  config.database = 'default'
+  config.username = 'default'
+  config.password = ''
+  config.ssl = false
+  config.timeout = 60
+end
+
+# Use the default client
+client = ClickhouseRuby.client
+```
+
+### Configuration Options
+
+| Option | Description | Default |
+|--------|-------------|---------|
+| `host` | ClickHouse server hostname | `localhost` |
+| `port` | HTTP interface port | `8123` |
+| `database` | Default database | `default` |
+| `username` | Authentication username | `default` |
+| `password` | Authentication password | `''` |
+| `ssl` | Enable HTTPS | `false` |
+| `timeout` | Request timeout in seconds | `60` |
+| `max_retries` | Number of retry attempts | `3` |
+
+### Environment Variables
+
+ClickhouseRuby can be configured via environment variables:
+
+```bash
+CLICKHOUSE_HOST=localhost
+CLICKHOUSE_PORT=8123
+CLICKHOUSE_DATABASE=default
+CLICKHOUSE_USERNAME=default
+CLICKHOUSE_PASSWORD=secret
+CLICKHOUSE_SSL=false
+```
+
+## Usage
+
+### Querying Data
+
+```ruby
+# Simple query
+result = client.query('SELECT * FROM events LIMIT 10')
+
+# Query with parameters (prevents SQL injection)
+result = client.query(
+  'SELECT * FROM events WHERE date = {date:Date}',
+  params: { date: '2024-01-01' }
+)
+
+# Query with specific format
+result = client.query('SELECT * FROM events', format: 'JSONEachRow')
+```
+
+### Inserting Data
+
+```ruby
+# Insert hash array
+client.insert('events', [
+  { date: '2024-01-01', event_type: 'click', count: 100 },
+  { date: '2024-01-02', event_type: 'view', count: 250 }
+])
+
+# Insert with explicit columns
+client.insert('events', data, columns: [:date, :event_type, :count])
+
+# Bulk insert from CSV
+client.insert_from_file('events', '/path/to/data.csv', format: 'CSV')
+```
+
+### DDL Operations
+
+```ruby
+# Create table
+client.execute(<<~SQL)
+  CREATE TABLE events (
+    date Date,
+    event_type String,
+    count UInt32
+  ) ENGINE = MergeTree()
+  ORDER BY date
+SQL
+
+# Check if table exists
+client.table_exists?('events') # => true
+
+# Get table schema
+schema = client.describe_table('events')
+```
+
+### Connection Management
+
+```ruby
+# Check connection
+client.ping # => true
+
+# Get server version
+client.server_version # => "24.1.1.123"
+
+# Execute multiple queries in a session
+client.with_session do |session|
+  session.execute('SET max_memory_usage = 1000000000')
+  session.query('SELECT * FROM large_table')
+end
+```
+
+## ActiveRecord Integration
+
+ClickhouseRuby provides optional ActiveRecord integration for familiar model-based access.
+
+```ruby
+# config/initializers/clickhouse-ruby.rb
+require 'clickhouse-ruby/active_record'
+
+ClickhouseRuby::ActiveRecord.establish_connection(
+  host: 'localhost',
+  database: 'analytics'
+)
+
+# app/models/event.rb
+class Event < ClickhouseRuby::ActiveRecord::Base
+  self.table_name = 'events'
+end
+
+# Usage
+Event.where(date: '2024-01-01').limit(10).each do |event|
+  puts event.event_type
+end
+```
+
+## Error Handling
+
+```ruby
+begin
+  client.query('SELECT * FROM nonexistent_table')
+rescue ClickhouseRuby::ConnectionError => e
+  # Handle connection issues
+  puts "Connection failed: #{e.message}"
+rescue ClickhouseRuby::QueryError => e
+  # Handle query errors
+  puts "Query failed: #{e.message}"
+  puts "Error code: #{e.code}"
+rescue ClickhouseRuby::TimeoutError => e
+  # Handle timeouts
+  puts "Request timed out: #{e.message}"
+end
+```
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests.
+
+### Running Tests
+
+```bash
+# Start ClickHouse
+docker-compose up -d
+
+# Run all tests
+bundle exec rake spec
+
+# Run only unit tests
+bundle exec rake spec_unit
+
+# Run integration tests
+bundle exec rake spec_integration
+```
+
+### Code Quality
+
+```bash
+# Run RuboCop
+bundle exec rake rubocop
+
+# Auto-fix issues
+bundle exec rake rubocop_fix
+```
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/yourusername/clickhouse-ruby.
+
+1. Fork it
+2. Create your feature branch (`git checkout -b feature/my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin feature/my-new-feature`)
+5. Create a new Pull Request
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](LICENSE).
+
+## Documentation
+
+Full documentation is available at [RubyDoc](https://rubydoc.info/gems/clickhouse-ruby).