Skip to content
Snippets Groups Projects
  • Mehdi Abaakouk's avatar
    Allow to compile the extension everywhere · e4c0de94
    Mehdi Abaakouk authored
    This change:
    * uses to setuptools Cython automatic extension build system.
    * Add tox.ini to run tests and build docs into virtualenv
    * Add .travis.yaml and Dockerfile to run tests in CI
    * Change requirements to ensure:
      - Cython and setuptools are installed before we build the Cython
        extension
      - tests dependencies are not installed by default
      - doc dependencies are explicit
    * Add missing lz4 library
    * Allow to build the module with any librocksdb headers (no-rtti)
    
    Closes #15
    e4c0de94
index.rst 11.01 KiB

Basic Usage of python-rocksdb

Open

The most basic open call is

import rocksdb

db = rocksdb.DB("test.db", rocksdb.Options(create_if_missing=True))

A more production ready open can look like this

import rocksdb

opts = rocksdb.Options()
opts.create_if_missing = True
opts.max_open_files = 300000
opts.write_buffer_size = 67108864
opts.max_write_buffer_number = 3
opts.target_file_size_base = 67108864

opts.table_factory = rocksdb.BlockBasedTableFactory(
    filter_policy=rocksdb.BloomFilterPolicy(10),
    block_cache=rocksdb.LRUCache(2 * (1024 ** 3)),
    block_cache_compressed=rocksdb.LRUCache(500 * (1024 ** 2)))

db = rocksdb.DB("test.db", opts)

It assings a cache of 2.5G, uses a bloom filter for faster lookups and keeps more data (64 MB) in memory before writting a .sst file.

About Bytes And Unicode

RocksDB stores all data as uninterpreted byte strings. pyrocksdb behaves the same and uses nearly everywhere byte strings too. In python2 this is the str type. In python3 the bytes type. Since the default string type for string literals differs between python 2 and 3, it is strongly recommended to use an explicit b prefix for all byte string literals in both python2 and python3 code. For example b'this is a byte string'. This avoids ambiguity and ensures that your code keeps working as intended if you switch between python2 and python3.

The only place where you can pass unicode objects are filesytem paths like

  • Directory name of the database itself :py:meth:`rocksdb.DB.__init__`
  • :py:attr:`rocksdb.Options.wal_dir`
  • :py:attr:`rocksdb.Options.db_log_dir`

To encode this path name, sys.getfilesystemencoding() encoding is used.

Access

Store, Get, Delete is straight forward

# Store
db.put(b"key", b"value")

# Get
db.get(b"key")

# Delete
db.delete(b"key")

It is also possible to gather modifications and apply them in a single operation

batch = rocksdb.WriteBatch()
batch.put(b"key", b"v1")
batch.delete(b"key")
batch.put(b"key", b"v2")
batch.put(b"key", b"v3")

db.write(batch)