DriftDB Development Assistant

Expert guidance for working with DriftDB, an experimental append-only database with built-in time travel, immutable audit trails, and guaranteed data integrity.

Overview

DriftDB is an append-only database with time-travel capabilities, structured as a Rust workspace. It implements event-sourcing with CRC-verified segments, B-tree indexes, and zstd-compressed snapshots for efficient historical queries.

Build Commands

**Release build:**

```bash

cargo build --release

```

**Development build:**

```bash

cargo build

```

Testing Strategy

**Run all tests:**

```bash

cargo test --all

```

**Test specific crate:**

```bash

cargo test -p driftdb-core

cargo test -p driftdb-cli

```

**Single test with output:**

```bash

cargo test test_name -- --nocapture

```

Tests are co-located with source using `#[cfg(test)]` modules. The project uses unit tests, integration tests with temporary databases, property-based testing with `proptest`, and `criterion` benchmarks.

Development Workflow

**Format code:**

```bash

cargo fmt --all

```

**Run linter (must pass with zero warnings):**

```bash

cargo clippy --all -- -D warnings

```

**Full CI check (format + clippy + tests):**

```bash

make ci

```

**Run benchmarks:**

```bash

cargo bench --all

```

**Run demo scenario:**

```bash

make demo

```

Architecture

Crate Structure

**`crates/driftdb-core/`** - Core database engine:

**`crates/driftdb-cli/`** - Command-line interface:

Core Components

**Storage Architecture:**

**Engine (`src/engine.rs`):**

**Event System:**

Time Travel Implementation

Queries support temporal clauses to access historical states:

**Note:** DriftDB uses custom temporal syntax, not SQL:2011's `FOR SYSTEM_TIME` standard.

Safety Features

SQL Query Language

DriftDB implements a SQL-inspired query language with custom temporal extensions. Parser is in `crates/driftdb-core/src/query/parser.rs` using nom combinators.

**Supported operations:**

**Example time-travel query:**

```sql

SELECT * FROM users AS OF @seq:1000 WHERE age > 25;

SELECT * FROM events AS OF "2024-01-15T10:00:00Z";

```

Key Dependencies

Guidelines for Claude Code

When working with DriftDB:

1. **Always run `cargo clippy --all -- -D warnings`** before committing - zero warnings required

2. **Format with `cargo fmt --all`** to maintain consistent style

3. **Co-locate tests** with source files using `#[cfg(test)]` modules

4. **Verify CRC integrity** when modifying storage layer code

5. **Test time-travel queries** when changing event replay logic

6. **Run `make ci`** for full validation before pushing

7. **Use `parking_lot` primitives** instead of std for synchronization

8. **Preserve immutability** - never modify existing events, only append new ones

9. **Consider snapshot performance** when modifying query paths

10. **Document temporal semantics** clearly when adding new query features