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.
What the Library Providesโ
ZIO RocksDB covers the parts of the RocksDB API that an application touches most often:
| Capability | Entry point | Guide |
|---|---|---|
| Reading and writing keys | RocksDB | This page |
| Typed keys and values | Serializer, Deserializer, Serde | Serialization |
| Scanning and range queries | RocksDB#newIterator | Iterators and Range Scans |
| Atomic multi-key updates | TransactionDB, Transaction | Transactions |
| Atomic batched writes without locks | WriteBatch, RocksDB#write | Write 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.