Olric

Distributed In-Memory Cache & Key/Value Store

Olric provides a simple way to create a fast, scalable, and shared pool of RAM across a cluster of machines. It's a distributed, in-memory key/value store and cache, written entirely in Go and designed specifically for distributed environments.

Flexible Deployment:

• Embedded Go Library: Integrate Olric directly into your Go applications.
• Standalone Service: Run Olric as a language-independent service.

Key Features:

• Effortless Scalability: Designed to handle hundreds of members and thousands of clients. New nodes auto-discover the cluster and linearly increase capacity.
• Automatic Distribution: Provides partitioning (sharding) and data re-balancing out-of-the-box, requiring no external coordination services. Data and backups are automatically balanced when capacity is added.
• Wide Client Support: Uses the standard Redis Serialization Protocol (RESP), ensuring client libraries are available in nearly all major programming languages.
• Common Use Cases: Ideal for distributed caching, managing application cluster state, and implementing publish-subscribe messaging.

See Docker and Samples sections to get started!

Join our Discord server!

The current production version is v0.7.0

About renaming the module

github.com/buraksezer/olric module has been renamed to github.com/olric-data/olric. This change has been effective since v0.6.0. Importing previous versions should redirect you to the new repository, but you should change the import paths in your codebase as soon as possible.

There is no other difference between v0.5.7 and v0.6.0.

At a glance

• Designed to share some transient, approximate, fast-changing data between servers,
• Uses Redis serialization protocol,
• Implements a distributed hash table,
• Provides a drop-in replacement for Redis Publish/Subscribe messaging system,
• Supports both programmatic and declarative configuration,
• Embeddable but can be used as a language-independent service with olric-server,
• Supports different eviction algorithms (including LRU and TTL),
• Highly available and horizontally scalable,
• Provides best-effort consistency guarantees without being a complete CP (indeed PA/EC) solution,
• Supports replication by default (with sync and async options),
• Quorum-based voting for replica control (Read/Write quorums),
• Supports atomic operations,
• Provides an iterator on distributed maps,
• Provides a plugin interface for service discovery daemons,
• Provides a locking primitive which inspired by SETNX of Redis,

Possible Use Cases

Olric is an eventually consistent, unordered key/value data store. It supports various eviction mechanisms for distributed caching implementations. Olric also provides publish-subscribe messaging, data replication, failure detection and simple anti-entropy services.

It's good at distributed caching and publish/subscribe messaging.

Table of Contents

• Features
• Support
• Installing
  • Docker
• Getting Started
  • Operation Modes
    • Embedded Member
    • Client-Server
• Golang Client
• Cluster Events
• Authentication
• Commands
  • Distributed Map
    • DM.PUT
    • DM.GET
    • DM.DEL
    • DM.EXPIRE
    • DM.PEXPIRE
    • DM.DESTROY
    • Atomic Operations
      • DM.INCR
      • DM.DECR
      • DM.GETPUT
      • DM.INCRBYFLOAT
    • Locking
      • DM.LOCK
      • DM.UNLOCK
      • DM.LOCKLEASE
      • DM.PLOCKLEASE
    • DM.SCAN
  • Publish-Subscribe
    • SUBSCRIBE
    • PSUBSCRIBE
    • UNSUBSCRIBE
    • PUNSUBSCRIBE
    • PUBSUB CHANNELS
    • PUBSUB NUMPAT
    • PUBSUB NUMSUB
    • QUIT
    • PING
  • Cluster
    • CLUSTER.ROUTINGTABLE
    • CLUSTER.MEMBERS
  • Others
    • PING
    • STATS
    • AUTH
• Configuration
  • Embedded Member Mode
    • Manage the configuration in YAML format
  • Client-Server Mode
  • Network Configuration
  • Service discovery
  • Timeouts
• Architecture
  • Overview
  • Consistency and Replication Model
    • Last-write-wins conflict resolution
    • PACELC Theorem
    • Read-Repair on DMaps
    • Quorum-based Replica Control
    • Simple Split-Brain Protection
  • Eviction
    • Expire with TTL
    • Expire with MaxIdleDuration
    • Expire with LRU
  • Lock Implementation
  • Storage Engine
• Samples
• Contributions
• License
• About the name

Features

• Designed to share some transient, approximate, fast-changing data between servers,
• Accepts arbitrary types as value,
• Only in-memory,
• Uses Redis protocol,
• Compatible with existing Redis clients,
• Embeddable but can be used as a language-independent service with olric-server,
• GC-friendly storage engine,
• O(1) running time for lookups,
• Supports atomic operations,
• Provides a lock implementation which can be used for non-critical purposes,
• Different eviction policies: LRU, MaxIdleDuration and Time-To-Live (TTL),
• Highly available,
• Horizontally scalable,
• Provides best-effort consistency guarantees without being a complete CP (indeed PA/EC) solution,
• Distributes load fairly among cluster members with a consistent hash function,
• Supports replication by default (with sync and async options),
• Quorum-based voting for replica control,
• Thread-safe by default,
• Provides an iterator on distributed maps,
• Provides a plugin interface for service discovery daemons and cloud providers,
• Provides a locking primitive which inspired by SETNX of Redis,
• Provides a drop-in replacement of Redis' Publish-Subscribe messaging feature.

See the Architecture section to see details.

Support

We have a few communication channels:

• Issue Tracker
• Discord server

You should know that the issue tracker is only intended for bug reports and feature requests.

Software doesn't maintain itself. If you need support on complex topics or request new features, please consider sponsoring Olric.

Installing

With a correctly configured Golang environment:

go install github.com/olric-data/olric/cmd/olric-server@v0.7.0

Now you can start using Olric:

olric-server -c cmd/olric-server/olric-server-local.yaml

See the Configuration section to create your cluster properly.

Docker

You can launch olric-server Docker container by running the following command.

docker pull ghcr.io/olric-data/olric:latest

This command will pull olric-server Docker image and run a new Olric Instance. You should know that the container exposes 3320 and 3322 ports.

Now, you can access an Olric cluster using any Redis client including redis-cli:

redis-cli -p 3320
127.0.0.1:3320> DM.PUT my-dmap my-key "Olric Rocks!"
OK
127.0.0.1:3320> DM.GET my-dmap my-key
"Olric Rocks!"
127.0.0.1:3320>

Getting Started

With olric-server, you can create an Olric cluster with a few commands. This is how to install olric-server:

go install github.com/olric-data/olric/cmd/olric-server@v0.7.0

Let's create a cluster with the following:

olric-server -c <YOUR_CONFIG_FILE_PATH>

You can find the sample configuration file under cmd/olric-server/olric-server-local.yaml. It can perfectly run with single node. olric-server also supports OLRIC_SERVER_CONFIG environment variable to set configuration. Just like that:

OLRIC_SERVER_CONFIG=<YOUR_CONFIG_FILE_PATH> olric-server

Olric uses