🚀 PulseDB

A high-performance, lightweight Redis clone written in Go, implementing the RESP2 protocol from scratch. This project serves as a deep dive into building low-level systems and understanding the inner workings of Redis.

⚠️ Educational Project: This is primarily an educational implementation designed for learning purposes. For production use, consider Redis or KeyDB.

🎯 Quick Start

# Using Docker (Recommended)
docker-compose up --build

# Or build from source
go build -o PulseDB ./cmd/PulseDB
./PulseDB

✨ Features

Core Functionality

🔧 Custom RESP2 Protocol: Complete implementation of Redis Serialization Protocol v2
📊 Redis Data Types: Support for all core Redis data types:
- Simple Strings (+OK\r\n)
- Errors (-ERROR message\r\n)
- Integers (:100\r\n)
- Bulk Strings ($6\r\nfoobar\r\n)
- Arrays (*2\r\n$3\r\nfoo\r\n$3\r\nbar\r\n)
⚡High Concurrency: Thread-safe operations with concurrent client handling
💾 Persistence: AOF (Append Only File) and memory snapshots
⏰ Key Expiration: TTL support with automatic cleanup

Performance & Reliability

🔒 Thread Safety: Robust concurrent access with RWMutex
📈 Benchmarks: Comprehensive performance testing included
🧪 Test Coverage: Extensive test suite with >95% coverage
📊 Memory Efficient: Optimized memory usage patterns

📁 Project Structure

PulseDB/
├── cmd/
│   └── PulseDB/        # Main application entry point
├── internal/
│   ├── command/        # Command parsing and execution
│   ├── resp/           # RESP2 protocol implementation
│   ├── server/         # TCP server setup and client handling
│   ├── store/          # In-memory data storage with persistence
│   └── utils/          # Utility functions and helpers
├── bin/                # Compiled binaries
├── docker-compose.yml  # Docker setup for easy deployment
├── Dockerfile          # Container configuration
├── Makefile           # Build automation
├── go.mod             # Go module dependencies
└── README.md          # Project documentation

🛠️ Getting Started

Prerequisites

Go 1.20+ - Download & Install Go
Docker (optional) - Get Docker
Make (optional) - For using the Makefile commands

Installation Options

Option 1: Using Docker (Recommended)

# Clone the repository
git clone https://github.com/DNahar74/PulseDB.git
cd PulseDB

# Run with Docker Compose
docker-compose up --build

# The server will be available at localhost:6378

Option 2: Build from Source

# Clone the repository
git clone https://github.com/DNahar74/PulseDB.git
cd PulseDB

# Build using Makefile
make build

# Or build manually
go build -o bin/PulseDB ./cmd/PulseDB

# Run the server
./bin/PulseDB

Option 3: Development Mode

# Run directly with Go
make run

# Or manually
go run ./cmd/PulseDB

Configuration

PulseDB accepts the following command-line flags:

-addr : Server address (default: :6379)
-v : Show version information
-verbose : Enable verbose logging

./bin/PulseDB -addr :6378 -verbose

🧪 Usage

Connecting to PulseDB

Once the server is running, you can connect using various Redis clients:

Using Redis CLI

# If you have redis-cli installed
redis-cli -p 6379

# Using Docker with redis-cli
docker run -it --rm redis:alpine redis-cli -h host.docker.internal -p 6379

Using Telnet

telnet localhost 6379

Using Docker Compose Redis CLI

# Start the redis-cli service defined in docker-compose.yml
docker-compose run --rm redis-cli

Basic Commands

# Test connection
PING

# Set and get values
SET mykey "Hello, PulseDB!"
GET mykey

# Set with expiration (100 seconds)
SET tempkey "temporary value" EX 100
GET tempkey

# Delete keys
DEL mykey tempkey

# Echo command
ECHO "Hello World"

🔧 Development

Building

# Build for current platform
make build

# Build for all platforms
make build-all

# Clean build artifacts
make clean

Testing

# Run all tests
make test

# Run tests with coverage
make test-coverage

# Run benchmarks
make benchmark

Code Quality

# Format code
make fmt

# Run linter
make lint

# Run security checks
make security

🐳 Docker

The project includes Docker support for easy deployment:

# Build Docker image
docker build -t pulsedb .

# Run container
docker run -p 6379:6378 pulsedb

# Using docker-compose for full setup
docker-compose up -d

📊 Performance

PulseDB is designed for high performance with the following characteristics:

Concurrent Connections: Handles thousands of concurrent clients
Memory Efficiency: Optimized data structures for minimal memory footprint
Protocol Efficiency: Full RESP2 implementation with minimal overhead
Persistence: AOF and snapshot mechanisms for data durability

Benchmarks

Run benchmarks to test performance:

make benchmark

🛠️ Implemented Commands

🟢 `PING`

Description: Tests the connection with the server.
Usage:
```
PING
```
Response:
```
+PONG
```

🗣️ `ECHO`

Description: Returns the input string.
Usage:
```
ECHO "hello world"
```
Response:
```
"hello world"
```

💾 `SET`

Description: Stores a key with a string value. Optional expiry flag in seconds.

Usage:

SET hello world
SET hello world EX 100  # Key expires in 100 seconds

Response:
```
+OK
```

📥 `GET`

Description: Retrieves the value of the given key.
Usage:
```
GET hello
```
Response (if found):
```
"world"
```

❌ `DEL`

Description: Deletes the specified key.
Usage:
```
DEL hello
```
Response:
```
+OK
```

📚 RESP2 Protocol Overview

PulseDB implements the Redis Serialization Protocol (RESP) version 2 for client-server communication.

Data Types

Type	Format	Example
Simple Strings	`+<string>\r\n`	`+OK\r\n`
Errors	`-<error>\r\n`	`-ERROR Invalid command\r\n`
Integers	`:<number>\r\n`	`:1000\r\n`
Bulk Strings	`$<length>\r\n<string>\r\n`	`$6\r\nfoobar\r\n`
Arrays	`*<count>\r\n<element1>...<elementN>`	`*2\r\n$3\r\nfoo\r\n$3\r\nbar\r\n`

For detailed protocol specification, see the Redis Protocol documentation.

🚀 Roadmap

Completed ✅

In Progress 🚧

More Redis commands (INCR, DECR, LPUSH, RPOP, etc.)
Redis data structures (Lists, Sets, Hashes)
Pub/Sub functionality
Clustering support

Future Plans 📋

RESP3 protocol support
Redis modules compatibility
Replication
Lua scripting support

🧱 Contributing

We welcome contributions! Here's how you can help:

Getting Started

Fork the repository
Clone your fork: git clone https://github.com/yourusername/PulseDB.git
Create a feature branch: git checkout -b feature/amazing-feature
Make your changes
Test your changes: make test
Commit your changes: git commit -m 'Add amazing feature'
Push to the branch: git push origin feature/amazing-feature
Open a Pull Request

Development Guidelines

Follow Go best practices and conventions
Add tests for new functionality
Update documentation for API changes
Run make fmt and make lint before committing
Write clear, descriptive commit messages

Issues

Found a bug or have a feature request? Please open an issue with:

Clear description of the problem/feature
Steps to reproduce (for bugs)
Expected vs actual behavior
Go version and OS information

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙌 Acknowledgements

Redis - For the inspiration and protocol specification
Go Team - For creating an amazing programming language
Docker - For simplifying deployment and development
Open Source Community - For continuous inspiration and support

📞 Contact

Project Maintainer: DNahar74

Issues: GitHub Issues
Discussions: GitHub Discussions

⭐ Star this repository if you found it helpful! ⭐

Name		Name	Last commit message	Last commit date
Latest commit History 81 Commits
cmd/PulseDB		cmd/PulseDB
internal		internal
.gitignore		.gitignore
CONTRIBUTING.md		CONTRIBUTING.md
Dockerfile		Dockerfile
LICENSE		LICENSE
Makefile		Makefile
README.md		README.md
RESPdoc.md		RESPdoc.md
docker-compose.yml		docker-compose.yml
go.mod		go.mod

License

DNahar74/PulseDB

Folders and files

Latest commit

History

Repository files navigation