How to Build a Connector from a Template

This tutorial walks you through scaffolding a connector project from a working example, testing it locally, and deploying it to Fivetran.

Prerequisites

Connector SDK installed. See Install Connector SDK.
A destination in your Fivetran account where the connection will deliver data.
A Base64-encoded Fivetran API key to deploy the connector.

Choose a template

Browse the available examples to find one close to your use case:

Quickstart examples: the simplest implementations of the Connector SDK
Common patterns for connectors: sample code to use in your project
Community Connectors: tested and working source connectors contributed by Fivetran and the community

Scaffold your project

Run the fivetran init command:

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

This creates your project directory and copies the necessary project files from the template, such as connector.py, configuration.json, and an optional dependency file, either requirements.txt or pyproject.toml.

If you omit the project path, fivetran init copies the files to your current directory.
If you omit --template, fivetran init copies the template connector files.

After creating the project files, fivetran init checks your PATH for installed AI coding agents. If any of the following are detected, you are prompted to install the Fivetran Connector SDK plugin for your chosen agent:

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

Installing the plugin is optional for this tutorial. We recommend it if you plan to use an AI agent to modify the template. If you choose not to install it during setup, you can install the plugin manually at any time from the Connector SDK Tools repository.

Modify the template (optional)

The template works as-is, so you can skip this step to test and deploy it first. When you're ready to connect to your own data source, edit the template code in your project folder. You can:

Work with your AI agent to modify the template to meet your needs. See Building Connectors with AI.
Edit the code manually, or delete it and write your own. Read our Connector SDK concepts documentation. It covers the core building blocks of connector development, such as authentication, data extraction, schema, state management, pagination, and error handling.

Test your connector

From your project directory, run:

fivetran debug --configuration configuration.json

This creates 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 connector

After your local test succeeds, deploy to Fivetran to create a connection:

fivetran deploy --api-key <BASE_64_ENCODED_API_KEY> --destination <DESTINATION_NAME> --connection <CONNECTION_NAME> --configuration configuration.json

--destination: the name of your destination as it appears on the Destinations page in the Fivetran dashboard.
--connection: the name you want to give this connection in Fivetran. It must start with a lowercase letter or underscore and contain only lowercase letters, numbers, and underscores.

For example:

fivetran deploy --api-key $FIVETRAN_API_KEY --destination production_snowflake --connection my_first_connector --configuration configuration.json

Fivetran pauses new connections by default. To start syncing data, open the connection in the Fivetran dashboard and click Start Initial Sync.

For full deployment options and guidance, see Deploying Connectors.