0
# Database Operations
1

2
Core functionality for creating, opening, saving, and managing KeePass database files with support for various authentication methods and database formats.
3

4
## Capabilities
5

6
### Database Creation
7

8
Creates a new KeePass database file with specified authentication credentials.
9

10
```python { .api }
11
def create_database(filename, password=None, keyfile=None, transformed_key=None) -> PyKeePass:
12
    """
13
    Create a new KeePass database.
14
    
15
    Parameters:
16
    - filename (str): Path where the new database file will be saved
17
    - password (str, optional): Master password for the database
18
    - keyfile (str, optional): Path to keyfile for authentication
19
    - transformed_key (bytes, optional): Pre-computed transformed key
20
    
21
    Returns:
22
    PyKeePass: New database instance ready for use
23
    
24
    Raises:
25
    BinaryError: If there's an issue creating the database structure
26
    """
27
```
28

29
**Usage Example:**
30

31
```python
32
from pykeepass import create_database
33

34
# Create with password only
35
kp = create_database('my_passwords.kdbx', password='supersecret')
36

37
# Create with keyfile only  
38
kp = create_database('my_passwords.kdbx', keyfile='my_keyfile.key')
39

40
# Create with both password and keyfile
41
kp = create_database('my_passwords.kdbx', password='secret', keyfile='keyfile.key')
42
```
43

44
### Database Opening and Reading
45

46
Opens existing KeePass database files with various authentication methods.
47

48
```python { .api }
49
class PyKeePass:
50
    def __init__(filename, password=None, keyfile=None, transformed_key=None):
51
        """
52
        Open a KeePass database.
53
        
54
        Parameters:
55
        - filename (str): Path to the KeePass database file
56
        - password (str, optional): Master password for the database
57
        - keyfile (str, optional): Path to keyfile for authentication  
58
        - transformed_key (bytes, optional): Pre-computed transformed key for faster opening
59
        
60
        Raises:
61
        CredentialsError: Wrong password/keyfile or transformed key
62
        PayloadChecksumError: Payload block checksum error (corruption)
63
        HeaderChecksumError: Header checksum error (tampering/corruption)
64
        """
65
    
66
    def read(filename=None, password=None, keyfile=None, transformed_key=None):
67
        """
68
        Read/reload database from file.
69
        
70
        Parameters:
71
        - filename (str, optional): Path to database file (uses current if None)
72
        - password (str, optional): Master password 
73
        - keyfile (str, optional): Path to keyfile
74
        - transformed_key (bytes, optional): Pre-computed transformed key
75
        
76
        Raises:
77
        CredentialsError: Authentication failed
78
        PayloadChecksumError: Database corruption detected
79
        HeaderChecksumError: Database tampering detected
80
        """
81
```
82

83
**Usage Examples:**
84

85
```python
86
from pykeepass import PyKeePass
87

88
# Open with password
89
kp = PyKeePass('database.kdbx', password='mypassword')
90

91
# Open with keyfile
92
kp = PyKeePass('database.kdbx', keyfile='my_keyfile.key')
93

94
# Open with both password and keyfile
95
kp = PyKeePass('database.kdbx', password='secret', keyfile='keyfile.key')
96

97
# Reload database (useful after external changes)
98
kp.read()
99

100
# Read from different file
101
kp.read('backup_database.kdbx', password='mypassword')
102
```
103

104
### Database Saving
105

106
Saves the current database state to disk with optional filename and transformed key optimization.
107

108
```python { .api }
109
def save(filename=None, transformed_key=None):
110
    """
111
    Save database to disk.
112
    
113
    Parameters:
114
    - filename (str, optional): Path to save database (uses current filename if None)
115
    - transformed_key (bytes, optional): Pre-computed transformed key for optimization
116
    
117
    Raises:
118
    BinaryError: If there's an issue writing the database
119
    """
120
```
121

122
**Usage Examples:**
123

124
```python
125
# Save to current filename
126
kp.save()
127

128
# Save to new filename
129
kp.save('backup_database.kdbx')
130

131
# Save with transformed key for performance
132
kp.save(transformed_key=kp.transformed_key)
133
```
134

135
### Database Properties and Metadata
136

137
Access database version information, encryption settings, and internal structure.
138

139
```python { .api }
140
class PyKeePass:
141
    @property
142
    def version() -> tuple:
143
        """Database version as (major, minor) tuple, e.g., (3, 1) or (4, 0)"""
144
    
145
    @property 
146
    def encryption_algorithm() -> str:
147
        """Encryption algorithm: 'aes256', 'chacha20', or 'twofish'"""
148
    
149
    @property
150
    def kdf_algorithm() -> str:
151
        """Key derivation algorithm: 'aeskdf' or 'argon2'"""
152
    
153
    @property
154
    def transformed_key() -> bytes:
155
        """Transformed key for faster database opening"""
156
    
157
    @property
158
    def tree() -> lxml.etree._ElementTree:
159
        """Database XML payload"""
160
    
161
    @property
162
    def root_group() -> Group: 
163
        """Root group of the database"""
164
    
165
    @property
166
    def groups() -> list:
167
        """All groups in database"""
168
    
169
    @property  
170
    def entries() -> list:
171
        """All entries in database (excluding history)"""
172
    
173
    @property
174
    def attachments() -> list:
175
        """All attachments in database"""
176
    
177
    @property
178
    def binaries() -> list:
179
        """Binary data storage"""
180
```
181

182
**Usage Examples:**
183

184
```python
185
# Check database version and encryption
186
print(f"Database version: {kp.version}")
187
print(f"Encryption: {kp.encryption_algorithm}")
188
print(f"Key derivation: {kp.kdf_algorithm}")
189

190
# Access database structure
191
root = kp.root_group
192
all_groups = kp.groups
193
all_entries = kp.entries
194

195
# Store transformed key for faster subsequent opens
196
transformed_key = kp.transformed_key
197
# Use this key later: PyKeePass('db.kdbx', transformed_key=transformed_key)
198
```
199

200
### Database Export and XML Operations
201

202
Export database content to XML format for analysis or backup purposes.
203

204
```python { .api }
205
def xml() -> str:
206
    """
207
    Get XML payload as string.
208
    
209
    Returns:
210
    str: Complete database XML content
211
    """
212

213
def dump_xml(filename):
214
    """
215
    Export database XML to file.
216
    
217
    Parameters:
218
    - filename (str): Path where XML file will be saved
219
    """
220
```
221

222
**Usage Examples:**
223

224
```python
225
# Get XML as string
226
xml_content = kp.xml()
227
print(xml_content[:200])  # Preview first 200 characters
228

229
# Export to XML file
230
kp.dump_xml('database_backup.xml')
231
```
232

233
### Utility Functions
234

235
Utility functions for working with database field references and values.
236

237
```python { .api }
238
def deref(value) -> str:
239
    """
240
    Dereference field references in values.
241
    
242
    Parameters:
243
    - value (str): Value that may contain field references like {REF:T@I:46C9B1FFBD4ABC4BBB260C6190BAD20B}
244
    
245
    Returns:
246
    str: Dereferenced value with references resolved to actual values
247
    """
248
```
249

250
**Usage Example:**
251

252
```python
253
# Resolve field references in entry values
254
entry_title = kp.deref(entry.title) 
255
entry_notes = kp.deref(entry.notes)
256
```