0
# Cluster Operations
1
2
Cluster-level operations for connecting to Couchbase, managing authentication, and accessing cluster-wide services. The Cluster class serves as the main entry point for all database operations.
3
4
## Capabilities
5
6
### Connection and Initialization
7
8
Establish connections to Couchbase clusters with various configuration options and authentication methods.
9
10
```python { .api }
11
class Cluster:
12
def __init__(self, connection_string: str, options: ClusterOptions = None):
13
"""
14
Create a new Cluster instance.
15
16
Args:
17
connection_string (str): Connection string (e.g., "couchbase://localhost")
18
options (ClusterOptions, optional): Cluster configuration options
19
20
Raises:
21
AuthenticationException: If authentication fails
22
NetworkException: If connection cannot be established
23
"""
24
25
class ClusterOptions:
26
def __init__(self, authenticator: Authenticator = None,
27
timeout_options: ClusterTimeoutOptions = None,
28
tracing_options: ClusterTracingOptions = None):
29
"""
30
Cluster configuration options.
31
32
Args:
33
authenticator (Authenticator, optional): Authentication mechanism
34
timeout_options (ClusterTimeoutOptions, optional): Timeout configuration
35
tracing_options (ClusterTracingOptions, optional): Tracing configuration
36
"""
37
38
class ClusterTimeoutOptions:
39
def __init__(self, kv_timeout: timedelta = None,
40
query_timeout: timedelta = None,
41
search_timeout: timedelta = None,
42
analytics_timeout: timedelta = None,
43
management_timeout: timedelta = None):
44
"""
45
Timeout configuration for various operations.
46
47
Args:
48
kv_timeout (timedelta, optional): Key-value operation timeout
49
query_timeout (timedelta, optional): N1QL query timeout
50
search_timeout (timedelta, optional): Search query timeout
51
analytics_timeout (timedelta, optional): Analytics query timeout
52
management_timeout (timedelta, optional): Management operation timeout
53
"""
54
```
55
56
### Authentication
57
58
Various authentication mechanisms for secure cluster access.
59
60
```python { .api }
61
class Authenticator:
62
"""Base class for all authenticators."""
63
64
class PasswordAuthenticator(Authenticator):
65
def __init__(self, username: str, password: str):
66
"""
67
Username/password authentication.
68
69
Args:
70
username (str): RBAC username
71
password (str): User password
72
"""
73
74
class CertificateAuthenticator(Authenticator):
75
def __init__(self, cert_path: str, key_path: str,
76
trust_store_path: str = None):
77
"""
78
Certificate-based authentication.
79
80
Args:
81
cert_path (str): Path to client certificate
82
key_path (str): Path to client private key
83
trust_store_path (str, optional): Path to trust store
84
"""
85
```
86
87
### Bucket Access
88
89
Access to individual buckets within the cluster.
90
91
```python { .api }
92
class Cluster:
93
def bucket(self, bucket_name: str) -> Bucket:
94
"""
95
Get a bucket reference.
96
97
Args:
98
bucket_name (str): Name of the bucket
99
100
Returns:
101
Bucket: Bucket instance for data operations
102
103
Raises:
104
BucketNotFoundException: If bucket doesn't exist
105
"""
106
107
def wait_until_ready(self, timeout: timedelta, options: WaitUntilReadyOptions = None) -> None:
108
"""
109
Wait until cluster services are ready for operations.
110
111
Args:
112
timeout (timedelta): Maximum time to wait
113
options (WaitUntilReadyOptions, optional): Wait options
114
115
Raises:
116
TimeoutException: If cluster is not ready within timeout
117
"""
118
```
119
120
### Diagnostics and Health Monitoring
121
122
Cluster health monitoring and diagnostic operations.
123
124
```python { .api }
125
class Cluster:
126
def ping(self, options: PingOptions = None) -> PingResult:
127
"""
128
Ping cluster services to check connectivity.
129
130
Args:
131
options (PingOptions, optional): Ping operation options
132
133
Returns:
134
PingResult: Connectivity status for each service
135
"""
136
137
def diagnostics(self, options: DiagnosticsOptions = None) -> DiagnosticsResult:
138
"""
139
Get cluster diagnostic information.
140
141
Args:
142
options (DiagnosticsOptions, optional): Diagnostic options
143
144
Returns:
145
DiagnosticsResult: Detailed cluster health information
146
"""
147
148
class PingOptions:
149
def __init__(self, timeout: timedelta = None,
150
service_types: List[ServiceType] = None):
151
"""
152
Options for ping operations.
153
154
Args:
155
timeout (timedelta, optional): Operation timeout
156
service_types (List[ServiceType], optional): Services to ping
157
"""
158
159
class DiagnosticsOptions:
160
def __init__(self, report_id: str = None):
161
"""
162
Options for diagnostics operations.
163
164
Args:
165
report_id (str, optional): Custom report identifier
166
"""
167
168
class PingResult:
169
@property
170
def id(self) -> str: ...
171
@property
172
def services(self) -> Dict[ServiceType, List[PingResultEndpoint]]: ...
173
174
class DiagnosticsResult:
175
@property
176
def id(self) -> str: ...
177
@property
178
def services(self) -> Dict[ServiceType, List[DiagnosticsEndpoint]]: ...
179
```
180
181
### Query Operations
182
183
Cluster-level query operations for N1QL, Analytics, and Search.
184
185
```python { .api }
186
class Cluster:
187
def query(self, statement: str, options: QueryOptions = None) -> QueryResult:
188
"""
189
Execute N1QL query.
190
191
Args:
192
statement (str): N1QL query statement
193
options (QueryOptions, optional): Query execution options
194
195
Returns:
196
QueryResult: Query results iterator
197
198
Raises:
199
QueryException: If query execution fails
200
"""
201
202
def analytics_query(self, statement: str, options: AnalyticsOptions = None) -> AnalyticsResult:
203
"""
204
Execute Analytics query.
205
206
Args:
207
statement (str): Analytics query statement
208
options (AnalyticsOptions, optional): Analytics execution options
209
210
Returns:
211
AnalyticsResult: Analytics results iterator
212
213
Raises:
214
AnalyticsException: If analytics execution fails
215
"""
216
217
def search_query(self, index: str, query: SearchQuery, options: SearchOptions = None) -> SearchResult:
218
"""
219
Execute full-text search query.
220
221
Args:
222
index (str): Search index name
223
query (SearchQuery): Search query object
224
options (SearchOptions, optional): Search execution options
225
226
Returns:
227
SearchResult: Search results iterator
228
229
Raises:
230
SearchException: If search execution fails
231
"""
232
```
233
234
### Management Interface Access
235
236
Access to various management interfaces for administrative operations.
237
238
```python { .api }
239
class Cluster:
240
def buckets(self) -> BucketManager:
241
"""Get bucket management interface."""
242
243
def users(self) -> UserManager:
244
"""Get user management interface."""
245
246
def query_indexes(self) -> QueryIndexManager:
247
"""Get N1QL index management interface."""
248
249
def analytics_indexes(self) -> AnalyticsIndexManager:
250
"""Get Analytics index management interface."""
251
252
def search_indexes(self) -> SearchIndexManager:
253
"""Get Search index management interface."""
254
255
def eventing_functions(self) -> EventingFunctionManager:
256
"""Get Eventing function management interface."""
257
```
258
259
## Usage Examples
260
261
### Basic Connection
262
263
```python
264
from couchbase.cluster import Cluster
265
from couchbase.auth import PasswordAuthenticator
266
from couchbase.options import ClusterOptions
267
268
# Simple connection
269
cluster = Cluster("couchbase://localhost",
270
ClusterOptions(PasswordAuthenticator("user", "pass")))
271
272
# With timeout configuration
273
from datetime import timedelta
274
timeout_opts = ClusterTimeoutOptions(
275
kv_timeout=timedelta(seconds=10),
276
query_timeout=timedelta(seconds=30)
277
)
278
cluster = Cluster("couchbase://localhost",
279
ClusterOptions(
280
PasswordAuthenticator("user", "pass"),
281
timeout_options=timeout_opts
282
))
283
```
284
285
### Certificate Authentication
286
287
```python
288
from couchbase.auth import CertificateAuthenticator
289
290
auth = CertificateAuthenticator(
291
cert_path="/path/to/cert.pem",
292
key_path="/path/to/key.pem",
293
trust_store_path="/path/to/ca.pem"
294
)
295
cluster = Cluster("couchbases://localhost", ClusterOptions(auth))
296
```
297
298
### Health Monitoring
299
300
```python
301
# Basic ping
302
ping_result = cluster.ping()
303
print(f"Ping ID: {ping_result.id}")
304
for service_type, endpoints in ping_result.services.items():
305
print(f"{service_type}: {len(endpoints)} endpoints")
306
307
# Detailed diagnostics
308
diag_result = cluster.diagnostics()
309
print(f"Diagnostics: {diag_result.id}")
310
```
311
312
## Additional Types
313
314
```python { .api }
315
enum ServiceType:
316
KV = "kv"
317
QUERY = "n1ql"
318
SEARCH = "fts"
319
ANALYTICS = "cbas"
320
MANAGEMENT = "mgmt"
321
VIEWS = "views"
322
EVENTING = "eventing"
323
324
class WaitUntilReadyOptions:
325
def __init__(self, service_types: List[ServiceType] = None,
326
desired_state: ClusterState = ClusterState.ONLINE):
327
"""
328
Options for wait_until_ready operation.
329
330
Args:
331
service_types (List[ServiceType], optional): Services to wait for
332
desired_state (ClusterState, optional): Target cluster state
333
"""
334
335
enum ClusterState:
336
ONLINE = "online"
337
DEGRADED = "degraded"
338
OFFLINE = "offline"
339
```