Skip to content

CLAUDE.md

Latest commit

 

History

History
73 lines (56 loc) · 2.61 KB

CLAUDE.md

File metadata and controls

73 lines (56 loc) · 2.61 KB
Raw

CLAUDE.md

Project Overview

libsql-ruby2 — Ruby bindings for libSQL using the libsql crate + magnus. Resolves issues in the existing turso_libsql gem (INTEGER sign bug, debug logging, encoding, etc.).

Language Rules

  • All code, comments, commit messages, and documentation must be in English.

Documentation

Design documents are in docs/. Review before implementation.

  • docs/README.md — Document index
  • docs/architecture.md — Architecture, tech choices, implementation patterns
  • docs/api.md — Ruby API design, type mapping
  • docs/testcase.md — TDD test case specifications
  • docs/private/README.md — Internal development documents index (gitignored)

Tech Stack

  • Ruby: gem (libsql2), RSpec, rake-compiler, rb_sys
  • Rust: magnus 0.8, libsql 0.9, tokio (rt-multi-thread)
  • Build: rb-sys + rake-compiler, ext/libsql2/extconf.rb
  • Release: GitHub Actions cross-compilation via oxidize-rb/actions

Directory Structure

├── ext/libsql2/         # Rust native extension (magnus)
│   ├── src/             # Rust source
│   ├── Cargo.toml
│   └── extconf.rb
├── lib/                 # Ruby code
│   ├── libsql2.rb       # require entry point
│   └── libsql/          # module
├── spec/                # RSpec tests
├── docs/                # Design documents
├── Cargo.toml           # Rust workspace
├── Rakefile
├── Gemfile
└── libsql2.gemspec

Development Commands

bundle install           # Install Ruby dependencies
rake compile             # Compile Rust extension
rake spec                # Run RSpec tests
rake build               # Build gem
rake lint                # Run all linters (rubocop + clippy)
rake fmt                 # Auto-format all code (rubocop -a + cargo fmt)
rake fmt:check           # Check formatting (CI)

Development Approach

  • TDD: write tests first, implement to make them pass
  • Test cases defined in docs/testcase.md (RSpec-style specs)
  • Follow development phases in docs/private/ (Phase 0–7)
  • API must conform to docs/api.md

Key Design Decisions

  • tokio Runtime: Owned by Database, shared to Connection/Statement via Arc
  • Rows fetching: Eager (all rows read into Vec at query time)
  • Thread safety: Assumes GVL. Ractor support is a future consideration
  • Parameters: Positional (Array) only. Named params (Hash) not in initial release
  • Blob detection: Blob is a String subclass — check is_a?(Blob) before is_a?(String)
  • Fork safety: Database#discard! for explicit resource cleanup. tokio Runtime is not fork-safe