{"id":2104,"library":"lmdb","title":"LMDB Python Binding","description":"lmdb (py-lmdb) is a universal Python binding for the LMDB 'Lightning' Database, a fast, memory-efficient, embedded key-value store. It provides an ordered map interface, multi-version concurrency control (MVCC) with reader/writer transactions, and utilizes memory-mapped files for zero-copy operations. The library is actively maintained, with frequent releases; the current version is 2.2.0.","status":"active","version":"2.2.0","language":"en","source_language":"en","source_url":"https://github.com/jnwatson/py-lmdb/","tags":["database","key-value store","embedded","LMDB","MVCC"],"install":[{"cmd":"pip install lmdb","lang":"bash","label":"Install `lmdb`"}],"dependencies":[],"imports":[{"symbol":"lmdb","correct":"import lmdb"}],"quickstart":{"code":"import lmdb\nimport os\nimport shutil\n\ndb_path = './my_lmdb_data'\n\n# Ensure cleanup for demonstration\nif os.path.exists(db_path):\n    shutil.rmtree(db_path)\n\n# 1. Open an LMDB environment\n# map_size: Maximum size of the database. Crucial to set correctly.\n# max_dbs: Max number of named databases (sub-databases).\nenv = lmdb.open(db_path, map_size=10*1024*1024, max_dbs=10, subdir=True)\n\n# 2. Write data to the database\nwith env.begin(write=True) as txn:\n    txn.put(b'my_key_1', b'my_value_1')\n    txn.put(b'my_key_2', b'my_value_2')\n    txn.put(b'another_key', b'another_value')\n    print(\"Wrote data to LMDB.\")\n\n# 3. Read data from the database\nwith env.begin() as txn:\n    value1 = txn.get(b'my_key_1')\n    value_non_existent = txn.get(b'non_existent_key')\n    print(f\"Value for my_key_1: {value1.decode('utf-8') if value1 else None}\")\n    print(f\"Value for non_existent_key: {value_non_existent}\")\n\n    # Iterate through all key-value pairs\n    print(\"\\nAll items in DB:\")\n    for key, value in txn.cursor():\n        print(f\"  {key.decode('utf-8')}: {value.decode('utf-8')}\")\n\n# 4. Close the environment\nenv.close()\nprint(\"\\nLMDB environment closed.\")\n\n# Cleanup (optional, for examples)\nif os.path.exists(db_path):\n    shutil.rmtree(db_path)\n    print(f\"Cleaned up database at {db_path}\")","lang":"python","description":"This quickstart demonstrates how to open an LMDB environment, write key-value pairs, read specific values, iterate through all entries using a cursor, and properly close the environment. Note the use of byte strings for keys and values, and the importance of `map_size` and `max_dbs` configuration. The example also includes basic cleanup."},"warnings":[{"fix":"Always `.encode()` Python strings to bytes before `put()` and `.decode()` bytes to strings after `get()` or cursor iteration.","message":"Keys and values in LMDB must be byte strings. Python strings (unicode) need to be explicitly encoded (e.g., `s.encode('utf-8')`) before being stored, and decoded (`b.decode('utf-8')`) after retrieval.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Estimate your maximum database size and set `map_size` generously when initially opening the environment. Ensure `map_size` is consistent if multiple processes access the same database. If resizing is necessary, ensure only one process is active.","message":"The `map_size` parameter in `lmdb.open()` sets the maximum size of the database. It is crucial to set this value sufficiently large upfront, especially if the database is opened by multiple processes. Modifying `map_size` from multiple processes concurrently can lead to catastrophic data loss.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Determine the maximum number of named databases you will use and specify `max_dbs` in `lmdb.open()` when the environment is created or first accessed.","message":"When using named databases (sub-databases), the `max_dbs` parameter must be set in `lmdb.open()` during the *first* opening of the environment by any process or thread. This allocates shared memory resources for the maximum number of named databases.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Always use `with env.begin(write=True) as txn:` for write operations. The context manager handles `commit()` on success and `abort()` on exceptions automatically.","message":"Write transactions (`env.begin(write=True)`) must be committed using `txn.commit()`. If not explicitly committed (e.g., if an exception occurs within the `with` block without proper handling), changes will be rolled back by default.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Ensure your project runs on Python 3.9 or a newer compatible version. For older Python environments, use `py-lmdb < 1.4.1` (e.g., `pip install 'lmdb<1.4.1'`).","message":"Version 1.4.1 and newer of `py-lmdb` dropped support for Python 2.x and older Python 3.x versions. Specifically, Python 3.9 or newer is now required.","severity":"breaking","affected_versions":"1.4.1 and above"}],"env_vars":null,"last_verified":"2026-04-09T00:00:00.000Z","next_check":"2026-07-08T00:00:00.000Z"}