0
# Core Database Operations
1

2
Essential environment and database management functionality for LMDB. This includes opening and configuring databases, environment management, synchronization operations, and basic database introspection.
3

4
## Capabilities
5

6
### Environment Creation and Configuration
7

8
Opens or creates LMDB environments with extensive configuration options for performance tuning and operational requirements.
9

10
```python { .api }
11
def open(path: str, map_size: int = 10485760, subdir: bool = True, readonly: bool = False, 
12
         metasync: bool = True, sync: bool = True, map_async: bool = False, mode: int = 0o755,
13
         create: bool = True, readahead: bool = True, writemap: bool = False, 
14
         meminit: bool = True, max_readers: int = 126, max_dbs: int = 0, 
15
         max_spare_txns: int = 1, lock: bool = True) -> Environment:
16
    """
17
    Open an LMDB environment.
18

19
    Parameters:
20
    - path: Directory (if subdir=True) or file prefix for database files
21
    - map_size: Maximum size of memory map (default 10MB)
22
    - subdir: If True, path is directory; if False, path is file prefix
23
    - readonly: Open environment in read-only mode
24
    - metasync: Flush system buffers to disk when committing transactions
25
    - sync: Flush buffers to disk immediately on transaction commit
26
    - map_async: Use asynchronous flushes when sync=True (Unix only)
27
    - mode: File permissions for created files (Unix only)
28
    - create: Create database if it doesn't exist
29
    - readahead: Use read-ahead prefetching
30
    - writemap: Use writeable memory map
31
    - meminit: Initialize memory pages to zeros
32
    - max_readers: Maximum number of read-only transactions
33
    - max_dbs: Maximum number of named databases (0 = default database only)
34
    - max_spare_txns: Number of transaction slots to cache for reuse
35
    - lock: Enable file locking
36

37
    Returns:
38
    Environment instance
39
    """
40
```
41

42
### Environment Management
43

44
Core environment operations for lifecycle management, synchronization, and introspection.
45

46
```python { .api }
47
class Environment:
48
    def close(self) -> None:
49
        """
50
        Close environment, invalidating all open iterators, cursors, and transactions.
51
        Subsequent calls to close() have no effect.
52
        """
53

54
    def sync(self, force: bool = False) -> None:
55
        """
56
        Flush environment buffers to disk.
57

58
        Parameters:
59
        - force: Force synchronous flush (may be expensive)
60
        """
61

62
    def set_mapsize(self, map_size: int) -> None:
63
        """
64
        Change maximum size of memory map. Fails if any transactions are active.
65

66
        Parameters:
67
        - map_size: New size in bytes
68

69
        Warning:
70
        Contains data race - use external locking if multiple processes access database
71
        """
72

73
    def path(self) -> str:
74
        """
75
        Get directory path or file prefix where environment is stored.
76

77
        Returns:
78
        Environment path string
79
        """
80

81
    def copy(self, path: str, compact: bool = False, txn=None) -> None:
82
        """
83
        Make consistent copy of environment in destination directory.
84

85
        Parameters:
86
        - path: Destination directory path
87
        - compact: Omit free pages and renumber pages (slower but smaller)
88
        - txn: Optional transaction for consistent snapshot
89
        """
90

91
    def copyfd(self, fd: int, compact: bool = False, txn=None) -> None:
92
        """
93
        Copy environment to file descriptor.
94

95
        Parameters:
96
        - fd: Target file descriptor
97
        - compact: Omit free pages and renumber pages (slower but smaller)
98
        - txn: Optional transaction for consistent snapshot
99
        """
100
```
101

102
### Environment Information and Statistics
103

104
Retrieve environment configuration, usage statistics, and operational metadata.
105

106
```python { .api }
107
class Environment:
108
    def stat(self) -> dict:
109
        """
110
        Get environment statistics.
111

112
        Returns:
113
        Dictionary with keys:
114
        - psize: Page size in bytes
115
        - depth: B-tree depth
116
        - branch_pages: Number of internal pages
117
        - leaf_pages: Number of leaf pages
118
        - overflow_pages: Number of overflow pages
119
        - entries: Number of data items
120
        """
121

122
    def info(self) -> dict:
123
        """
124
        Get environment information.
125

126
        Returns:
127
        Dictionary with keys:
128
        - mapaddr: Address of memory map (if fixed)
129
        - mapsize: Size of memory map
130
        - last_pgno: Last used page number
131
        - last_txnid: Last transaction ID
132
        - maxreaders: Maximum readers allowed
133
        - numreaders: Current number of readers
134
        """
135

136
    def flags(self) -> dict:
137
        """
138
        Get environment flags.
139

140
        Returns:
141
        Dictionary of boolean flags showing environment configuration
142
        """
143

144
    def max_key_size(self) -> int:
145
        """
146
        Get maximum key size supported by environment.
147

148
        Returns:
149
        Maximum key size in bytes
150
        """
151

152
    def max_readers(self) -> int:
153
        """
154
        Get maximum number of readers.
155

156
        Returns:
157
        Maximum reader count
158
        """
159

160
    def readers(self) -> str:
161
        """
162
        Get reader information as formatted string.
163

164
        Returns:
165
        Multi-line string with reader slot information
166
        """
167

168
    def reader_check(self) -> int:
169
        """
170
        Check for stale reader slots and clear them.
171

172
        Returns:
173
        Number of stale readers cleared
174
        """
175
```
176

177
### Database Creation
178

179
Create and configure named databases within environments for data organization and isolation.
180

181
```python { .api }
182
class Environment:
183
    def open_db(self, key: bytes = None, txn=None, reverse_key: bool = False,
184
                dupsort: bool = False, create: bool = True, integerkey: bool = False,
185
                integerdup: bool = False, dupfixed: bool = False) -> _Database:
186
        """
187
        Open named database within environment.
188

189
        Parameters:
190
        - key: Database name (None for default database)
191
        - txn: Transaction to use (creates temporary if None)
192
        - reverse_key: Keys are strings in reverse order
193
        - dupsort: Duplicate keys allowed and sorted
194
        - create: Create database if it doesn't exist
195
        - integerkey: Keys are C integers (native byte order)
196
        - integerdup: Duplicate values are C integers (requires dupsort=True)
197
        - dupfixed: Duplicate values are fixed-size (requires dupsort=True)
198

199
        Returns:
200
        Database handle for use in transactions
201
        """
202
```
203

204
### Usage Examples
205

206
#### Basic Environment Setup
207

208
```python
209
import lmdb
210

211
# Open environment with custom configuration
212
env = lmdb.open('/path/to/database', 
213
                map_size=100*1024*1024,  # 100MB
214
                max_dbs=10,              # Support 10 named databases
215
                max_readers=50)          # Support 50 concurrent readers
216

217
# Get environment information
218
print("Map size:", env.info()['mapsize'])
219
print("Max key size:", env.max_key_size())
220

221
# Synchronize to disk
222
env.sync()
223

224
# Copy database for backup
225
env.copy('/path/to/backup')
226

227
# Close environment
228
env.close()
229
```
230

231
#### Multi-Database Setup
232

233
```python
234
import lmdb
235

236
# Open environment with multiple database support
237
env = lmdb.open('/path/to/database', max_dbs=5)
238

239
# Create named databases
240
users_db = env.open_db(b'users')
241
products_db = env.open_db(b'products')
242
orders_db = env.open_db(b'orders', dupsort=True)  # Allow duplicate keys
243

244
# Use databases in transactions
245
with env.begin(write=True) as txn:
246
    txn.put(b'user1', b'John Doe', db=users_db)
247
    txn.put(b'prod1', b'Widget', db=products_db)
248
    txn.put(b'user1', b'order123', db=orders_db)  # Duplicate key allowed
249
    txn.put(b'user1', b'order456', db=orders_db)
250

251
env.close()
252
```