> 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/planning/prerequisites/metadata-database.md).

# Metadata Database

## Overview

CARTO Self-Hosted requires an **external PostgreSQL** metadata database. You must provision and manage this database as part of your infrastructure before deploying CARTO.

See [How CARTO uses the Metadata Database](/carto-self-hosted/concepts/metadata-database.md) for background on what this database stores and why it matters.

## Supported versions

CARTO Self-Hosted requires **PostgreSQL 14 or above**.

## Managed service options

CARTO recommends using a cloud-managed PostgreSQL service for automated backups, high availability, and maintenance.

| Provider            | Recommended service                             | Notes                                     |
| ------------------- | ----------------------------------------------- | ----------------------------------------- |
| Google Cloud        | Cloud SQL for PostgreSQL                        | Use Private IP for network isolation      |
| Amazon Web Services | Amazon RDS for PostgreSQL                       | Use Multi-AZ for high availability        |
| Microsoft Azure     | Azure Database for PostgreSQL – Flexible Server | Preferred over Single Server (deprecated) |

{% hint style="warning" %}
**Azure PostgreSQL Flexible Server**:

* Make sure you add ownership over the carto database and all privileges over the schema.
* Extensions must be allowlisted before creation. Run `az postgres flexible-server parameter set --name azure.extensions --value "pgcrypto"` then create the extension as the admin user. See [Azure docs](https://go.microsoft.com/fwlink/?linkid=2301063).
  {% endhint %}

The minimum requirements for production are:

* 1 vCPU
* 2 GB of RAM memory
* 20 GB of SSD storage

{% hint style="info" %}
The CARTO metadata PostgreSQL database is only used to store CARTO metadata. This database is **not** the database used with CARTO to store your geospatial data.
{% endhint %}

When [enabling CARTO AI](/carto-self-hosted/configuration/ai-features/configure-carto-ai-prerequisites.md), a **second** PostgreSQL database is required. It can be omitted if you don't plan to use AI in CARTO.

## Naming recommendations

When deploying the PostgreSQL instance for CARTO Self-Hosted, we recommend following these best practices to ensure consistency and avoid common configuration errors:

1. **Instance Name (Cloud SQL / RDS / VM-based PostgreSQL)**
   * Use a nomenclature that includes the **environment**.
   * Example:

     ```
     carto-prod-instance
     carto-dev-instance
     ```
2. **Database and User Names**
   * Use `carto` for both the **database name** and the **database user**.
   * Recommended:

     ```
     Database: carto
     User:     carto
     ```

{% hint style="warning" %}
:warning: **Important Constraint** :warning:

**Do not use hyphens (`-`)** in database names or usernames due to PostgreSQL constraints.

* If needed, replace hyphens with underscores (`_`).
* *Example*:
  * Allowed: **carto\_prod\_user, carto** :white\_check\_mark:
  * Not valid: **carto-prod-user, carto-maps** :x:
    {% endhint %}

{% hint style="warning" %}
:warning: **PostgreSQL Password Constraint** :warning:

**Avoid URI-special characters** (`@`, `#`, `%`, `/`, `?`, `&`, `=`, `+`) in the PostgreSQL user password. These characters can cause connection failures in components that construct database connection URLs internally, particularly the **AI Proxy (LiteLLM)**.

* Use alphanumeric passwords with underscores (`_`) or dashes (`-`).
* *Example*:
  * Recommended: **MyS3cure\_Pass123** :white\_check\_mark:
  * Problematic: **p\@ss#word!** :x:
    {% endhint %}

## Checklist

* [ ] PostgreSQL instance is provisioned and accessible from your CARTO deployment
* [ ] A dedicated database and user have been created for CARTO
* [ ] The CARTO user has the required permissions (`CREATE`, `CONNECT`, etc.)
* [ ] Backups are configured for the database
* [ ] Connection string and credentials are ready


---

# 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 dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.carto.com/carto-self-hosted/planning/prerequisites/metadata-database.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.