Skip to main content
Version: 2.x

Introduction to ZIO RocksDB

ZIO RocksDB is a ZIO-based interface to RocksDB, an embeddable persistent key-value store that is optimized for fast storage. The library wraps the RocksDB Java API (rocksdbjni) so that a database handle is a ZLayer, every operation is a ZIO effect, and scans are ZStreams.

Development CI Badge Sonatype Releases Sonatype Snapshots javadoc ZIO RocksDB

What the Library Providesโ€‹

ZIO RocksDB covers the parts of the RocksDB API that an application touches most often:

CapabilityEntry pointGuide
Reading and writing keysRocksDBThis page
Typed keys and valuesSerializer, Deserializer, SerdeSerialization
Scanning and range queriesRocksDB#newIteratorIterators and Range Scans
Atomic multi-key updatesTransactionDB, TransactionTransactions
Atomic batched writes without locksWriteBatch, RocksDB#writeWrite Batches

Installationโ€‹

To use the library, add the following line to build.sbt:

libraryDependencies += "dev.zio" %% "zio-rocksdb" % "0.4.5"

The library is published for Scala 2.12, 2.13 and 3, requires ZIO 2, and runs on JDK 17 or newer. The native RocksDB binaries come with the rocksdbjni dependency, so no separate installation of RocksDB is needed.

Getting Startedโ€‹

Every operation in ZIO RocksDB takes and returns Array[Byte], because that is what RocksDB stores. The examples below encode strings as UTF-8 by hand; to avoid this for richer types, see Serialization.

Opening a Databaseโ€‹

To open a database, build a ZLayer with RocksDB.live. The layer opens the database when the layer is built and closes it when the enclosing Scope ends, so the handle cannot leak. To create the database directory when it does not exist yet, pass an Options value with setCreateIfMissing(true):

import org.rocksdb.Options
import zio._
import zio.rocksdb.RocksDB

val database: ZLayer[Any, Throwable, RocksDB] =
RocksDB.live(new Options().setCreateIfMissing(true), "/tmp/zio-rocksdb-intro")

RocksDB.live(path) is a shorthand that opens the database with RocksDB's default options.

Reading, Writing and Deleting Keysโ€‹

Once a RocksDB layer is available, the accessor methods on the RocksDB companion object write, read and delete keys. RocksDB.get returns None when the key does not exist:

import java.nio.charset.StandardCharsets.UTF_8
import org.rocksdb.Options
import zio._
import zio.rocksdb.RocksDB

object IntroExample extends ZIOAppDefault {
private val key = "greeting".getBytes(UTF_8)
private val value = "hello".getBytes(UTF_8)

private val program: ZIO[RocksDB, Throwable, Unit] =
for {
_ <- RocksDB.put(key, value)
found <- RocksDB.get(key)
_ <- Console.printLine(found.map(new String(_, UTF_8)))
_ <- RocksDB.delete(key)
missing <- RocksDB.get(key)
_ <- Console.printLine(missing.isEmpty)
} yield ()

def run =
program.provide(RocksDB.live(new Options().setCreateIfMissing(true), "/tmp/zio-rocksdb-intro"))
}

All operations fail with Throwable, which is whatever RocksDB raised (a RocksDBException for most storage errors).

Reading Several Keys at Onceโ€‹

To fetch many keys in one call, use RocksDB.multiGetAsList. The result list lines up positionally with the keys that were passed in, with None for each missing key:

import java.nio.charset.StandardCharsets.UTF_8
import zio._
import zio.rocksdb.RocksDB

val lookup: ZIO[RocksDB, Throwable, List[Option[String]]] =
RocksDB
.multiGetAsList(List("a", "b", "c").map(_.getBytes(UTF_8)))
.map(_.map(_.map(new String(_, UTF_8))))

Where to Go Nextโ€‹

The rest of the documentation builds on the layer and the accessor methods shown above. Serialization explains how to store domain types instead of raw bytes, Iterators and Range Scans shows how to read ranges of keys as a stream, Transactions covers TransactionDB for atomic multi-key updates, and Write Batches shows how to apply several writes atomically without a transaction.

ZIO Chat

Hi, fellow coder! ๐ŸŒŸ Welcome to your ZIO adventure with the ZIO Chat Bot. ๐Ÿš€ Let's master functional Scala together. From referential transparency to concurrent prowess, I've got your back. Ready to dive in? Your questions, my insights โ€“ let's conquer ZIO! ๐Ÿ’ก๐Ÿค–