Connector SDK Getting Started Guide

Follow our getting started guide to set up the Connector SDK locally, start building your custom data connectors, and deploy them to Fivetran.

Fast-track your Connector SDK deployment with up to 60 days of free expert technical support.

Our Professional Services team is ready to help you write, troubleshoot, and deploy your connections in record time. Get your project live faster by filing a support ticket today.

Save me time

Prerequisites

To write and deploy a custom connector using Connector SDK, you need:

A Fivetran account
A Python virtual environment with one of the supported Python versions
An operating system supported by the Connector SDK

If you're new to Python and running terminal commands, see our Complete Walkthrough, which will guide you every step of the way while you're building your own custom Fivetran connector.

Also, see our Connector SDK tutorials section for step-by-step instructions in written and video format.

Install Connector SDK

Install Connector SDK by running the following command:

pip install fivetran-connector-sdk

For more in depth information, including how to set up a Python virtual environment, see How to Install Connector SDK.

To learn how to work with the SDK's CLI, see our Connector SDK CLI Commands documentation.

Identify a source and plan your connector

We offer Community Connectors, which are free and ready to use, and quickstart examples, which are minimal working implementations of the Connector SDK. You can skip this step and adapt either to your needs.

Before you begin, decide which data source you want your connector to pull data from. For example:

A REST API (public or private) using a Python HTTP library (for example, requests)
A database like PostgreSQL, MySQL, or MongoDB, using official or community Python drivers
A file-based source (for example, CSV, Excel, JSON) using built-in or third-party libraries

Your custom connector must rely on Python to fetch and parse the source data. Confirm you can retrieve data with Python first, so you're not blocked later by missing drivers or libraries.

Consider the most important aspects of building custom connectors. To help you in that process, see the diagram below and read through our connector development concepts documentation.

React Flow

Build your connector

Choose how you want to build:

Build with AI

Use an AI coding agent to build, test, evaluate, and deploy your connector using natural language prompts. Fivetran offers plugins for Claude Code, Codex CLI, Gemini CLI, and GitHub Copilot that provide the skills to do this end to end. For more information, see Building Connectors with AI and our AI tutorials.

You can use the AI agent to complete the Test your custom connector and Deploy your custom connector steps, so you can skip them.

Build from a template

Fivetran provides quickstart examples and Community Connectors as starting points. Use fivetran init to scaffold a project using any of these as a template:

fivetran init ./my-connector --template examples/quickstart/hello

For a full walkthrough, see our Build from a Template tutorial.

You can use our AI plugin with your coding agent to adapt the template to your use case.

Build from scratch

Write your own connector code from the ground up, defining your own data extraction logic, authentication, state management, and schema without starting from a template.

For a complete end-to-end walkthrough, see Complete Walkthrough: Building and Deploying Your First Custom Connector.

You can use our AI plugin with your coding agent to get assistance writing your connector logic.

Test your custom connector

Option 1: In the terminal, navigate to the directory containing your connector.py file and run:

fivetran debug --configuration <PATH_TO_CONFIGURATION_JSON>

Configuration is required. If configuration.json is in your project folder, the CLI detects it automatically, and you can omit the --configuration flag. If your connector does not use configuration, pass an empty configuration.json file. For more information, see Working with configuration.json.

Option 2: If you prefer to run debug from your IDE, include the following snippet in connector.py:

if __name__ == "__main__":
 # Open the configuration.json file and load its contents into a dictionary.
 with open("configuration.json", "r") as f:
     configuration = json.load(f)
 # Adding this code to your `connector.py` allows you to test your connector by running your file directly from your IDE.
 connector.debug(configuration=configuration)

Both options create a local warehouse.db file at <project_directory>/files/warehouse.db, a DuckDB instance that mimics the data the connection delivers to your destination. Use DBeaver or the DuckDB CLI to inspect the output and verify the data. For more information, see Local Testing.

Deploy your custom connector

After you're satisfied with your connector.py and the local test output, create a connection by deploying the code to Fivetran.

Gather the information you need to specify in the fivetran deploy command. You need the following parameters:
Fivetran API key
- Your <BASE_64_ENCODED_API_KEY> is a base64-encoded string in the format {API-key}:{API-secret}.
- See our scoped API key documentation or system API key documentation for guidance on obtaining a key.
- Use environment variables to avoid typing your API key for every command.
If you are a Fivetran Account Administrator, click the button to create a system key with the minimal permissions required to deploy, edit, and delete your Connector SDK connection.
Destination name
- <DESTINATION_NAME> identifies the destination where data will be delivered. Use the name that appears on your Fivetran dashboard on the Destinations page.
- If your destination is configured for Hybrid Deployment, your connection will use the hybrid deployment agent configured for that destination. If you want to use a different agent, specify the optional parameter, --hybrid-deployment-agent-id <NON_DEFAULT_HYBRID_DEPLOYMENT_AGENT_ID>. Get your Agent ID using the Fivetran REST API or find it in the Fivetran dashboard under Settings > General > Hybrid Deployment Agents.
  Expand to see detailed instructions to find your destination name
  1. From the Fivetran dashboard, go to Destinations.
  2. In the Name column, find the name of the destination you want to sync to and make a note of it.
  To learn more and see an example of a destinations page with multiple destinations, go to Fivetran dashboard documentation about the destinations page.
Connection name
- <CONNECTION_NAME> is the name you define for this connection. This name will appear in your Fivetran dashboard. To see an example, go to View connections in our dashboard documentation.
- The connection name must follow the Fivetran naming conventions:
  - Begin with _ or a lowercase letter (a-z).
  - Only use _, lowercase letters, or digits (0-9) after the first character.
  - Uppercase letters are not allowed.
- If the name doesn't meet these criteria, the connection will fail to deploy.
Run the deployment command.
From your project's root directory, run the following command, replacing each placeholder with your actual values:
```
fivetran deploy --api-key <BASE_64_ENCODED_API_KEY> --destination <DESTINATION_NAME> --connection <CONNECTION_NAME> --configuration <PATH_TO_CONFIGURATION_JSON>
```
Configuration is required. If your connector does not use configuration, pass an empty configuration.json file. For more information, see Working with configuration.json.
If you already set FIVETRAN_API_KEY, FIVETRAN_DESTINATION_NAME, and FIVETRAN_CONNECTION_NAME, you can use:
```
fivetran deploy
```
Expand to see an example with actual values

If your API key is dlkh34o8==, your destination name is Testing, and your connector name is my_first_connector, your command would be:
```
fivetran deploy --api-key dlkh34o8== --destination Testing --connection my_first_connector --configuration configuration.json
```

Deploying the same connector SDK code multiple times using different connection names and configurations can be very useful for maintaining a dedicated test connector and a separate one for production.

Start syncing data

Your newly built connection is paused by default. To begin syncing data, unpause it using any of the following methods:

Option 1: Through your terminal (clickable link)

If your terminal displays a clickable link after deployment:

Click the connection URL.
In the browser, open the connection details page.
On the connection details page, switch the toggle in the top right corner from Unpaused to Enabled to start the initial sync.

Option 2: In your Fivetran dashboard

Go to your Fivetran dashboard and click Connections.
Find and select your newly created Connector SDK connection. Its name is what you passed as the <FIVETRAN_CONNECTION_NAME> in the deploy command.
On the connection details page, do any of the following to start syncing:
- Click Start Initial Sync.
- Toggle from Unpaused to Enabled.
- Click Sync Now.

Option 3: Using the Fivetran REST API

In your terminal or in the built-in terminal in your IDE, find the log generated after you ran the deploy command.

Find your connection ID in the deploy log. Look for Fivetran-Connector-SDK: Connection ID: <my_connection_id>.

Expand to see an example deploy log

In this example deploy log, the connection ID is supplementary_unacquainted.

Apr 21, 2025 01:39:04 PM INFO Fivetran-Connector-SDK: Deploying '/Users/janedoe/projects/myenv' to connection 'my_connector_sdk_connector' in destination 'Testing'.\n  
Apr 21, 2025 01:39:04 PM INFO Fivetran-Connector-SDK: Packaging your project for upload...  
Apr 21, 2025 01:39:04 PM INFO Fivetran-Connector-SDK: Uploading your project...  
Apr 21, 2025 01:39:19 PM INFO Fivetran-Connector-SDK: The connection 'my_first_connector' has been created successfully.\n  
Apr 21, 2025 01:39:19 PM INFO Fivetran-Connector-SDK: Python Version: 3.13.7  
Apr 21, 2025 01:39:19 PM INFO Fivetran-Connector-SDK: Connection ID: supplementary_unacquainted 
Apr 21, 2025 01:39:19 PM INFO Fivetran-Connector-SDK: Visit the Fivetran dashboard to start the initial sync: [https://fivetran.com/dashboard/connections/supplementary_unacquainted/status](https://fivetran.com/dashboard/connections/supplementary_unacquainted/status)

Unpause the connection by sending a request to the Update a Connection endpoint with your connection ID.

After your connection is unpaused, Fivetran will begin syncing data from your source to your selected destination.

Connector Overview

Documentation Home