or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

core-operations.mdcursors.mdindex.mdmulti-database.mdtransactions.md
tile.json

tessl/pypi-lmdb

Universal Python binding for the LMDB 'Lightning' Database

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
pypipkg:pypi/lmdb@1.7.x

To install, run

npx @tessl/cli install tessl/pypi-lmdb@1.7.0

index.mddocs/

LMDB

Universal Python binding for OpenLDAP's LMDB (Lightning Memory-Mapped Database), a high-performance embedded transactional database. LMDB provides exceptional performance through memory-mapped file architecture, zero-copy reads, ACID transactions, multi-version concurrency control, and memory efficiency for applications requiring fast key-value storage.

Package Information

  • Package Name: lmdb
  • Language: Python
  • Installation: pip install lmdb

Core Imports

import lmdb

Basic Usage

import lmdb

# Open environment (creates database files if they don't exist)
env = lmdb.open('/path/to/database')

# Basic key-value operations using transactions
with env.begin(write=True) as txn:
    # Store data
    txn.put(b'key1', b'value1')
    txn.put(b'key2', b'value2')
    
    # Retrieve data
    value = txn.get(b'key1')
    print(value)  # b'value1'

# Read-only operations
with env.begin() as txn:
    value = txn.get(b'key1')
    
    # Iterate over all key-value pairs
    for key, value in txn.cursor():
        print(key, value)

# Always close the environment when done
env.close()

Architecture

LMDB's architecture centers around four core components that provide ACID transactions and high-performance key-value storage:

  • Environment: Top-level database container managing memory mapping, transactions, and configuration
  • Database: Named key-value stores within environments (default database plus optional named databases)
  • Transaction: ACID transaction contexts for consistent read/write operations
  • Cursor: Iteration and positioned access interface for efficient database traversal

The memory-mapped file design enables zero-copy reads and eliminates buffer cache overhead, while the copy-on-write B+ tree structure provides MVCC (Multi-Version Concurrency Control) for concurrent readers and writers. This architecture makes LMDB ideal for embedded applications, caching systems, and high-throughput data processing where traditional databases would be overkill.

Capabilities

Core Database Operations

Essential environment and database management functionality including opening databases, configuration, synchronization, and basic key-value operations through transactions.

def open(path: str, **kwargs) -> Environment: ...

class Environment:
    def close(self) -> None: ...
    def sync(self, force: bool = False) -> None: ...
    def begin(self, db=None, parent=None, write: bool = False, buffers: bool = False) -> Transaction: ...

Core Operations

Transaction Management

ACID transaction handling with commit/abort operations, context manager support, and data manipulation methods for consistent database operations.

class Transaction:
    def commit(self) -> None: ...
    def abort(self) -> None: ...
    def get(self, key: bytes, default=None, db=None) -> bytes: ...
    def put(self, key: bytes, value: bytes, **kwargs) -> bool: ...
    def delete(self, key: bytes, **kwargs) -> bool: ...

Transactions

Cursor Operations and Iteration

Efficient database traversal and positioned access using cursors, supporting forward/backward iteration, range queries, and bulk operations.

class Cursor:
    def first(self) -> bool: ...
    def last(self) -> bool: ...
    def next(self) -> bool: ...
    def prev(self) -> bool: ...
    def set_key(self, key: bytes) -> bool: ...
    def key(self) -> bytes: ...
    def value(self) -> bytes: ...

Cursors and Iteration

Multi-Database Support

Working with multiple named databases within a single environment, including database creation, configuration, and isolation.

class Environment:
    def open_db(self, key: bytes = None, **kwargs) -> _Database: ...

Multi-Database Support

Exception Types

class Error(Exception):
    """Base exception for all LMDB errors"""

class KeyExistsError(Error):
    """Key already exists when MDB_NOOVERWRITE specified"""

class NotFoundError(Error):
    """Requested item not found"""

class MapFullError(Error):
    """Environment map_size limit reached"""

class DbsFullError(Error):
    """Environment max_dbs limit reached"""

class ReadersFullError(Error):
    """Environment max_readers limit reached"""

class TxnFullError(Error):
    """Transaction has too many dirty pages"""

class CursorFullError(Error):
    """Cursor stack too deep"""

class PageFullError(Error):
    """Page has insufficient space"""

class MapResizedError(Error):
    """Environment map resized by another process"""

class VersionMismatchError(Error):
    """Database version mismatch"""

class InvalidError(Error):
    """File is not valid LMDB file"""

class CorruptedError(Error):
    """Located page is corrupted"""

class PanicError(Error):
    """Fatal error occurred, environment must be closed"""

class ReadonlyError(Error):
    """Attempt to modify read-only database"""

class LockError(Error):
    """Environment lock table full or contention"""

class MemoryError(Error):
    """Out of memory"""

class DiskError(Error):
    """Disk I/O error"""

class BadDbiError(Error):
    """Invalid database handle"""

class BadRslotError(Error):
    """Invalid reader slot"""

class BadTxnError(Error):
    """Invalid transaction handle"""

class BadValsizeError(Error):
    """Value size exceeds maximum"""

class IncompatibleError(Error):
    """Operation incompatible with database configuration"""

class InvalidParameterError(Error):
    """Invalid function parameter"""

class PageNotFoundError(Error):
    """Request page not found"""

class TlsFullError(Error):
    """Thread-local storage full"""

Utility Functions

def version(subpatch: bool = False) -> tuple:
    """
    Returns LMDB library version tuple.
    
    Parameters:
    - subpatch: If True, returns (major, minor, patch, subpatch), otherwise (major, minor, patch)
    
    Returns:
    Version tuple
    """

def preload(mv) -> None:
    """
    Preloads memory mapped data to improve read performance.
    
    Parameters:
    - mv: Memory view to preload
    """

def enable_drop_gil() -> None:
    """
    Enable dropping Python GIL during LMDB operations for better threading performance.
    
    Note:
    This function is deprecated and has no effect in modern versions of py-lmdb.
    The GIL is automatically managed for optimal performance.
    """