Vachis - High-Performance Redis-Compatible Cache

This document serves as both a quick start guide to Vachis and a detailed resource for building it from source.

Table of contents

• What is Vachis?
  • Key use cases
  • Why choose Vachis?
• Getting started
  • Using Docker
  • Using a Redis client (redis-cli)
• Vachis features, engines, and capabilities
• Community
• Build Vachis from source
  • Build and run Vachis - Linux / macOS / Windows
  • Building Vachis - general notes
• Configuration
  • Command Line Options
  • Environment Variables
• Testing and Benchmarking
• Code contributions
• License

What is Vachis?

For developers who are building high-performance applications, Vachis is a next-generation, in-memory cache system that provides Redis protocol compatibility alongside an advanced storage engine, structured data support, and intelligent memory management.

Key use cases

Vachis excels in various applications, including:

• Drop-in Cache Replacement: Use existing Redis clients and infrastructure for a seamless upgrade.
• Structured Data Caching: Natively store, query, and manipulate JSON, MessagePack, and binary JSON (JSONB) objects.
• High-Volume, Repetitive Data Storage: Significantly reduce memory footprint with automatic SHA256 content deduplication and smart compression.
• Cost-Effective Memory Management: Handle workloads larger than available RAM with an automatic and intelligent disk overflow system.
• High-Concurrency Systems: Built with thread-safe, sharded data structures to maximize parallelism and throughput.
• Real-time Analytics & Monitoring: Use fast existence checks (Bloom filters) and efficient sorted operations (skip lists) for demanding workloads.

Why choose Vachis?

Vachis is a compelling choice for developers due to its unique combination of compatibility, efficiency, and modern features.

• Performance: Vachis is written in the V language for high performance. It uses optimized data structures like concurrent hash maps, skip lists, and bloom filters to achieve low-latency operations.
• Flexibility: Vachis isn't just a key-value store. It provides native support for structured data like JSON and MessagePack, complete with query and manipulation commands.
• Efficiency: The storage engine automatically deduplicates content and applies entropy-based compression, leading to significant memory savings.
• Resilience: An integrated Memory Security System monitors system memory and gracefully overflows to disk when nearing capacity, preventing out-of-memory errors and promoting hot data back to RAM on access.
• Simplicity: Vachis offers a drop-in replacement experience for Redis users. The build process is straightforward, and it can be run easily via command line or Docker.
• Protocol Intelligence: The server can handle both the standard Redis protocol and the native Vedis protocol, automatically detecting the client type.

Getting started

If you want to get up and running with Vachis quickly without needing to build from source, use Docker.

Using Docker

The official Vachis Docker images provide the quickest path to a running instance.

# Build the Docker image from the source directory
make docker-build

# Run the Vachis container
make docker-run

This will start a Vachis instance on the default port 6379.

Using a Redis client (redis-cli)

Because Vachis is Redis protocol compatible, you can use redis-cli and other Redis clients to interact with it.

Start a Vachis server, and then, in another terminal, try the following:

# Connect with redis-cli
redis-cli

redis> ping
PONG
redis> set mykey "Hello Vachis"
OK
redis> get mykey
"Hello Vachis"
redis> incr counter
(integer) 1
redis> # Set a JSON object
redis> JSET user:1 $ '{"name":"John","age":30,"city":"NYC"}'
OK
redis> # Get a specific field from the JSON object
redis> JGET user:1 $.name
"John"

Vachis features, engines, and capabilities

Vachis provides a variety of data types, storage engines, and capabilities to support a wide range of use cases:

• Redis-Compatible Commands: Supports core commands like GET, SET, DEL, EXISTS, MGET, MSET, INCR, DECR, EXPIRE, TTL, KEYS, and PING for drop-in compatibility.
• JSON: Store, retrieve, and query nested JSON documents. Supports path-based operations for getting, setting, deleting, and merging fields.
• JSONB (Binary JSON): A compressed binary format for JSON, offering improved performance and reduced memory usage for structured data.
• MessagePack: An efficient binary serialization format for storing and retrieving complex data structures compactly.
• V Structs: Native serialization for structs from the V programming language.
• SHA256 Content Deduplication: An intelligent storage feature that automatically detects and deduplicates identical values, storing only a single copy with a reference counter. This dramatically reduces memory usage for repetitive data.
• Smart Compression: An entropy-based compression system that analyzes data and chooses the most effective algorithm to reduce its size in memory.
• Memory Security System: A three-tier storage strategy to ensure stability:
  • Hot Memory: Frequently accessed data in RAM.
  • Cold Memory: Less-accessed data, compressed in RAM.
  • Disk Overflow: Automatically migrates the least-recently-used (LRU) data to ephemeral disk storage when system memory usage exceeds a 90% threshold. Data is automatically promoted back to memory on access.
• Bloom Filters: A probabilistic data structure providing O(1) existence checks with minimal memory overhead and a low rate of false positives.
• Skip Lists: A data structure that allows for fast search, insertion, and deletion operations on sorted data, enabling efficient range queries.
• Concurrent Hash Maps: The core key-value storage is built on sharded hash maps (32-way by default) to allow for high-concurrency operations with minimal lock contention.
• Monitoring: Provides detailed server statistics via the STATS command, including cache performance, compression ratios, deduplication savings, and memory/disk usage.

Community

• Issues: GitHub Issues
• Discussions: GitHub Discussions

Build Vachis from source

This section refers to building Vachis from its source code. If you prefer to use a pre-built environment, see the Getting started section.

Build and run Vachis - Linux / macOS / Windows

Install required dependencies

Vachis requires the V language compiler.

• Follow the official instructions to install V.

Download the Vachis source

Clone the repository from GitHub:

git clone https://github.com/yourusername/vachis.git
cd vachis

Build Vachis

Compile the source code using the provided Makefile:

make build

This creates the vachis executable in the current directory.

Run Vachis

You can now start the server:

# Start with default settings
./vachis

# Start on a different port
./vachis --port 6380

Building Vachis - general notes

• To install the binary system-wide (typically to /usr/local/bin), use make install.
• A development build can be created with make dev.
• The build process is designed to be simple and cross-platform, leveraging the V compiler's capabilities.

Configuration

Vachis can be configured via command-line options or environment variables.

Command Line Options

./vachis [OPTIONS]

Options:
  --host HOST           Bind address (default: 127.0.0.1)
  --port PORT           Listen port (default: 6379)
  --max-connections N   Maximum connections (default: 1000)
  --help                Show help message

Environment Variables

export VACHIS_HOST=0.0.0.0
export VACHIS_PORT=6379
export VACHIS_MAX_CONNECTIONS=2000

Testing and Benchmarking

To ensure the stability and performance of Vachis, run the built-in tests.

Run unit tests

make test

Run benchmarks

To test performance, you can use the built-in benchmark suite or a Redis-compatible tool.

# Run the native Vachis benchmark
make benchmark

# Use redis-benchmark for compatibility testing
redis-benchmark -p 6379 -t set,get -n 100000 -c 50

Code contributions

By contributing code to the Vachis project in any form, including sending a pull request via GitHub, a code fragment or patch via private email or public discussion groups, you agree to release your code under the terms of the project's license.

1. Fork the repository.
2. Create a feature branch (git checkout -b feature/amazing-feature).
3. Commit your changes (git commit -m 'Add amazing feature').
4. Push to the branch (git push origin feature/amazing-feature).
5. Open a Pull Request.

License

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

---

About

Vachis is a next-generation, high-performance in-memory cache system that provides Redis protocol compatibility alongside an advanced storage engine, structured data support, and intelligent memory management.