-- |
-- Module : Database.RocksDB
-- Copyright : (c) 2012-2013 The leveldb-haskell Authors
-- (c) 2014-2020 The rocksdb-haskell Authors
-- (c) 2025 JP Rupp
-- License : BSD3
-- Maintainer : jprupp@protonmail.ch
-- Stability : experimental
-- Portability : non-portable
--
-- Haskell bindings to <https://rocksdb.org RocksDB>, an embedded persistent
-- key-value store.
--
-- = Purpose
--
-- RocksDB is a fast embedded key-value store: a library, not a server, that
-- keeps sorted keys and values in files on local disk. These bindings let a
-- Haskell program use it as its storage engine. They were written for, and are
-- used by, the Haskoin Bitcoin indexer, which keeps hundreds of
-- gigabytes in RocksDB and reads them concurrently from many threads.
--
-- = Design
--
-- * __Close to the C API.__ The functions map almost one to one to RocksDB's C
-- functions, so the RocksDB documentation applies directly and nothing is
-- hidden behind an abstraction you would have to learn separately. Higher
-- level conveniences, such as typed keys and values, belong in libraries on
-- top, like @rocksdb-query@.
--
-- * __Resources are scoped.__ A database, a snapshot and an iterator are C
-- objects that must be freed exactly once and never used afterwards. Every
-- such resource has a @with@ function that frees it when the scope ends, even
-- on an exception. Manual @create@ and @destroy@ functions exist for the cases
-- where a lifetime cannot be a scope.
--
-- * __Plain 'IO'.__ Every function runs in 'IO'. Lifting into an application
-- monad is left to the caller, which keeps the bindings free of monad
-- transformer dependencies and keeps their types simple.
--
-- * __Bytes in, bytes out.__ Keys and values are strict
-- 'Data.ByteString.ByteString's, the representation RocksDB itself uses.
-- Serialization is a separate concern.
--
-- * __Memory you can bound.__ RocksDB keeps a lot of memory outside the Haskell
-- heap. 'Config' exposes the settings that put a ceiling on it, because an
-- indexer that grows until the machine runs out of memory is not usable.
--
-- This is the only module that needs to be imported. It re-exports
-- "Database.RocksDB.Base", which in turn re-exports the iterator functions.
--
-- = Quick start
--
-- @
-- -- with OverloadedStrings
-- import Data.Default (def)
-- import Database.RocksDB
--
-- main :: IO ()
-- main =
-- 'withDB' "\/tmp\/example" def{'createIfMissing' = True} $ \\db -> do
-- 'put' db "hello" "world"
-- 'get' db "hello" >>= print -- Just "world"
-- 'write' db ['Put' "a" "1", 'Put' "b" "2", 'Del' "hello"]
-- 'withIter' db $ \\it -> do
-- 'iterFirst' it
-- 'iterEntry' it >>= print -- Just ("a","1")
-- @
--
-- = Keys and values
--
-- Keys and values are strict 'Data.ByteString.ByteString's. RocksDB orders keys
-- lexicographically by their bytes, which is the order used by iterators.
--
-- = Column families
--
-- A database can hold several independent key spaces called column families.
-- Open such a database with 'withDBCF'. The handles for the extra column
-- families are found in 'columnFamilies', in the same order as they were passed
-- to 'withDBCF'. Functions ending in @CF@ act on a given column family; the
-- others act on the default column family.
--
-- = Errors
--
-- Errors reported by RocksDB are thrown as 'IOError' exceptions created with
-- 'userError', with a message that names the failing operation.
module Database.RocksDB (module Base) where
import Database.RocksDB.Base as Base