# Migrating CARTO Self-Hosted installation to an external database

{% hint style="danger" %}
**This documentation is for the CARTO Self-Hosted Legacy Version**. Use only if you've installed this specific version. Explore our latest documentation for updated features.
{% 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:

Run the following command from the installation folder:

```
docker-compose exec workspace-postgres pg_dump -U postgres -d workspace > dump.sql
```

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/carto-self-hosted-legacy/guides/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.