/setting-up-a-data-warehouse-source

name: setting-up-a-data-warehouse-source
description: >
  Guide the user through connecting a new data warehouse source — Postgres, MySQL, Stripe, Hubspot, MongoDB,
  Salesforce, BigQuery, Snowflake, and so on. Use when the user wants to "connect Stripe", "import data from
  Postgres", "add a new data source", "sync my warehouse tables", or wants to pick sync methods for each table. Walks
  through source-type discovery, credential validation, table discovery, per-table sync_type selection, and the
  final create call. Also covers picking a good prefix and what to do right after creation.

Setting up a data warehouse source

Use this skill when the user wants to connect an external data source to PostHog's data warehouse for the first time.

**Default to the one-step flow:** `data-warehouse-source-setup` validates credentials, discovers every table, enables them with sensible sync defaults (incremental where possible), and creates the source in a single call — no `schemas` array to assemble. For credentials, hand the user a secure browser link with `data-warehouse-source-connect-link` instead of collecting secrets in chat. Only drop to the manual `wizard → db-schema → create` flow when the user wants to hand-pick which tables sync or set non-default sync types per table.

When to use this skill

• The user wants to connect a new source: "connect Stripe", "import my Postgres orders table", "sync Hubspot contacts"
• The user isn't sure what source types PostHog supports
• The user has credentials but doesn't know how to structure the `schemas` payload
• The user wants guidance on which sync method to pick per table

Available tools

| Tool | Purpose | | ------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------- | | `data-warehouse-source-connect-link` | **Preferred for credentials** — get a secure browser/OAuth link so the user authenticates without pasting secrets in chat | | `data-warehouse-source-setup` | **Preferred to create** — one call: validate creds, discover tables, apply sync defaults, create the source | | `external-data-sources-wizard` | Discover which source types exist and what fields each needs (advanced flow) | | `external-data-sources-db-schema` | Validate credentials and list tables with available sync methods per table (advanced flow) | | `external-data-sources-create` | Advanced create — requires a `schemas` array built from the db-schema response | | `external-data-sources-check-cdc-prerequisites-create` | Postgres CDC pre-flight check (optional, only for Postgres CDC) | | `external-data-sources-webhook-info-retrieve` | Check if a source supports webhooks and whether one has been registered | | `external-data-sources-create-webhook-create` | Register a webhook with the external service after source creation | | `external-data-sources-update-webhook-inputs-create` | Supply the signing secret manually when auto-registration failed | | `external-data-sources-list` | After creation, confirm the source is listed and see its initial status | | `external-data-schemas-list` | See per-table sync status once the source is created |

Pre-flight: credential gotchas that cause most failures

Surface these **before** collecting credentials — they're the top reasons setup fails on the first try. Validating against them up front avoids burning credential prompts on retries.

• **The host must be reachable from PostHog's network.** `localhost`, `127.0.0.1`, and private/RFC-1918 hosts

(`10.x`, `192.168.x`, `172.16–31.x`) are rejected — PostHog runs the connection from its own infrastructure, not the user's machine. Serverless/managed Postgres (Neon, Supabase, RDS behind strict rules) often also needs PostHog's egress IPs allowlisted first. If the DB isn't publicly reachable, route to the browser deep-link (`data-warehouse-source-connect-link`) or an SSH tunnel rather than collecting credentials that can't validate.

• **Supabase is Postgres — don't collect it twice.** Use the **Session pooler** connection, not the direct host (the

direct host is IPv6-only). The pooler host looks like `aws-0-<region>.pooler.supabase.com`, the **username** must be `postgres.<project-ref>`, and the **port is 6543** (not 5432). The password is the **database** password (Settings → Database), which is distinct from the `anon`/`service_role` JWT keys and from the Supabase account password. If `SUPABASE_URL` is in the project env, derive the project ref from `db.<ref>.supabase.co` to pre-fill these instead of asking the user to guess.

• **Many SaaS sources need a specific key type or plan** — get the right one before the create call fails:
• **Stripe** — a _restricted_ key (`rk_live_…`), not the standard secret key (`sk_live_…`).
• **RevenueCat** — a v2 secret key (`sk_…`) with the read scopes enabled.
• **Sentry** — an internal-integration token, not a DSN and not a personal auth token.
• **Convex** — requires the Professional plan.
• **Twilio** — API Key SID + Secret, not the account auth token.
• **Mailchimp** — the key carries its datac