0
# LMDB
1

2
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.
3

4
## Package Information
5

6
- **Package Name**: lmdb
7
- **Language**: Python
8
- **Installation**: `pip install lmdb`
9

10
## Core Imports
11

12
```python
13
import lmdb
14
```
15

16
## Basic Usage
17

18
```python
19
import lmdb
20

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

24
# Basic key-value operations using transactions
25
with env.begin(write=True) as txn:
26
    # Store data
27
    txn.put(b'key1', b'value1')
28
    txn.put(b'key2', b'value2')
29
    
30
    # Retrieve data
31
    value = txn.get(b'key1')
32
    print(value)  # b'value1'
33

34
# Read-only operations
35
with env.begin() as txn:
36
    value = txn.get(b'key1')
37
    
38
    # Iterate over all key-value pairs
39
    for key, value in txn.cursor():
40
        print(key, value)
41

42
# Always close the environment when done
43
env.close()
44
```
45

46
## Architecture
47

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

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

55
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.
56

57
## Capabilities
58

59
### Core Database Operations
60

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

63
```python { .api }
64
def open(path: str, **kwargs) -> Environment: ...
65

66
class Environment:
67
    def close(self) -> None: ...
68
    def sync(self, force: bool = False) -> None: ...
69
    def begin(self, db=None, parent=None, write: bool = False, buffers: bool = False) -> Transaction: ...
70
```
71

72
[Core Operations](./core-operations.md)
73

74
### Transaction Management
75

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

78
```python { .api }
79
class Transaction:
80
    def commit(self) -> None: ...
81
    def abort(self) -> None: ...
82
    def get(self, key: bytes, default=None, db=None) -> bytes: ...
83
    def put(self, key: bytes, value: bytes, **kwargs) -> bool: ...
84
    def delete(self, key: bytes, **kwargs) -> bool: ...
85
```
86

87
[Transactions](./transactions.md)
88

89
### Cursor Operations and Iteration
90

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

93
```python { .api }
94
class Cursor:
95
    def first(self) -> bool: ...
96
    def last(self) -> bool: ...
97
    def next(self) -> bool: ...
98
    def prev(self) -> bool: ...
99
    def set_key(self, key: bytes) -> bool: ...
100
    def key(self) -> bytes: ...
101
    def value(self) -> bytes: ...
102
```
103

104
[Cursors and Iteration](./cursors.md)
105

106
### Multi-Database Support
107

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

110
```python { .api }
111
class Environment:
112
    def open_db(self, key: bytes = None, **kwargs) -> _Database: ...
113
```
114

115
[Multi-Database Support](./multi-database.md)
116

117
## Exception Types
118

119
```python { .api }
120
class Error(Exception):
121
    """Base exception for all LMDB errors"""
122

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

126
class NotFoundError(Error):
127
    """Requested item not found"""
128

129
class MapFullError(Error):
130
    """Environment map_size limit reached"""
131

132
class DbsFullError(Error):
133
    """Environment max_dbs limit reached"""
134

135
class ReadersFullError(Error):
136
    """Environment max_readers limit reached"""
137

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

141
class CursorFullError(Error):
142
    """Cursor stack too deep"""
143

144
class PageFullError(Error):
145
    """Page has insufficient space"""
146

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

150
class VersionMismatchError(Error):
151
    """Database version mismatch"""
152

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

156
class CorruptedError(Error):
157
    """Located page is corrupted"""
158

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

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

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

168
class MemoryError(Error):
169
    """Out of memory"""
170

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

174
class BadDbiError(Error):
175
    """Invalid database handle"""
176

177
class BadRslotError(Error):
178
    """Invalid reader slot"""
179

180
class BadTxnError(Error):
181
    """Invalid transaction handle"""
182

183
class BadValsizeError(Error):
184
    """Value size exceeds maximum"""
185

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

189
class InvalidParameterError(Error):
190
    """Invalid function parameter"""
191

192
class PageNotFoundError(Error):
193
    """Request page not found"""
194

195
class TlsFullError(Error):
196
    """Thread-local storage full"""
197
```
198

199
## Utility Functions
200

201
```python { .api }
202
def version(subpatch: bool = False) -> tuple:
203
    """
204
    Returns LMDB library version tuple.
205
    
206
    Parameters:
207
    - subpatch: If True, returns (major, minor, patch, subpatch), otherwise (major, minor, patch)
208
    
209
    Returns:
210
    Version tuple
211
    """
212

213
def preload(mv) -> None:
214
    """
215
    Preloads memory mapped data to improve read performance.
216
    
217
    Parameters:
218
    - mv: Memory view to preload
219
    """
220

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