Resource Architecture
The Fivetran Terraform provider splits pipeline configuration across multiple resources - one per concern. This guide explains how those resources relate to each other, why they are separated, and how to compose them into a working pipeline.
Why resources are split
Each resource in the Fivetran provider has an independent lifecycle:
- A destination can exist without any connections.
- A connection can be created before it is unpaused.
- A schema configuration can be updated independently of the connection's credentials.
- Certificates can be rotated without touching the connection configuration.
Separating these concerns means you can update one without forcing Terraform to recreate or interrupt another. It also means different teams can own different parts of the configuration - for example, a platform team owns the destination, while individual teams own their own connections.
Dependency chain
A production-ready connection requires resources created in the following order:
fivetran_group └── fivetran_destination └── fivetran_connection_v2 ├── fivetran_connection_v2_pause_state ├── fivetran_connector_schema_config ├── fivetran_connector_certificates (if required) └── fivetran_connector_fingerprints (if required)
Use depends_on to enforce this order explicitly when implicit dependencies are not sufficient:
resource "fivetran_group" "main" {
name = "production"
}
resource "fivetran_destination" "main" {
group_id = fivetran_group.main.id
service = "big_query"
time_zone_offset = "0"
run_setup_tests = true
# ... config block
}
resource "fivetran_connection_v2" "main" {
group_id = fivetran_group.main.id
service = "postgres"
destination_schema_names = "FIVETRAN_NAMING"
sync_frequency = 360
run_setup_tests = true
config = {
host = var.pg_host
port = 5432
user = var.pg_user
password = var.pg_password
database = var.pg_database
}
depends_on = [fivetran_destination.main]
}
resource "fivetran_connector_schema_config" "main" {
connector_id = fivetran_connection_v2.main.id
schema_change_handling = "ALLOW_ALL"
# Schema config is async for large sources.
# Increase the timeout if your source has many tables.
timeouts {
create = "6h"
}
}
resource "fivetran_connection_v2_pause_state" "main" {
connection_id = fivetran_connection_v2.main.id
paused = false
depends_on = [fivetran_connector_schema_config.main]
}
Group and destination
A group is the top-level organizational unit. It acts as a namespace: all connections and their destination belong to a group. Every group has exactly one destination.
When you create a destination, you specify the group_id. After that, group_id, destination_id, and destination_group_id all refer to the same entity across different API and Terraform contexts.
What happens if you delete a destination?
Deleting the fivetran_destination resource removes the destination configuration but does not delete the group or its connections. Connections become inactive until a new destination is configured for the group.
What happens if you delete a group?
Deleting fivetran_group deletes the group, its destination, and all connections within it. This is irreversible.
Starting connection data sync
fivetran_connection_v2 always creates connections in a paused state. To start syncing, add a fivetran_connection_v2_pause_state resource:
resource "fivetran_connection_v2_pause_state" "main" {
connection_id = fivetran_connection_v2.main.id
paused = false
}
Without this resource, the connection exists but never syncs. This is intentional - it lets you fully configure the connection, including schema and certificates, before you start syncing.
Schedule settings (sync_frequency, schedule_type, daily_sync_time) are attributes on fivetran_connection_v2 itself and do not require a separate resource.
Schema configuration timing
fivetran_connector_schema_config triggers an async reload of the connection's schema. For connections with large schemas, this can take significant time. The default timeout is 6 hours. Increase it if your source has many tables or columns:
resource "fivetran_connector_schema_config" "main" {
connector_id = fivetran_connection_v2.main.id
timeouts {
create = "6h"
update = "6h"
}
}
A single connection may only have one fivetran_connector_schema_config resource. Attempting to manage the same connection's schema config from multiple Terraform resources will cause conflicts on each apply.
Config and auth validation
fivetran_connection_v2 validates config and auth at plan time against connector metadata fetched from the Fivetran API. The provider checks:
- Required fields are present
- Field types match the expected type (string, integer, boolean, etc.)
- Enum fields contain valid values
- Immutable fields that change trigger resource replacement with a warning about historical resync
This validation runs automatically during terraform plan. To skip it (for example, when the metadata API is unavailable), set skip_plan_time_validation = true on the provider block.
Setup tests
Both fivetran_connection_v2 and fivetran_destination support run_setup_tests = true, which validates connectivity after creation. Setup tests run asynchronously and can take up to 30 minutes by default. Override with a custom timeout:
resource "fivetran_connection_v2" "main" {
# ...
destination_schema_names = "FIVETRAN_NAMING"
run_setup_tests = true
timeouts {
create = "60m"
}
}
Set run_setup_tests = false when creating in CI environments where test latency is unacceptable, then run tests separately via the REST API.
Importing existing resources
Use terraform import to bring Fivetran resources that already exist (created via the dashboard or API) under Terraform management without recreating them.
Import a group:
terraform import fivetran_group.my_group <group_id>
Import a destination:
terraform import fivetran_destination.my_destination <group_id>
Import a connection:
terraform import fivetran_connection_v2.my_connection <connection_id>
Import a transformation:
terraform import fivetran_transformation.my_transformation <transformation_id>
After importing, run terraform plan to verify the imported state matches your configuration. Adjust the Terraform resource definition to match any fields Terraform flags as differences.
When importing a fivetran_connection_v2 resource, the provider cannot retrieve auth secrets from the API. You must add the auth attribute to your configuration manually after import.
Networking resources
For connections that require private connectivity, attach the relevant networking resource to the connection:
resource "fivetran_private_link" "main" {
name = "prod-private-link"
region = "US_EAST_1"
service = "AMAZON_S3"
}
resource "fivetran_connection_v2" "main" {
group_id = fivetran_group.main.id
service = "s3"
destination_schema_names = "FIVETRAN_NAMING"
private_link_id = fivetran_private_link.main.id
# ...
}