0
# Database Management
1

2
Database lifecycle management within Kusto clusters including creation, configuration, principal management, and database sharing through attached database configurations. Databases are containers for tables, functions, and other data objects within a Kusto cluster.
3

4
## Capabilities
5

6
### Database CRUD Operations
7

8
Core database lifecycle operations for creating, reading, updating, and deleting databases within Kusto clusters.
9

10
```python { .api }
11
def get(
12
    resource_group_name: str,
13
    cluster_name: str,
14
    database_name: str,
15
    **kwargs
16
) -> Database:
17
    """
18
    Get a database in a Kusto cluster.
19
    
20
    Parameters:
21
    - resource_group_name: Name of the resource group
22
    - cluster_name: Name of the Kusto cluster
23
    - database_name: Name of the database
24
    
25
    Returns:
26
    Database object (ReadWriteDatabase or ReadOnlyFollowingDatabase)
27
    """
28

29
def begin_create_or_update(
30
    resource_group_name: str,
31
    cluster_name: str,
32
    database_name: str,
33
    parameters: Database,
34
    caller_role: CallerRole = None,
35
    **kwargs
36
) -> LROPoller[Database]:
37
    """
38
    Create or update a database in a Kusto cluster.
39
    
40
    Parameters:
41
    - resource_group_name: Name of the resource group
42
    - cluster_name: Name of the Kusto cluster
43
    - database_name: Name of the database
44
    - parameters: Database object with configuration
45
    - caller_role: Role of the caller (Admin or User)
46
    
47
    Returns:
48
    LROPoller for the long-running operation returning Database
49
    """
50

51
def begin_update(
52
    resource_group_name: str,
53
    cluster_name: str,
54
    database_name: str,
55
    parameters: Database,
56
    caller_role: CallerRole = None,
57
    **kwargs
58
) -> LROPoller[Database]:
59
    """
60
    Update a database in a Kusto cluster.
61
    
62
    Parameters:
63
    - resource_group_name: Name of the resource group
64
    - cluster_name: Name of the Kusto cluster
65
    - database_name: Name of the database
66
    - parameters: Database object with updates
67
    - caller_role: Role of the caller (Admin or User)
68
    
69
    Returns:
70
    LROPoller for the long-running operation returning updated Database
71
    """
72

73
def begin_delete(
74
    resource_group_name: str,
75
    cluster_name: str,
76
    database_name: str,
77
    **kwargs
78
) -> LROPoller[None]:
79
    """
80
    Delete a database from a Kusto cluster.
81
    
82
    Parameters:
83
    - resource_group_name: Name of the resource group
84
    - cluster_name: Name of the Kusto cluster
85
    - database_name: Name of the database
86
    
87
    Returns:
88
    LROPoller for the long-running delete operation
89
    """
90
```
91

92
### Database Listing Operations
93

94
Operations to discover and list databases within Kusto clusters.
95

96
```python { .api }
97
def list_by_cluster(
98
    resource_group_name: str,
99
    cluster_name: str,
100
    top: int = None,
101
    skiptoken: str = None,
102
    **kwargs
103
) -> Iterable[Database]:
104
    """
105
    List databases in a Kusto cluster.
106
    
107
    Parameters:
108
    - resource_group_name: Name of the resource group
109
    - cluster_name: Name of the Kusto cluster
110
    - top: Maximum number of results to return
111
    - skiptoken: Token for pagination
112
    
113
    Returns:
114
    Iterable of Database objects
115
    """
116
```
117

118
### Name Validation
119

120
Operations to validate database names before creation.
121

122
```python { .api }
123
def check_name_availability(
124
    resource_group_name: str,
125
    cluster_name: str,
126
    resource_name: CheckNameRequest,
127
    **kwargs
128
) -> CheckNameResult:
129
    """
130
    Check if a database name is available in the cluster.
131
    
132
    Parameters:
133
    - resource_group_name: Name of the resource group
134
    - cluster_name: Name of the Kusto cluster
135
    - resource_name: CheckNameRequest with name to validate
136
    
137
    Returns:
138
    CheckNameResult indicating availability and any issues
139
    """
140
```
141

142
### Database Principal Management
143

144
Operations to manage security principals (users, groups, applications) at the database level.
145

146
```python { .api }
147
def list_principals(
148
    resource_group_name: str,
149
    cluster_name: str,
150
    database_name: str,
151
    **kwargs
152
) -> Iterable[DatabasePrincipal]:
153
    """
154
    List principals with access to the database.
155
    
156
    Parameters:
157
    - resource_group_name: Name of the resource group
158
    - cluster_name: Name of the Kusto cluster
159
    - database_name: Name of the database
160
    
161
    Returns:
162
    Iterable of DatabasePrincipal objects
163
    """
164

165
def add_principals(
166
    resource_group_name: str,
167
    cluster_name: str,
168
    database_name: str,
169
    database_principals_to_add: DatabasePrincipalListRequest,
170
    **kwargs
171
) -> DatabasePrincipalListResult:
172
    """
173
    Add principals to the database.
174
    
175
    Parameters:
176
    - resource_group_name: Name of the resource group
177
    - cluster_name: Name of the Kusto cluster
178
    - database_name: Name of the database
179
    - database_principals_to_add: List of principals to add
180
    
181
    Returns:
182
    DatabasePrincipalListResult with operation results
183
    """
184

185
def remove_principals(
186
    resource_group_name: str,
187
    cluster_name: str,
188
    database_name: str,
189
    database_principals_to_remove: DatabasePrincipalListRequest,
190
    **kwargs
191
) -> DatabasePrincipalListResult:
192
    """
193
    Remove principals from the database.
194
    
195
    Parameters:
196
    - resource_group_name: Name of the resource group
197
    - cluster_name: Name of the Kusto cluster
198
    - database_name: Name of the database
199
    - database_principals_to_remove: List of principals to remove
200
    
201
    Returns:
202
    DatabasePrincipalListResult with operation results
203
    """
204
```
205

206
### Database Invitation Operations
207

208
Operations to invite followers for database sharing across clusters.
209

210
```python { .api }
211
def invite_follower(
212
    resource_group_name: str,
213
    cluster_name: str,
214
    database_name: str,
215
    parameters: DatabaseInviteFollowerRequest,
216
    **kwargs
217
) -> DatabaseInviteFollowerResult:
218
    """
219
    Invite a follower database to replicate from this database.
220
    
221
    Parameters:
222
    - resource_group_name: Name of the resource group
223
    - cluster_name: Name of the Kusto cluster
224
    - database_name: Name of the database
225
    - parameters: Invitation configuration
226
    
227
    Returns:
228
    DatabaseInviteFollowerResult with invitation details
229
    """
230
```
231

232
## Usage Examples
233

234
### Creating a Read-Write Database
235

236
```python
237
from azure.mgmt.kusto.models import ReadWriteDatabase
238

239
# Configure database parameters
240
database_params = ReadWriteDatabase(
241
    location="East US",
242
    soft_delete_period="P365D",  # 365 days retention
243
    hot_cache_period="P31D"      # 31 days hot cache
244
)
245

246
# Create the database
247
poller = client.databases.begin_create_or_update(
248
    resource_group_name="my-resource-group",
249
    cluster_name="my-cluster",
250
    database_name="my-database",
251
    parameters=database_params
252
)
253

254
database = poller.result()
255
print(f"Database created: {database.name}")
256
```
257

258
### Adding Database Principals
259

260
```python
261
from azure.mgmt.kusto.models import (
262
    DatabasePrincipalListRequest,
263
    DatabasePrincipal,
264
    DatabasePrincipalRole,
265
    DatabasePrincipalType
266
)
267

268
# Create principal objects
269
principals_to_add = DatabasePrincipalListRequest(
270
    value=[
271
        DatabasePrincipal(
272
            role=DatabasePrincipalRole.ADMIN,
273
            name="admin-user@company.com",
274
            type=DatabasePrincipalType.USER,
275
            fqn="aaduser=admin-user@company.com",
276
            email="admin-user@company.com"
277
        ),
278
        DatabasePrincipal(
279
            role=DatabasePrincipalRole.VIEWER,
280
            name="analysts",
281
            type=DatabasePrincipalType.GROUP,
282
            fqn="aadgroup=analysts-group-id"
283
        )
284
    ]
285
)
286

287
# Add principals to database
288
result = client.databases.add_principals(
289
    resource_group_name="my-resource-group",
290
    cluster_name="my-cluster",
291
    database_name="my-database",
292
    database_principals_to_add=principals_to_add
293
)
294

295
print(f"Added {len(result.value)} principals to database")
296
```
297

298
### Creating a Read-Only Following Database
299

300
```python
301
from azure.mgmt.kusto.models import ReadOnlyFollowingDatabase
302

303
# Configure following database
304
following_db_params = ReadOnlyFollowingDatabase(
305
    location="West US",
306
    leader_cluster_resource_id="/subscriptions/sub-id/resourceGroups/rg/providers/Microsoft.Kusto/clusters/leader-cluster",
307
    attached_database_configuration_name="my-attached-config"
308
)
309

310
# Create following database
311
poller = client.databases.begin_create_or_update(
312
    resource_group_name="my-resource-group",
313
    cluster_name="my-follower-cluster",
314
    database_name="my-following-database",
315
    parameters=following_db_params
316
)
317

318
following_db = poller.result()
319
print(f"Following database created: {following_db.name}")
320
```
321

322
## Key Types
323

324
```python { .api }
325
class Database:
326
    """Base class for database resources."""
327
    # Read-only properties
328
    id: str  # Resource ID
329
    name: str  # Database name
330
    type: str  # Resource type
331
    
332
    # Common properties
333
    location: str  # Azure region
334
    kind: Kind  # Database kind (ReadWrite or ReadOnlyFollowing)
335

336
class ReadWriteDatabase(Database):
337
    """A read-write database in a Kusto cluster."""
338
    kind: Kind = Kind.READ_WRITE
339
    
340
    # Configuration properties
341
    provisioning_state: ProvisioningState  # Provisioning state
342
    soft_delete_period: str  # Data retention period (ISO 8601 duration)
343
    hot_cache_period: str  # Hot cache period (ISO 8601 duration)
344
    statistics: DatabaseStatistics  # Database size and statistics
345
    is_followed: bool  # Whether database is being followed
346

347
class ReadOnlyFollowingDatabase(Database):
348
    """A read-only database following a leader database."""
349
    kind: Kind = Kind.READ_ONLY_FOLLOWING
350
    
351
    # Following configuration
352
    provisioning_state: ProvisioningState  # Provisioning state
353
    leader_cluster_resource_id: str  # Resource ID of leader cluster
354
    attached_database_configuration_name: str  # Configuration name
355
    principals_modification_kind: PrincipalsModificationKind  # Principal handling
356
    table_level_sharing_properties: TableLevelSharingProperties  # Table sharing
357
    database_share_origin: DatabaseShareOrigin  # Share origin type
358
    original_database_name: str  # Original database name
359
    statistics: DatabaseStatistics  # Database statistics
360

361
class DatabasePrincipal:
362
    """Represents a security principal with database access."""
363
    role: DatabasePrincipalRole  # Principal role
364
    name: str  # Principal name
365
    type: DatabasePrincipalType  # Principal type
366
    fqn: str  # Fully qualified name
367
    email: str  # Email address (for users)
368
    app_id: str  # Application ID (for apps)
369
    tenant_name: str  # Tenant name
370

371
class DatabasePrincipalListRequest:
372
    """Request to add or remove database principals."""
373
    value: List[DatabasePrincipal]  # List of principals
374

375
class DatabasePrincipalListResult:
376
    """Result of principal add/remove operations."""
377
    value: List[DatabasePrincipal]  # Updated list of principals
378

379
class DatabaseInviteFollowerRequest:
380
    """Request to invite a follower database."""
381
    invitee_email: str  # Email of the invitee
382
    table_level_sharing_properties: TableLevelSharingProperties  # Sharing config
383

384
class DatabaseInviteFollowerResult:
385
    """Result of database follower invitation."""
386
    generated_invitation: str  # Invitation token
387

388
from enum import Enum
389

390
class Kind(str, Enum):
391
    """Database kind values."""
392
    READ_WRITE = "ReadWrite"
393
    READ_ONLY_FOLLOWING = "ReadOnlyFollowing"
394

395
class DatabasePrincipalRole(str, Enum):
396
    """Database principal role values."""
397
    ADMIN = "Admin"
398
    INGESTOR = "Ingestor"
399
    MONITOR = "Monitor"
400
    USER = "User"
401
    UNRESTRICTED_VIEWER = "UnrestrictedViewer"
402
    VIEWER = "Viewer"
403

404
class DatabasePrincipalType(str, Enum):
405
    """Database principal type values."""
406
    APP = "App"
407
    GROUP = "Group"
408
    USER = "User"
409

410
class CallerRole(str, Enum):
411
    """Caller role values."""
412
    ADMIN = "Admin"
413
    USER = "User"
414

415
class PrincipalsModificationKind(str, Enum):
416
    """Principal modification behavior."""
417
    UNION = "Union"
418
    REPLACE = "Replace"
419
    NONE = "None"
420

421
class DatabaseShareOrigin(str, Enum):
422
    """Database share origin values."""
423
    DIRECT = "Direct"
424
    DATA_SHARE = "DataShare"
425
    OTHER = "Other"
426
```