setting-up-a-data-warehouse-source

用途

当用户希望首次把外部数据源连接到 PostHog 数据仓库时使用本技能。典型触发场景包括：用户想连接某个新数据源（如“连接 Stripe”“导入我的 Postgres orders 表”“同步 Hubspot contacts”）；用户不确定 PostHog 支持哪些数据源类型；用户已有凭据但不知道如何组织 schemas 载荷；用户需要针对每张表选择同步方式的指导。

主要能力

本技能提供一组工具来支撑数据源接入：

data-warehouse-source-connect-link：生成安全的浏览器/OAuth 链接，让用户在页面上完成认证，避免在聊天中粘贴密钥。
data-warehouse-source-setup：一步式创建，单次调用完成凭据校验、表发现、应用同步默认值并创建数据源。
external-data-sources-wizard：发现存在哪些数据源类型以及每种类型需要哪些字段（高级流程）。
external-data-sources-db-schema：校验凭据并列出表及每张表可用的同步方式（高级流程）。
external-data-sources-create：高级创建，需要基于 db-schema 响应构建 schemas 数组。
external-data-sources-check-cdc-prerequisites-create：Postgres CDC 预检（可选，仅用于 Postgres CDC）。
external-data-sources-webhook-info-retrieve：检查数据源是否支持 Webhook 以及是否已注册。
external-data-sources-create-webhook-create：数据源创建后向外部服务注册 Webhook。
external-data-sources-update-webhook-inputs-create：自动注册失败时手动提供签名密钥。
external-data-sources-list：创建后确认数据源已列出并查看初始状态。
external-data-schemas-list：数据源创建后查看每张表的同步状态。

使用方式

凭据预检

在收集凭据前应先提示以下常见失败原因：主机必须能从 PostHog 网络访问，localhost、127.0.0.1 及私有/RFC-1918 地址会被拒绝；Serverless/托管 Postgres（Neon、Supabase、严格规则下的 RDS）通常需要先把 PostHog 的出站 IP 加入白名单。Supabase 本质是 Postgres，应使用 Session pooler 连接而非直连主机（直连主机仅 IPv6），pooler 主机形如 aws-0-<region>.pooler.supabase.com，用户名必须为 postgres.<project-ref>，端口为 6543（不是 5432），密码是数据库密码。许多 SaaS 数据源需要特定密钥类型或套餐：Stripe 需要受限密钥（rk_live_…）而非标准密钥（sk_live_…）；RevenueCat 需要启用读取权限的 v2 密钥（sk_…）；Sentry 需要内部集成令牌；Convex 需要 Professional 套餐；Twilio 需要 API Key SID + Secret；Mailchimp 的密钥带数据中心后缀（key-usX）；Resend、Mailgun 等仅发送服务的密钥通常受限，仓库导入需要完整/读取权限密钥。不要传入未解析的密钥引用（如 {"secretRef": ...}）。

高级：手动挑选表（三步流程）

当用户想精确选择同步哪些表或设置非默认同步类型时使用。流程为：wizard → db-schema → create。

步骤 1：调用 external-data-sources-wizard 发现数据源类型。响应按类型键控，包含 name（规范 source_type 字符串）、caption、fields（所需配置字段）、featured、unreleasedSource。对 OAuth 类数据源（Hubspot、Salesforce、Google Ads），应引导用户在 PostHog UI 中授权。
步骤 2：调用 external-data-sources-db-schema 校验凭据并列出表。每张表返回 table、should_sync、rows、incremental_available、append_available、cdc_available、supports_webhooks、incremental_fields、detected_primary_keys、available_columns、description。向用户总结而非直接倾倒原始 JSON。
步骤 3：确认每张表的同步配置。同步类型选择建议：小/维度表（<50k 行，无自然排序列）用 full_refresh；有 updated_at/modified_at 的大表用 incremental；仅追加的不可变表（日志、事件）用 append；启用 CDC 的 Postgres 且需要近实时用 cdc；支持 Webhook 的数据源（目前 Stripe）对 supports_webhooks: true 的表设 sync_type: "webhook"。使用 incremental/append/cdc 时还需 incremental_field（优先 updated_at 而非 created_at）、incremental_field_type、CDC 需要 primary_key_columns。
步骤 4：选择前缀。前缀会加到 HogQL 中的表名前，形如 {prefix}_{table_name}。默认用数据源类型小写；若已有同类型数据源，用可区分的名称如 postgres_prod。使用小写、下划线分隔，创建前与用户确认。
步骤 5：调用 external-data-sources-create，传入 source_type、prefix、payload（含凭据和 schemas 数组）。schemas 数组规则：db-schema 返回的每张表都应包含，不想要的设 should_sync: false；sync_type 仅在 should_sync: true 时必需；incremental/append 需 incremental_field 和 incremental_field_type；cdc 需 primary_key_columns。成功后返回新 id，首次同步自动触发。
步骤 6：注册 Webhook（仅当有 schema 的 sync_type 为 "webhook"）。这是数据源创建后的第二次调用。调用前先用 external-data-sources-webhook-info-retrieve({id}) 检查，若已返回 exists: true 则不要重复调用。然后调用 external-data-sources-create-webhook-create({id})。

适用场景

适用于首次接入外部数据源到 PostHog 数据仓库的引导场景，涵盖关系型数据库（Postgres、MySQL、MongoDB）、SaaS 服务（Stripe、Hubspot、Salesforce）、云数据仓库（BigQuery、Snowflake）等。既适合希望快速完成接入的用户，也适合需要精细控制同步表与同步方式的用户。

限制

主机必须能从 PostHog 网络访问，本地和私有地址被拒绝。
部分数据源需要特定密钥类型或套餐，未满足会导致创建失败。
存储凭据一次性使用，24 小时后过期。
CDC 不会自动选择，需要高级流程和 Postgres 前置条件。
Webhook 目前仅 Stripe 实现。
未解析的密钥引用会被拒绝。
关于具体价格、收费、平台支持范围等更多细节，资料中暂未提供。

技能介绍

用途