0
# Connection Management
1

2
Core CRUD operations for managing BigQuery connections to external data sources. These operations allow you to create, retrieve, list, update, and delete connection resources programmatically.
3

4
## Capabilities
5

6
### Creating Connections
7

8
Creates a new BigQuery connection to an external data source. The connection configuration depends on the target data source type.
9

10
```python { .api }
11
def create_connection(
12
    request: CreateConnectionRequest = None,
13
    *,
14
    parent: str = None,
15
    connection: Connection = None,
16
    connection_id: str = None,
17
    retry: OptionalRetry = DEFAULT,
18
    timeout: Union[float, object] = DEFAULT,
19
    metadata: Sequence[Tuple[str, Union[str, bytes]]] = (),
20
) -> Connection:
21
    """
22
    Creates a new connection in the given project and location.
23
    
24
    Parameters:
25
    - request: The request object containing connection details
26
    - parent: Required. Parent resource name in format 'projects/{project_id}/locations/{location_id}'
27
    - connection: Required. Connection configuration object
28
    - connection_id: Optional. Connection ID to assign to the created connection
29
    - retry: Retry configuration for the request
30
    - timeout: Timeout for the request in seconds
31
    - metadata: Additional metadata to send with the request
32
    
33
    Returns:
34
    Connection: The created connection object with server-generated fields populated
35
    
36
    Raises:
37
    google.api_core.exceptions.GoogleAPICallError: If the request fails
38
    """
39
```
40

41
**Usage Example:**
42

43
```python
44
from google.cloud.bigquery_connection import (
45
    ConnectionServiceClient,
46
    Connection,
47
    CloudSqlProperties,
48
    CloudSqlCredential
49
)
50

51
client = ConnectionServiceClient()
52

53
# Configure a Cloud SQL connection
54
connection = Connection()
55
connection.friendly_name = "Production Database"
56
connection.description = "Connection to production PostgreSQL database"
57
connection.cloud_sql = CloudSqlProperties()
58
connection.cloud_sql.instance_id = "my-project:us-central1:prod-db"
59
connection.cloud_sql.database = "analytics"
60
connection.cloud_sql.type_ = CloudSqlProperties.DatabaseType.POSTGRES
61
connection.cloud_sql.credential = CloudSqlCredential(
62
    username="bigquery_user",
63
    password="secure_password"
64
)
65

66
# Create the connection
67
parent = "projects/my-project/locations/us-central1"
68
created_connection = client.create_connection(
69
    parent=parent,
70
    connection=connection,
71
    connection_id="prod-analytics-db"
72
)
73

74
print(f"Created connection: {created_connection.name}")
75
print(f"Service account: {created_connection.cloud_sql.service_account_id}")
76
```
77

78
### Retrieving Connections
79

80
Retrieves a specific connection by its resource name.
81

82
```python { .api }
83
def get_connection(
84
    request: GetConnectionRequest = None,
85
    *,
86
    name: str = None,
87
    retry: OptionalRetry = DEFAULT,
88
    timeout: Union[float, object] = DEFAULT,
89
    metadata: Sequence[Tuple[str, Union[str, bytes]]] = (),
90
) -> Connection:
91
    """
92
    Returns the specified connection.
93
    
94
    Parameters:
95
    - request: The request object containing the connection name
96
    - name: Required. Name of the connection in format 'projects/{project_id}/locations/{location_id}/connections/{connection_id}'
97
    - retry: Retry configuration for the request
98
    - timeout: Timeout for the request in seconds
99
    - metadata: Additional metadata to send with the request
100
    
101
    Returns:
102
    Connection: The requested connection object
103
    
104
    Raises:
105
    google.api_core.exceptions.NotFound: If the connection does not exist
106
    google.api_core.exceptions.GoogleAPICallError: If the request fails
107
    """
108
```
109

110
**Usage Example:**
111

112
```python
113
# Get a specific connection
114
connection_name = "projects/my-project/locations/us-central1/connections/prod-analytics-db"
115
connection = client.get_connection(name=connection_name)
116

117
print(f"Connection: {connection.friendly_name}")
118
print(f"Created: {connection.creation_time}")
119
print(f"Has credential: {connection.has_credential}")
120
```
121

122
### Listing Connections
123

124
Lists all connections in a given project and location with pagination support.
125

126
```python { .api }
127
def list_connections(
128
    request: ListConnectionsRequest = None,
129
    *,
130
    parent: str = None,
131
    retry: OptionalRetry = DEFAULT,
132
    timeout: Union[float, object] = DEFAULT,
133
    metadata: Sequence[Tuple[str, Union[str, bytes]]] = (),
134
) -> ListConnectionsPager:
135
    """
136
    Returns a list of connections in the given project and location.
137
    
138
    Parameters:
139
    - request: The request object containing parent and pagination parameters
140
    - parent: Required. Parent resource name in format 'projects/{project_id}/locations/{location_id}'
141
    - retry: Retry configuration for the request
142
    - timeout: Timeout for the request in seconds
143
    - metadata: Additional metadata to send with the request
144
    
145
    Returns:
146
    ListConnectionsPager: A pager for iterating through connections
147
    
148
    Raises:
149
    google.api_core.exceptions.GoogleAPICallError: If the request fails
150
    """
151
```
152

153
**Usage Examples:**
154

155
```python
156
# List all connections
157
parent = "projects/my-project/locations/us-central1"
158
connections = client.list_connections(parent=parent)
159

160
# Iterate through all connections
161
for connection in connections:
162
    print(f"Connection: {connection.name}")
163
    print(f"  Name: {connection.friendly_name}")
164
    print(f"  Description: {connection.description}")
165
    if connection.cloud_sql:
166
        print(f"  Type: Cloud SQL ({connection.cloud_sql.database})")
167
    elif connection.aws:
168
        print(f"  Type: AWS")
169
    elif connection.azure:
170
        print(f"  Type: Azure")
171

172
# Iterate through pages manually
173
for page in connections.pages:
174
    print(f"Page with {len(page.connections)} connections")
175
    for connection in page.connections:
176
        print(f"  - {connection.friendly_name}")
177
```
178

179
### Updating Connections
180

181
Updates an existing connection. Use field masks to specify which fields to update.
182

183
```python { .api }
184
def update_connection(
185
    request: UpdateConnectionRequest = None,
186
    *,
187
    connection: Connection = None,
188
    update_mask: FieldMask = None,
189
    retry: OptionalRetry = DEFAULT,
190
    timeout: Union[float, object] = DEFAULT,
191
    metadata: Sequence[Tuple[str, Union[str, bytes]]] = (),
192
) -> Connection:
193
    """
194
    Updates a connection.
195
    
196
    Parameters:
197
    - request: The request object containing update details
198
    - connection: Required. Connection object with updated field values (connection.name specifies which connection to update)
199
    - update_mask: Required. Field mask specifying which fields to update
200
    - retry: Retry configuration for the request
201
    - timeout: Timeout for the request in seconds
202
    - metadata: Additional metadata to send with the request
203
    
204
    Returns:
205
    Connection: The updated connection object
206
    
207
    Raises:
208
    google.api_core.exceptions.NotFound: If the connection does not exist
209
    google.api_core.exceptions.GoogleAPICallError: If the request fails
210
    """
211
```
212

213
**Usage Example:**
214

215
```python
216
from google.protobuf import field_mask_pb2
217

218
# Get the existing connection
219
connection_name = "projects/my-project/locations/us-central1/connections/prod-analytics-db"
220
connection = client.get_connection(name=connection_name)
221

222
# Update the description and friendly name
223
connection.friendly_name = "Production Analytics Database"
224
connection.description = "Updated: Connection to production PostgreSQL for analytics workloads"
225

226
# Create update mask specifying which fields to update
227
update_mask = field_mask_pb2.FieldMask(
228
    paths=["friendly_name", "description"]
229
)
230

231
# Perform the update
232
updated_connection = client.update_connection(
233
    connection=connection,
234
    update_mask=update_mask
235
)
236

237
print(f"Updated connection: {updated_connection.friendly_name}")
238
```
239

240
### Deleting Connections
241

242
Deletes a connection permanently. This operation cannot be undone.
243

244
```python { .api }
245
def delete_connection(
246
    request: DeleteConnectionRequest = None,
247
    *,
248
    name: str = None,
249
    retry: OptionalRetry = DEFAULT,
250
    timeout: Union[float, object] = DEFAULT,
251
    metadata: Sequence[Tuple[str, Union[str, bytes]]] = (),
252
) -> None:
253
    """
254
    Deletes connection and associated credential.
255
    
256
    Parameters:
257
    - request: The request object containing the connection name
258
    - name: Required. Name of the connection to delete in format 'projects/{project_id}/locations/{location_id}/connections/{connection_id}'
259
    - retry: Retry configuration for the request
260
    - timeout: Timeout for the request in seconds
261
    - metadata: Additional metadata to send with the request
262
    
263
    Returns:
264
    None
265
    
266
    Raises:
267
    google.api_core.exceptions.NotFound: If the connection does not exist
268
    google.api_core.exceptions.GoogleAPICallError: If the request fails
269
    """
270
```
271

272
**Usage Example:**
273

274
```python
275
# Delete a connection
276
connection_name = "projects/my-project/locations/us-central1/connections/prod-analytics-db"
277

278
try:
279
    client.delete_connection(name=connection_name)
280
    print(f"Deleted connection: {connection_name}")
281
except Exception as e:
282
    print(f"Failed to delete connection: {e}")
283
```
284

285
## Types
286

287
### Request Types
288

289
```python { .api }
290
class CreateConnectionRequest:
291
    """Request message for creating a connection."""
292
    parent: str  # Required. Parent resource name 'projects/{project_id}/locations/{location_id}'
293
    connection_id: str  # Optional. Connection ID to assign
294
    connection: Connection  # Required. Connection configuration
295

296
class GetConnectionRequest:
297
    """Request message for getting a connection."""
298
    name: str  # Required. Connection resource name
299

300
class ListConnectionsRequest:
301
    """Request message for listing connections."""
302
    parent: str  # Required. Parent resource name 'projects/{project_id}/locations/{location_id}'
303
    page_size: int  # Required. Maximum number of connections to return
304
    page_token: str  # Page token for pagination
305

306
class UpdateConnectionRequest:
307
    """Request message for updating a connection."""
308
    name: str  # Required. Connection resource name
309
    connection: Connection  # Required. Updated connection object
310
    update_mask: field_mask_pb2.FieldMask  # Required. Fields to update
311

312
class DeleteConnectionRequest:
313
    """Request message for deleting a connection."""
314
    name: str  # Required. Connection resource name to delete
315
```
316

317
### Response Types
318

319
```python { .api }
320
class ListConnectionsResponse:
321
    """Response message for listing connections."""
322
    next_page_token: str  # Token for next page of results
323
    connections: MutableSequence[Connection]  # List of connection objects
324
    
325
    @property
326
    def raw_page(self) -> "ListConnectionsResponse":
327
        """Returns the raw page for pagination support."""
328
        return self
329
```
330

331
### Pagination Support
332

333
```python { .api }
334
class ListConnectionsPager:
335
    """Synchronous pager for iterating through list_connections results."""
336
    
337
    def __iter__(self) -> Iterator[Connection]:
338
        """Iterate through individual connections."""
339
        
340
    @property
341
    def pages(self) -> Iterator[ListConnectionsResponse]:
342
        """Iterate through response pages."""
343

344
class ListConnectionsAsyncPager:
345
    """Asynchronous pager for iterating through list_connections results."""
346
    
347
    def __aiter__(self) -> AsyncIterator[Connection]:
348
        """Async iterate through individual connections."""
349
        
350
    @property
351
    def pages(self) -> AsyncIterator[ListConnectionsResponse]:
352
        """Async iterate through response pages."""
353
```