waldb

A Write-Ahead Log (WAL) based key-value database written in Go. It provides durability and atomicity for key-value operations using a simple and efficient design.

Features

• Write-ahead logging for durability
• Simple key-value operations
• Batch operations support
• Database snapshots
• Health checks and repair utilities

Documentation

• Design Document - Architecture and design decisions

Installation

From Source

git clone https://github.com/julianstephens/waldb.git
cd waldb
go build -o waldb ./cmd/waldb

From Release

Download pre-built binaries from the releases page.

Usage

# Initialize a new database
waldb init /path/to/db

# Store a key-value pair
waldb put mykey myvalue

# Retrieve a value
waldb get mykey

# Delete a key
waldb del mykey

# Show database statistics
waldb stats

# Check database health
waldb doctor

# Repair a database
waldb repair /path/to/db

For detailed command help:

waldb --help
waldb <command> --help

Development

Prerequisites

• Go 1.25 or later
• golangci-lint (for linting)

Building

go build -o waldb ./cmd/waldb

Testing

Run all tests:

go test ./...

Run unit tests:

go test ./internal/waldb/... ./cmd/...

Run E2E tests:

go test ./internal/tests/e2e/...

Run tests with race detection:

go test -race ./...

Run tests with coverage:

go test -coverprofile=coverage.out ./...
go tool cover -html=coverage.out

Linting

Format code:

golangci-lint fmt

Run golangci-lint:

golangci-lint run

Using Make (Optional)

A Makefile is provided for convenience:

make build    # Build the binary
make test     # Run tests
make lint     # Run linters
make fmt      # Format code
make clean    # Clean build artifacts

Project Structure

waldb/
├── cmd/
│   └── waldb/          # Main CLI application
├── internal/
│   ├── waldb/          # Core database implementation
│   ├── cli/            # Command handlers
│   ├── testutil/       # Test helpers and mocks
│   └── tests/e2e/      # End-To-End tests
├── docs/               # Documentation
├── .github/
│   └── workflows/      # CI/CD workflows
├── go.mod
├── go.sum
├── Makefile
├── LICENSE
└── README.md

License

MIT License - see LICENSE for details.