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.

chore(data-warehouse): point agents at managed bucket and upload sources (#130344)

Tom Owers02e90ed75447
diff --git a/ee/hogai/chat_agent/prompts/base.py b/ee/hogai/chat_agent/prompts/base.py
index 08702d891a61..c5f3f2050e59 100644
--- a/ee/hogai/chat_agent/prompts/base.py
+++ b/ee/hogai/chat_agent/prompts/base.py
@@ -214,7 +214,7 @@ PostHog products:
- **Experiments** – A/B testing and no-code A/B testing with statistical rigor
- **Surveys** – in-app questionnaires, NPS, user feedback collection
- **LLM observability** – monitor AI/LLM application costs, latency, and quality
-- **Data warehouse** – connect external data sources (Stripe, Hubspot, Postgres, etc.) for combined analysis
+- **Data warehouse**: Import data from SaaS tools, databases, Amazon S3, Google Cloud Storage, Azure Blob, and Cloudflare R2. Upload local files in the app.
- **Data pipelines (CDP)** – import data from 20+ sources, transform events in real-time, and export to external destinations
- **Revenue analytics** – track and analyze revenue metrics alongside product data
- **Logs** – collect and search application logs
diff --git a/products/data_warehouse/backend/presentation/views/table.py b/products/data_warehouse/backend/presentation/views/table.py
index 2ca36f02d1c9..0415ebe65493 100644
--- a/products/data_warehouse/backend/presentation/views/table.py
+++ b/products/data_warehouse/backend/presentation/views/table.py
@@ -459,7 +459,8 @@ class TableSerializer(UserAccessControlSerializerMixin, serializers.ModelSeriali
):
raise serializers.ValidationError(
"PostHog manages where this table reads from, so its URL can't be changed. "
- "To read from your own bucket, add it as a self-managed source with an access key and secret."
+ "To read from your own bucket, add a managed Amazon S3, Google Cloud Storage, "
+ "Azure Blob, or Cloudflare R2 source."
)
return url_pattern
@@ -781,11 +782,12 @@ class TableViewSet(TeamAndOrgViewSetMixin, AccessControlViewSetMixin, viewsets.M
responses={200: OpenApiResponse(description="Schema refreshed from the table's underlying source")},
summary="Refresh table schema from source",
description=(
- "Re-introspect a self-managed (manually linked) warehouse table's schema from its underlying "
+ "Re-introspect an existing direct-read warehouse table's schema from its underlying "
"source files and overwrite its stored column list. Use when the source schema has evolved "
"(e.g. new columns in the underlying Delta/Parquet/CSV files) but queries still can't see the "
"new columns, because PostHog serves a cached column snapshot until the table is refreshed. "
- "Not for tables managed by an external data source sync — those refresh on their own schedule."
+ "This applies only to existing direct-read tables. New direct-read tables cannot be created. "
+ "Tables managed by an external data source sync refresh on their own schedule."
),
)
@action(methods=["POST"], detail=True, required_scopes=["warehouse_table:write"])
@@ -820,7 +822,7 @@ class TableViewSet(TeamAndOrgViewSetMixin, AccessControlViewSetMixin, viewsets.M
}
},
responses={201: FileUploadResponseSerializer},
- summary="Upload a file for a new self-managed warehouse table",
+ summary="Upload a file for a new warehouse table and FileUpload source",
)
@action(
methods=["POST"],
@@ -829,7 +831,7 @@ class TableViewSet(TeamAndOrgViewSetMixin, AccessControlViewSetMixin, viewsets.M
parser_classes=[parsers.MultiPartParser, parsers.FormParser],
)
def upload_file(self, request: request.Request, *args: Any, **kwargs: Any) -> response.Response:
- """Store an uploaded file in object storage so a self-managed table can be created from it.
+ """Store an uploaded file for a new warehouse table and FileUpload source.
Uploading is a separate first step from `create_from_upload` so the create call stays JSON-only:
this returns an `upload_id` the caller passes back to build the table. The file is written under
@@ -853,7 +855,8 @@ class TableViewSet(TeamAndOrgViewSetMixin, AccessControlViewSetMixin, viewsets.M
status=status.HTTP_413_REQUEST_ENTITY_TOO_LARGE,
data={
"message": f"Upload exceeds the maximum of {MAX_FILE_UPLOAD_SIZE_BYTES // (1024 * 1024)}MB. "
- "For larger files, connect the bucket they live in as a self-managed source instead."
+ "For larger files, connect the bucket with a managed Amazon S3, Google Cloud Storage, "
+ "Azure Blob, or Cloudflare R2 source."
},
)
@@ -882,7 +885,8 @@ class TableViewSet(TeamAndOrgViewSetMixin, AccessControlViewSetMixin, viewsets.M
status=status.HTTP_400_BAD_REQUEST,
data={
"message": f"File size exceeds the maximum of {MAX_FILE_UPLOAD_SIZE_BYTES // (1024 * 1024)}MB. "
- "For larger files, connect the bucket they live in as a self-managed source instead."
+ "For larger files, connect the bucket with a managed Amazon S3, Google Cloud Storage, "
+ "Azure Blob, or Cloudflare R2 source."
},
)
@@ -911,15 +915,15 @@ class TableViewSet(TeamAndOrgViewSetMixin, AccessControlViewSetMixin, viewsets.M
@extend_schema(
request=CreateTableFromUploadSerializer,
responses={201: TableSerializer},
- summary="Create a self-managed warehouse table from an uploaded file",
+ summary="Create a warehouse table and FileUpload source from an uploaded file",
)
@action(methods=["POST"], detail=False, required_scopes=["warehouse_table:write"])
def create_from_upload(self, request: request.Request, *args: Any, **kwargs: Any) -> response.Response:
- """Turn a previously uploaded file into a self-managed warehouse table.
+ """Turn a previously uploaded file into a warehouse table with a FileUpload source.
The file already sits in PostHog's own bucket (see `upload_file`), so the table points straight
- at it and is read in place — no import pipeline and no recurring sync, the same shape as a linked
- S3/GCS bucket. The read location is always derived from the caller's own team, so a client-supplied
+ at it for the initial direct read. The source imports it on its first sync. The read location
+ is always derived from the caller's own team, so a client-supplied
`upload_id` can only resolve inside that team's folder, and the table carries no credential (reads
fall back to the node role, never a user-supplied key).
diff --git a/products/data_warehouse/frontend/generated/api.ts b/products/data_warehouse/frontend/generated/api.ts
index 345c450ec718..e97a3ca38a57 100644
--- a/products/data_warehouse/frontend/generated/api.ts
+++ b/products/data_warehouse/frontend/generated/api.ts
@@ -2318,7 +2318,7 @@ export const getWarehouseTablesRefreshSchemaCreateUrl = (projectId: string, id:
}
/**
- * Re-introspect a self-managed (manually linked) warehouse table's schema from its underlying source files and overwrite its stored column list. Use when the source schema has evolved (e.g. new columns in the underlying Delta/Parquet/CSV files) but queries still can't see the new columns, because PostHog serves a cached column snapshot until the table is refreshed. Not for tables managed by an external data source sync — those refresh on their own schedule.
+ * Re-introspect an existing direct-read warehouse table's schema from its underlying source files and overwrite its stored column list. Use when the source schema has evolved (e.g. new columns in the underlying Delta/Parquet/CSV files) but queries still can't see the new columns, because PostHog serves a cached column snapshot until the table is refreshed. This applies only to existing direct-read tables. New direct-read tables cannot be created. Tables managed by an external data source sync refresh on their own schedule.
* @summary Refresh table schema from source
*/
export const warehouseTablesRefreshSchemaCreate = async (
@@ -2380,17 +2380,17 @@ export const getWarehouseTablesCreateFromUploadCreateUrl = (projectId: string) =
}
/**
- * Turn a previously uploaded file into a self-managed warehouse table.
+ * Turn a previously uploaded file into a warehouse table with a FileUpload source.
*
* The file already sits in PostHog's own bucket (see `upload_file`), so the table points straight
- * at it and is read in place — no import pipeline and no recurring sync, the same shape as a linked
- * S3/GCS bucket. The read location is always derived from the caller's own team, so a client-supplied
+ * at it for the initial direct read. The source imports it on its first sync. The read location
+ * is always derived from the caller's own team, so a client-supplied
* `upload_id` can only resolve inside that team's folder, and the table carries no credential (reads
* fall back to the node role, never a user-supplied key).
*
* For a team with object storage sources, the table also gets a file upload source. Its first
* sync imports the file and turns the same table row into a managed table.
- * @summary Create a self-managed warehouse table from an uploaded file
+ * @summary Create a warehouse table and FileUpload source from an uploaded file
*/
export const warehouseTablesCreateFromUploadCreate = async (
projectId: string,
@@ -2441,12 +2441,12 @@ export const getWarehouseTablesUploadFileCreateUrl = (projectId: string) => {
}
/**
- * Store an uploaded file in object storage so a self-managed table can be created from it.
+ * Store an uploaded file for a new warehouse table and FileUpload source.
*
* Uploading is a separate first step from `create_from_upload` so the create call stays JSON-only:
* this returns an `upload_id` the caller passes back to build the table. The file is written under
* a team-scoped prefix, so a table can only ever read back its own team's uploads.
- * @summary Upload a file for a new self-managed warehouse table
+ * @summary Upload a file for a new warehouse table and FileUpload source
*/
export const warehouseTablesUploadFileCreate = async (
projectId: string,
diff --git a/products/data_warehouse/frontend/generated/api.zod.ts b/products/data_warehouse/frontend/generated/api.zod.ts
index dc8f28c853ff..63c34f532357 100644
--- a/products/data_warehouse/frontend/generated/api.zod.ts
+++ b/products/data_warehouse/frontend/generated/api.zod.ts
@@ -1596,17 +1596,17 @@ export const WarehouseTablesUpdateSchemaCreateBody = /* @__PURE__ */ zod
.describe('Mixin for serializers to add user access control fields')
/**
- * Turn a previously uploaded file into a self-managed warehouse table.
+ * Turn a previously uploaded file into a warehouse table with a FileUpload source.
*
* The file already sits in PostHog's own bucket (see `upload_file`), so the table points straight
- * at it and is read in place — no import pipeline and no recurring sync, the same shape as a linked
- * S3/GCS bucket. The read location is always derived from the caller's own team, so a client-supplied
+ * at it for the initial direct read. The source imports it on its first sync. The read location
+ * is always derived from the caller's own team, so a client-supplied
* `upload_id` can only resolve inside that team's folder, and the table carries no credential (reads
* fall back to the node role, never a user-supplied key).
*
* For a team with object storage sources, the table also gets a file upload source. Its first
* sync imports the file and turns the same table row into a managed table.
- * @summary Create a self-managed warehouse table from an uploaded file
+ * @summary Create a warehouse table and FileUpload source from an uploaded file
*/
export const WarehouseTablesCreateFromUploadCreateBody = /* @__PURE__ */ zod.object({
upload_id: zod.uuid().describe('Id returned by upload_file for the stored file.'),
@@ -1723,12 +1723,12 @@ export const WarehouseTablesFileCreateBody = /* @__PURE__ */ zod
.describe('Mixin for serializers to add user access control fields')
/**
- * Store an uploaded file in object storage so a self-managed table can be created from it.
+ * Store an uploaded file for a new warehouse table and FileUpload source.
*
* Uploading is a separate first step from `create_from_upload` so the create call stays JSON-only:
* this returns an `upload_id` the caller passes back to build the table. The file is written under
* a team-scoped prefix, so a table can only ever read back its own team's uploads.
- * @summary Upload a file for a new self-managed warehouse table
+ * @summary Upload a file for a new warehouse table and FileUpload source
*/
export const WarehouseTablesUploadFileCreateBody = /* @__PURE__ */ zod.object({
file: zod.instanceof(File).describe('The file to upload.'),
diff --git a/products/posthog_ai/backend/services/system_prompt/prompt.py b/products/posthog_ai/backend/services/system_prompt/prompt.py
index cdfb848a925c..9a01209ce381 100644
--- a/products/posthog_ai/backend/services/system_prompt/prompt.py
+++ b/products/posthog_ai/backend/services/system_prompt/prompt.py
@@ -63,7 +63,7 @@ PostHog products:
- **Experiments** – A/B testing and no-code A/B testing with statistical rigor
- **Surveys** – in-app questionnaires, NPS, user feedback collection
- **AI observability** (also called AIO, LLM analytics, or LLMA) – monitor AI/LLM application costs, latency, and quality
-- **Data warehouse** – connect external data sources (Stripe, Hubspot, Postgres, etc.) for combined analysis
+- **Data warehouse**: Import data from SaaS tools, databases, Amazon S3, Google Cloud Storage, Azure Blob, and Cloudflare R2. Upload local files in the app.
- **Data pipelines (CDP)** – import data from 20+ sources, transform events in real-time, and export to external destinations
- **Revenue analytics** – track and analyze revenue metrics alongside product data
- **Logs** – collect and search application logs
diff --git a/products/posthog_ai/skills/querying-posthog-data/references/models-data-warehouse.md.j2 b/products/posthog_ai/skills/querying-posthog-data/references/models-data-warehouse.md.j2
index 9340dab58cb4..c4e7546e43bc 100644
--- a/products/posthog_ai/skills/querying-posthog-data/references/models-data-warehouse.md.j2
+++ b/products/posthog_ai/skills/querying-posthog-data/references/models-data-warehouse.md.j2
@@ -2,7 +2,7 @@
## External Data Source (`system.data_warehouse_sources`)
-External data sources represent connections to third-party data providers (Stripe, Hubspot, Postgres, etc.) that sync data into PostHog.
+External data sources connect providers, databases, and files to PostHog's data warehouse.
### Columns
@@ -18,7 +18,11 @@ Common source types include:
- `MySQL` - MySQL databases
- `Snowflake` - Snowflake data warehouse
- `BigQuery` - Google BigQuery
-- `S3` - Amazon S3 files
+- `AmazonS3` - Amazon S3 files
+- `GoogleCloudStorage` - Google Cloud Storage files
+- `AzureBlob` - Azure Blob files
+- `CloudflareR2` - Cloudflare R2 files
+- `FileUpload` - Files uploaded through the PostHog app
- `Zendesk` - Customer support data
- `Salesforce` - CRM data
@@ -30,7 +34,7 @@ Common source types include:
## Data Warehouse Table (`system.data_warehouse_tables`)
-Individual tables synced from external sources or manually uploaded. Each table contains columns with their types and metadata.
+Individual tables imported from external sources or uploaded files. Each table contains columns with their types and metadata.
### Columns
@@ -70,7 +74,7 @@ The `columns` field contains column definitions with their types:
- The `columns` field is synced from the actual data schema
- `valid: false` columns may have type mismatches or other issues
- Tables with `external_data_source_id` are managed by the sync system
-- Tables without a source are user-uploaded or manually created
+- An uploaded file gets a `FileUpload` source. A missing source can indicate a legacy table awaiting migration or its first sync.
---
diff --git a/products/warehouse_sources/mcp/tools.yaml b/products/warehouse_sources/mcp/tools.yaml
index 9f95795567db..a4e18c09d761 100644
--- a/products/warehouse_sources/mcp/tools.yaml
+++ b/products/warehouse_sources/mcp/tools.yaml
@@ -43,25 +43,29 @@ tools:
title: Set up a data warehouse source (one step)
description: >
Reach for this the moment a user wants to analyze data PostHog doesn't store — Stripe revenue, Hubspot or
- Salesforce CRM, Zendesk tickets, Shopify orders, or their own Postgres/MySQL/BigQuery/Snowflake database.
- Connect an external data source and start importing it into queryable warehouse tables in a single call.
- Validates credentials, discovers all available tables, enables them with sensible sync defaults (incremental
- where supported to keep ongoing cost low), and creates the source — no 'schemas' array required. For
- webhook-capable sources (e.g. Stripe) a webhook is auto-registered after creation: check the 'webhook' key
- in the response — on success webhook-capable tables sync in real time (including webhook-only tables like
- Stripe Discount); on failure (e.g. the API key can't create webhooks) tables keep the polling defaults and
- webhook-only tables stay disabled. If 'webhook.pending_inputs' is non-empty, ask the user for those values
- and submit them via 'external-data-sources-update-webhook-inputs-create'. Use this for revenue (Stripe), CRM
- (Hubspot, Salesforce), support tickets (Zendesk), e-commerce (Shopify), and your own databases (Postgres,
- MySQL, BigQuery, Snowflake). Discover required credential fields per source_type with
- 'external-data-sources-wizard'. Prefer references over raw secrets in the payload: pass {'credential_id':
- '<uuid>'} referencing the connection details the user stored via the 'data-warehouse-source-connect-link'
- page (discover ids with 'data-warehouse-stored-credentials-list'); stored credentials are deleted once the
- source is created. For an already-connected OAuth integration you can instead pass its integration id key
- (e.g. {'hubspot_integration_id': 123}). NOTE: this enables EVERY discovered table — ideal for small fixed
- schemas (Stripe, Zendesk) but on a large production database (a Postgres/MySQL/BigQuery/Snowflake with many
- tables) it syncs them all, which can be costly and noisy. When the user wants only specific tables, or
- non-default sync types per table, use 'external-data-sources-create' instead.
+ Salesforce CRM, Zendesk tickets, Shopify orders, their own database, or files in an Amazon S3, Google Cloud
+ Storage, Azure Blob, or Cloudflare R2 bucket. Use source_type AmazonS3, GoogleCloudStorage, AzureBlob, or
+ CloudflareR2 for bucket files. For a local file, ask the user to upload it in the PostHog app. That flow
+ creates a FileUpload source; no MCP tool uploads files. Connect an external data source and start importing
+ it into queryable warehouse tables in a single call. Validates credentials, discovers all available tables,
+ enables them with sensible sync defaults (incremental where supported to keep ongoing cost low), and creates
+ the source. No 'schemas' array is required. Bucket sources use full_refresh by default. For webhook-capable
+ sources (e.g. Stripe), a webhook is auto-registered after creation: check the 'webhook' key in the response
+ — on success webhook-capable tables sync in real time (including webhook-only tables like Stripe Discount);
+ on failure (e.g. the API key can't create webhooks) tables keep the polling defaults and webhook-only tables
+ stay disabled. If 'webhook.pending_inputs' is non-empty, ask the user for those values and submit them via
+ 'external-data-sources-update-webhook-inputs-create'. Use this for revenue (Stripe), CRM (Hubspot,
+ Salesforce), support tickets (Zendesk), e-commerce (Shopify), your own databases (Postgres, MySQL, BigQuery,
+ Snowflake), and bucket files (AmazonS3, GoogleCloudStorage, AzureBlob, CloudflareR2). Discover required
+ credential fields per source_type with 'external-data-sources-wizard'. Prefer references over raw secrets in
+ the payload: pass {'credential_id': '<uuid>'} referencing the connection details the user stored via the
+ 'data-warehouse-source-connect-link' page (discover ids with 'data-warehouse-stored-credentials-list');
+ stored credentials are deleted once the source is created. For an already-connected OAuth integration you
+ can instead pass its integration id key (e.g. {'hubspot_integration_id': 123}). NOTE: this enables EVERY
+ discovered table — ideal for small fixed schemas (Stripe, Zendesk) but on a large production database (a
+ Postgres/MySQL/BigQuery/Snowflake with many tables) it syncs them all, which can be costly and noisy. When
+ the user wants only specific tables, or non-default sync types per table, use 'external-data-sources-create'
+ instead.
exclude_params:
- client_secret
- account_id
@@ -157,12 +161,14 @@ tools:
list: true
title: List data warehouse table schemas (imported tables)
description: >
- List all table schemas across all data warehouse sources. Each schema represents one table being synced from
- an external source. Returns the schema name, sync status, sync frequency, incremental field configuration,
- last_synced_at, and latest error. Use this to see which tables are actively syncing and their health. To
- check one table's freshness, pass `search` with the table/schema name to narrow to that schema. Column
- definitions are omitted here — use external-data-schemas-retrieve for a single schema's columns. When a
- table stopped syncing, check `incremental_sync_blocked`: it names why the last run could not merge on the
+ List all table schemas across all data warehouse sources. Each schema represents one table linked to an
+ external source. A migrated table with pending_self_managed_table=true and should_sync=false still reads its
+ original bucket. Its first sync imports the table. Read the syncing-migrated-self-managed-tables skill
+ before you turn syncing on. Returns the schema name, sync status, sync frequency, incremental field
+ configuration, last_synced_at, and latest error. Use this to see which tables are actively syncing and their
+ health. To check one table's freshness, pass `search` with the table/schema name to narrow to that schema.
+ Column definitions are omitted here — use external-data-schemas-retrieve for a single schema's columns. When
+ a table stopped syncing, check `incremental_sync_blocked`: it names why the last run could not merge on the
table's primary key, and the table is disabled until that is resolved. A retry with nothing changed fails
the same way; a later run that succeeds, or fails for another reason, clears it. That field's description
lists the resolutions, which are applied with 'external-data-schemas-partial-update'.
@@ -318,7 +324,8 @@ tools:
primary_key_columns. Build the entries from the rows returned by 'external-data-sources-db-schema' first.
Omit 'schemas' entirely and every discovered table syncs with default settings. Sources back queryable
warehouse tables for revenue (Stripe), CRM (Hubspot, Salesforce), support (Zendesk), and your own databases
- (Postgres, MySQL, BigQuery).
+ (Postgres, MySQL, BigQuery) or bucket files (AmazonS3, GoogleCloudStorage, AzureBlob, CloudflareR2). For a
+ local file, direct the user to upload it in the PostHog app. The upload creates a FileUpload source.
exclude_params:
- client_secret
- account_id
@@ -575,15 +582,17 @@ tools:
description: >
Use this whenever the user needs data PostHog doesn't capture natively — revenue and payments (Stripe,
Chargebee), CRM contacts and deals (Hubspot, Salesforce), support tickets (Zendesk), e-commerce orders
- (Shopify), ad spend, or their own application/production database (Postgres, MySQL, BigQuery, Snowflake) —
- or when a HogQL query fails because the table doesn't exist yet. Importing turns that data into queryable
- warehouse tables you can JOIN against product events. Returns the configuration metadata for every supported
- source type: the required fields (host, port, database, credentials, etc.), field types, and OAuth flows, so
- you know what a connection needs. ALWAYS pass 'source_type' with the specific kind(s) you need
- (comma-separated, e.g. 'Postgres,Stripe') — the unfiltered response describes every source and is very large
- (hundreds of KB). Only omit 'source_type' if you genuinely need to enumerate every available type — and when
- enumerating, pass fields: ['*.name', '*.caption'] to skip the large per-source field definitions. To
- actually connect a source, prefer 'data-warehouse-source-setup'.
+ (Shopify), ad spend, their own database (Postgres, MySQL, BigQuery, Snowflake), or files in an Amazon S3,
+ Google Cloud Storage, Azure Blob, or Cloudflare R2 bucket. Use it when a HogQL query fails because the table
+ doesn't exist yet. Importing turns that data into queryable warehouse tables you can JOIN against product
+ events. Returns the configuration metadata for every supported source type: the required fields (host, port,
+ database, credentials, etc.), field types, and OAuth flows, so you know what a connection needs. ALWAYS pass
+ 'source_type' with the specific kind(s) you need (comma-separated, e.g. 'Postgres,Stripe') — the unfiltered
+ response describes every source and is very large (hundreds of KB). Only omit 'source_type' if you genuinely
+ need to enumerate every available type — and when enumerating, pass fields: ['*.name', '*.caption'] to skip
+ the large per-source field definitions. To actually connect a bucket source, use source_type AmazonS3,
+ GoogleCloudStorage, AzureBlob, or CloudflareR2 with 'data-warehouse-source-setup'. 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.
response:
include:
- '*.name'
diff --git a/products/warehouse_sources/skills/setting-up-a-data-warehouse-source/SKILL.md b/products/warehouse_sources/skills/setting-up-a-data-warehouse-source/SKILL.md
index b44eb1d0efdc..b20e1a40339b 100644
--- a/products/warehouse_sources/skills/setting-up-a-data-warehouse-source/SKILL.md
+++ b/products/warehouse_sources/skills/setting-up-a-data-warehouse-source/SKILL.md
@@ -1,10 +1,10 @@
---
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
+ 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).
---
@@ -13,6 +13,12 @@ description: >
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`
@@ -22,6 +28,7 @@ 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
@@ -156,6 +163,9 @@ Match the user's request to a source. If they said "Postgres", look up `Postgres
like "database", present the top relevant matches (Postgres, MySQL, MongoDB, BigQuery, Snowflake, Redshift) and let
them pick.
+For bucket files, use the canonical `source_type`: `AmazonS3`, `GoogleCloudStorage`, `AzureBlob`, or `CloudflareR2`.
+For a local file, use the app's upload flow. It creates a `FileUpload` source after the user uploads the file.
+
For OAuth-based sources (Hubspot, Salesforce, Google Ads), the wizard entry hints at an OAuth flow. These typically
need the user to authorize in the PostHog UI rather than pasting credentials — explain this and direct them to the
source setup page rather than trying to collect tokens in chat. OAuth is about _authentication_, not about how data
diff --git a/products/warehouse_sources/skills/setting-up-a-data-warehouse-source/references/sync-types.md b/products/warehouse_sources/skills/setting-up-a-data-warehouse-source/references/sync-types.md
index cd5ccbb4954f..d3e794dbcecc 100644
--- a/products/warehouse_sources/skills/setting-up-a-data-warehouse-source/references/sync-types.md
+++ b/products/warehouse_sources/skills/setting-up-a-data-warehouse-source/references/sync-types.md
@@ -16,17 +16,20 @@ much it costs, how fresh the data is, and what shape it has after import.
## The five sync types
-| Sync type | What it does | Requires | Good for |
-| -------------- | -------------------------------------------------------- | ---------------------------------------------- | ---------------------------------------------------- |
-| `full_refresh` | Drops everything, re-imports the whole table each sync | Nothing | Small tables, dimension tables, when in doubt |
-| `incremental` | Imports only rows where `incremental_field > last_value` | `incremental_field` + `incremental_field_type` | Large tables with an `updated_at` / `modified_at` |
-| `append` | Like incremental but keeps prior versions of rows | `incremental_field` + `incremental_field_type` | Immutable or append-only tables (events, logs) |
-| `cdc` | Streams changes via Postgres logical replication | Postgres, primary keys, wal_level=logical | Near-real-time, large Postgres tables |
-| `webhook` | Real-time push ingestion via source-side webhook | Source must implement `WebhookSource` | Near-real-time from sources that support it (Stripe) |
+| Sync type | What it does | Requires | Good for |
+| -------------- | ------------------------------------------------------ | ---------------------------------------------- | ---------------------------------------------------- |
+| `full_refresh` | Drops everything, re-imports the whole table each sync | Nothing | Small tables, dimension tables, when in doubt |
+| `incremental` | Imports changed rows, files, or Delta versions | `incremental_field` + `incremental_field_type` | Large tables with changes since the last sync |
+| `append` | Like incremental but keeps prior versions of rows | `incremental_field` + `incremental_field_type` | Immutable or append-only tables (events, logs) |
+| `cdc` | Streams changes via Postgres logical replication | Postgres, primary keys, wal_level=logical | Near-real-time, large Postgres tables |
+| `webhook` | Real-time push ingestion via source-side webhook | Source must implement `WebhookSource` | Near-real-time from sources that support it (Stripe) |
Not every source supports every type — the `db-schema` response surfaces which are available per-table via
`incremental_available`, `append_available`, `cdc_available`, `supports_webhooks`.
+For database tables, incremental sync imports rows where `incremental_field > last_value`. For object storage files,
+it tracks changed files with `_file_modified_at`. For Delta tables, it tracks changed versions with `_delta_version`.
+
## How to choose
**Small table, no obvious ordering column** → `full_refresh`.
@@ -61,8 +64,9 @@ not sufficient. Tables on the same source that don't support webhooks need a nor
## Picking an `incremental_field`
-Must be present in the `incremental_fields` list returned by `db-schema`. Not every column qualifies — the source
-only surfaces timestamp/integer/ObjectID columns that it can filter cheaply.
+Must be present in the `incremental_fields` list returned by `db-schema`. Database sources offer columns they can
+filter, such as timestamps, integers, or ObjectIDs. Object storage sources offer `_file_modified_at` for files or
+`_delta_version` for Delta tables.
Priority order:
diff --git a/products/warehouse_sources/skills/suggesting-data-imports/SKILL.md b/products/warehouse_sources/skills/suggesting-data-imports/SKILL.md
index 814114067195..cbc46318268f 100644
--- a/products/warehouse_sources/skills/suggesting-data-imports/SKILL.md
+++ b/products/warehouse_sources/skills/suggesting-data-imports/SKILL.md
@@ -1,6 +1,6 @@
---
name: suggesting-data-imports
-description: 'Use when the user asks about revenue, payments, subscriptions, billing, CRM deals, support tickets, ad spend, production database tables, or other data PostHog does not collect natively — or wants to join or correlate PostHog product events with that external business data. Also use when a query fails because a table does not exist or returns no results for expected external data. The data warehouse can import from SaaS tools (Stripe, Hubspot, Zendesk, etc.), ad platforms, production databases (Postgres, MySQL, BigQuery, Snowflake), and other arbitrary data sources. Covers checking existing sources, identifying the right source type, and guiding the setup.'
+description: 'Use when the user asks about revenue, payments, subscriptions, billing, CRM deals, support tickets, ad spend, production database tables, bucket files, or local file uploads. Also use when the user wants to join PostHog events with external data, or when a query fails because an expected table is missing. The data warehouse can import from SaaS tools, ad platforms, databases, object storage, and uploaded files. Covers checking existing sources, identifying the right source type, and guiding setup.'
---
# Suggesting data imports
@@ -19,6 +19,7 @@ PostHog collects product analytics events, persons, sessions, and groups via its
- The user asks "how do I get my X data into PostHog?"
- Analysis requires joining PostHog events with external data
- The user asks about exporting PostHog data for comparison elsewhere (in a google sheet, external warehouse, etc)
+- The user wants to import files from a bucket or upload a local file
## Workflow
@@ -27,6 +28,7 @@ PostHog collects product analytics events, persons, sessions, and groups via its
Listen for signals that the user needs external data:
- They mention a specific tool or system (Stripe, Hubspot, Zendesk, their production database, etc.)
+- They mention bucket files or a local CSV, JSON, or Parquet file
- A query references a table that doesn't exist in PostHog
- They want to analyze something PostHog doesn't track natively (revenue, support tickets, CRM deals, etc.)
@@ -59,6 +61,9 @@ definitions. Match the user's need to a source:
| Project management | Linear | issues, projects |
| Error tracking (external) | Sentry | issues, events |
+For bucket files, use `AmazonS3`, `GoogleCloudStorage`, `AzureBlob`, or `CloudflareR2`. For local files, use the
+PostHog app upload flow. It creates a `FileUpload` source.
+
### 4. Suggest the import
Present the recommendation concisely:
@@ -77,6 +82,9 @@ credentials securely in the browser rather than in chat. For anything beyond the
non-default sync types, webhooks, CDC), hand off to the **`setting-up-a-data-warehouse-source`** skill, which covers
the full flow, sync-type selection, webhook registration, and prefix guidance. Do not duplicate that workflow here.
+For a local file, direct the user to upload it in the PostHog app. The upload creates a `FileUpload` source. No MCP
+tool uploads files.
+
### 6. Show what's possible after import
Once connected, help the user write their first query joining PostHog data with the imported data. Use `posthog:execute-sql` to demonstrate.
diff --git a/products/warehouse_sources/skills/syncing-migrated-self-managed-tables/SKILL.md b/products/warehouse_sources/skills/syncing-migrated-self-managed-tables/SKILL.md
index b608a47df479..ed6e2d54f49d 100644
--- a/products/warehouse_sources/skills/syncing-migrated-self-managed-tables/SKILL.md
+++ b/products/warehouse_sources/skills/syncing-migrated-self-managed-tables/SKILL.md
@@ -10,8 +10,8 @@ description: >
# Syncing migrated self-managed tables
-PostHog no longer links tables that read a bucket directly. Every existing self-managed table now has a managed source
-and a schema that is turned off. The table keeps working and keeps its name. It costs nothing until someone turns
+PostHog no longer links tables that read a bucket directly. Eligible existing self-managed tables now have a managed
+source and a schema that is turned off. The table keeps working and keeps its name. It costs nothing until someone turns
syncing on. Turning syncing on starts billing, so the user must agree first.
## What happened
diff --git a/services/mcp/schema/generated-tool-definitions.json b/services/mcp/schema/generated-tool-definitions.json
index ad0d0a5aac0a..514bdc0fa1ac 100644
--- a/services/mcp/schema/generated-tool-definitions.json
+++ b/services/mcp/schema/generated-tool-definitions.json
@@ -4659,7 +4659,7 @@
}
},
"data-warehouse-source-setup": {
- "description": "Reach for this the moment a user wants to analyze data PostHog doesn't store — Stripe revenue, Hubspot or Salesforce CRM, Zendesk tickets, Shopify orders, or their own Postgres/MySQL/BigQuery/Snowflake database. Connect an external data source and start importing it into queryable warehouse tables in a single call. Validates credentials, discovers all available tables, enables them with sensible sync defaults (incremental where supported to keep ongoing cost low), and creates the source — no 'schemas' array required. For webhook-capable sources (e.g. Stripe) a webhook is auto-registered after creation: check the 'webhook' key in the response — on success webhook-capable tables sync in real time (including webhook-only tables like Stripe Discount); on failure (e.g. the API key can't create webhooks) tables keep the polling defaults and webhook-only tables stay disabled. If 'webhook.pending_inputs' is non-empty, ask the user for those values and submit them via 'external-data-sources-update-webhook-inputs-create'. Use this for revenue (Stripe), CRM (Hubspot, Salesforce), support tickets (Zendesk), e-commerce (Shopify), and your own databases (Postgres, MySQL, BigQuery, Snowflake). Discover required credential fields per source_type with 'external-data-sources-wizard'. Prefer references over raw secrets in the payload: pass {'credential_id': '<uuid>'} referencing the connection details the user stored via the 'data-warehouse-source-connect-link' page (discover ids with 'data-warehouse-stored-credentials-list'); stored credentials are deleted once the source is created. For an already-connected OAuth integration you can instead pass its integration id key (e.g. {'hubspot_integration_id': 123}). NOTE: this enables EVERY discovered table — ideal for small fixed schemas (Stripe, Zendesk) but on a large production database (a Postgres/MySQL/BigQuery/Snowflake with many tables) it syncs them all, which can be costly and noisy. When the user wants only specific tables, or non-default sync types per table, use 'external-data-sources-create' instead.",
+ "description": "Reach for this the moment a user wants to analyze data PostHog doesn't store — Stripe revenue, Hubspot or Salesforce CRM, Zendesk tickets, Shopify orders, their own database, or files in an Amazon S3, Google Cloud Storage, Azure Blob, or Cloudflare R2 bucket. Use source_type AmazonS3, GoogleCloudStorage, AzureBlob, or CloudflareR2 for bucket files. For a local file, ask the user to upload it in the PostHog app. That flow creates a FileUpload source; no MCP tool uploads files. Connect an external data source and start importing it into queryable warehouse tables in a single call. Validates credentials, discovers all available tables, enables them with sensible sync defaults (incremental where supported to keep ongoing cost low), and creates the source. No 'schemas' array is required. Bucket sources use full_refresh by default. For webhook-capable sources (e.g. Stripe), a webhook is auto-registered after creation: check the 'webhook' key in the response — on success webhook-capable tables sync in real time (including webhook-only tables like Stripe Discount); on failure (e.g. the API key can't create webhooks) tables keep the polling defaults and webhook-only tables stay disabled. If 'webhook.pending_inputs' is non-empty, ask the user for those values and submit them via 'external-data-sources-update-webhook-inputs-create'. Use this for revenue (Stripe), CRM (Hubspot, Salesforce), support tickets (Zendesk), e-commerce (Shopify), your own databases (Postgres, MySQL, BigQuery, Snowflake), and bucket files (AmazonS3, GoogleCloudStorage, AzureBlob, CloudflareR2). Discover required credential fields per source_type with 'external-data-sources-wizard'. Prefer references over raw secrets in the payload: pass {'credential_id': '<uuid>'} referencing the connection details the user stored via the 'data-warehouse-source-connect-link' page (discover ids with 'data-warehouse-stored-credentials-list'); stored credentials are deleted once the source is created. For an already-connected OAuth integration you can instead pass its integration id key (e.g. {'hubspot_integration_id': 123}). NOTE: this enables EVERY discovered table — ideal for small fixed schemas (Stripe, Zendesk) but on a large production database (a Postgres/MySQL/BigQuery/Snowflake with many tables) it syncs them all, which can be costly and noisy. When the user wants only specific tables, or non-default sync types per table, use 'external-data-sources-create' instead.",
"category": "Warehouse sources",
"feature": "warehouse_sources",
"summary": "Set up a data warehouse source (one step)",
@@ -6486,7 +6486,7 @@
}
},
"external-data-schemas-list": {
- "description": "List all table schemas across all data warehouse sources. Each schema represents one table being synced from an external source. Returns the schema name, sync status, sync frequency, incremental field configuration, last_synced_at, and latest error. Use this to see which tables are actively syncing and their health. To check one table's freshness, pass `search` with the table/schema name to narrow to that schema. Column definitions are omitted here — use external-data-schemas-retrieve for a single schema's columns. When a table stopped syncing, check `incremental_sync_blocked`: it names why the last run could not merge on the table's primary key, and the table is disabled until that is resolved. A retry with nothing changed fails the same way; a later run that succeeds, or fails for another reason, clears it. That field's description lists the resolutions, which are applied with 'external-data-schemas-partial-update'.",
+ "description": "List all table schemas across all data warehouse sources. Each schema represents one table linked to an external source. A migrated table with pending_self_managed_table=true and should_sync=false still reads its original bucket. Its first sync imports the table. Read the syncing-migrated-self-managed-tables skill before you turn syncing on. Returns the schema name, sync status, sync frequency, incremental field configuration, last_synced_at, and latest error. Use this to see which tables are actively syncing and their health. To check one table's freshness, pass `search` with the table/schema name to narrow to that schema. Column definitions are omitted here — use external-data-schemas-retrieve for a single schema's columns. When a table stopped syncing, check `incremental_sync_blocked`: it names why the last run could not merge on the table's primary key, and the table is disabled until that is resolved. A retry with nothing changed fails the same way; a later run that succeeds, or fails for another reason, clears it. That field's description lists the resolutions, which are applied with 'external-data-schemas-partial-update'.",
"category": "Warehouse sources",
"feature": "warehouse_sources",
"summary": "List data warehouse table schemas (imported tables)",
@@ -6606,7 +6606,7 @@
}
},
"external-data-sources-create": {
- "description": "Low-level create for a data warehouse import source when you need to hand-pick tables and sync types. If you only have credentials and want every table, call 'data-warehouse-source-setup' instead — one call, fewer ways to get it wrong. Use this path when the user asked for specific tables or sync types. The 'schemas' array is NOT a top-level argument — it goes INSIDE 'payload', alongside the credential fields: payload = {<credential fields…>, \"schemas\": [...]}. Each schemas entry has: name, should_sync (bool), sync_type (incremental/full_refresh/append), and optionally incremental_field, incremental_field_type, and primary_key_columns. Build the entries from the rows returned by 'external-data-sources-db-schema' first. Omit 'schemas' entirely and every discovered table syncs with default settings. Sources back queryable warehouse tables for revenue (Stripe), CRM (Hubspot, Salesforce), support (Zendesk), and your own databases (Postgres, MySQL, BigQuery).",
+ "description": "Low-level create for a data warehouse import source when you need to hand-pick tables and sync types. If you only have credentials and want every table, call 'data-warehouse-source-setup' instead — one call, fewer ways to get it wrong. Use this path when the user asked for specific tables or sync types. The 'schemas' array is NOT a top-level argument — it goes INSIDE 'payload', alongside the credential fields: payload = {<credential fields…>, \"schemas\": [...]}. Each schemas entry has: name, should_sync (bool), sync_type (incremental/full_refresh/append), and optionally incremental_field, incremental_field_type, and primary_key_columns. Build the entries from the rows returned by 'external-data-sources-db-schema' first. Omit 'schemas' entirely and every discovered table syncs with default settings. Sources back queryable warehouse tables for revenue (Stripe), CRM (Hubspot, Salesforce), support (Zendesk), and your own databases (Postgres, MySQL, BigQuery) or bucket files (AmazonS3, GoogleCloudStorage, AzureBlob, CloudflareR2). For a local file, direct the user to upload it in the PostHog app. The upload creates a FileUpload source.",
"category": "Warehouse sources",
"feature": "warehouse_sources",
"summary": "Create data warehouse source (advanced; prefer source setup)",
@@ -6818,7 +6818,7 @@
}
},
"external-data-sources-wizard": {
- "description": "Use this whenever the user needs data PostHog doesn't capture natively — revenue and payments (Stripe, Chargebee), CRM contacts and deals (Hubspot, Salesforce), support tickets (Zendesk), e-commerce orders (Shopify), ad spend, or their own application/production database (Postgres, MySQL, BigQuery, Snowflake) — or when a HogQL query fails because the table doesn't exist yet. Importing turns that data into queryable warehouse tables you can JOIN against product events. Returns the configuration metadata for every supported source type: the required fields (host, port, database, credentials, etc.), field types, and OAuth flows, so you know what a connection needs. ALWAYS pass 'source_type' with the specific kind(s) you need (comma-separated, e.g. 'Postgres,Stripe') — the unfiltered response describes every source and is very large (hundreds of KB). Only omit 'source_type' if you genuinely need to enumerate every available type — and when enumerating, pass fields: ['*.name', '*.caption'] to skip the large per-source field definitions. To actually connect a source, prefer 'data-warehouse-source-setup'.",
+ "description": "Use this whenever the user needs data PostHog doesn't capture natively — revenue and payments (Stripe, Chargebee), CRM contacts and deals (Hubspot, Salesforce), support tickets (Zendesk), e-commerce orders (Shopify), ad spend, their own database (Postgres, MySQL, BigQuery, Snowflake), or files in an Amazon S3, Google Cloud Storage, Azure Blob, or Cloudflare R2 bucket. Use it when a HogQL query fails because the table doesn't exist yet. Importing turns that data into queryable warehouse tables you can JOIN against product events. Returns the configuration metadata for every supported source type: the required fields (host, port, database, credentials, etc.), field types, and OAuth flows, so you know what a connection needs. ALWAYS pass 'source_type' with the specific kind(s) you need (comma-separated, e.g. 'Postgres,Stripe') — the unfiltered response describes every source and is very large (hundreds of KB). Only omit 'source_type' if you genuinely need to enumerate every available type — and when enumerating, pass fields: ['*.name', '*.caption'] to skip the large per-source field definitions. To actually connect a bucket source, use source_type AmazonS3, GoogleCloudStorage, AzureBlob, or CloudflareR2 with 'data-warehouse-source-setup'. 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.",
"category": "Warehouse sources",
"feature": "warehouse_sources",
"summary": "List data warehouse source types you can import",
diff --git a/services/mcp/schema/tool-definitions-all.json b/services/mcp/schema/tool-definitions-all.json
index 5c5312cf7487..c487d7bebf50 100644
--- a/services/mcp/schema/tool-definitions-all.json
+++ b/services/mcp/schema/tool-definitions-all.json
@@ -4674,7 +4674,7 @@
}
},
"data-warehouse-source-setup": {
- "description": "Reach for this the moment a user wants to analyze data PostHog doesn't store — Stripe revenue, Hubspot or Salesforce CRM, Zendesk tickets, Shopify orders, or their own Postgres/MySQL/BigQuery/Snowflake database. Connect an external data source and start importing it into queryable warehouse tables in a single call. Validates credentials, discovers all available tables, enables them with sensible sync defaults (incremental where supported to keep ongoing cost low), and creates the source — no 'schemas' array required. For webhook-capable sources (e.g. Stripe) a webhook is auto-registered after creation: check the 'webhook' key in the response — on success webhook-capable tables sync in real time (including webhook-only tables like Stripe Discount); on failure (e.g. the API key can't create webhooks) tables keep the polling defaults and webhook-only tables stay disabled. If 'webhook.pending_inputs' is non-empty, ask the user for those values and submit them via 'external-data-sources-update-webhook-inputs-create'. Use this for revenue (Stripe), CRM (Hubspot, Salesforce), support tickets (Zendesk), e-commerce (Shopify), and your own databases (Postgres, MySQL, BigQuery, Snowflake). Discover required credential fields per source_type with 'external-data-sources-wizard'. Prefer references over raw secrets in the payload: pass {'credential_id': '<uuid>'} referencing the connection details the user stored via the 'data-warehouse-source-connect-link' page (discover ids with 'data-warehouse-stored-credentials-list'); stored credentials are deleted once the source is created. For an already-connected OAuth integration you can instead pass its integration id key (e.g. {'hubspot_integration_id': 123}). NOTE: this enables EVERY discovered table — ideal for small fixed schemas (Stripe, Zendesk) but on a large production database (a Postgres/MySQL/BigQuery/Snowflake with many tables) it syncs them all, which can be costly and noisy. When the user wants only specific tables, or non-default sync types per table, use 'external-data-sources-create' instead.",
+ "description": "Reach for this the moment a user wants to analyze data PostHog doesn't store — Stripe revenue, Hubspot or Salesforce CRM, Zendesk tickets, Shopify orders, their own database, or files in an Amazon S3, Google Cloud Storage, Azure Blob, or Cloudflare R2 bucket. Use source_type AmazonS3, GoogleCloudStorage, AzureBlob, or CloudflareR2 for bucket files. For a local file, ask the user to upload it in the PostHog app. That flow creates a FileUpload source; no MCP tool uploads files. Connect an external data source and start importing it into queryable warehouse tables in a single call. Validates credentials, discovers all available tables, enables them with sensible sync defaults (incremental where supported to keep ongoing cost low), and creates the source. No 'schemas' array is required. Bucket sources use full_refresh by default. For webhook-capable sources (e.g. Stripe), a webhook is auto-registered after creation: check the 'webhook' key in the response — on success webhook-capable tables sync in real time (including webhook-only tables like Stripe Discount); on failure (e.g. the API key can't create webhooks) tables keep the polling defaults and webhook-only tables stay disabled. If 'webhook.pending_inputs' is non-empty, ask the user for those values and submit them via 'external-data-sources-update-webhook-inputs-create'. Use this for revenue (Stripe), CRM (Hubspot, Salesforce), support tickets (Zendesk), e-commerce (Shopify), your own databases (Postgres, MySQL, BigQuery, Snowflake), and bucket files (AmazonS3, GoogleCloudStorage, AzureBlob, CloudflareR2). Discover required credential fields per source_type with 'external-data-sources-wizard'. Prefer references over raw secrets in the payload: pass {'credential_id': '<uuid>'} referencing the connection details the user stored via the 'data-warehouse-source-connect-link' page (discover ids with 'data-warehouse-stored-credentials-list'); stored credentials are deleted once the source is created. For an already-connected OAuth integration you can instead pass its integration id key (e.g. {'hubspot_integration_id': 123}). NOTE: this enables EVERY discovered table — ideal for small fixed schemas (Stripe, Zendesk) but on a large production database (a Postgres/MySQL/BigQuery/Snowflake with many tables) it syncs them all, which can be costly and noisy. When the user wants only specific tables, or non-default sync types per table, use 'external-data-sources-create' instead.",
"category": "Warehouse sources",
"feature": "warehouse_sources",
"summary": "Set up a data warehouse source (one step)",
@@ -6619,7 +6619,7 @@
}
},
"external-data-schemas-list": {
- "description": "List all table schemas across all data warehouse sources. Each schema represents one table being synced from an external source. Returns the schema name, sync status, sync frequency, incremental field configuration, last_synced_at, and latest error. Use this to see which tables are actively syncing and their health. To check one table's freshness, pass `search` with the table/schema name to narrow to that schema. Column definitions are omitted here — use external-data-schemas-retrieve for a single schema's columns. When a table stopped syncing, check `incremental_sync_blocked`: it names why the last run could not merge on the table's primary key, and the table is disabled until that is resolved. A retry with nothing changed fails the same way; a later run that succeeds, or fails for another reason, clears it. That field's description lists the resolutions, which are applied with 'external-data-schemas-partial-update'.",
+ "description": "List all table schemas across all data warehouse sources. Each schema represents one table linked to an external source. A migrated table with pending_self_managed_table=true and should_sync=false still reads its original bucket. Its first sync imports the table. Read the syncing-migrated-self-managed-tables skill before you turn syncing on. Returns the schema name, sync status, sync frequency, incremental field configuration, last_synced_at, and latest error. Use this to see which tables are actively syncing and their health. To check one table's freshness, pass `search` with the table/schema name to narrow to that schema. Column definitions are omitted here — use external-data-schemas-retrieve for a single schema's columns. When a table stopped syncing, check `incremental_sync_blocked`: it names why the last run could not merge on the table's primary key, and the table is disabled until that is resolved. A retry with nothing changed fails the same way; a later run that succeeds, or fails for another reason, clears it. That field's description lists the resolutions, which are applied with 'external-data-schemas-partial-update'.",
"category": "Warehouse sources",
"feature": "warehouse_sources",
"summary": "List data warehouse table schemas (imported tables)",
@@ -6739,7 +6739,7 @@
}
},
"external-data-sources-create": {
- "description": "Low-level create for a data warehouse import source when you need to hand-pick tables and sync types. If you only have credentials and want every table, call 'data-warehouse-source-setup' instead — one call, fewer ways to get it wrong. Use this path when the user asked for specific tables or sync types. The 'schemas' array is NOT a top-level argument — it goes INSIDE 'payload', alongside the credential fields: payload = {<credential fields…>, \"schemas\": [...]}. Each schemas entry has: name, should_sync (bool), sync_type (incremental/full_refresh/append), and optionally incremental_field, incremental_field_type, and primary_key_columns. Build the entries from the rows returned by 'external-data-sources-db-schema' first. Omit 'schemas' entirely and every discovered table syncs with default settings. Sources back queryable warehouse tables for revenue (Stripe), CRM (Hubspot, Salesforce), support (Zendesk), and your own databases (Postgres, MySQL, BigQuery).",
+ "description": "Low-level create for a data warehouse import source when you need to hand-pick tables and sync types. If you only have credentials and want every table, call 'data-warehouse-source-setup' instead — one call, fewer ways to get it wrong. Use this path when the user asked for specific tables or sync types. The 'schemas' array is NOT a top-level argument — it goes INSIDE 'payload', alongside the credential fields: payload = {<credential fields…>, \"schemas\": [...]}. Each schemas entry has: name, should_sync (bool), sync_type (incremental/full_refresh/append), and optionally incremental_field, incremental_field_type, and primary_key_columns. Build the entries from the rows returned by 'external-data-sources-db-schema' first. Omit 'schemas' entirely and every discovered table syncs with default settings. Sources back queryable warehouse tables for revenue (Stripe), CRM (Hubspot, Salesforce), support (Zendesk), and your own databases (Postgres, MySQL, BigQuery) or bucket files (AmazonS3, GoogleCloudStorage, AzureBlob, CloudflareR2). For a local file, direct the user to upload it in the PostHog app. The upload creates a FileUpload source.",
"category": "Warehouse sources",
"feature": "warehouse_sources",
"summary": "Create data warehouse source (advanced; prefer source setup)",
@@ -6993,7 +6993,7 @@
}
},
"external-data-sources-wizard": {
- "description": "Use this whenever the user needs data PostHog doesn't capture natively — revenue and payments (Stripe, Chargebee), CRM contacts and deals (Hubspot, Salesforce), support tickets (Zendesk), e-commerce orders (Shopify), ad spend, or their own application/production database (Postgres, MySQL, BigQuery, Snowflake) — or when a HogQL query fails because the table doesn't exist yet. Importing turns that data into queryable warehouse tables you can JOIN against product events. Returns the configuration metadata for every supported source type: the required fields (host, port, database, credentials, etc.), field types, and OAuth flows, so you know what a connection needs. ALWAYS pass 'source_type' with the specific kind(s) you need (comma-separated, e.g. 'Postgres,Stripe') — the unfiltered response describes every source and is very large (hundreds of KB). Only omit 'source_type' if you genuinely need to enumerate every available type — and when enumerating, pass fields: ['*.name', '*.caption'] to skip the large per-source field definitions. To actually connect a source, prefer 'data-warehouse-source-setup'.",
+ "description": "Use this whenever the user needs data PostHog doesn't capture natively — revenue and payments (Stripe, Chargebee), CRM contacts and deals (Hubspot, Salesforce), support tickets (Zendesk), e-commerce orders (Shopify), ad spend, their own database (Postgres, MySQL, BigQuery, Snowflake), or files in an Amazon S3, Google Cloud Storage, Azure Blob, or Cloudflare R2 bucket. Use it when a HogQL query fails because the table doesn't exist yet. Importing turns that data into queryable warehouse tables you can JOIN against product events. Returns the configuration metadata for every supported source type: the required fields (host, port, database, credentials, etc.), field types, and OAuth flows, so you know what a connection needs. ALWAYS pass 'source_type' with the specific kind(s) you need (comma-separated, e.g. 'Postgres,Stripe') — the unfiltered response describes every source and is very large (hundreds of KB). Only omit 'source_type' if you genuinely need to enumerate every available type — and when enumerating, pass fields: ['*.name', '*.caption'] to skip the large per-source field definitions. To actually connect a bucket source, use source_type AmazonS3, GoogleCloudStorage, AzureBlob, or CloudflareR2 with 'data-warehouse-source-setup'. 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.",
"category": "Warehouse sources",
"feature": "warehouse_sources",
"summary": "List data warehouse source types you can import",
diff --git a/services/mcp/src/generated/data_warehouse/api.ts b/services/mcp/src/generated/data_warehouse/api.ts
index 299c47e82262..e007e7d4eb13 100644
--- a/services/mcp/src/generated/data_warehouse/api.ts
+++ b/services/mcp/src/generated/data_warehouse/api.ts
@@ -853,7 +853,7 @@ export const WarehouseSavedQueriesCheckIncrementalCreateBody = () => zod
.describe('Body of the `check_incremental` action: a query and an optional config to check it against.')
/**
- * Re-introspect a self-managed (manually linked) warehouse table's schema from its underlying source files and overwrite its stored column list. Use when the source schema has evolved (e.g. new columns in the underlying Delta/Parquet/CSV files) but queries still can't see the new columns, because PostHog serves a cached column snapshot until the table is refreshed. Not for tables managed by an external data source sync — those refresh on their own schedule.
+ * Re-introspect an existing direct-read warehouse table's schema from its underlying source files and overwrite its stored column list. Use when the source schema has evolved (e.g. new columns in the underlying Delta/Parquet/CSV files) but queries still can't see the new columns, because PostHog serves a cached column snapshot until the table is refreshed. This applies only to existing direct-read tables. New direct-read tables cannot be created. Tables managed by an external data source sync refresh on their own schedule.
* @summary Refresh table schema from source
*/
export const WarehouseTablesRefreshSchemaCreateParams = () => zod.object({
diff --git a/services/mcp/src/tools/exec.ts b/services/mcp/src/tools/exec.ts
index f2d2a7682f96..481073ea452b 100644
--- a/services/mcp/src/tools/exec.ts
+++ b/services/mcp/src/tools/exec.ts
@@ -690,7 +690,7 @@ const DEPRECATED_TOOL_REDIRECTS: Record<string, (allTools: Tool<ZodObjectAny>[])
'Tool "loops-run-create" was removed. Loops run on workflows. "workflows-test-run" tests the graph one node at a time and mocks outbound calls by default; it does not start a real task run. To fire a loop for real, use Run now on an enabled schedule loop in PostHog Desktop, or wait for its trigger.',
// Self-managed tables (reading a bucket in place) can no longer be created.
'warehouse-tables-create': () =>
- 'Tool "warehouse-tables-create" was removed. PostHog no longer links tables that read your bucket directly. To import files from a bucket, add an Amazon S3, Google Cloud Storage, Azure Blob or Cloudflare R2 source with "data-warehouse-source-setup" (run "external-data-sources-wizard" for the credential fields of each source type).',
+ 'Tool "warehouse-tables-create" was removed. PostHog no longer links tables that read your bucket directly. To import bucket files, add an Amazon S3, Google Cloud Storage, Azure Blob, or Cloudflare R2 source with "data-warehouse-source-setup". Run "external-data-sources-wizard" for the required fields. To import a local file, upload it in the PostHog app at /data-warehouse/new-source?kind=FileUpload. The upload creates a FileUpload source.',
'loops-runs-retrieve': () =>
'Tool "loops-runs-retrieve" was removed. Loops run on workflows. For run history, call "tasks-list" with the hog_flow_id of the loop and archived set to all, then "tasks-runs-retrieve" on a run for its branch and output.',
}