Bigquery Connection

BigQuery Connection Skill

On Entry

Tell the user:

Setting up BigQuery connection — I'll configure and test a connection to your source Google BigQuery project. I'll need a few connection details.

Prerequisites

• A Google Cloud project with BigQuery enabled and the datasets you want to migrate
• A service account JSON key with read access to the source data and catalog (INFORMATION_SCHEMA)
• The service account granted roles/bigquery.dataViewer, roles/bigquery.jobUser, and roles/bigquery.readSessionUser on the project
• The scai CLI installed and available

Required Connection Details

Service Account Auth (only auth method supported in MVP)

BigQuery has no host or port to configure — the worker reaches the BigQuery API over HTTPS on port 443, and TLS is always enforced by the endpoint. BigQuery is read through the google-cloud-bigquery client (BigQuery Storage Read API), which stages Parquet — there is no ODBC install required on the worker host.

Workflow

Step 1: Ask How to Provide Credentials

Ask the user:

"I need the following to connect to BigQuery:

• GCP project ID
• Service account JSON key file (path)
• Default dataset (optional)
• Location (optional, e.g. US)

How would you like to provide these?"

Options:

1. 1Password — Credentials stored in 1Password vault
2. Enter manually — Provide values directly

Step 2: Route Based on Answer

Step 3: Add the Connection

scai connection add-bigquery \
  -s <CONNECTION_NAME> \
  --auth service-account \
  --project-id <GCP_PROJECT_ID> \
  --dataset <DATASET> \
  --credentials-file <PATH_TO_SERVICE_ACCOUNT_JSON> \
  --location <LOCATION>

• Omit --dataset to scope discovery to the whole project.
• Omit --location unless your datasets live in a specific region and auto-detection fails.

Step 4: Save and Test Source Connection

Call the configure tool with source_connection set to <CONNECTION_NAME>. The MCP server runs scai connection test internally and only persists the connection if the test passes.

• On success: the response includes connection_test: ok.
• On failure: the tool returns an error containing the scai message. Surface it to the user, help them fix the issue, then re-run configure(source_connection=<CONNECTION_NAME>).

Common errors:

CHECKPOINT

Confirm with user:

• configure returned connection_test: ok
• Connection appears in scai connection list -l bigquery --json
• Source connection saved to session config

On Completion

After the CHECKPOINT passes, tell the user:

Connection configured — Successfully connected to BigQuery using connection <connection_name>.

Then return to the calling skill.

Security Rules

• NEVER log or display secrets (service account keys) in plain text.
• NEVER include secrets in command-line arguments that might be logged. Prefer a credential manager (e.g. 1Password op run, or use /secrets capability from Cortex Code to store them). Pass the key as a file path, not inline JSON.

Quick Reference