[[rocksdb_cache_store]]
=== RocksDB Cache Store
{brandname} supports using RocksDB as a cache store.

==== Introduction
link:http://rocksdb.org/[RocksDB] is a fast key-value filesystem-based storage from Facebook. It started as a fork of
Google's LevelDB, but provides superior performance and reliability, especially in highly concurrent scenarios.

//Exclude segmentation support from productized docs.
ifndef::productized[]
==== Segmentation support
The RocksDB cache store supports segmentation and creates a separate column
family per segment, which substantially improves lookup performance and
iteration. However, write operations are a little slower when the cache store
is segmented.

[NOTE]
====
You should not configure more than a few hundred segments. RocksDB is not
designed to have an unlimited number of column families. Too many segments also
significantly increases startup time for the cache store.
====
endif::productized[]

===== Sample Usage
The RocksDB cache store requires 2 filesystem directories to be configured - each directory contains a RocksDB database:
one location is used to store non-expired data, while the second location is used to store expired keys pending purge.

[source,java]
----
Configuration cacheConfig = new ConfigurationBuilder().persistence()
				.addStore(RocksDBStoreConfigurationBuilder.class)
				.build();
EmbeddedCacheManager cacheManager = new DefaultCacheManager(cacheConfig);

Cache<String, User> usersCache = cacheManager.getCache("usersCache");
usersCache.put("raytsang", new User(...));

----

==== Configuration

It is also possible to configure the underlying rocks db instance. This can be done
via properties in the store configuration. Any property that is prefixed with the
name `database` will configure the rocks db database. Data is now stored in column
families, these can be configured independently of the database by setting
a property prefixed with the name `data`.

Note that you do not have to supply properties and this is entirely optional.

===== Sample Programatic Configuration

[source,java]
----
Properties props = new Properties();
props.put("database.max_background_compactions", "2");
props.put("data.write_buffer_size", "512MB");

Configuration cacheConfig = new ConfigurationBuilder().persistence()
				.addStore(RocksDBStoreConfigurationBuilder.class)
				.location("/tmp/rocksdb/data")
				.expiredLocation("/tmp/rocksdb/expired")
        .properties(props)
				.build();

----

[options="header"]
|===============
|Parameter|Description
|location|Directory to use for RocksDB to store primary cache store data.  The directory will be auto-created if it does not exit.
|expiredLocation| Directory to use for RocksDB to store expiring data pending to be purged permanently.  The directory will be auto-created if it does not exit.
| expiryQueueSize |Size of the in-memory queue to hold expiring entries before it gets flushed into expired RocksDB store
|clearThreshold| There are two methods to clear all entries in RocksDB.  One method is to iterate through all entries and remove each entry individually.  The other method is to delete the database and re-init.  For smaller databases, deleting individual entries is faster than the latter method.  This configuration sets the max number of entries allowed before using the latter method
| compressionType |Configuration for RocksDB for data compression, see CompressionType enum for options
| blockSize | Configuration for RocksDB - see link:$$https://github.com/facebook/rocksdb/wiki/RocksDB-Tuning-Guide$$[documentation] for performance tuning
| cacheSize | Configuration for RocksDB - see link:$$https://github.com/facebook/rocksdb/wiki/RocksDB-Tuning-Guide$$[documentation] for performance tuning

|===============


===== Sample XML Configuration

.infinispan.xml
[source,xml]
----

<local-cache name="vehicleCache">
   <persistence>
      <rocksdb-store path="/tmp/rocksdb/data">
         <expiration path="/tmp/rocksdb/expired"/>
         <property name="database.max_background_compactions">2</property>
         <property name="data.write_buffer_size">512MB</property>
      </rocksdb-store>
   </persistence>
</local-cache>

----

[NOTE]
====
{brandname} servers log warning messages at startup when you add configuration
properties that are specific to RocksDB.

For example, as in the preceding example, if you set `data.write_buffer_size`
in your configuration, then the following message is written to logs:

----
WARN  [org.infinispan.configuration.parsing.XmlConfigHelper] ISPN000292:
Unrecognized attribute 'data.write_buffer_size'. Please check your
configuration. Ignoring!
----

{brandname} applies the RocksDB properties even though the log message
indicates they do not take effect. You can ignore these `WARN` messages. 
====

==== Additional References

Refer to the link:$$https://github.com/infinispan/infinispan/blob/master/persistence/rocksdb/src/test/java/org/infinispan/persistence/rocksdb/config/ConfigurationTest.java$$[test case] for code samples in action.

Refer to link:$$https://github.com/infinispan/infinispan/tree/master/persistence/rocksdb/src/test/resources/config/$$[test configurations] for configuration samples.
