Skip to content

:hedgehog: PostHog is the leading platform for building self-driving products. Our developer tools – AI observability, analytics, session replay, flags, experiments, error tracking, logs, and more – capture all the context agents need to diagnose problems, uncover opportunities, and ship fixes. Steer it all from Slack, web, desktop, or the MCP.

feat(data-warehouse): match fivetran connectors to posthog sources by rule (#125065)

Daniel RC14c20aeea13d
diff --git a/products/warehouse_sources/backend/migration/__init__.py b/products/warehouse_sources/backend/migration/__init__.py
new file mode 100644
index 000000000000..e69de29bb2d1
diff --git a/products/warehouse_sources/backend/migration/catalog/__init__.py b/products/warehouse_sources/backend/migration/catalog/__init__.py
new file mode 100644
index 000000000000..5ec8323107f1
--- /dev/null
+++ b/products/warehouse_sources/backend/migration/catalog/__init__.py
@@ -0,0 +1,198 @@
+"""Matches a vendor's connectors, tables and settings to PostHog sources.
+
+Matching runs on every call against the live source registry, so a new PostHog source or table
+matches without a code change. Vendor files such as `fivetran.py` hold only the exceptions.
+"""
+
+import re
+import functools
+from collections.abc import Collection, Iterable, Mapping
+from enum import StrEnum
+from typing import Any
+
+import structlog
+
+from posthog.dataclasses import frozen
+
+from products.warehouse_sources.backend.facade.source_config import SourceFieldInputConfig, SourceFieldSSHTunnelConfig
+from products.warehouse_sources.backend.migration.catalog import fivetran
+from products.warehouse_sources.backend.models.external_data_destination import ExternalDataDestination
+from products.warehouse_sources.backend.temporal.data_imports.sources.common.registry import SourceRegistry
+from products.warehouse_sources.backend.types import ExternalDataSourceType
+
+logger = structlog.get_logger(__name__)
+
+
+@frozen
+class _Provider:
+ source_overrides: Mapping[str, ExternalDataSourceType]
+ rejected_sources: Collection[str]
+ table_suffix_rewrites: tuple[tuple[str, str], ...]
+ tunnel_config_keys: Mapping[str, str]
+ config_key_overrides: Mapping[ExternalDataSourceType, Mapping[str, str]]
+ destination_types: Mapping[str, ExternalDataDestination.Type]
+
+
+_PROVIDERS: Mapping[str, _Provider] = {
+ "fivetran": _Provider(
+ source_overrides=fivetran.SOURCE_OVERRIDES,
+ rejected_sources=fivetran.REJECTED_SOURCES,
+ table_suffix_rewrites=fivetran.TABLE_SUFFIX_REWRITES,
+ tunnel_config_keys=fivetran.TUNNEL_CONFIG_KEYS,
+ config_key_overrides=fivetran.CONFIG_KEY_OVERRIDES,
+ destination_types=fivetran.DESTINATION_TYPES,
+ )
+}
+
+
+class MatchConfidence(StrEnum):
+ # The names are the same apart from case and separators.
+ EXACT = "exact"
+ # A naming rule paired them, so the user should confirm the pair.
+ INFERRED = "inferred"
+
+
+@frozen
+class TableMatch:
+ vendor_table: str
+ # None when no PostHog table matches. The agent can propose one from `posthog_tables`.
+ posthog_table: str | None
+ confidence: MatchConfidence | None
+
+
+@frozen
+class PostHogTables:
+ names: frozenset[str]
+ # False when the source also syncs tables it discovers in the user's account, such as Firebase
+ # collections. An unmatched vendor table can then still exist under its own name.
+ complete: bool
+
+
+def _letters(name: str) -> str:
+ return re.sub(r"[^a-z0-9]", "", name.lower())
+
+
+def _source_types_by_letters() -> Mapping[str, ExternalDataSourceType]:
+ return {_letters(source_type.value): source_type for source_type in ExternalDataSourceType}
+
+
+def match_source(provider: str, vendor_service: str) -> ExternalDataSourceType | None:
+ # Unreleased sources match too, so the caller can tell a planned source from a missing one.
+ rules = _PROVIDERS[provider]
+ if vendor_service in rules.rejected_sources:
+ source_type = None
+ else:
+ source_type = rules.source_overrides.get(vendor_service) or _source_types_by_letters().get(
+ _letters(vendor_service)
+ )
+ if source_type is None:
+ logger.info("warehouse_migration_unmatched_source", provider=provider, vendor_service=vendor_service)
+ return source_type
+
+
+def match_destination(provider: str, vendor_service: str) -> ExternalDataDestination.Type | None:
+ return _PROVIDERS[provider].destination_types.get(vendor_service)
+
+
+def posthog_tables(source_type: ExternalDataSourceType) -> PostHogTables | None:
+ """Tables the source can sync, or None when the user defines them all, as in a database."""
+ source = SourceRegistry.get_source(source_type)
+ if source.lists_tables_without_credentials:
+ documented = frozenset(table["name"] for table in source.get_documented_tables())
+ if documented:
+ return PostHogTables(names=documented, complete=True)
+ # A source that cannot list its tables without credentials or config still describes the
+ # tables it always has, but it can discover more in the user's account.
+ described = frozenset(source.get_canonical_descriptions())
+ return PostHogTables(names=described, complete=False) if described else None
+
+
+def _inferred_keys(vendor_table: str, rewrites: tuple[tuple[str, str], ...]) -> list[str]:
+ stems = [vendor_table] + [
+ vendor_table.removesuffix(suffix) + replacement
+ for suffix, replacement in rewrites
+ if vendor_table.endswith(suffix)
+ ]
+ keys: list[str] = []
+ for stem in (_letters(s) for s in stems if s):
+ keys += [stem, f"{stem}s", f"{stem}es"]
+ if stem.endswith("y"):
+ keys.append(f"{stem[:-1]}ies")
+ if stem.endswith("s"):
+ keys.append(stem[:-1])
+ return keys
+
+
+def match_tables(
+ provider: str, vendor_tables: Iterable[str], posthog_table_names: Collection[str]
+) -> tuple[TableMatch, ...]:
+ rewrites = _PROVIDERS[provider].table_suffix_rewrites
+ by_letters: dict[str, str] = {}
+ for name in sorted(posthog_table_names):
+ by_letters.setdefault(_letters(name), name)
+
+ vendor_tables = list(vendor_tables)
+ exact = {t: by_letters[_letters(t)] for t in vendor_tables if _letters(t) in by_letters}
+ taken = set(exact.values())
+ # A table another vendor table matches exactly is taken. Salesforce `account_history` is a
+ # field audit log, not the `Account` records that `account` already holds.
+ inferred: dict[str, tuple[str, int]] = {}
+ for vendor_table in vendor_tables:
+ if vendor_table in exact:
+ continue
+ keys = _inferred_keys(vendor_table, rewrites)
+ hit = next(
+ ((by_letters[k], rank) for rank, k in enumerate(keys) if k in by_letters and by_letters[k] not in taken),
+ None,
+ )
+ if hit is not None:
+ inferred[vendor_table] = hit
+ # When two vendor tables infer the same PostHog table, the one whose name needed the smaller
+ # change keeps it, so `campaign` beats `campaign_history` for `campaigns`. The name breaks ties,
+ # so the result does not depend on the input order.
+ winners: dict[str, str] = {}
+ for vendor_table, (target, _rank) in sorted(inferred.items(), key=lambda item: (item[1][1], item[0])):
+ winners.setdefault(target, vendor_table)
+
+ matches: list[TableMatch] = []
+ for vendor_table in vendor_tables:
+ if vendor_table in exact:
+ matches.append(
+ TableMatch(
+ vendor_table=vendor_table, posthog_table=exact[vendor_table], confidence=MatchConfidence.EXACT
+ )
+ )
+ elif vendor_table in inferred and winners[inferred[vendor_table][0]] == vendor_table:
+ matches.append(
+ TableMatch(
+ vendor_table=vendor_table,
+ posthog_table=inferred[vendor_table][0],
+ confidence=MatchConfidence.INFERRED,
+ )
+ )
+ else:
+ matches.append(TableMatch(vendor_table=vendor_table, posthog_table=None, confidence=None))
+ unmatched = [m.vendor_table for m in matches if m.posthog_table is None]
+ if unmatched:
+ logger.info("warehouse_migration_unmatched_tables", provider=provider, vendor_tables=unmatched)
+ return tuple(matches)
+
+
+def prefill_config(
+ provider: str, source_type: ExternalDataSourceType, vendor_config: Mapping[str, Any]
+) -> dict[str, Any]:
+ """Non-secret source settings keyed by PostHog payload path. A dot is a nested field."""
+ rules = _PROVIDERS[provider]
+ fields = SourceRegistry.get_source(source_type).get_source_config.fields
+ key_map = {
+ field.name: field.name for field in fields if isinstance(field, SourceFieldInputConfig) and not field.secret
+ }
+ if any(isinstance(field, SourceFieldSSHTunnelConfig) for field in fields):
+ key_map.update(rules.tunnel_config_keys)
+ key_map.update(rules.config_key_overrides.get(source_type, {}))
+ return {
+ posthog_key: vendor_config[vendor_key]
+ for vendor_key, posthog_key in key_map.items()
+ if vendor_config.get(vendor_key) not in (None, "")
+ }
diff --git a/products/warehouse_sources/backend/migration/catalog/fivetran.py b/products/warehouse_sources/backend/migration/catalog/fivetran.py
new file mode 100644
index 000000000000..8ca183f3aacd
--- /dev/null
+++ b/products/warehouse_sources/backend/migration/catalog/fivetran.py
@@ -0,0 +1,188 @@
+"""Fivetran-specific exceptions to the name-based matching rules in `catalog/__init__.py`.
+
+Keep this file to the cases a rule cannot get right. A missing override or rewrite leaves the
+connector or table unmatched, and the user and the agent choose what to do. A missing rejection
+is not safe: it lets a different product of the same name match.
+"""
+
+from products.warehouse_sources.backend.models.external_data_destination import ExternalDataDestination
+from products.warehouse_sources.backend.types import ExternalDataSourceType as T
+
+# Fivetran service ids that name matching cannot pair with their PostHog source, or pairs wrongly.
+SOURCE_OVERRIDES: dict[str, T] = {
+ # Hosted and managed flavors of the same database engine.
+ "aurora_postgres": T.POSTGRES,
+ "azure_postgres": T.POSTGRES,
+ "google_cloud_postgresql": T.POSTGRES,
+ "heroku_postgres": T.POSTGRES,
+ "postgres_rds": T.POSTGRES,
+ "aurora": T.MYSQL,
+ "google_cloud_mysql": T.MYSQL,
+ "magento_mysql": T.MYSQL,
+ "magento_mysql_rds": T.MYSQL,
+ "maria": T.MYSQL,
+ "maria_azure": T.MYSQL,
+ "maria_rds": T.MYSQL,
+ "mysql_azure": T.MYSQL,
+ "mysql_rds": T.MYSQL,
+ "azure_sql_db": T.MSSQL,
+ "azure_sql_managed_db": T.MSSQL,
+ "google_cloud_sqlserver": T.MSSQL,
+ "sql_server": T.MSSQL,
+ "sql_server_hva": T.MSSQL,
+ "sql_server_rds": T.MSSQL,
+ "oracle_hva": T.ORACLE,
+ "oracle_rac": T.ORACLE,
+ "oracle_rds": T.ORACLE,
+ "db2i_hva": T.DB2,
+ "db2luw": T.DB2,
+ "db2z": T.DB2,
+ "mongo": T.MONGODB,
+ "mongo_sharded": T.MONGODB,
+ "azure_cosmos_for_mongo": T.MONGODB,
+ "cosmos": T.COSMOSDB,
+ "documentdb": T.AWSDOCUMENTDB,
+ "sap_hana_db": T.SAPHANA,
+ "bigquery_db": T.BIGQUERY,
+ "databricks_db": T.DATABRICKS,
+ "planetscale": T.PLANETSCALEMYSQL,
+ "singlestore_source": T.SINGLESTORE,
+ "snowflake_db": T.SNOWFLAKE,
+ "apache_kafka": T.KAFKA,
+ # A name match gives the PostHog Confluent Cloud source, which reads the Metrics API, not topics.
+ "confluent_cloud": T.KAFKA,
+ "aws_msk": T.KAFKA,
+ "heroku_kafka": T.KAFKA,
+ "kinesis": T.AMAZONKINESIS,
+ "elastic_cloud": T.ELASTICSEARCH,
+ "elastic_cloud_serverless": T.ELASTICSEARCH,
+ "es_self_hosted": T.ELASTICSEARCH,
+ # File storage.
+ "azure_blob_storage": T.AZUREBLOB,
+ "gcs": T.GOOGLECLOUDSTORAGE,
+ "s3": T.AMAZONS3,
+ # Sandbox and test accounts of a vendor use the same PostHog source.
+ "braintree_sandbox": T.BRAINTREE,
+ "pardot_sandbox": T.PARDOT,
+ "paypal_sandbox": T.PAYPAL,
+ "salesforce_sandbox": T.SALESFORCE,
+ "stripe_test": T.STRIPE,
+ "zuora_sandbox": T.ZUORA,
+ # Same product under a different or older name.
+ "anthropic_claude": T.ANTHROPIC,
+ "autodesk_bim_360": T.AUTODESKCONSTRUCTIONCLOUD,
+ "atlassian_ops_genie": T.OPSGENIE,
+ "aws_cost_report": T.AWSCOSTANDUSAGEREPORT,
+ "bigin_by_zoho_crm": T.ZOHOBIGIN,
+ "business_central": T.DYNAMICS365BUSINESSCENTRAL,
+ "canvas_by_instructure": T.CANVASLMS,
+ "ceridian_dayforce": T.DAYFORCE,
+ "chargebee_product_catalog_1": T.CHARGEBEE,
+ "chargebee_product_catalog_2": T.CHARGEBEE,
+ "checkout": T.CHECKOUTCOM,
+ "chorusai": T.CHORUS,
+ "circle_community_platform": T.CIRCLESO,
+ "cj_commission_detail": T.COMMISSIONJUNCTION,
+ "concur": T.SAPCONCUR,
+ "dbt_cloud": T.DBT,
+ "double_click_campaign_manager": T.CAMPAIGNMANAGER360,
+ "double_click_publishers": T.GOOGLEADMANAGER,
+ "facebook_ads": T.METAADS,
+ "float": T.FLOATAPP,
+ "freshdesk_contact_center": T.FRESHCALLER,
+ "gainsight_customer_success": T.GAINSIGHTCS,
+ "gainsight_product_experience": T.GAINSIGHTPX,
+ "genesys": T.GENESYSCLOUD,
+ "gongio": T.GONG,
+ "google_analytics_4": T.GOOGLEANALYTICS,
+ "google_display_and_video_360": T.DISPLAYVIDEO360,
+ "google_play": T.GOOGLEPLAYCONSOLE,
+ "google_search_ads_360": T.SEARCHADS360,
+ "h_level": T.HIGHLEVEL,
+ "instagram_business": T.INSTAGRAM,
+ "ironsource": T.IRONSOURCEADS,
+ "itunes_connect": T.APPSTORECONNECT,
+ "jamf": T.JAMFPRO,
+ "lightspeed_retail_xseries": T.LIGHTSPEEDRETAIL,
+ "linkedin_company_pages": T.LINKEDINPAGES,
+ "looker_source": T.LOOKER,
+ "maxio_chargify": T.CHARGIFY,
+ "netsuite_suiteanalytics": T.NETSUITE,
+ "odoo_native": T.ODOO,
+ "oracle_fusion_cloud_apps_crm": T.ORACLEFUSION,
+ "oracle_fusion_cloud_apps_fscm": T.ORACLEFUSION,
+ "oracle_fusion_cloud_apps_hcm": T.ORACLEFUSION,
+ "partnerstack_vendor": T.PARTNERSTACK,
+ "pylon_support_platform": T.PYLON,
+ "rokt": T.ROKTADS,
+ "sigma_computing_source": T.SIGMACOMPUTING,
+ "sprout": T.SPROUTSOCIAL,
+ "stackadapt_graphql": T.STACKADAPT,
+ "the_movie_database": T.TMDB,
+ "tiktok_shop_partner_center": T.TIKTOKSHOP,
+ "toggl_track": T.TOGGL,
+ "workday_hcm": T.WORKDAY,
+ "zoho_campaigns": T.ZOHOCAMPAIGN,
+}
+
+# Same vendor, different product. Each entry names what the Fivetran connector reads and what the
+# PostHog source of the same name reads, so a match would sync none of the customer's data.
+REJECTED_SOURCES: frozenset[str] = frozenset(
+ {
+ # Fivetran reads the Lightspeed R-Series API. PostHog reads X-Series.
+ "light_speed_retail",
+ # Fivetran takes in the event stream. PostHog reads workspace config from the Public API.
+ "segment",
+ # Fivetran takes in the event stream. PostHog reads pipeline health from the BDP Console.
+ "snowplow",
+ # Fivetran reads Workday RaaS custom reports. PostHog reads the HCM API, which is `workday_hcm`.
+ "workday",
+ }
+)
+
+
+# Fivetran table name endings and what to try in their place. A history-mode table such as Google Ads
+# `campaign_history` holds the same records as `campaigns`, and `campaign_performance_daily_report`
+# as `campaign_performance_report`. The match is only inferred, because some `_history` tables are
+# audit logs instead.
+# A plain `_report` ending stays, because `campaign_report` holds metrics, not the records in `campaigns`.
+TABLE_SUFFIX_REWRITES: tuple[tuple[str, str], ...] = (
+ ("_history", ""),
+ ("_daily_report", "_report"),
+)
+
+# Fivetran keeps the SSH tunnel in flat config keys. PostHog nests it under the `ssh_tunnel` field.
+TUNNEL_CONFIG_KEYS: dict[str, str] = {
+ "tunnel_host": "ssh_tunnel.host",
+ "tunnel_port": "ssh_tunnel.port",
+ "tunnel_user": "ssh_tunnel.auth.username",
+}
+
+# Non-secret config keys whose PostHog field has a different name. Keys with the same name on both
+# sides are copied without an entry here.
+CONFIG_KEY_OVERRIDES: dict[T, dict[str, str]] = {
+ T.SNOWFLAKE: {"user": "auth_type.user"},
+ T.BIGQUERY: {"data_set_name": "dataset_id"},
+}
+
+_D = ExternalDataDestination.Type
+
+# Fivetran destination service ids, from
+# https://github.com/fivetran/terraform-provider-fivetran/blob/main/destination-services.txt.
+# The managed data lake is left out because it can sit on ADLS or GCS, which an S3 destination cannot write to.
+DESTINATION_TYPES: dict[str, ExternalDataDestination.Type] = {
+ "snowflake": _D.SNOWFLAKE,
+ "big_query": _D.BIGQUERY,
+ "big_query_dts": _D.BIGQUERY,
+ "managed_big_query": _D.BIGQUERY,
+ "redshift": _D.REDSHIFT,
+ "aurora_postgres_warehouse": _D.POSTGRES,
+ "azure_postgres_warehouse": _D.POSTGRES,
+ "postgres_databricks_warehouse": _D.POSTGRES,
+ "postgres_gcp_warehouse": _D.POSTGRES,
+ "postgres_rds_warehouse": _D.POSTGRES,
+ "postgres_warehouse": _D.POSTGRES,
+ "postgres_wh": _D.POSTGRES,
+ "databricks": _D.DATABRICKS,
+ "databricks_via_managed_data_lake": _D.DATABRICKS,
+}
diff --git a/products/warehouse_sources/backend/migration/catalog/tests/__init__.py b/products/warehouse_sources/backend/migration/catalog/tests/__init__.py
new file mode 100644
index 000000000000..e69de29bb2d1
diff --git a/products/warehouse_sources/backend/migration/catalog/tests/test_catalog.py b/products/warehouse_sources/backend/migration/catalog/tests/test_catalog.py
new file mode 100644
index 000000000000..e7bbb749e165
--- /dev/null
+++ b/products/warehouse_sources/backend/migration/catalog/tests/test_catalog.py
@@ -0,0 +1,122 @@
+from typing import Any
+
+from parameterized import parameterized
+
+from products.warehouse_sources.backend.migration.catalog import (
+ MatchConfidence,
+ PostHogTables,
+ TableMatch,
+ match_source,
+ match_tables,
+ posthog_tables,
+ prefill_config,
+)
+from products.warehouse_sources.backend.migration.catalog.fivetran import SOURCE_OVERRIDES
+from products.warehouse_sources.backend.temporal.data_imports.sources.common.registry import SourceRegistry
+from products.warehouse_sources.backend.types import ExternalDataSourceType as T
+
+
+class TestCatalog:
+ def test_every_source_override_is_a_registered_source(self) -> None:
+ registered = set(SourceRegistry.get_all_sources())
+ assert {service: str(t) for service, t in SOURCE_OVERRIDES.items() if t not in registered} == {}
+
+ @parameterized.expand(
+ [
+ ("name_match", "fivetran", "google_ads", T.GOOGLEADS),
+ ("override_beats_name_match", "fivetran", "confluent_cloud", T.KAFKA),
+ ("rejected_name_match", "fivetran", "segment", None),
+ ]
+ )
+ def test_match_source(self, _name: str, provider: str, service: str, expected: T | None) -> None:
+ assert match_source(provider, service) == expected
+
+ @parameterized.expand(
+ [
+ ("case_and_separators", "balance_transaction", "BalanceTransaction", MatchConfidence.EXACT),
+ ("plural", "contact", "contacts", MatchConfidence.INFERRED),
+ ("plural_ies", "category", "categories", MatchConfidence.INFERRED),
+ ("history_suffix", "campaign_history", "campaigns", MatchConfidence.INFERRED),
+ (
+ "daily_report_suffix",
+ "campaign_performance_daily_report",
+ "campaign_performance_report",
+ MatchConfidence.INFERRED,
+ ),
+ ]
+ )
+ def test_match_tables(
+ self, _name: str, vendor_table: str, posthog_table: str | None, confidence: MatchConfidence | None
+ ) -> None:
+ candidates = {
+ "BalanceTransaction",
+ "contacts",
+ "categories",
+ "campaigns",
+ "campaign_performance_report",
+ }
+ assert match_tables("fivetran", [vendor_table], candidates) == (
+ TableMatch(vendor_table=vendor_table, posthog_table=posthog_table, confidence=confidence),
+ )
+
+ def test_exact_match_wins_over_an_inferred_one(self) -> None:
+ (match,) = match_tables("fivetran", ["campaign_history"], {"campaign_history", "campaigns"})
+ assert (match.posthog_table, match.confidence) == ("campaign_history", MatchConfidence.EXACT)
+
+ def test_inferred_match_skips_a_table_another_vendor_table_matches_exactly(self) -> None:
+ assert match_tables("fivetran", ["account", "account_history"], {"Account"}) == (
+ TableMatch(vendor_table="account", posthog_table="Account", confidence=MatchConfidence.EXACT),
+ TableMatch(vendor_table="account_history", posthog_table=None, confidence=None),
+ )
+
+ @parameterized.expand(
+ [
+ ("plural_listed_first", ["campaign", "campaign_history"]),
+ ("history_listed_first", ["campaign_history", "campaign"]),
+ ]
+ )
+ def test_closer_name_keeps_a_posthog_table_two_vendor_tables_infer(
+ self, _name: str, vendor_tables: list[str]
+ ) -> None:
+ matches = {
+ m.vendor_table: (m.posthog_table, m.confidence)
+ for m in match_tables("fivetran", vendor_tables, {"campaigns"})
+ }
+ assert matches == {"campaign": ("campaigns", MatchConfidence.INFERRED), "campaign_history": (None, None)}
+
+ @parameterized.expand(
+ [
+ ("static_catalog", T.STRIPE, "Charge", True),
+ ("needs_config_to_list", T.GITHUB, "issues", False),
+ ("also_discovers_tables", T.FIREBASE, "auth_users", False),
+ ]
+ )
+ def test_posthog_tables(self, _name: str, source_type: T, known_table: str, complete: bool) -> None:
+ tables = posthog_tables(source_type)
+ assert isinstance(tables, PostHogTables)
+ assert (known_table in tables.names, tables.complete) == (True, complete)
+
+ def test_posthog_tables_is_none_for_user_defined_tables(self) -> None:
+ assert posthog_tables(T.POSTGRES) is None
+
+ @parameterized.expand(
+ [
+ (
+ "same_name_and_tunnel",
+ T.POSTGRES,
+ {"host": "db.example.com", "port": 5432, "user": "reader", "password": "******", "tunnel_user": "jump"},
+ {"host": "db.example.com", "port": 5432, "user": "reader", "ssh_tunnel.auth.username": "jump"},
+ ),
+ (
+ "renamed_nested_field",
+ T.SNOWFLAKE,
+ {"database": "analytics", "user": "reader", "role": ""},
+ {"database": "analytics", "auth_type.user": "reader"},
+ ),
+ ("no_tunnel_field", T.STRIPE, {"tunnel_host": "jump.example.com"}, {}),
+ ]
+ )
+ def test_prefill_config(
+ self, _name: str, source_type: T, vendor_config: dict[str, Any], expected: dict[str, Any]
+ ) -> None:
+ assert prefill_config("fivetran", source_type, vendor_config) == expected
diff --git a/products/warehouse_sources/skills/migrating-from-fivetran/references/connector-notes.md b/products/warehouse_sources/skills/migrating-from-fivetran/references/connector-notes.md
new file mode 100644
index 000000000000..d06095fd63f2
--- /dev/null
+++ b/products/warehouse_sources/skills/migrating-from-fivetran/references/connector-notes.md
@@ -0,0 +1,26 @@
+# Fivetran connector notes
+
+## Table matches
+
+Each Fivetran table on a migration item comes with a match to a PostHog table and a confidence:
+
+- `exact`: the names are the same apart from case and underscores, for example `balance_transaction` and `BalanceTransaction`. Use it without asking.
+- `inferred`: a naming rule paired them, for example `campaign_history` with `campaigns`. List these pairs and ask the user to confirm them before you apply.
+- No match: no rule found a PostHog table. Compare the Fivetran table with the source's PostHog tables and their descriptions, and propose a table when one holds the same records. Mark it as your guess and let the user decide. When nothing fits, say the table does not move.
+
+Propose a pair only when the PostHog table holds the same kind of record. A Fivetran `campaign_report` holds daily metrics, so it is not `campaigns`.
+
+## Per connector
+
+Read the matching note to the user when the migration has that connector.
+
+| Fivetran connector | What to tell the user |
+| ------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `github` | PostHog keeps a separate set of tables for each repository, for example `owner/repo.issues`. Choose the repositories when you connect the source. |
+| `google_analytics_4` | Fivetran custom reports do not move over. Recreate them in the Custom reports field when you connect. |
+| `google_search_console` | PostHog's query and page tables do not break down by country and device like the Fivetran reports do. PostHog also keeps web results apart from image, video and news results, so turn on the tables for the other search types to sync them. |
+| `hubspot` | Newer Fivetran connections keep every engagement in one `engagement` table. PostHog splits engagements into the calls, emails, meetings, notes, tasks and communications tables. |
+| `klaviyo` | Fivetran keeps email and SMS campaigns in one `campaign` table. PostHog splits them into `email_campaigns` and `sms_campaigns`. |
+| `iterable` | Fivetran keeps every event in one `event` table. PostHog has one table per event type, such as `email_send` and `push_open`. |
+| `sql_server_hva` | Fivetran reads this database through an agent on the user's network. PostHog connects to the database directly, so it must be reachable from PostHog or through an SSH tunnel. |
+| `azure_cosmos_for_mongo` | PostHog reads Cosmos DB for MongoDB with its MongoDB source. |