0
# Management Operations
1

2
Administrative operations for managing cluster resources including buckets, collections, users, roles, and indexes across all service types. These operations require appropriate administrative privileges.
3

4
## Capabilities
5

6
### Bucket Management
7

8
Administrative operations for managing buckets within the cluster.
9

10
```python { .api }
11
class BucketManager:
12
    def create_bucket(self, settings: CreateBucketSettings, options: CreateBucketOptions = None) -> None:
13
        """
14
        Create a new bucket.
15

16
        Args:
17
            settings (CreateBucketSettings): Bucket configuration
18
            options (CreateBucketOptions, optional): Creation options
19

20
        Raises:
21
            BucketExistsException: If bucket already exists
22
            InvalidArgumentException: If settings are invalid
23
        """
24

25
    def update_bucket(self, settings: BucketSettings, options: UpdateBucketOptions = None) -> None:
26
        """
27
        Update bucket settings.
28

29
        Args:
30
            settings (BucketSettings): Updated bucket configuration
31
            options (UpdateBucketOptions, optional): Update options
32

33
        Raises:
34
            BucketNotFoundException: If bucket doesn't exist
35
        """
36

37
    def drop_bucket(self, bucket_name: str, options: DropBucketOptions = None) -> None:
38
        """
39
        Delete a bucket.
40

41
        Args:
42
            bucket_name (str): Name of bucket to delete
43
            options (DropBucketOptions, optional): Deletion options
44

45
        Raises:
46
            BucketNotFoundException: If bucket doesn't exist
47
        """
48

49
    def get_bucket(self, bucket_name: str, options: GetBucketOptions = None) -> BucketSettings:
50
        """
51
        Get bucket settings.
52

53
        Args:
54
            bucket_name (str): Bucket name
55
            options (GetBucketOptions, optional): Retrieval options
56

57
        Returns:
58
            BucketSettings: Current bucket configuration
59

60
        Raises:
61
            BucketNotFoundException: If bucket doesn't exist
62
        """
63

64
    def get_all_buckets(self, options: GetAllBucketsOptions = None) -> Dict[str, BucketSettings]:
65
        """
66
        Get all bucket settings.
67

68
        Args:
69
            options (GetAllBucketsOptions, optional): Retrieval options
70

71
        Returns:
72
            Dict[str, BucketSettings]: All bucket configurations
73
        """
74

75
    def flush_bucket(self, bucket_name: str, options: FlushBucketOptions = None) -> None:
76
        """
77
        Flush all data from bucket.
78

79
        Args:
80
            bucket_name (str): Bucket name
81
            options (FlushBucketOptions, optional): Flush options
82

83
        Raises:
84
            BucketNotFoundException: If bucket doesn't exist
85
            FeatureNotAvailableException: If flush is disabled
86
        """
87
```
88

89
### Collection and Scope Management
90

91
Manage collections and scopes within buckets.
92

93
```python { .api }
94
class CollectionManager:
95
    def create_scope(self, scope_name: str, options: CreateScopeOptions = None) -> None:
96
        """
97
        Create a new scope.
98

99
        Args:
100
            scope_name (str): Scope name
101
            options (CreateScopeOptions, optional): Creation options
102

103
        Raises:
104
            ScopeExistsException: If scope already exists
105
        """
106

107
    def drop_scope(self, scope_name: str, options: DropScopeOptions = None) -> None:
108
        """
109
        Delete a scope and all its collections.
110

111
        Args:
112
            scope_name (str): Scope name
113
            options (DropScopeOptions, optional): Deletion options
114

115
        Raises:
116
            ScopeNotFoundException: If scope doesn't exist
117
        """
118

119
    def create_collection(self, collection_spec: CollectionSpec, options: CreateCollectionOptions = None) -> None:
120
        """
121
        Create a new collection.
122

123
        Args:
124
            collection_spec (CollectionSpec): Collection configuration
125
            options (CreateCollectionOptions, optional): Creation options
126

127
        Raises:
128
            CollectionExistsException: If collection already exists
129
            ScopeNotFoundException: If parent scope doesn't exist
130
        """
131

132
    def drop_collection(self, collection_spec: CollectionSpec, options: DropCollectionOptions = None) -> None:
133
        """
134
        Delete a collection.
135

136
        Args:
137
            collection_spec (CollectionSpec): Collection to delete
138
            options (DropCollectionOptions, optional): Deletion options
139

140
        Raises:
141
            CollectionNotFoundException: If collection doesn't exist
142
        """
143

144
    def get_all_scopes(self, options: GetAllScopesOptions = None) -> List[ScopeSpec]:
145
        """
146
        Get all scopes and their collections.
147

148
        Args:
149
            options (GetAllScopesOptions, optional): Retrieval options
150

151
        Returns:
152
            List[ScopeSpec]: All scopes with their collections
153
        """
154
```
155

156
### User and Role Management
157

158
Manage users, roles, and groups for RBAC (Role-Based Access Control).
159

160
```python { .api }
161
class UserManager:
162
    def upsert_user(self, user: User, options: UpsertUserOptions = None) -> None:
163
        """
164
        Create or update a user.
165

166
        Args:
167
            user (User): User configuration
168
            options (UpsertUserOptions, optional): Upsert options
169

170
        Raises:
171
            InvalidArgumentException: If user configuration is invalid
172
        """
173

174
    def drop_user(self, username: str, options: DropUserOptions = None) -> None:
175
        """
176
        Delete a user.
177

178
        Args:
179
            username (str): Username to delete
180
            options (DropUserOptions, optional): Deletion options
181

182
        Raises:
183
            UserNotFoundException: If user doesn't exist
184
        """
185

186
    def get_user(self, username: str, options: GetUserOptions = None) -> UserAndMetadata:
187
        """
188
        Get user information.
189

190
        Args:
191
            username (str): Username
192
            options (GetUserOptions, optional): Retrieval options
193

194
        Returns:
195
            UserAndMetadata: User information with metadata
196

197
        Raises:
198
            UserNotFoundException: If user doesn't exist
199
        """
200

201
    def get_all_users(self, options: GetAllUsersOptions = None) -> List[UserAndMetadata]:
202
        """
203
        Get all users.
204

205
        Args:
206
            options (GetAllUsersOptions, optional): Retrieval options
207

208
        Returns:
209
            List[UserAndMetadata]: All users with metadata
210
        """
211

212
    def get_roles(self, options: GetRolesOptions = None) -> List[RoleAndDescription]:
213
        """
214
        Get available roles.
215

216
        Args:
217
            options (GetRolesOptions, optional): Retrieval options
218

219
        Returns:
220
            List[RoleAndDescription]: Available roles with descriptions
221
        """
222

223
    def upsert_group(self, group: Group, options: UpsertGroupOptions = None) -> None:
224
        """
225
        Create or update a group.
226

227
        Args:
228
            group (Group): Group configuration
229
            options (UpsertGroupOptions, optional): Upsert options
230
        """
231

232
    def drop_group(self, group_name: str, options: DropGroupOptions = None) -> None:
233
        """
234
        Delete a group.
235

236
        Args:
237
            group_name (str): Group name
238
            options (DropGroupOptions, optional): Deletion options
239
        """
240

241
    def get_group(self, group_name: str, options: GetGroupOptions = None) -> Group:
242
        """
243
        Get group information.
244

245
        Args:
246
            group_name (str): Group name
247
            options (GetGroupOptions, optional): Retrieval options
248

249
        Returns:
250
            Group: Group configuration
251
        """
252

253
    def get_all_groups(self, options: GetAllGroupsOptions = None) -> List[Group]:
254
        """
255
        Get all groups.
256

257
        Args:
258
            options (GetAllGroupsOptions, optional): Retrieval options
259

260
        Returns:
261
            List[Group]: All group configurations
262
        """
263
```
264

265
### Query Index Management
266

267
Manage N1QL indexes for query performance optimization.
268

269
```python { .api }
270
class QueryIndexManager:
271
    def create_index(self, bucket_name: str, index_name: str, keys: List[str], options: CreateQueryIndexOptions = None) -> None:
272
        """
273
        Create a N1QL index.
274

275
        Args:
276
            bucket_name (str): Bucket name
277
            index_name (str): Index name
278
            keys (List[str]): Index key fields
279
            options (CreateQueryIndexOptions, optional): Creation options
280

281
        Raises:
282
            IndexExistsException: If index already exists
283
        """
284

285
    def create_primary_index(self, bucket_name: str, options: CreatePrimaryQueryIndexOptions = None) -> None:
286
        """
287
        Create a primary index.
288

289
        Args:
290
            bucket_name (str): Bucket name
291
            options (CreatePrimaryQueryIndexOptions, optional): Creation options
292

293
        Raises:
294
            IndexExistsException: If primary index already exists
295
        """
296

297
    def drop_index(self, bucket_name: str, index_name: str, options: DropQueryIndexOptions = None) -> None:
298
        """
299
        Drop a N1QL index.
300

301
        Args:
302
            bucket_name (str): Bucket name
303
            index_name (str): Index name
304
            options (DropQueryIndexOptions, optional): Drop options
305

306
        Raises:
307
            IndexNotFoundException: If index doesn't exist
308
        """
309

310
    def drop_primary_index(self, bucket_name: str, options: DropPrimaryQueryIndexOptions = None) -> None:
311
        """
312
        Drop the primary index.
313

314
        Args:
315
            bucket_name (str): Bucket name
316
            options (DropPrimaryQueryIndexOptions, optional): Drop options
317

318
        Raises:
319
            IndexNotFoundException: If primary index doesn't exist
320
        """
321

322
    def get_all_indexes(self, bucket_name: str, options: GetAllQueryIndexesOptions = None) -> List[QueryIndex]:
323
        """
324
        Get all indexes for bucket.
325

326
        Args:
327
            bucket_name (str): Bucket name
328
            options (GetAllQueryIndexesOptions, optional): Retrieval options
329

330
        Returns:
331
            List[QueryIndex]: All indexes in bucket
332
        """
333

334
    def watch_indexes(self, bucket_name: str, index_names: List[str], options: WatchQueryIndexOptions = None) -> None:
335
        """
336
        Watch for indexes to come online.
337

338
        Args:
339
            bucket_name (str): Bucket name
340
            index_names (List[str]): Index names to watch
341
            options (WatchQueryIndexOptions, optional): Watch options
342

343
        Raises:
344
            TimeoutException: If indexes don't come online within timeout
345
        """
346

347
    def build_deferred_indexes(self, bucket_name: str, options: BuildDeferredQueryIndexOptions = None) -> None:
348
        """
349
        Build all deferred indexes.
350

351
        Args:
352
            bucket_name (str): Bucket name
353
            options (BuildDeferredQueryIndexOptions, optional): Build options
354
        """
355
```
356

357
## Configuration Types
358

359
### Bucket Configuration
360

361
```python { .api }
362
class BucketSettings:
363
    def __init__(self, name: str, bucket_type: BucketType, 
364
                 ram_quota_mb: int, **kwargs):
365
        """
366
        Bucket configuration settings.
367

368
        Args:
369
            name (str): Bucket name
370
            bucket_type (BucketType): Type of bucket
371
            ram_quota_mb (int): RAM quota in MB
372
            **kwargs: Additional configuration options
373
        """
374

375
    @property
376
    def name(self) -> str: ...
377
    @property
378
    def bucket_type(self) -> BucketType: ...
379
    @property
380
    def ram_quota_mb(self) -> int: ...
381
    @property
382
    def num_replicas(self) -> int: ...
383
    @property
384
    def replica_indexes(self) -> bool: ...
385
    @property
386
    def flush_enabled(self) -> bool: ...
387
    @property
388
    def max_expiry(self) -> int: ...
389
    @property
390
    def compression_mode(self) -> CompressionMode: ...
391
    @property
392
    def conflict_resolution_type(self) -> ConflictResolutionType: ...
393

394
class CreateBucketSettings(BucketSettings):
395
    """Settings for creating new buckets."""
396

397
class BucketType:
398
    COUCHBASE = "couchbase"
399
    EPHEMERAL = "ephemeral"
400
    MEMCACHED = "memcached"
401

402
class CompressionMode:
403
    OFF = "off"
404
    PASSIVE = "passive"
405
    ACTIVE = "active"
406

407
class ConflictResolutionType:
408
    TIMESTAMP = "lww"
409
    SEQUENCE_NUMBER = "seqno"
410
```
411

412
### Collection Configuration
413

414
```python { .api }
415
class CollectionSpec:
416
    def __init__(self, name: str, scope_name: str = "_default", 
417
                 max_expiry: int = None):
418
        """
419
        Collection specification.
420

421
        Args:
422
            name (str): Collection name
423
            scope_name (str): Parent scope name (default: "_default")
424
            max_expiry (int, optional): Maximum document expiry in seconds
425
        """
426

427
    @property
428
    def name(self) -> str: ...
429
    @property
430
    def scope_name(self) -> str: ...
431
    @property
432
    def max_expiry(self) -> int: ...
433

434
class ScopeSpec:
435
    def __init__(self, name: str, collections: List[CollectionSpec] = None):
436
        """
437
        Scope specification.
438

439
        Args:
440
            name (str): Scope name
441
            collections (List[CollectionSpec], optional): Collections in scope
442
        """
443

444
    @property
445
    def name(self) -> str: ...
446
    @property
447
    def collections(self) -> List[CollectionSpec]: ...
448
```
449

450
### User Configuration
451

452
```python { .api }
453
class User:
454
    def __init__(self, username: str, display_name: str = None,
455
                 password: str = None, groups: List[str] = None,
456
                 roles: List[Role] = None):
457
        """
458
        User configuration.
459

460
        Args:
461
            username (str): Username
462
            display_name (str, optional): Display name
463
            password (str, optional): User password
464
            groups (List[str], optional): User groups
465
            roles (List[Role], optional): Assigned roles
466
        """
467

468
    @property
469
    def username(self) -> str: ...
470
    @property
471
    def display_name(self) -> str: ...
472
    @property
473
    def groups(self) -> List[str]: ...
474
    @property
475
    def roles(self) -> List[Role]: ...
476

477
class Role:
478
    def __init__(self, name: str, bucket: str = None, scope: str = None, collection: str = None):
479
        """
480
        Role definition.
481

482
        Args:
483
            name (str): Role name
484
            bucket (str, optional): Bucket restriction
485
            scope (str, optional): Scope restriction  
486
            collection (str, optional): Collection restriction
487
        """
488

489
    @property
490
    def name(self) -> str: ...
491
    @property
492
    def bucket(self) -> str: ...
493
    @property
494
    def scope(self) -> str: ...
495
    @property
496
    def collection(self) -> str: ...
497

498
class Group:
499
    def __init__(self, name: str, description: str = None,
500
                 roles: List[Role] = None, ldap_group_reference: str = None):
501
        """
502
        Group configuration.
503

504
        Args:
505
            name (str): Group name
506
            description (str, optional): Group description
507
            roles (List[Role], optional): Group roles
508
            ldap_group_reference (str, optional): LDAP group reference
509
        """
510

511
    @property
512
    def name(self) -> str: ...
513
    @property
514
    def description(self) -> str: ...
515
    @property
516
    def roles(self) -> List[Role]: ...
517
    @property
518
    def ldap_group_reference(self) -> str: ...
519
```
520

521
### Index Configuration
522

523
```python { .api }
524
class QueryIndex:
525
    @property
526
    def name(self) -> str:
527
        """Index name."""
528

529
    @property
530
    def bucket_name(self) -> str:
531
        """Bucket containing the index."""
532

533
    @property
534
    def scope_name(self) -> str:
535
        """Scope containing the index."""
536

537
    @property
538
    def collection_name(self) -> str:
539
        """Collection containing the index."""
540

541
    @property
542
    def is_primary(self) -> bool:
543
        """Whether this is a primary index."""
544

545
    @property
546
    def index_key(self) -> List[str]:
547
        """Index key fields."""
548

549
    @property
550
    def condition(self) -> str:
551
        """Index condition (WHERE clause)."""
552

553
    @property
554
    def state(self) -> str:
555
        """Index state (online, building, etc.)."""
556

557
    @property
558
    def type(self) -> str:
559
        """Index type (gsi, etc.)."""
560
```
561

562
## Usage Examples
563

564
### Bucket Management
565

566
```python
567
from couchbase.management.buckets import BucketManager, BucketSettings, BucketType, CompressionMode
568
from datetime import timedelta
569

570
bucket_mgr = cluster.buckets()
571

572
# Create bucket
573
settings = BucketSettings(
574
    name="my-bucket",
575
    bucket_type=BucketType.COUCHBASE,
576
    ram_quota_mb=256,
577
    num_replicas=1,
578
    max_expiry=timedelta(days=30).total_seconds(),
579
    compression_mode=CompressionMode.ACTIVE
580
)
581
bucket_mgr.create_bucket(settings)
582

583
# Get bucket info
584
bucket_info = bucket_mgr.get_bucket("my-bucket")
585
print(f"Bucket RAM: {bucket_info.ram_quota_mb}MB")
586

587
# Update bucket
588
bucket_info.ram_quota_mb = 512
589
bucket_mgr.update_bucket(bucket_info)
590

591
# List all buckets
592
all_buckets = bucket_mgr.get_all_buckets()
593
for name, settings in all_buckets.items():
594
    print(f"Bucket: {name}, Type: {settings.bucket_type}")
595
```
596

597
### Collection Management
598

599
```python
600
from couchbase.management.collections import CollectionManager, CollectionSpec, ScopeSpec
601

602
coll_mgr = bucket.collections()
603

604
# Create scope
605
coll_mgr.create_scope("my-scope")
606

607
# Create collection
608
collection_spec = CollectionSpec("my-collection", "my-scope", max_expiry=3600)
609
coll_mgr.create_collection(collection_spec)
610

611
# List all scopes and collections
612
scopes = coll_mgr.get_all_scopes()
613
for scope in scopes:
614
    print(f"Scope: {scope.name}")
615
    for collection in scope.collections:
616
        print(f"  Collection: {collection.name}")
617
```
618

619
### User Management
620

621
```python
622
from couchbase.management.users import UserManager, User, Role
623

624
user_mgr = cluster.users()
625

626
# Create user with roles
627
user = User(
628
    username="developer",
629
    display_name="Developer User",
630
    password="secure_password",
631
    roles=[
632
        Role("bucket_admin", bucket="my-bucket"),
633
        Role("query_select", bucket="my-bucket")
634
    ]
635
)
636
user_mgr.upsert_user(user)
637

638
# Get user info
639
user_info = user_mgr.get_user("developer")
640
print(f"User: {user_info.user.display_name}")
641
for role in user_info.user.roles:
642
    print(f"  Role: {role.name} on {role.bucket}")
643

644
# List available roles
645
available_roles = user_mgr.get_roles()
646
for role in available_roles:
647
    print(f"Role: {role.role.name} - {role.description}")
648
```
649

650
### Index Management
651

652
```python
653
from couchbase.management.queries import QueryIndexManager
654
from datetime import timedelta
655

656
index_mgr = cluster.query_indexes()
657

658
# Create secondary index
659
index_mgr.create_index("my-bucket", "idx_type", ["type"])
660

661
# Create primary index
662
index_mgr.create_primary_index("my-bucket")
663

664
# Create conditional index
665
options = CreateQueryIndexOptions(
666
    condition="type = 'user'",
667
    deferred=True  # Build later
668
)
669
index_mgr.create_index("my-bucket", "idx_users", ["name", "email"], options)
670

671
# Build deferred indexes
672
index_mgr.build_deferred_indexes("my-bucket")
673

674
# Watch indexes come online
675
index_mgr.watch_indexes("my-bucket", ["idx_type", "idx_users"], 
676
                       WatchQueryIndexOptions(timeout=timedelta(minutes=5)))
677

678
# List all indexes
679
indexes = index_mgr.get_all_indexes("my-bucket")
680
for index in indexes:
681
    print(f"Index: {index.name} - State: {index.state}")
682
```