moneta

Moneta: A unified interface for key/value stores

Moneta provides a standard interface for interacting with various kinds of key/value stores. Moneta supports the well-known NoSQL and document based stores.

A short overview of the features:

• Supports a lot of backends with consistent behaviour (See below)
• Allows a full configuration of the serialization -> compression -> adapter stack using proxies (Similar to Rack middlewares)
  • Configurable serialization via Moneta::Transformer proxy (Marshal/JSON/YAML and many more)
  • Configurable value compression via Moneta::Transformer proxy (Zlib, Snappy, LZMA, ...)
  • Configurable key transformation via Moneta::Transformer proxy
• Expiration for all stores (Added via proxy Moneta::Expires if not supported natively)
• Atomic operations
  • Atomic incrementation and decrementation for most stores (Method #increment and #decrement)
  • Atomic creation of entries (Method #create)
  • Shared/distributed database-wide synchronization primitives Moneta::Mutex and Moneta::Semaphore
• Includes a simple pure-ruby key/value server (Moneta::Server) and client (Moneta::Adapters::Client)
• Integration with Rails, Rack/Rack-Cache, Sinatra, Padrino and Ramaze.

If you are not yet convinced, you might ask why? What are the goals of the project?

• Get people started quickly with key/value stores! Therefore all the adapters are included in the gem and you are ready to go. Tilt does the same for template languages.
• Make it easy to compare different key/value stores and benchmark them
• To hide a lot of different and maybe complex APIs behind one well-designed and simple Moneta API
• Give people a starting point or example code to start working with their favourite key/value store. Feel free to copy code, please mention Moneta then :)
• Create a reusable piece of code, since similar things are solved over and over again (Rails brings its own cache stores, and many frameworks do the same...)

Moneta is tested thoroughly using GitHub Actions.

---

Getting started

Install Moneta via Rubygems

$ gem install moneta

or add it to your Gemfile

gem 'moneta'

Now you are ready to go:

require 'moneta'

# Create a simple file store
store = Moneta.new(:File, dir: 'moneta')

# Store some entries
store['key'] = 'value'

# Read entry
store.key?('key') # returns true
store['key'] # returns 'value'

store.close

---

Links

• Source:
• Bugs:
• Tests and benchmarks:
• API documentation:
  • Latest Gem:
  • GitHub main:
• Changelog:

In case you are wondering, Moneta uses Semantic Versioning since v1.0.0.

---

Supported backends

Out of the box, it supports the following backends. Use the backend name symbol in the Moneta constructor (e.g. Moneta.new(:Memory)).

• Memory:
  • In-memory store (:Memory)
  • LRU hash - prefer this over :Memory! (:LRUHash)
  • LocalMemCache (:LocalMemCache)
  • Memcached store (:Memcached, :MemcachedNative and :MemcachedDalli)
• Relational Databases:
  • DataMapper (:DataMapper)
  • ActiveRecord (:ActiveRecord)
  • Sequel (:Sequel)
  • Sqlite3 (:Sqlite)
• Filesystem:
  • PStore (:PStore)
  • YAML store (:YAML)
  • Filesystem directory store (:File)
  • Filesystem directory store which spreads files in subdirectories using md5 hash (:HashFile)
• Key/value databases:
  • Berkeley DB using DBM interface or NDBM (Depends on Ruby environment) (:DBM)
  • Cassandra (:Cassandra)
  • Daybreak (:Daybreak)
  • GDBM (:GDBM)
  • HBase (:HBase)
  • LevelDB (:LevelDB)
  • LMDB (:LMDB)
  • Redis (:Redis)
  • Riak (:Riak)
  • SDBM (:SDBM)
  • KyotoCabinet (:KyotoCabinet)
  • TokyoCabinet (:TokyoCabinet)
  • TokyoTyrant (:TokyoTyrant)
  • Simple Samba database TDB (:TDB)
• Document databases:
  • CouchDB (:Couch)
  • MongoDB (:Mongo)
• Moneta network protocols:
  • Moneta key/value client (:Client works with Moneta::Server)
  • Moneta HTTP/REST client (:RestClient works with Rack::MonetaRest)
• Other
  • Fog cloud storage which supports Amazon S3, Rackspace, etc. (:Fog)
  • Storage which doesn't store anything (:Null)

Some of the backends are not exactly based on key/value stores, e.g. the relational ones. These are useful if you already use the corresponding backend in your application. You get a key/value store for free then without installing any additional services and you still have the possibility to upgrade to a real key/value store.

Backend feature matrix

NOTE: The backend matrix is much more readable on rubydoc.info than on github. Go there!

AdapterRequired gemsMRI support1JRuby support1Multi-thread safe2Multi-process safe3Atomic increment4Atomic create5Native expires6PersistentKey TraversalBulk read7Bulk write8Description

Persistent stores

Mongomongo✓✓✓✓✓✓✓✓✓✓✓MongoDB database

Redisredis✓✓✓✓✓✓✓✓✓✓✓Redis database

ActiveRecordactiverecord✓✓✓✓✓✓✗✓✓✓✓ActiveRecord ORM

File-✓✓✓✓✓✓✗✓✓✗✗File store

LMDBlmdb✓✗✓✓✓✓✗✓✓✓✓Symas Lightning Memory-Mapped Database (LMDB)

Sequelsequel✓✓✓✓✓✓✗✓✓✓✓Sequel ORM

TokyoTyranttokyotyrant or ruby-tokyotyrant✓✓✗✓✓✓✗✓✗✓✗TokyoTyrant database

PStore-✓✗✗✓9✓✓✗✓✓✓✓PStore store

YAML-✓✓✗✓9✓✓✗✓✓✗✗YAML store

Sqlitesqlite3✓✗?✓9✓✓✗✓✓✓✓Sqlite3 database

Daybreakdaybreak✓✓✗✓✓✓✗✓✓✗✓Incredibly fast pure-ruby key/value store Daybreak

DBM-✓✗✗✗✓✓✗✓✓✓✓Berkeley DB using DBM interface or NDBM (Depends on Ruby environment)

GDBMffi-gdbm on JRuby✓✓✗✗✓✓✗✓✓✓✓GDBM database

LevelDBleveldb✓✗✗✗✓✓✗✓✓✓✓LevelDB database

SDBM-✓✗✗✗✓✓✗✓✓✓✓SDBM database

TDBtdb✓✗✗✗✓✓✗✓✓✗✗TDB database

KyotoCabinetkyotocabinet-ruby or kyotocabinet-ruby-reanimated✓✗✗✗✓✓✗✓✓✓✓KyotoCabinet database

TokyoCabinettokyocabinet✓✗✗✗✓✓✗✓✓✗✗TokyoCabinet database

DataMapperdm-core, dm-migrations✓✗✓✓✗✓✗✓✗✗✗DataMapper ORM

Couchfaraday, multi_json✓✓✗✓✗✓✗✓✓✓✓CouchDB database

HBasehbaserb✗✗?✓✓✗✗✓✗✗✗HBase database

Cassandracassandra✓✓?✓✗✗✓✓✓✓✓Cassandra distributed database

LocalMemCachelocalmemcache✓✗✓✓✗✗✗✓✗✗✗LocalMemCache database

Fogfog✓✓?✓✗✗✗✓✗✗✗Fog cloud store

Riakriak-client✗✗✗✓✗✗✗✓✗✗✗Riak database

Non-persistent stores

MemcachedDallidalli✓✓✓✓✓✓✓✗10✗✓✓Memcached database with Dalli library

Memcacheddalli or memcached✓?11?11✓✓✓✓✗10✗?11?11Memcached database

MemcachedNativememcached✓✗✗✓✓✓✓✗10✗✗✗Memcached database with native library

Cookie-✓✓✗✓12✓✓✓✗✓✗✗Cookie in memory store

LRUHash-✓✓✗✓12✓✓✗✗✓✗✗LRU memory store

Memory-✓✓✗✓12✓✓✗✗✓✓✓Memory store

Null-✓✓✓✓✗✗✗✗✗✗✗No database

Network clients

Client-✓✓✗✓?13?13?13?13?13✗✗Moneta client adapter

RestClient-✓✓✗✓✗✗✗?13✗✗✗Moneta REST client adapter

1. Indicates that the adapter is expected to work on this platform. Most adapters will at least work on MRI, but some are curently considered unstable, in which case they are not supported on any platform.
2. Make adapters thread-safe by using Moneta::Lock or by passing the option threadsafe: true to Moneta#new. There is also Moneta::Pool which can be used to share a store between multiple threads if the store is multi-process safe. I recommend to add the option :threadsafe to ensure thread-safety since for example under JRuby and Rubinius even the basic datastructures are not thread safe due to the lack of a global interpreter lock (GIL). This differs from MRI where some adapters might appear thread safe already but only due to the GIL.
3. Share a Moneta store between multiple processes using Moneta::Shared (See below).
4. If a store provides atomic increment it can be used with Moneta::Semaphore. You can add weak #increment support using the Moneta::WeakIncrement proxy.
5. If a store provides atomic creation it can be used with Moneta::Mutex. You can add weak #create support using the Moneta::WeakCreate proxy.
6. Add expiration support by using Moneta::Expires or by passing the option expires: true to Moneta#new.
7. This indicates that there is some performance gain when fetching multiple values at once using #values_at/#fetch_values or #slice. For instance, the MGET instruction in Redis, or the ability to retrieve several rows in one query in SQL.
8. This indicates that there is some performance gain when storing multiple key/value pairs at once using #merge!/#update.
9. Sqlite/YAML/PStore are multiprocess safe, but the performance suffers badly since the whole database file must be locked for writing. Use a key/value server if you want multiprocess concurrency!
10. There are some servers which use the memcached protocol but which are persistent (e.g. MemcacheDB, Kai, IronCache, Roma, Flare and Kumofs)
11. This feature is only available if the dalli backend is selected
12. Store is multi-process safe because it is an in-memory store, values are not shared between multiple processes
13. Depends on server

---

Proxies

In addition it supports proxies (Similar to Rack middlewares) which add additional features to storage backends:

• Moneta::Proxy and Moneta::Wrapper are the proxy base classes.
• Moneta::Cache combine two stores, one as backend and one as cache (e.g. Moneta::Adapters::File + Moneta::Adapters::LRUHash). Add it in the builder using use(:Cache) {}.
• Moneta::Expires to add expiration support to stores which don't support it natively. Add it in the builder using use :Expires.
• Moneta::Fallback use a store as a fallback when exceptions occur (by default the :Null adapter is used so that an error results in a no-op). Add it to the builder using use(:Fallback, rescue: IOError)
• Moneta::Lock to make store thread safe. Add it in the builder using use :Lock.
• Moneta::Logger to log database accesses. Add it in the builder using use :Logger.
• Moneta::Pool to create a pool of stores as a means of making the store thread safe. Add it in the builder using use(:Pool, min: 2, max: 4, ttl: 60, timeout: 5) {}.
• Moneta::Shared to share a store between multiple processes. Add it in the builder using use(:Shared) {}.
• Moneta::Stack to stack multiple stores (Read returns result from first where the key is found, writes go to all stores). Add it in the builder using use(:Stack) {}.
• Moneta::Transformer transforms keys and values (Marshal, YAML, JSON, Base64, MD5, ...). Add it in the builder using use :Transformer.
• Moneta::WeakIncrement