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 hashicorp/memberlist for failure detection and cluster membership. Currently, there are different ways to discover peers in a cluster. You can use a static list of nodes in your configuration. It's ideal for development and test environments. Olric also supports Consul, Kubernetes and all well-known cloud providers for service discovery. Please take a look at Service Discovery section for further information.

See Client-Server section to get more information about this deployment scenario.

Maintaining a list of peers manually

Basically, there is a list of nodes under memberlist block in the configuration file. In order to create an Olric cluster, you just need to add Host:Port pairs of the other nodes. Please note that the Port is the memberlist port of the peer. It is 3322 by default.

memberlist:
  peers:
    - "localhost:3322"

Thanks to hashicorp/memberlist, Olric nodes can share the full list of members with each other. So an Olric node can discover the whole cluster by using a single member address.

Embedding into your Go application.

See Samples section to learn how to embed Olric into your existing Golang application.

Operation Modes

Olric has two different operation modes.

Embedded Member

In Embedded Member Mode, members include both the application and Olric data and services. The advantage of the Embedded Member Mode is having a low-latency data access and locality.

Client-Server

In Client-Server Mode, Olric data and services are centralized in one or more servers, and they are accessed by the application through clients. You can have a cluster of servers that can be independently created and scaled. Your clients communicate with these members to reach to Olric data and services on them.

Client-Server deployment has advantages including more predictable and reliable performance, easier identification of problem causes and, most importantly, better scalability. When you need to scale in this deployment type, just add more Olric server members. You can address client and server scalability concerns separately.

Golang Client

The official Golang client is defined by the Client interface. There are two different implementations of that interface in this repository. EmbeddedClient provides a client implementation for embedded-member scenario, ClusterClient provides an implementation of the same interface for client-server deployment scenario. Obviously, you can use ClusterClient for your embedded-member deployments. But it's good to use EmbeddedClient provides a better performance due to localization of the queries.

See the client documentation on pkg.go.dev

Cluster Events

Olric can send push cluster events to cluster.events channel. Available cluster events:

• node-join-event
• node-left-event
• fragment-migration-event
• fragment-received-even

If you want to receive these events, set true to EnableClusterEventsChannel and subscribe to cluster.events channel. The default is false.

See the events/cluster_events.go file to get more information about events.

Authentication

Olric supports simple password-based authentication to restrict access to the data store. This mechanism is similar to the requirepass directive in Redis and is intended to provide a basic level of protection in trusted environments (e.g., internal networks or local development).

Important: This authentication method does not provide transport-layer encryption or full access control. For secure deployments over untrusted networks (e.g., Internet), it's strongly recommended to place Olric behind a reverse proxy with TLS support or use a secure network overlay (e.g., WireGuar