# Migrating CARTO Self-hosted installation to an external database (Helm)

{% hint style="info" %}
This documentation only applies to **advanced Orchestrated container deployments** using **Kubernetes** and **Helm**
{% endhint %}

This guide outlines the steps to migrate the internal database of a CARTO Self-Hosted installation to an external database. By following these steps, you can seamlessly transition your CARTO workspace to a new database environment.

### Prerequisites

Before starting the migration process, ensure that you have the following:

* Access to the CARTO Self-Hosted installation
* Credentials for the external database (hostname, port, username, password)

### How to perform the migration to an external database

#### Step 1: Dump the Container Database

Use the following command to create a dump of the internal database:

1. Obtain the PostgreSQL password generated by the CARTO installation from the secret created for postgresql:\\

   ```bash
   kubectl get secret <postgresql_secret_name> \
    -n <namespace> \
    -ogo-template='{{ index .data "postgres-password" }}' | base64 -D
   ```

{% hint style="info" %}
You can obtain the name of your PostgreSQL secret running the following command:

`kubectl get secrets -n <namespace>`
{% endhint %}

2. Obtain the name of your `workspace database` pod. The following command should return a pod named `postgresql`

   ```bash
   kubectl get pods -n <namespace> | grep postgresql
   ```
3. Run the following command to perform a backup of the internal database located in your cluster:

   <pre class="language-bash"><code class="lang-bash">kubectl exec &#x3C;postgresql_pod_name> \
    -n &#x3C;namespace> \
   <strong> -- pg_dump --dbname=postgresql://postgres:&#x3C;postgres_password>@localhost:5432/workspace > dump.sql
   </strong></code></pre>

This command exports the database structure and data to a SQL file named `dump.sql`

#### Step 2: Create Workspace Admin User in External Database

Run the following command to create the necessary user in the new external database:

```bash
CREATE USER workspace_admin with encrypted password '<password>';
```

#### Step 3: Create Database in External Database

Execute the following commands to create the database in the external database:

```
CREATE DATABASE workspace OWNER workspace_admin;
```

#### Step 4: Restore the Dump

Restore the dumped data into the new external database. If you have access to the external database using `psql` you can directly restore the database using the following command:

```bash
psql -h <external_db_host> -p <external_db_port> -U workspace_admin -d workspace -f dump.sql
```

You have successfully migrated your CARTO Self-Hosted installation to an external database! :tada: Ensure that you update your CARTO configuration files to reflect the changes in the database connection details. You can find more information about how to connect your Self-Hosted installation to an external database in our [quickstart guides](/carto-self-hosted/deployment-guides.md).


---

# Agent Instructions: 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:

```
GET https://docs.carto.com/carto-self-hosted/guides/guides-helm/migrating-carto-self-hosted-installation-to-an-external-database.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.