Update to a new version

Updating your CARTO Self-Hosted deployment

Support lifecycle policy

At CARTO, we are committed to providing reliable, secure, and high-quality support for all our users. To ensure the best experience, our support services are available only for CARTO Self-hosted versions released within the past 12 months.

Maintaining your installation on an up-to-date version is essential to:

• Guarantee optimal performance of the platform.

• Ensure security and compliance through the latest patches.

• Benefit from continuous improvements, including new features and resolved issues.

We strongly recommend that all users regularly update their CARTO installations. Doing so not only secures continued eligibility for support services but also allows you to take full advantage of CARTO's latest capabilities and innovations.

Keeping your environment current is the best way to maximize the value of your CARTO deployment while ensuring stability, security, and a seamless user experience.

Upgrade Selfhosted version

Follow the steps below if you're using an Orchestrated container deployment in Kubernetes.

Warning: Version rollbacks are not supported

CARTO Self-Hosted does not support rolling back to previous versions. This includes:

• Using helm rollback to revert to an older release

• Installing a previous chart version after upgrading

• Downgrading the appVersion in any way

Why? Database schema migrations run automatically during upgrades and are designed to be forward-only. Rolling back the application while the database remains at a newer schema version will cause:

• Application errors due to schema mismatches

• Potential data corruption

• Features becoming non-functional

If an upgrade fails: Contact CARTO Support immediately. Do not attempt to rollback. If you must restore to a previous state, you will need to restore from a database backup taken before the upgrade and reinstall the matching chart version.

Pre-upgrade requirements

Important: Always Back Up Your Databases Before Upgrading

Before performing any upgrade to a new CARTO Self-Hosted version, you must create a backup of your databases:

1. Backup the following databases:

   • carto / metadata - Main CARTO metadata database (PostgreSQL) - Required

   • aiproxy - AI Proxy database (PostgreSQL) - Only if AI features are enabled

2. Verify backups are complete and restorable before proceeding with the upgrade.

3. Document the current chart version (helm list -n <namespace>) in case you need to reinstall.

This is your only recovery path if an upgrade fails. Without a pre-upgrade backup, rolling back to a previous working state is not possible.

Download customer package (Helm)

This section only applies to advanced Orchestrated container deployments using Kubernetes and Helm.

Once a new release is available, you will need to download the latest customer package.

Clone the CARTO Self-Hosted github repo:

git clone https://github.com/CartoDB/carto-selfhosted.git
cd carto-selfhosted

Checkout to the latest stable release:

git checkout tags/2026.5.14

You should Install the following packages on your machine:yq, jq and gcloud.

Run the script passing the following arguments:

flag	description
-d	Directory containing the existing customer package files.
-s	Carto selfhosted installation mode. Possible values for mode are docker (Single VM deployment) and k8s(Orchestrated container deployment)

./tools/carto-download-customer-package.sh -s k8s -d /tmp/carto

Example output:

ℹ️  selfhosted mode: k8s
✅ found: ../carto3-onprem-customers/package/<customer-id>/k8s/carto-values.yaml
✅ found: ../carto3-onprem-customers/package/<customer-id>/k8s/carto-secrets.yaml
✅ activating: service account credentials for: [[e-mail]]
ℹ️  latest version: 2025-1-10
ℹ️  download file: gs://xxx-customer-package-storage/customer-package/carto-selfhosted-k8s-customer-package-<customer-id>-2025-1-10.zip
Copying gs://xxx-customer-package-storage/customer-package/carto-selfhosted-k8s-customer-package-<customer-id>-2025-1-10.zip...
/ [1 files][  3.0 KiB/  3.0 KiB]
Operation completed over 1 objects/3.0 KiB.
✅ downloading: carto-selfhosted-k8s-customer-package-<customer-id>-2025-1-10.zip

##############################################################
Current selfhosted version in [carto-values.yaml]: 2024-12-10
Latest selfhosted version downloaded: 2025-1-10
Downloaded file: carto-selfhosted-k8s-customer-package-<customer-id>-2025-1-10.zip
Downloaded from: gs://xxx-customer-package-storage/customer-package/carto-selfhosted-k8s-customer-package-<customer-id>-2025-1-10.zip
##############################################################

✅ finished [0]

Install upgrade

Kots

Kots

Upgrade Single VM deployment

To upgrade your CARTO Self-Hosted deployment, simply access the Admin Console and check for any available updates.

1. Login to the Admin Console.

2. Click on "Check for Updates" link.

3. If there are new SelfHosted version availabile, you will see it in the "New version available" section in the Admin Console.

4. Wait for the Preflight Checks to Complete.

1. Click on the blue "Deploy" button to deploy your new version.

2. Monitor the progres in the "Details" section.

Once the update has been downloaded and all the preflight checks have completed successfully, initiate the upgrade process by clicking the "Deploy" button. Upon completion of the deployment, your single VM deployment will be successfully updated to the latest version.

Upgrade Orchestrated container deployment (Kots in K8s)

Follow the steps below if you're using an Orchestrated container deployment in Kubernetes.

1. Login to the Admin Console.

2. Click on "Check for Updates" link.

3. If there are new SelfHosted version availabile, you will see it in the "New version available" section in the Admin Console.

4. Wait for the Preflight Checks to Complete.

1. Click on the blue "Deploy" button to deploy your new version.

2. Monitor the progres in the "Details" section.

Once the update has been downloaded and all the preflight checks have completed successfully, initiate the upgrade process by clicking the "Deploy" button. Upon completion of the deployment, your CARTO Deployment i K8s with Kots will be successfully updated to the latest version.

(Optional) Upgrade Kots admin-console

In some cases, you may need to update the KOTS Admin Console to ensure compatibility with the latest CARTO Self-Hosted release or to receive important fixes. This process should always be performed independently of the CARTO upgrade to avoid conflicts or delays.

When should I upgrade KOTS?

• When required by the Admin Console during the upgrade process: If your Kots version is below our minimum version you'll have to upgrade the Admin Console version before upgrading CARTO. You can view our minKotsVersion value here.

• Release notes notification: We recommend upgrade KOTS when explicitly required in the CARTO release notes. These notes will clearly specify the exact version of KOTS that has been validated by CARTO.

• Do not upgrade on your own: Avoid upgrading KOTS independently (e.g., every X months). Running unvalidated versions may introduce incompatibilities.

Steps to upgrade KOTS:

1. Update the Kots version in your local machine to match the one specified in the release notes:

export VERSION="<kots-version-in-release-notes>"
curl https://kots.io/install/${VERSION} | bash

1. Update the Kots version in the cluster:

kubectl kots admin-console upgrade -n <namespace>

Helm

Post-change verification

After applying an update, confirm the deployment is healthy:

• All pods are in Running or Completed state

• The CARTO application is reachable and you can log in

• The Admin Console shows the expected new version

• A basic map renders successfully

• Data warehouse connections are healthy