Using Windsurf AI IDE to Build a Custom Connector With Fivetran’s Connector SDK

We're going to take a quick look at writing a Fivetran Connector SDK custom connector using Windsurf, an AI IDE (Integrated Development Environment).

We're starting in the Fivetran docs under the Connector SDK examples, where there's a link explaining how to use AI for building connectors. Following that, we land in the Fivetran public GitHub repo and open agents.md, which contains system instructions. This file, along with a template connector.py, becomes our rule set for the AI inside Windsurf.

Purpose summary:

• Build a Fivetran Connector SDK connector using AI (Windsurf)
• Leverage agents.md and template code as AI instruction context

The setup guide lists what we need: a Fivetran API key, Python (version 3.10), and macOS in this case. The demo uses OpenFDA's Tobacco API as a data source, with no API key required.

Context from the FDA docs (authentication rules, example queries, schema) is extracted manually into notes.txt. The API’s searchable fields are copied into a fields.yaml file.

Setup summary:

• Data source: OpenFDA Tobacco API
• Context stored in notes.txt and fields.yaml
• No API keys needed initially (testing phase)

Inside Windsurf Cascade, we add agents.md and the template connector.py as rule sets. These help the AI model maintain structure and logic when responding to prompts. The project folder includes all context: notes, fields, rules, and code templates.

Configuration summary:

• Windsurf Cascade setup uses system rules + project-level files
• Provides AI with best practice framing and schema reference

The prompt is structured in three parts:

1. Data source instructions - Use the endpoint, upsert records, track state by table
2. Constraints - Limit the data scope to 10 records, skip API key, exit gracefully, define only primary key, all config values must be strings
3. Contextual content - best practices, notes, field structure, output paths, use Cascade's SWE-1 model

The goal is to let the AI draft a connector that’s testable with minimal edits.

Prompt strategy summary:

• Three-part structure: task, constraints, context
• Optimized for clarity and minimal iteration

Windsurf responds by generating a build plan:

• Draft connector.py with schema and incremental logic
• Generate requirements.txt, configuration.json, and README.md
• Add logging, comments, and limit API call volume

All files are reviewed in-session and accepted.

Build summary:

• AI generates full connector skeleton with required SDK files
• Comments and DuckDB testing scaffold included

The AI is prompted to test the connector using the fivetran debug command. It generates the command, runs it, and confirms successful upsert of 10 records.

The data is then verified using DuckDB syntax directly within Windsurf by pointing to the generated warehouse.db file.

Testing Summary:

• fivetran debug confirms schema and sync logic
• Output inspected using DuckDB queries inline

After local validation, the AI walks through deploying the connector using the fivetran deploy command. In this step, we provide:

• Deployment destination name
• Connection name (FDA Tobacco Test)
• Configuration path (defaulted from project root)

The model uploads the solution and outputs a link to the connector page in Fivetran.

Deployment Summary:

• Deployment steps automated within chat context
• Human intervention required only for inputs like destination name

We follow the deployment link and trigger the initial sync directly in the Fivetran dashboard.

The final segment recaps the flow:

• Loaded AI system instructions and setup project context
• Constructed a detailed prompt
• Used AI to write and validate all required connector files
• Debugged, reviewed, and tested the connector output
• Deployed and synced the connector

Final summary:

• Full Connector SDK lifecycle executed within Windsurf
• Instruction system powered by agents.md, connector templates, and SDK best practices
• Minimal external tooling required