How kojix2/leveldb works
Purpose and Entry Point
This is a Crystal shard exposing Google LevelDB as an idiomatic Crystal key-value database API. Consumers load src/leveldb.cr, which assembles the public namespace and binding layers. The native LevelDB shared library is an external runtime dependency installed through the host OS package manager.
Paths: src/leveldb.cr, shard.yml, c.h
Native Binding Boundary
LevelDB::LibLevelDB is the FFI boundary to LevelDB’s C API: opaque native handles, C enums, and calls for database operations, options, iterators, snapshots, and batches. Crystal-facing code must translate strings/buffers, native error outputs, and handle ownership across this boundary.
Paths: src/leveldb/lib_leveldb.cr, c.h, src/leveldb/errors.cr
Database Lifecycle and Core Operations
LevelDB::DB owns an opened native database handle and is the primary application control surface. DB.open supports scoped use so callers can reliably close the database. It provides reads, writes, deletes, indexed access, batch writes, iteration, snapshots, and error propagation.
Primary flow: application → LevelDB::DB → LibLevelDB C API → local LevelDB database files. Native failures become LevelDB::Error.
Paths: src/leveldb/db.cr, src/leveldb/lib_leveldb.cr, src/leveldb/errors.cr
Configuration and Read/Write Semantics
Crystal option wrappers encapsulate native LevelDB option handles and setters. Options configures database creation, cache/file behavior, and compression; ReadOptions carries consistency choices such as snapshots; write options control write behavior. These objects form a configuration boundary: callers set policy before passing handles into DB operations.
Paths: src/leveldb/options.cr, src/leveldb/db.cr, src/leveldb/lib_leveldb.cr
Iteration and Snapshot Consistency
Iterator wraps a native iterator and exposes seek, validity checks, movement, key/value access, and deferred error checking. DB convenience iteration delegates to this lifecycle. Snapshots are native consistency handles created by the DB, attached to read options, then explicitly released, allowing stable reads while writes continue.
Paths: src/leveldb/iterator.cr, src/leveldb/db.cr, src/leveldb/options.cr
Atomic Batch Mutation
WriteBatch is a separate native-backed mutation accumulator. Callers add puts and deletes, submit the batch through DB#write, and close it when finished. This separates construction of an atomic write unit from database execution and makes batch-handle lifetime explicit.
Paths: src/leveldb/write_batch.cr, src/leveldb/db.cr, src/leveldb/lib_leveldb.cr
Execution and Verification Context
The runtime is Crystal plus the system-installed LevelDB C library on macOS or Debian/Ubuntu. Examples demonstrate the intended public API patterns; CI validates the shard’s native integration and Crystal behavior.
Paths: examples/basic.cr, examples/iterator.cr, .github/workflows/ci.yml
Main entry points: lib_leveldb.cr LibLevelDB · leveldb.cr LevelDB namespace · db.cr DB · iterator.cr Iterator
Components 14
Crystal API
- LevelDB namespace · Assembles the public API and bindings.
src/leveldb.cr - DB · Owns the opened native database handle.
src/leveldb/db.cr - Options · Own native option handles and read/write policy.
src/leveldb/options.cr - Iterator · Wraps native traversal and deferred error checks.
src/leveldb/iterator.cr - WriteBatch · Builds an atomic native-backed write unit.
src/leveldb/write_batch.cr - LevelDB::Error · Represents translated native failures.
src/leveldb/errors.cr
Native boundary
- LibLevelDB · C API handles, enums, calls, and ownership boundary.
src/leveldb/lib_leveldb.cr - LevelDB C header
c.h
Runtime & verification
- System LevelDB · Host-installed LevelDB C runtime.
- LevelDB files
- Usage examples · Demonstrate basic database and iterator API patterns.
examples/basic.cr - Iterator example
examples/iterator.cr - CI · Validates Crystal behavior against native LevelDB.
.github/workflows/ci.yml - Shard manifest
shard.yml
Connections 19
- LevelDB namespace → DB: exports
- LevelDB namespace → Options: exports
- LevelDB namespace → Iterator: exports
- LevelDB namespace → WriteBatch: exports
- LevelDB namespace → LibLevelDB: loads bindings
- DB → Options: accepts policies
- DB → Iterator: creates and drives
- DB → WriteBatch: submits batch
- DB → LibLevelDB: database operations
- Iterator → LibLevelDB: iterator calls
- WriteBatch → LibLevelDB: batch calls
- LibLevelDB → LevelDB::Error: translates failures
- LibLevelDB → LevelDB C header: maps C API
- LibLevelDB → System LevelDB: FFI calls
- System LevelDB → LevelDB files: reads and writes
- Usage examples → DB: uses
- Iterator example → Iterator: uses
- CI → System LevelDB: tests integration
- Shard manifest → LevelDB namespace: packages