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.

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

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 data source

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.

Plan your connector

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.

Build custom connector

We recommend starting with our example code, especially if it's your first time working with the Connector SDK. To start from example code, browse our quickstart and common pattern examples or explore Community Connectors for custom connector implementations. Common entry points include:

• Quickstart examples - simplest implementations of the Fivetran Connector SDK
• Common patterns for connectors - sample code to use in your project
• Community Connectors - tested and working source connectors contributed by Fivetran team and Community members
  If this is your first time working with the Connector SDK, try one of the Quickstart examples before writing your custom connector. It will help you get familiar with the Connector SDK.

1. Run the fivetran init command to set up your connector project structure by creating a new project directory and copying the files required for the chosen example connector, such as connector.py, any additional Python files, configuration.json, and, an optional dependency file (requirements.txt or pyproject.toml). After creating the project files, fivetran init automatically detects any installed AI coding agents and offers to install the Fivetran Connector SDK plugin for your chosen agent.

   • You can provide the path and name of the project folder (for example, fivetran init ./my-new-connector-project) and provide the path to the code example you selected by using the --template parameter (for example, fivetran init --template examples/quickstart/hello).
   • If you don't provide a project path, we copy the files to the folder you are in when you run fivetran init.
   • If you don't provide a path to your selected code example, the command copies our template connector files to the project folder.

2. After project files are created, fivetran init checks your PATH for installed AI coding agents. If any of the following are detected, you are prompted to choose which one to install the Fivetran Connector SDK plugin for:

   • Claude code (claude)
   • Codex CLI (codex)
   • Gemini CLI (gemini)
   • GitHub Copilot CLI (copilot)

3. Build your connector based on the chosen template code in the project folder. You can do either of the following:

   • Work with your AI agent of choice to modify the template connector to meet your needs. You may find our How to Build a Connector SDK Connector video tutorials useful to learn more about this process.
   • Modify the code or delete the code and write your own to meet your needs.

Either way, your connector.py must include:

• The operations to send data to Fivetran
• An initialization of the connector object
• The required imports

You can organize your connector logic into multiple files as long as they are located in your project directory and called from connector.py. If you need additional libraries, install them with pip and list them in requirements.txt or pyproject.toml.

However you organize your project directory, follow these best practices to maintain a lean, secure project structure:

• Include only essential files: Unnecessary files in the project folder can slow deployments.
• Do not hardcode credentials: Store sensitive information in environment variables or external config files.
• Ignore config files in version control: If you use a file like configuration.json, add it to .gitignore to prevent exposing credentials.

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>

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)

This test creates a local warehouse.db file in <project_directory>/files/warehouse.db. This file is a DuckDB instance that mimics the data the connection delivers to your destination.

Apr 11, 2025 01:28:06 PM: INFO ⚡ debugger: SYNC PROGRESS:

Operation     | Calls
------------- + ------------
Upserts       | 44
Updates       | 0
Deletes       | 0
Truncates     | 0
SchemaChanges | 1
Checkpoints   | 1

Apr 11, 2025 01:28:06 PM: INFO ⚡ debugger: Sync SUCCEEDED

2. Inspect the DuckDB output. Use DBeaver or the DuckDB CLI to connect to warehouse.db and verify the data the Fivetran Local Tester wrote during the sync.

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.

1. 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.

   Add system key

   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 account has only one destination, this parameter is optional.

   • 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.

2. 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.

   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
   

Redeploy a connector

To update an existing Connector SDK connection, redeploy it by running the fivetran deploy command using your existing connection name and destination name.

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:

1. Click the connection URL.
2. In the browser, open the connection details page.
3. 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

1. Go to your Fivetran dashboard and click Connections.
2. Find and select your newly created Connector SDK connection. Its name is what you passed as the <FIVETRAN_CONNECTION_NAME> in the deploy command.
3. 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

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

2. 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)  
   

3. 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.

Related articles

Connector Overview

Documentation Home