Metadata Database

Metadata database prerequisites for CARTO Self-Hosted

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 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)

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.

The minimum requirements for production are:

• 1 vCPU

• 2 GB of RAM memory

• 20 GB of SSD storage

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.

When enabling CARTO AI, 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

⚠️ Important Constraint ⚠️

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 ✅

  • Not valid: carto-prod-user, carto-maps ❌

⚠️ PostgreSQL Password Constraint ⚠️

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 ✅

  • Problematic: p@ss#word! ❌

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