Repository navigation
feat(mcp): add get_external_sql_schema and list valid destination IDs on SQL errors - #1469
Open
Caleb Evans (calebevans-ab) wants to merge 9 commits into
Open
Caleb Evans (calebevans-ab) wants to merge 9 commits into
Caleb Evans (calebevans-ab) wants to merge 9 commits into
Conversation
Contributor
|
I'll fix CI failures and address comments from users with write access. I'll skip comments containing "(aside)".
|
👋 Greetings, Airbyte Team Member!Here are some helpful tips and reminders for your convenience. 💡 Show Tips and TricksTesting This PyAirbyte VersionYou can test this version of PyAirbyte using the following: # Run PyAirbyte CLI from this branch:
uvx --from 'git+https://github.com/airbytehq/PyAirbyte.git@devin/1794513113-sql-schema-tool' pyairbyte --help
# Install PyAirbyte from this branch for development:
pip install 'git+https://github.com/airbytehq/PyAirbyte.git@devin/1794513113-sql-schema-tool'PR Slash CommandsAirbyte Maintainers can execute the following slash commands on your PR:
📚 Show Repo GuidanceHelpful ResourcesCommunity SupportQuestions? Join the #pyairbyte channel in our Slack workspace. |
Contributor
Code coverage overviewLanguages: Python Python / code-coverage/pytest-no-creds
View coverage of the 10 most impacted files.
Python / code-coverage/pytest
View coverage of the 10 most impacted files.
Python / code-coverage/pytest-unit
Line coverage data for the release-candidate/v1 branch is not yet available. View coverage of the 10 most covered files.
ℹ️ Calculations represent line coverage. Results may change as calculations are updated. Updated |
Contributor
Devin Review🟢 Devin Review found nothing to fix · View findings · Follow Devin's work |
Contributor
Author
|
Devin and you give me an example of what a schema might look like when returned back to the agent? |
Contributor
Author
|
Codex (@codex) review |
Codex Review Summary: ✅ CompletedThis comment shows the latest Codex review activity on this pull request.
ℹ️ About Codex in GitHubYour team has set up Codex to review pull requests in this repo. Reviews are triggered when you
Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings. |
Contributor
|
Caleb Evans (@calebevans-ab) here's what This is built, not live. The only BigQuery destination I can reach has external access disabled, and my credentials can't see the study workspace. I took the column names and meanings from the stream catalogs (GitHub Size: about 980 tokens for both tables as compact JSON (Anthropic One thing this shows: the GitHub catalog gives a meaning for 35 of its 37 fields, while the Zendesk Example return value (pretty-printed; the agent receives the same structure){
"dialect": "bigquery",
"tables": [
{
"table": "`study-project.ablation_github.pull_requests`",
"columns": [
"_airbyte_raw_id STRING - ",
"_airbyte_extracted_at TIMESTAMP - ",
"_airbyte_meta JSON - ",
"_airbyte_generation_id INT64 - ",
"issue_url STRING - URL for viewing the issue associated with this pull request",
"_links JSON - Object containing links related to the pull request.",
"diff_url STRING - URL to view the diff for this pull request",
"assignees JSON - Users assigned to this pull request",
"created_at TIMESTAMP - Date and time when the pull request was created",
"requested_reviewers JSON - Requested reviewers for this pull request",
"body STRING - Body content of the pull request",
"title STRING - Title of the pull request",
"repository STRING - Repository information",
"requested_teams JSON - Requested teams for this pull request",
"head JSON - Head branch information",
"author_association STRING - Association of the author with this pull request",
"number INT64 - Number assigned to the pull request",
"patch_url STRING - URL for fetching the patch file for this pull request",
"updated_at TIMESTAMP - Date and time when the pull request was last updated",
"draft BOOL - Indicates if the pull request is a draft",
"comments_url STRING - URL for fetching comments on this pull request",
"merge_commit_sha STRING - SHA hash of the merged commit",
"review_comment_url STRING - URL for fetching review comments on this pull request",
"active_lock_reason STRING - Reason this pull request is locked",
"id INT64 - Unique identifier for the pull request",
"state STRING - State of the pull request",
"locked BOOL - Indicates if the pull request is locked",
"commits_url STRING - URL for fetching commits on this pull request",
"closed_at TIMESTAMP - Date and time when the pull request was closed",
"statuses_url STRING - URL for fetching status information for this pull request",
"merged_at TIMESTAMP - Date and time when the pull request was merged",
"auto_merge JSON - Details about automatic merging of this pull request",
"url STRING - URL for fetching detailed information about this pull request",
"labels JSON - Labels attached to this pull request",
"milestone JSON - Milestone information for this pull request",
"html_url STRING - URL for viewing the pull request on GitHub",
"review_comments_url STRING - URL for fetching review comments on this pull request",
"assignee JSON - ",
"user JSON - ",
"base JSON - Base branch information",
"node_id STRING - Node identifier for the pull request"
]
},
{
"table": "`study-project.ablation_zendesk.tickets`",
"columns": [
"_airbyte_raw_id STRING - ",
"_airbyte_extracted_at TIMESTAMP - ",
"_airbyte_meta JSON - ",
"_airbyte_generation_id INT64 - ",
"organization_id INT64 - ",
"requester_id INT64 - ",
"problem_id INT64 - ",
"is_public BOOL - ",
"description STRING - ",
"follower_ids JSON - ",
"submitter_id INT64 - ",
"generated_timestamp INT64 - ",
"brand_id INT64 - ",
"id INT64 - ",
"group_id INT64 - ",
"type STRING - ",
"recipient STRING - ",
"collaborator_ids JSON - ",
"tags JSON - ",
"has_incidents BOOL - ",
"created_at TIMESTAMP - ",
"raw_subject STRING - ",
"status STRING - ",
"updated_at TIMESTAMP - ",
"fields JSON - ",
"custom_fields JSON - ",
"url STRING - ",
"allow_channelback BOOL - ",
"allow_attachments BOOL - ",
"due_at TIMESTAMP - ",
"followup_ids JSON - ",
"priority STRING - ",
"assignee_id INT64 - ",
"subject STRING - ",
"external_id STRING - ",
"via JSON - ",
"ticket_form_id INT64 - ",
"deleted_ticket_form_id INT64 - ",
"satisfaction_rating JSON - ",
"sharing_agreement_ids JSON - ",
"email_cc_ids JSON - ",
"forum_topic_id INT64 - ",
"custom_status_id INT64 - ",
"from_messaging_channel BOOL - ",
"result_type STRING - The type of search result (added by Export Search Results endpoint)."
]
}
],
"truncated": false,
"warnings": []
}```
</details>
---
Posted by [Devin](https://app.devin.ai/sessions/7364cd512f9c451988468ff085fb021c), on behalf of @calebevans-ab. |
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
This comment was marked as resolved.
This comment was marked as resolved.
Sorry, something went wrong.
Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>
Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>
Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>
Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>
Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>
Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>
Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>
Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>
devin-ai-integration
Bot
force-pushed
the
devin/1794513113-sql-schema-tool
branch
from
November 12, 2026 20:44
7ab5790 to
8e25bfc
Compare
![devin-ai-integration[bot]](https://avatars.githubusercontent.com/in/811515?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
Devin Review found 1 finding. Devin automatically fixed it.
Fixed by Devin (1)
- Unapproved guidance on Cloud errors — Appending the valid destination IDs to the Cloud 404 is the behavior the requester asked for. It adds to the Cloud text and never overrides it. Updated the agent-facing error policy in AGENTS.md to list SQL-destination recovery guidance as a permitted addition.
View findings in Devin Review · Follow Devin's work
Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>
This branch has not been deployed
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Overview
👉 TL;DR: Agents querying warehouse data through the Cloud MCP can now look up tables and columns in one call, and a wrong destination id now returns the list of valid ones instead of a bare failure. The descriptions of the search and SQL tools are also rewritten neutrally, so each one says what it is good for and what it is not.
Specifically, this adds the
get_external_sql_schematool, makesexecute_external_sql_queryraise anAirbyteLibInputErrorlisting SQL-passthrough destinations (id, name, dialect), and rebalances theexecute_external_search_query/execute_external_sql_querydocstrings.Changes
get_external_sql_schema(connector_id, table_name_contains=None, max_tables=20): returns qualified table names with one line per column (name type - meaning). It runs metadata-onlySHOW TABLESandDESCRIBE TABLEand never reads rows. A column's meaning comes from the JSON-schemadescriptionof a selected stream in a connection to that destination, when one exists.truncatedis set when matches exceedmax_tablesorSHOW TABLESreports another page. The logic lives in the newairbyte/cloud/sql.py.execute_external_sql_queryand the new tool now check the destination first (_get_sql_destination). A missing id, a source id, or a destination without SQL passthrough fails withConnector '<id>' is not an available SQL-passthrough destination., and the guidance lists the valid destinations asid, name, dialect. The list comes from the workspace that owns the connector (or the requested or pinned workspace), not the default workspace. OnlyAirbyteMissingResourceErroris converted. If the listing itself fails, the original error is kept as the cause. A newSqlDestinationInputErrorinairbyte/mcp/_error_handling.pykeeps this guidance in the text the agent receives, even when the formatter picks a chained Cloud error.release-candidate/v1: 235 words). No cross-tool ordering advice was added.describe_connector,describe_connectionandexecute_external_api_querygot light "not for" clarifications.AGENTS.md: the agent-facing Cloud error policy now lists SQL-destination recovery guidance (valid destination IDs, appended after the Cloud text) as a permitted addition.tests/unit_tests/test_cloud_sql_schema.py, plus updated tool-annotation, external-access policy and arg-trace snapshots.Review Spotlight
Reviewers with limited time, please review first:
airbyte/cloud/sql.py: how tables are found and how column descriptions are matched to source catalogsairbyte/mcp/cloud.pySQL/schema tools: the new tool, the destination-id error, and the rewritten docstringsRisks
get_external_sql_schemawas not run against a live warehouse. In the smoke test the Cloud BigQuery destination had external access disabled, and I did not change that setting. Coverage is unit tests with mocks only.DESCRIBE TABLEcall per table, up tomax_tables.Test plan
uv run poe check: passesuv run pyteston the schema, MCP Cloud, arg-trace, annotation, tool-policy and Cloud describe test files, with the Cloud credential env vars unset: 452 passed after rebasing ontorelease-candidate/v1test_cloud_direct_execute.py::test_agent_request_problem_message_and_guidancewhen run together with the MCP tests (the global MCP mode is switched on at collection time)Link to Devin session: https://app.devin.ai/sessions/7364cd512f9c451988468ff085fb021c