{"id":6225,"library":"rocksdict","title":"RocksDict: Python On-Disk Key-Value Store","description":"RocksDict provides a Python binding for RocksDB, offering an efficient on-disk key-value storage solution. It enables users to store, query, and delete a large number of key-value pairs that may not fit into RAM. The library supports storing various Python objects (with Pickle) in its default mode and raw bytes in its raw mode. It also functions as an interface to inspect RocksDB databases created by other languages. The current version is 0.3.29, with a release cadence that includes frequent updates for Python version support and new features.","status":"active","version":"0.3.29","language":"en","source_language":"en","source_url":"https://github.com/rocksdict/RocksDict","tags":["database","key-value","rocksdb","storage","persistent dictionary","on-disk"],"install":[{"cmd":"pip install rocksdict","lang":"bash","label":"Install RocksDict"}],"dependencies":[],"imports":[{"symbol":"Rdict","correct":"from rocksdict import Rdict"},{"symbol":"Options","correct":"from rocksdict import Options"}],"quickstart":{"code":"import os\nfrom rocksdict import Rdict, Options\n\npath = str(\"./my_test_db\")\n\n# Ensure clean start for example\nif os.path.exists(path):\n    Rdict(path).destroy()\n\n# Create an Rdict with default options\ndb = Rdict(path)\n\n# Store various Python objects\ndb[1] = \"value_one\"\ndb[\"key_two\"] = 25\ndb[b\"binary_key\"] = b\"binary_value\"\ndb[\"list_key\"] = [1, 2, 3]\ndb[\"dict_key\"] = {\"a\": 1, \"b\": 2}\n\nprint(f\"Value for key_two: {db['key_two']}\")\n\n# Reopen Rdict from disk after closing\ndb.close()\ndb = Rdict(path)\n\nprint(f\"Value for list_key after reopen: {db['list_key']}\")\n\n# Iterate through items\nprint(\"\\nItems in the database:\")\nfor k, v in db.items():\n    print(f\"{k} -> {v}\")\n\n# Delete an item\ndel db[1]\nassert 1 not in db\n\n# Destroy the database (clean up)\ndb.destroy()","lang":"python","description":"This quickstart demonstrates how to create a RocksDict, store various data types, retrieve values, close and reopen the database, iterate through its contents, and finally clean up by destroying the database."},"warnings":[{"fix":"Remove calls to these deprecated `Options` methods. Consult RocksDB documentation for alternative configurations if needed.","message":"The methods `Options.set_ignore_range_deletions` and `Options.set_skip_checking_sst_file_sizes_on_db_open` have been removed. Code using these methods will break.","severity":"breaking","affected_versions":">=0.3.29 (associated with Python 3.14+ updates)"},{"fix":"Be aware of the mode when interacting with externally created databases. If non-byte Python objects are expected, ensure your application handles serialization/deserialization or re-evaluate the use of Raw Mode.","message":"When opening an existing RocksDB database created by other languages (C++, Java, etc.), `rocksdict` automatically defaults to 'Raw Mode' since v0.3.24b2. In Raw Mode, only bytes can be stored or retrieved as keys and values. Attempting to use Python objects will fail if not manually handled.","severity":"gotcha","affected_versions":">=0.3.24b2"},{"fix":"Avoid relying on RocksDB's merge operators or custom comparators when using `rocksdict`. Implement read-modify-write patterns at the application level if merge-like behavior is required, acknowledging potential performance implications and concurrency challenges.","message":"RocksDict currently does not have good support for `merge` operations or custom comparators directly within its Python interface. While RocksDB supports these features, they are not fully exposed or easily usable in `rocksdict`.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Always call `db.close()` before attempting operations like `db.repair(path)`. Ensure robust error handling and proper shutdown procedures in your application to minimize the risk of corruption. Consider using transactions or backups for critical data.","message":"When working with large datasets, especially if processes crash, you might encounter 'Corruption: Corrupt or unsupported format_version' or 'IO error: lock hold by current process' errors. This indicates data corruption or issues with database locks.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-14T00:00:00.000Z","next_check":"2026-07-13T00:00:00.000Z"}