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

name: setting-up-a-data-warehouse-source
description: >
  Guide the user through connecting a new data warehouse source, including databases, SaaS tools, and bucket files.
  Use when the user wants to "connect Stripe", "import data from Postgres", "import files from a bucket",
  "upload a file", "add a new data source", or pick sync methods for each table. This skill covers
  source-type discovery, credential validation, table discovery, per-table sync_type selection, and the
  final create call. Also covers picking a good prefix, what to do right after creation, and sending a source's
  tables to the user's own warehouse (Snowflake, BigQuery, Postgres, S3 and other destinations).

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.

Use `AmazonS3` for Amazon S3, `GoogleCloudStorage` for Google Cloud Storage, `AzureBlob` for Azure Blob, and `CloudflareR2` for Cloudflare R2. For a local file, direct the user to upload it in the PostHog app. That flow creates a `FileUpload` source. No MCP tool uploads files.

Bucket sources use `full_refresh` by default.

**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 wants to import bucket files or upload a local file
• 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 | | `external-data-destinations-list` | See existing destinations, including the PostHog warehouse | | `external-data-destinations-connect-link` | Secure browser link where the user enters a destination's credentials; returns nothing secret | | `external-data-destinations-connect-link-status` | Poll with the link's `connect_token` to get the integration the user saved | | `external-data-destinations-create` | Create a destination from the integration the connect page saved | | `external-data-destinations-add-sources` | Attach existing sources to a destination | | `external-data-sources-destinations-update` | Set a source's full destination list, for example to keep the PostHog warehouse before attaching | | `external-data-destinations-test-connection` | Diagnose a destination that is failing or paused (does not resume it) |

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 agains