Using Environment Variables With the Connector SDK

This guide explains how to manage environment variables when working with custom Fivetran connectors and the Connector SDK. Environment variables act as configuration shortcuts - settings provided by your operating system that influence how programs behave.

In the context of the Connector SDK, environment variables let you reuse common values like API keys, destination names, and configuration files, without having to manually input them every time.

Why use environment variables?

You can use environment variables to simplify CLI commands. For example:

fivetran deploy --api-key $FIVETRAN_API_KEY --destination $FIVETRAN_DESTINATION_NAME --connection sdk_video_testing --configuration configuration.json

In this example, $FIVETRAN_API_KEY and $FIVETRAN_DESTINATION_NAME are environment variables that replace hardcoded values.

You can also use variables in the interactive fivetran deploy command:

fivetran deploy 
Provide the destination name (as displayed in your dashboard): $MY_DESTINATION_NAME
Provide the connection name: sdk_video_testing
Provide your API Key (Base64 Encoded) [Default: c1lQNXdh********]:
Does this run/deploy need configuration (y/N): y  
Provide the configuration file path [Default: configuration.json]: ../config.json

Environment variable types

There are two types of environment variables:

Temporary environment variables are key-value pairs that exist only for the duration of your current terminal session (i.e., until you close the terminal window or restart your shell). They're stored in the shell's memory and not written to any permanent config file. They are useful for testing or short-term work.
Permanent environment variables are automatically set every time you open a new terminal session. Unlike temporary variables, they persist because they’re saved in a shell configuration file, like:
- ~/.bash_profile (for Bash)
- ~/.zshrc (for Zsh)
- ~/.profile (in some systems)

Permanent environment variables are particularly useful for your FIVETRAN_API_KEY.

How to configure environment variables

The sections below explain how to create temporary and permanent environment variables in macOS, Linux, and Windows.

See our Working with Connector SDK documentation for a full list of environment variables supported by Connector SDK.

How to set up temporary (session-only) variables

Temporary variables will disappear once you close the terminal.

Expand to see instructions for macOS and Linux

To configure temporary variables on macOS or Linux, use the export command. Here are common examples when working with the Connector SDK:

The command below sets your unique secret key, which allows the Connector SDK to connect securely to your Fivetran account.
```
export FIVETRAN_API_KEY=<your-api-key>
```
The following command sets your destination, which determines where the Connector SDK writes data:
```
export FIVETRAN_DESTINATION_NAME=<your-destination-name>
```
The command below specifies your Connector SDK connection:
```
export FIVETRAN_CONNECTION_NAME=<your-connection-name>
```
The following command sets the path to a configuration file that contains specific settings (e.g., config.json):
```
export FIVETRAN_CONFIGURATION=<path-to-your-config-file>
```
Replace text between <> with your actual values. For example, if your destination name is TestDestination, the command is export FIVETRAN_DESTINATION_NAME=TestDestination.

Expand to see instructions for Windows

To configure temporary variables on Windows, use the set command. Here are common examples when working with the Connector SDK:

The command below sets your unique secret key, which allows the Connector SDK to connect securely to your Fivetran account.
```
set FIVETRAN_API_KEY=<your-api-key>
```
The following command sets your destination, which determines where the Connector SDK writes data:
```
set FIVETRAN_DESTINATION_NAME=<your-destination-name>
```
The command below specifies your Connector SDK connection:
```
set FIVETRAN_CONNECTION_NAME=<your-connection-name>
```
The following command sets the path to a configuration file that contains specific settings (e.g., config.json):
```
set FIVETRAN_CONFIGURATION=<path-to-your-config-file>
```
Replace text between <> with your actual values. For example, if your destination name is TestDestination, the command is set FIVETRAN_DESTINATION_NAME=TestDestination.

How to set up permanent environment variables

Expand to see instructions for macOS and Linux

To make variables available in every terminal session on macOS and Linux, add them to your shell profile:

Identify your shell (your terminal’s language). Run the following command:
```
echo $SHELL
```
Typical outputs:
- /bin/zsh - You’re using Zsh (default on macOS 10.15+)
- /bin/bash - You’re using Bash
Open your shell configuration file:
- If you’re using zsh, run the nano ~/.zshrc command.
- If you’re using bash, run the nano ~/.bash_profile command.
Add the environment variables you intend to use to the file. For example, to add your FIVETRAN_API_KEY and destination name, add the following to the file:
```
export FIVETRAN_API_KEY=<your-api-key>  
export FIVETRAN_DESTINATION_NAME=<your-destination-name>
```
See our Working with Environment Variables documentation for a full list of supported variables and details about how to use the .env file in your project’s root directory.
Save your changes. In nano:
- Press CTRL + O, then Enter to save.
- Press CTRL + X to exit.
Apply the changes by running the following command:
- In zsh, run source ~/.zshrc
- In bash, source ~/.bash_profile

Your environment variables will now be available in all future terminal sessions, making it easier to work with the Connector SDK.

Expand to see instructions for Windows (using setx command)

To make variables available permanently, use the setx command. The command sets the variables for the current user only, not for the entire system. Here are some common examples you might use for the Connector SDK:

The command below sets your unique secret key, which allows the Connector SDK to connect securely to your Fivetran account.
```
setx FIVETRAN_API_KEY=<your-api-key>
```
The following command sets your destination, which determines where the Connector SDK writes data:
```
setx FIVETRAN_DESTINATION_NAME=<your-destination-name>
```
The command below specifies your Connector SDK connection:
```
setx FIVETRAN_CONNECTION_NAME=<your-connection-name>
```
The following command sets the path to a configuration file that contains specific settings (e.g., config.json):
```
setx FIVETRAN_CONFIGURATION=<path-to-your-config-file>
```
Replace text between <> with your actual values. For example, if your destination name is TestDestination, the command is setx FIVETRAN_DESTINATION_NAME=TestDestination.

Expand to see instructions for Windows (using system properties)

To set permanent environment variables on Windows using the graphical-user interface (GUI), do the following:

Open System Properties. Search for "environment variables" in the Windows search bar and click Edit the system environment variables.
Click Environment variables at the bottom of the window.
Click New... under User variables or System variables.
- User variables apply only to your user account. This is generally preferred for personal development projects.
- System variables apply to all users on the computer. You'll need administrator privileges to modify these.
Type in a variable name for the environment variable.
Type in a variable value for the environment variable. For example, it could be your FIVETRAN_API_KEY.
Click OK to confirm and apply the changes.

For these changes to take effect, you must close and reopen any command prompt or IDE (e.g., PyCharm or VS Code) that were open when you made the changes.

Verify environment variable

To verify that an environment variable has been set, use the echo command:

echo $your_var_name

If the variable is set correctly, the output should display its value.