0
# Database Account Management
1

2
Core database account lifecycle operations for Azure Cosmos DB. These operations manage the top-level Cosmos DB account resource that hosts all databases and containers, including creation, configuration, scaling, failover management, key rotation, and monitoring.
3

4
## Capabilities
5

6
### Account Lifecycle Management
7

8
Create, retrieve, update, and delete Cosmos DB database accounts with comprehensive configuration options.
9

10
```python { .api }
11
def get(self, resource_group_name: str, account_name: str) -> DatabaseAccountGetResults:
12
    """
13
    Get the properties of an existing database account.
14
    
15
    Parameters:
16
    - resource_group_name: Name of the resource group
17
    - account_name: Name of the Cosmos DB account
18
    
19
    Returns:
20
    DatabaseAccountGetResults: Complete account information
21
    """
22

23
def begin_create_or_update(
24
    self,
25
    resource_group_name: str,
26
    account_name: str,
27
    create_update_parameters: DatabaseAccountCreateUpdateParameters
28
) -> LROPoller[DatabaseAccountGetResults]:
29
    """
30
    Create or update a database account (Long Running Operation).
31
    
32
    Parameters:
33
    - resource_group_name: Name of the resource group
34
    - account_name: Name of the Cosmos DB account to create/update
35
    - create_update_parameters: Account configuration parameters
36
    
37
    Returns:
38
    LROPoller[DatabaseAccountGetResults]: Poller for monitoring operation progress
39
    """
40

41
def begin_update(
42
    self,
43
    resource_group_name: str,
44
    account_name: str,
45
    update_parameters: DatabaseAccountUpdateParameters
46
) -> LROPoller[DatabaseAccountGetResults]:
47
    """
48
    Update properties of an existing database account (Long Running Operation).
49
    
50
    Parameters:
51
    - resource_group_name: Name of the resource group
52
    - account_name: Name of the Cosmos DB account to update
53
    - update_parameters: Account update parameters
54
    
55
    Returns:
56
    LROPoller[DatabaseAccountGetResults]: Poller for monitoring operation progress
57
    """
58

59
def begin_delete(
60
    self,
61
    resource_group_name: str,
62
    account_name: str
63
) -> LROPoller[None]:
64
    """
65
    Delete a database account (Long Running Operation).
66
    
67
    Parameters:
68
    - resource_group_name: Name of the resource group
69
    - account_name: Name of the Cosmos DB account to delete
70
    
71
    Returns:
72
    LROPoller[None]: Poller for monitoring operation progress
73
    """
74
```
75

76
### Account Discovery
77

78
List and discover Cosmos DB accounts across subscriptions and resource groups.
79

80
```python { .api }
81
def list(self) -> ItemPaged[DatabaseAccountGetResults]:
82
    """
83
    List all database accounts in the subscription.
84
    
85
    Returns:
86
    ItemPaged[DatabaseAccountGetResults]: Paginated list of all accounts
87
    """
88

89
def list_by_resource_group(
90
    self,
91
    resource_group_name: str
92
) -> ItemPaged[DatabaseAccountGetResults]:
93
    """
94
    List all database accounts in a resource group.
95
    
96
    Parameters:
97
    - resource_group_name: Name of the resource group
98
    
99
    Returns:
100
    ItemPaged[DatabaseAccountGetResults]: Paginated list of accounts in resource group
101
    """
102

103
def check_name_exists(self, account_name: str) -> bool:
104
    """
105
    Check if a database account name is available.
106
    
107
    Parameters:
108
    - account_name: Name to check for availability
109
    
110
    Returns:
111
    bool: True if name exists, False if available
112
    """
113
```
114

115
### Key Management
116

117
Manage access keys for authentication and security operations.
118

119
```python { .api }
120
def list_keys(
121
    self,
122
    resource_group_name: str,
123
    account_name: str
124
) -> DatabaseAccountListKeysResult:
125
    """
126
    List access keys for a database account.
127
    
128
    Parameters:
129
    - resource_group_name: Name of the resource group
130
    - account_name: Name of the Cosmos DB account
131
    
132
    Returns:
133
    DatabaseAccountListKeysResult: Primary and secondary keys
134
    """
135

136
def list_read_only_keys(
137
    self,
138
    resource_group_name: str,
139
    account_name: str
140
) -> DatabaseAccountListReadOnlyKeysResult:
141
    """
142
    List read-only access keys for a database account.
143
    
144
    Parameters:
145
    - resource_group_name: Name of the resource group
146
    - account_name: Name of the Cosmos DB account
147
    
148
    Returns:
149
    DatabaseAccountListReadOnlyKeysResult: Read-only primary and secondary keys
150
    """
151

152
def list_connection_strings(
153
    self,
154
    resource_group_name: str,
155
    account_name: str
156
) -> DatabaseAccountListConnectionStringsResult:
157
    """
158
    List connection strings for a database account.
159
    
160
    Parameters:
161
    - resource_group_name: Name of the resource group
162
    - account_name: Name of the Cosmos DB account
163
    
164
    Returns:
165
    DatabaseAccountListConnectionStringsResult: Connection strings for different APIs
166
    """
167

168
def begin_regenerate_key(
169
    self,
170
    resource_group_name: str,
171
    account_name: str,
172
    key_to_regenerate: DatabaseAccountRegenerateKeyParameters
173
) -> LROPoller[None]:
174
    """
175
    Regenerate an access key for a database account (Long Running Operation).
176
    
177
    Parameters:
178
    - resource_group_name: Name of the resource group
179
    - account_name: Name of the Cosmos DB account
180
    - key_to_regenerate: Specifies which key to regenerate
181
    
182
    Returns:
183
    LROPoller[None]: Poller for monitoring operation progress
184
    """
185
```
186

187
### Failover and Region Management
188

189
Manage multi-region deployments, failover priorities, and region operations.
190

191
```python { .api }
192
def begin_failover_priority_change(
193
    self,
194
    resource_group_name: str,
195
    account_name: str,
196
    failover_parameters: FailoverPolicies
197
) -> LROPoller[None]:
198
    """
199
    Change failover priorities for multi-region accounts (Long Running Operation).
200
    
201
    Parameters:
202
    - resource_group_name: Name of the resource group
203
    - account_name: Name of the Cosmos DB account
204
    - failover_parameters: New failover priority configuration
205
    
206
    Returns:
207
    LROPoller[None]: Poller for monitoring operation progress
208
    """
209

210
def begin_offline_region(
211
    self,
212
    resource_group_name: str,
213
    account_name: str,
214
    region_parameter_for_offline: RegionForOnlineOffline
215
) -> LROPoller[None]:
216
    """
217
    Take a region offline for maintenance (Long Running Operation).
218
    
219
    Parameters:
220
    - resource_group_name: Name of the resource group
221
    - account_name: Name of the Cosmos DB account
222
    - region_parameter_for_offline: Region to take offline
223
    
224
    Returns:
225
    LROPoller[None]: Poller for monitoring operation progress
226
    """
227

228
def begin_online_region(
229
    self,
230
    resource_group_name: str,
231
    account_name: str,
232
    region_parameter_for_online: RegionForOnlineOffline
233
) -> LROPoller[None]:
234
    """
235
    Bring a region back online (Long Running Operation).
236
    
237
    Parameters:
238
    - resource_group_name: Name of the resource group
239
    - account_name: Name of the Cosmos DB account
240
    - region_parameter_for_online: Region to bring online
241
    
242
    Returns:
243
    LROPoller[None]: Poller for monitoring operation progress
244
    """
245
```
246

247
### Monitoring and Usage
248

249
Get metrics, usage statistics, and performance data for database accounts.
250

251
```python { .api }
252
def list_metrics(
253
    self,
254
    resource_group_name: str,
255
    account_name: str,
256
    filter: str
257
) -> ItemPaged[Metric]:
258
    """
259
    Get metrics for a database account.
260
    
261
    Parameters:
262
    - resource_group_name: Name of the resource group
263
    - account_name: Name of the Cosmos DB account
264
    - filter: OData filter for metrics (e.g., timespan, metric names)
265
    
266
    Returns:
267
    ItemPaged[Metric]: Paginated list of metrics
268
    """
269

270
def list_usages(
271
    self,
272
    resource_group_name: str,
273
    account_name: str,
274
    filter: Optional[str] = None
275
) -> ItemPaged[Usage]:
276
    """
277
    Get usage statistics for a database account.
278
    
279
    Parameters:
280
    - resource_group_name: Name of the resource group
281
    - account_name: Name of the Cosmos DB account
282
    - filter: Optional OData filter for usage data
283
    
284
    Returns:
285
    ItemPaged[Usage]: Paginated list of usage statistics
286
    """
287

288
def list_metric_definitions(
289
    self,
290
    resource_group_name: str,
291
    account_name: str
292
) -> ItemPaged[MetricDefinition]:
293
    """
294
    Get available metric definitions for a database account.
295
    
296
    Parameters:
297
    - resource_group_name: Name of the resource group
298
    - account_name: Name of the Cosmos DB account
299
    
300
    Returns:
301
    ItemPaged[MetricDefinition]: Available metric definitions
302
    """
303
```
304

305
## Usage Examples
306

307
### Creating a Multi-Region Cosmos DB Account
308

309
```python
310
from azure.mgmt.cosmosdb import CosmosDBManagementClient
311
from azure.mgmt.cosmosdb.models import DatabaseAccountCreateUpdateParameters, Location
312
from azure.identity import DefaultAzureCredential
313

314
client = CosmosDBManagementClient(DefaultAzureCredential(), "subscription-id")
315

316
# Define account configuration
317
create_params = DatabaseAccountCreateUpdateParameters(
318
    location="East US",
319
    locations=[
320
        Location(location_name="East US", failover_priority=0, is_zone_redundant=False),
321
        Location(location_name="West US", failover_priority=1, is_zone_redundant=False)
322
    ],
323
    kind="GlobalDocumentDB",
324
    consistency_policy={
325
        "default_consistency_level": "Session"
326
    },
327
    enable_automatic_failover=True,
328
    enable_multiple_write_locations=False
329
)
330

331
# Create account (Long Running Operation)
332
poller = client.database_accounts.begin_create_or_update(
333
    "my-resource-group",
334
    "my-cosmos-account",
335
    create_params
336
)
337

338
# Wait for completion
339
account = poller.result()
340
print(f"Created account: {account.name} in regions: {[loc.location_name for loc in account.locations]}")
341
```
342

343
### Managing Account Keys
344

345
```python
346
# List current keys
347
keys = client.database_accounts.list_keys("resource-group", "account-name")
348
print(f"Primary Key: {keys.primary_master_key}")
349
print(f"Secondary Key: {keys.secondary_master_key}")
350

351
# Regenerate secondary key
352
from azure.mgmt.cosmosdb.models import DatabaseAccountRegenerateKeyParameters
353

354
regenerate_params = DatabaseAccountRegenerateKeyParameters(key_kind="secondary")
355
poller = client.database_accounts.begin_regenerate_key(
356
    "resource-group", "account-name", regenerate_params
357
)
358
poller.result()  # Wait for completion
359

360
# Get connection strings
361
connection_strings = client.database_accounts.list_connection_strings(
362
    "resource-group", "account-name"
363
)
364
for conn_str in connection_strings.connection_strings:
365
    print(f"{conn_str.description}: {conn_str.connection_string}")
366
```
367

368
## Key Types
369

370
```python { .api }
371
class DatabaseAccountGetResults:
372
    """Complete database account information including properties, settings, and status."""
373
    id: str
374
    name: str
375
    type: str
376
    location: str
377
    tags: Dict[str, str]
378
    kind: str  # "GlobalDocumentDB", "MongoDB", "Parse"
379
    provisioning_state: str
380
    document_endpoint: str
381
    locations: List[Location]
382
    read_locations: List[Location]
383
    write_locations: List[Location]
384
    consistency_policy: ConsistencyPolicy
385
    capabilities: List[Capability]
386
    enable_automatic_failover: bool
387
    enable_multiple_write_locations: bool
388
    backup_policy: BackupPolicy
389

390
class DatabaseAccountCreateUpdateParameters:
391
    """Parameters for creating or updating a database account."""
392
    location: str
393
    tags: Dict[str, str]
394
    kind: str
395
    locations: List[Location]
396
    consistency_policy: ConsistencyPolicy
397
    capabilities: List[Capability]
398
    enable_automatic_failover: bool
399
    enable_multiple_write_locations: bool
400
    backup_policy: BackupPolicy
401
    public_network_access: str
402
    network_acl_bypass: str
403
    ip_rules: List[IpAddressOrRange]
404
    virtual_network_rules: List[VirtualNetworkRule]
405

406
class DatabaseAccountListKeysResult:
407
    """Database account access keys."""
408
    primary_master_key: str
409
    secondary_master_key: str
410
    primary_readonly_master_key: str
411
    secondary_readonly_master_key: str
412

413
class Location:
414
    """Azure region configuration for database account."""
415
    location_name: str
416
    failover_priority: int
417
    is_zone_redundant: bool
418

419
class ConsistencyPolicy:
420
    """Database consistency policy settings."""
421
    default_consistency_level: str  # "Eventual", "Session", "BoundedStaleness", "Strong", "ConsistentPrefix"
422
    max_staleness_prefix: int
423
    max_interval_in_seconds: int
424
```