Managing Connector Packages Private Preview

A Connector SDK package is a reusable connector that you can deploy to multiple connections in your Fivetran account. This guide covers how to configure your package using pyproject.toml and manage it with the Fivetran CLI.

pyproject.toml configuration

The pyproject.toml file in your connector project defines package metadata. The following sections and options are available:

[project] section

The [project] section contains standard Python project metadata:

Setting	Description	Default
`name`	Package name displayed in the Fivetran dashboard when you browse and search for connectors. For more information, see Package name requirements.	The package ID we generate
`version`	Optional Python project version metadata. Use a PEP 440-compatible value, for example `0.1.0`.	Not required by Connector SDK
`description`	A brief description of what your connector does.	Optional
`dependencies`	Python dependencies required by your connector. List each dependency as a string with optional version constraints.	Empty list

Example:

[project]
name = "MyCustomConnector"
version = "0.1.0"
description = "My custom Connector SDK connector that syncs data from my API."
dependencies = [
   "tenacity==9.1.4",
]

[tool.package-metadata] section

The [tool.package-metadata] section contains Fivetran-specific package configuration:

Setting	Description	Default
`visible`	Set to `true` to make the package available in the Fivetran dashboard for creating connections. When `true`, your package must implement a custom `configuration_form()`.	`false`
`python_version`	Optional. The Python version that the setup form pre-fills when it first loads for connections created from this package. Values the customer changes in the setup form take precedence. Specify it as a quoted string, for example `"3.12"`. Fivetran fails the CLI, if it isn't a recognized, supported Python version. The currently supported versions are `3.10`, `3.11`, `3.12`, `3.13`, and `3.14`.	The default Python version, `3.14`
`proxy_host_config_key`	Optional. For connections that use a proxy agent, the name of the configuration field that holds the host. The setup form pre-fills it on first load for new connections. Values the customer changes in the setup form take precedence.	The `host` or `hosts` field, if your setup form defines one

Example:

[tool.package-metadata]
visible = true
python_version = "3.12"
proxy_host_config_key = "api_host"

Package name requirements

The package name must meet the following requirements:

Contains only ASCII letters, digits, periods (.), underscores (_), and hyphens (-). Spaces and other special characters aren't allowed.
Starts and ends with an ASCII letter or digit.
Contains at least 3 characters.
Is unique within your account. You can't have two packages with the same name in one account.

If the name is missing, Fivetran uses the generated package ID as the package name. If the name is present but invalid, the fivetran package create and fivetran package update commands display a fails.

Duplicate package names aren't allowed within a single account. If the package name is already used by another package in your account, the fivetran package create or fivetran package update command fails. Choose a different name and run the command again.

Working with deployment packages

Use the Fivetran CLI to manage deployment packages.

Create a package

Run the following command from your project directory:

fivetran package create --api-key <BASE_64_ENCODED_API_KEY>

Fivetran reads your pyproject.toml file and creates a package with the specified configuration.

If you set visible = true but your package doesn't include a custom setup form, the command fails with the following error:

Visible packages must implement configuration_form().

Ensure that your connector implements the configuration_form() method before setting visible = true.

Update a package

Run the following command to update an existing package:

fivetran package update <package-id> --api-key <BASE_64_ENCODED_API_KEY>

Fivetran reads your updated pyproject.toml file and updates the package metadata and code. Every connection that uses the package picks up the new code on its next sync. Changes to the python_version and proxy_host_config_key setup-form defaults apply to new connections only; existing connections keep their saved settings.

List packages

To see all your packages, their names, and visibility status, run:

fivetran package list --api-key <BASE_64_ENCODED_API_KEY>

The output includes the following columns:

Column	Description
`PACKAGE ID`	The ID that Fivetran generates for the package.
`PACKAGE NAME`	The package name. If the package has missing name, this column shows the package ID.
`VISIBLE`	`true` if the package is available in the dashboard for creating connections, otherwise `false`.
`CONNECTIONS`	The number of connections that use the package.

The PACKAGE NAME and VISIBLE columns appear only if setup-form connection creation is enabled for your account. Otherwise, the output shows only PACKAGE ID and CONNECTIONS.

Managing package visibility

Making a package visible

To make a package available for creating connections in the Fivetran dashboard:

Ensure your connector implements the configuration_form() method.
Set visible = true in the [tool.package-metadata] section of your pyproject.toml file.
Run fivetran package update <package-id> --api-key <BASE_64_ENCODED_API_KEY>.

Your package appears in the dashboard under Browse our connectors with the Connector SDK logo and a Connector SDK label.

Hiding a package

To prevent users from creating new connections for a package in the dashboard:

Set visible = false in the [tool.package-metadata] section of your pyproject.toml file.
Run fivetran package update <package-id> --api-key <BASE_64_ENCODED_API_KEY>.

Existing connections continue to run and sync. Only the creation of new connections through the setup form is affected.

Limitations

Only packages in your account are available. You can't share a package across accounts.
Creating a visible package fails unless it implements configuration_form().
Redeploying a connection that uses a visible package requires a new package ID. Run fivetran deploy --package-id <new-package-id>.

Next steps

Create a Connection from the Dashboard - Learn how to use visible packages to create connections through the setup form.
Reusable Connectors - Learn more about creating and managing reusable connectors.