How to use the BigQuery SQL Migration Translator agent skill

What does this skill make the agent do?

Once installed, the agent knows how to move SQL written for Teradata, Oracle, Redshift, Snowflake, SparkSQL and HiveQL into BigQuery GoogleSQL. It does this by sending queries, DDL schemas or metadata zip archives to Google's BigQuery Migration Service (BQMS) through a remote MCP server, then reading back the translated SQL and its logs.

The skill also tells the agent how to check the result. It looks at error severity, categories and effects in the logs, and it treats some errors (such as ERROR_TYPE markers) as failures even when no log entry explains them. For larger jobs it can run batch translations over many files staged in Cloud Storage and keep a tracker of progress.

• Translate single queries interactively and inspect the output and logs
• Run batch translations of many files staged in Cloud Storage
• Extract and re-insert SQL embedded in Python code using the included template script
• Use example YAML translation configs for renaming, schema redirection and optimizer rules
• Triage translation errors across iterations

What you need before you start

The skill checks several prerequisites before translating. You need a Google Cloud project with an active Cloud Billing account attached, the Google Cloud SDK (gcloud) installed, and the BigQuery Migration API enabled. The translation service and Cloud Storage both incur costs, so the skill points you to Google Cloud Pricing for details.

Your identity or service account also needs the roles roles/mcp.toolUser and roles/bigquerymigration.editor. For batch work, you also need Cloud Storage object roles on the buckets that hold input and output files. The optional bq CLI is useful for dry-run checks.

• Google Cloud SDK (gcloud)
• A Google Cloud project with active Cloud Billing
• BigQuery Migration API (bigquerymigration.googleapis.com) enabled
• IAM roles roles/mcp.toolUser and roles/bigquerymigration.editor
• Cloud Storage object roles for batch work (roles/storage.objectViewer and roles/storage.objectCreator, or roles/storage.objectAdmin)
• Remote BigQuery Migration Service MCP server configured in your agent client
• Optional: bq CLI for dry-run checks

How do you install the skill?

Download the skill as a ZIP file from this page and unzip it. For a personal install, place the unzipped skill folder in ~/.claude/skills/. For a single project, place it in that project's .claude/skills/ folder instead. In the Claude apps, you can instead upload the ZIP under Settings, then Capabilities, then Skills.

After installing, the skill's SKILL.md file is what the agent reads. You do not need to run anything to install it, but the MCP server must be connected before translation tools such as translate_query and translate_batch_queries appear in the agent's tool list. The skill's references/mcp_config.md file covers setup for Claude, Cursor, Gemini CLI and VS Code.

• Personal install: ~/.claude/skills/
• Project install: .claude/skills/ inside your project
• Claude apps: Settings, then Capabilities, then Skills, then upload the ZIP

How do you trigger the skill with a natural request?

You do not need a special command. Describe the task in plain language and name the source system. The skill's description covers translating legacy queries, migrating schemas or metadata zip archives, and configuring BQMS YAML translation settings, so requests like these are a good fit.

• Translate this Teradata query to BigQuery GoogleSQL and show me the YAML you used.
• Convert this Oracle stored procedure to BigQuery and list any errors that remain.
• Migrate this Redshift schema, using metadata.zip in my Cloud Storage bucket for table definitions.
• Translate all the .sql files in this staging folder in one batch and give me the translation report.
• Extract the embedded SQL from this Python service, translate it, and put it back.

Walk through a single query translation

For a single query, the agent calls translate_query with your project number, location, the query text, the source dialect and BigQuery as the target. If the job is still running, it polls get_translation until the state is SUCCEEDED or FAILED. It then reviews the translated_query and each entry in translation_logs.

The skill is strict about one point: it reads the SQL itself, not only the logs. If a dry run stops on a missing table, the skill reports that the SQL is valid and the object simply does not exist in BigQuery yet, rather than inventing stub tables. A single query that translates cleanly on the first attempt needs no tracker; the agent reports the translation ID and logs instead.

• Check translated_query for the converted GoogleSQL
• Review severity (ERROR, WARNING), category and effect (CORRECTNESS, COMPLETENESS, COMPATIBILITY)
• Treat ERROR_TYPE markers and inline error comments as errors
• Treat NoSuchFunction results as untranslated, even if BigQuery has a function with that name

How do batch migrations and embedded SQL work?

Use batch translation when you have more than one file or a directory, or when SQL is embedded in application code. Extract the SQL into .sql files first. For Python codebases, the skill includes assets/python_embedded_sql_migrator_template.py, which extracts queries into staged files and re-injects the translated SQL.

The skill recommends running translate_batch_queries on the staged files first, because batch translation is faster, cheaper and resolves cross-file dependencies. Only use translate_query afterwards to debug a specific statement listed in translation_report.csv. For batch jobs, the skill asks the agent to keep a translation_tracker.md file recording each iteration's status and error counts.

• Batch translation is the default for many files
• translation_report.csv lists statements that need follow-up
• Example YAML configs are in assets/translation_config_examples/
• Keep a translation_tracker.md for multi-file or multi-iteration work

Safety notes: scripts and network access

This skill runs scripts and uses the network. It sends your SQL, schemas and metadata archives to Google's BigQuery Migration Service and can read and write files in Cloud Storage. Review what you send before translating, especially if the SQL contains sensitive table names or data.

When the job is finished, the skill asks the agent to delete temporary staged folders in Cloud Storage with gcloud storage rm -r. Replace the placeholders with your own bucket and folder names, and check the path before running it, because the command deletes everything under it.

• Scripts are included: the Python template and example YAML files
• Network use: translation requests go to Google Cloud
• Clean up staged input and output folders after batch work