carto-connect-datawarehouse

carto-connect-datawarehouse

CARTO runs spatial analytics in the user's own data warehouse. A connection is the bridge between CARTO and that warehouse: it carries credentials, target project/database scoping, and sometimes a service account or PAT. Most other CARTO operations (querying, importing, building maps, running workflows) require an existing connection.

Task	MCP	CLI (fallback)
List / inspect connections	explore_data (list_connections on any session; get_connection is OAuth-only)	carto connections list / get
Create / update a connection	manage_connections (create, update) — OAuth session only	carto connections create / update
Delete a connection	delete (kind=connection) — OAuth session only	carto connections delete

Access-path routing. With the MCP server attached, list over explore_data (list_connections); create/update over manage_connections; delete over delete. On a token session only list_connections is available — get_connection and the write tools (manage_connections, delete) need OAuth, so fall back to the carto connections CLI. Also use the CLI when the server isn't attached or for scripted setups. The engine-choice guidance and pitfalls below apply on either path. Detection signals: carto-basics/references/access-paths.md.

When to use this skill

• The user wants to connect a new warehouse to CARTO.
• The user is debugging a connection (auth failures, missing tables, permission errors).
• A downstream skill needs a connection name and you don't yet know which engine the user has.
• The user is rotating credentials or moving from one project/database to another.

Use carto-explore-datawarehouse once a connection exists and you want to inspect what's inside it.

Quick lifecycle (CLI)

carto connections list --json             # what's already connected? (--all, --search "prod")
carto connections get <id>                # detailed view of one connection
carto connections create                  # interactive create
carto connections update <id>             # rotate credentials, change scoping
carto connections delete <id>             # remove (irreversible)

List/inspect are non-destructive — run them freely before deciding what to do. If the user already has a connection, don't push a new one — use the existing one.

Choosing an engine

Engine	When to choose it	Reference
BigQuery	Google Cloud users; CARTO's flagship integration; rich GIS functions native.	references/bigquery.md
Snowflake	Snowflake-shop customers; geospatial via SQL functions and native types.	references/snowflake.md
Redshift	AWS-shop customers on Redshift Serverless or RA3 clusters.	references/redshift.md
Postgres	Self-hosted or RDS Postgres with PostGIS; common for small/medium deployments.	references/postgres.md
Databricks	Lakehouse / Unity Catalog users; SQL Warehouses for interactive workloads.	references/databricks.md
Oracle	Oracle Database with Spatial; on-prem or OCI / Autonomous Database.	references/oracle.md

Common pitfalls

• Auth-mode mismatch: BigQuery supports OAuth (interactive) and service-account JSON (CI). Pick one consistently per environment; mixing the two breaks shared connections.
• Region vs project: Some engines need both an account/project and a region (Snowflake, Redshift). Skipping the region typically yields "endpoint not found" rather than a permissions error.
• Default database/schema scoping: CARTO writes tilesets, named sources, and analytics output back into the warehouse. Confirm which dataset/schema CARTO may write to before creating the connection.
• Permissions for describe and table reads come from the credential CARTO holds, not the user's CARTO role. A CARTO Admin with a low-privilege service account still sees "permission denied" from the warehouse.

What this skill doesn't cover

• Browsing tables/schemas of an existing connection — carto-explore-datawarehouse.
• Running SQL against the warehouse — carto-query-datawarehouse.
• Importing files into the warehouse — carto-import-export-data.