How CARTO uses the Metadata Database

Understand what CARTO stores in the metadata database and why it matters

Overview

CARTO Self-Hosted requires an external PostgreSQL database to store platform metadata: information about maps, workflows, connections, users, and organizations. You provision and manage this database as part of your infrastructure, using a cloud-managed service such as Cloud SQL, RDS, or Azure Database for PostgreSQL.

This is distinct from the data warehouse where your spatial data lives. See Metadata Database vs. Data Warehouse for a comparison.

What CARTO stores in the metadata database

The metadata database is the source of truth for all CARTO platform configuration and user-generated content. It stores:

• Maps and layers — map definitions, layer configurations, styles, and filters

• Workflows — workflow definitions, component settings, and execution history

• Data connections — connection credentials (encrypted), data warehouse endpoints, and connection metadata

• User accounts — user profiles, roles, and permissions

• Organization settings — organization name, SSO configuration, feature flags, and branding

• Import job records — import history, status, error logs, and file references

• Application configuration — internal platform settings managed by CARTO services

The metadata database does not store your spatial data or map tile data. That data lives in your connected data warehouse (e.g., BigQuery, Snowflake, Redshift, PostgreSQL) and is queried at runtime.

Sizing

The metadata database stays small because it stores only lightweight structured records. Spatial data is never stored here. Provisioning requirements (supported versions, managed-service options, and minimum production specs) live in the Metadata Database prerequisites.

Next steps

• Metadata Database prerequisites — supported versions, managed service options, sizing, and checklist

• Metadata Database vs. Data Warehouse — understand the difference between the two database systems