> For the complete documentation index, see [llms.txt](https://docs.carto.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.carto.com/carto-self-hosted/concepts/metadata-database.md). # 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](/carto-self-hosted/concepts/metadata-database-vs-data-warehouse.md) 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 {% hint style="warning" %} 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. {% endhint %} ## 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](/carto-self-hosted/planning/prerequisites/metadata-database.md). ## Next steps * [Metadata Database prerequisites](/carto-self-hosted/planning/prerequisites/metadata-database.md) — supported versions, managed service options, sizing, and checklist * [Metadata Database vs. Data Warehouse](/carto-self-hosted/concepts/metadata-database-vs-data-warehouse.md) — understand the difference between the two database systems --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://docs.carto.com/carto-self-hosted/concepts/metadata-database.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.