Google Cloud BigQuery Connection Client Library

1.21.0 · active · verified Wed Apr 15

The Google Cloud BigQuery Connection API client library (google-cloud-bigquery-connection) is a Python library designed to manage BigQuery connections to external data sources. It provides a programmatic interface for creating, updating, listing, and deleting connections, which are crucial for BigQuery to interact with other Google Cloud services (like Cloud Spanner, Cloud SQL) or external databases. As of April 2026, the current stable version is 1.21.0, and it is actively maintained with regular updates as part of the broader `google-cloud-python` ecosystem.

Warnings

breaking The library officially supports Python 3.9 and newer. Older Python versions (3.8 and below) are not supported, and new major versions of Google Cloud client libraries often drop support for end-of-life Python versions.
Fix: Upgrade your Python environment to 3.9 or a newer supported version.
gotcha Authentication is a common hurdle. Ensure your environment is correctly set up for Google Cloud authentication (e.g., `GOOGLE_APPLICATION_CREDENTIALS` environment variable pointing to a service account key file, or running in a Google Cloud environment with appropriate service account permissions).
Fix: Refer to Google Cloud authentication documentation. Ensure the service account used has necessary roles like 'BigQuery Connection User' and 'BigQuery Connection Admin'.
gotcha Many BigQuery Connection API methods (like `list_connections`) require `project_id` and `location` parameters, often combined into a 'parent' resource path (e.g., `projects/{project}/locations/{location}`). Incorrectly formatted resource paths will result in API errors.
Fix: Always construct resource paths carefully following the API's expected format, as specified in the method's documentation.
gotcha The BigQuery Connection API must be explicitly enabled in your Google Cloud Project. If not enabled, API calls will result in 'API not enabled' or similar permission errors.
Fix: Enable the 'BigQuery Connection API' via the Google Cloud Console or `gcloud services enable bigqueryconnection.googleapis.com`.
gotcha In the broader Google Cloud client ecosystem, version incompatibilities can occur between `google-api-core` and specific `google-cloud-*` client libraries. For instance, `google-api-core==1.34.0` caused issues with older `google-cloud-bigquery` versions.
Fix: If encountering unexpected errors, try pinning `google-api-core` to a slightly older version (e.g., `pip install google-api-core==1.33.2`) or ensure all `google-cloud-*` libraries are updated to their latest versions.

Install

pip install google-cloud-bigquery-connection Install stable version

Imports

BigQueryConnectionServiceClient
wrong:
```
from google.cloud.bigquery_connection import BigQueryConnectionServiceClient
```
correct:
```
from google.cloud.bigquery_connection_v1 import BigQueryConnectionServiceClient
```
The client classes for versioned APIs are typically found under a `_v1` (or `_vX`) submodule for explicit API versioning.

Quickstart

This quickstart demonstrates how to instantiate the BigQuery Connection client and list existing connections within a specified Google Cloud project and location. Authentication is typically handled automatically via Application Default Credentials (ADC) or the `GOOGLE_APPLICATION_CREDENTIALS` environment variable.

import os
from google.cloud import bigquery_connection_v1

# It is highly recommended to set the GOOGLE_APPLICATION_CREDENTIALS environment variable
# to the path of your service account key file for authentication.
# For example (Linux/macOS): export GOOGLE_APPLICATION_CREDENTIALS="/path/to/keyfile.json"
# Or set programmatically, but generally discouraged for production:
# os.environ["GOOGLE_APPLICATION_CREDENTIALS"] = "/path/to/keyfile.json"

def list_bigquery_connections(project_id: str, location: str):
    """Lists all BigQuery connections in a given project and location."""
    client = bigquery_connection_v1.BigQueryConnectionServiceClient()
    # The parent resource for connections is formatted as 'projects/{project}/locations/{location}'
    parent = f"projects/{project_id}/locations/{location}"

    print(f"Listing connections in project '{project_id}' at location '{location}':")
    try:
        # API call to list connections
        for connection in client.list_connections(parent=parent):
            print(f"  Connection Name: {connection.name}")
            print(f"    Connection Type: {connection.cloud_resource.connection_type.name}")
            print(f"    Description: {connection.friendly_name or 'N/A'}")
            # You can access other connection properties like `cloud_sql` or `aws` here
    except Exception as e:
        print(f"Error listing connections: {e}")
        print("Please ensure the BigQuery Connection API is enabled for your project ")
        print("and the service account has the 'BigQuery Connection User' role or equivalent permissions.")

# Replace with your actual project ID and desired location
# It's best practice to get project_id from the environment or Google Cloud metadata.
PROJECT_ID = os.environ.get("GOOGLE_CLOUD_PROJECT", "your-gcp-project-id")
LOCATION = "us"  # Example: "us", "eu", "asia-east1"

if PROJECT_ID == "your-gcp-project-id":
    print("WARNING: Please set the 'GOOGLE_CLOUD_PROJECT' environment variable ")
    print("         or replace 'your-gcp-project-id' with your actual project ID.")
    print("         Authentication and API calls will likely fail without proper setup.")
else:
    list_bigquery_connections(PROJECT_ID, LOCATION)

view raw JSON →