Skip to content

docs: add Import Data Assistant for Postgres version and region migration #3501

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 5 additions & 1 deletion content/docs/import/import-data-assistant.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
---
title: Import Data Assistant
subtitle: Move your existing database to Neon using our automated import tool
subtitle: Move your database to Neon using our automated import tool
enableTableOfContents: true
tag: beta
updatedOn: '2025-05-09T09:25:03.623Z'
Expand All @@ -12,6 +12,10 @@ When you're ready to move your data to Neon, our Import Data Assistant can help

<FeatureBetaProps feature_name="Import Data Assistant"/>

<Admonition type="tip" title="Migrate between Neon projects">
You can also use the **Import Data Assistant** to migrate data between Neon projects. This is useful if you want to upgrade to a newer Postgres version (for example, from Postgres 16 to 17), or move your database to a different region. Just create a new project with the desired Postgres version or region, then use the database connection string from your existing Neon project to import the data into the new one.
</Admonition>

## Ways to import

The Import Data Assistant always creates a **new branch** for your imported data. There are two ways to launch the import:
Expand Down
7 changes: 6 additions & 1 deletion content/docs/import/migrate-from-neon.md
Original file line number Diff line number Diff line change
Expand Up @@ -18,7 +18,12 @@ Use these instructions to:
- Import a database from a Neon project created with one Postgres version to a Neon project created with another Postgres version.

<Admonition type="tip">
You can also use **logical replication** to move your data from one Neon project to another. See [Replicate data from one Neon project to another](/docs/guides/logical-replication-neon-to-neon).

You can also use these alternative methods to migrate data between Neon projects:

- **Import Data Assistant**: A fast and simple option for databases under 10 GB. See [Import Data Assistant](/docs/import/import-data-assistant).
- **Logical replication**: Move your data from one Neon project to another. Consider this option for large databases requiring near-zero downtime. See [Replicate data from one Neon project to another](/docs/guides/logical-replication-neon-to-neon).

</Admonition>

## Important considerations
Expand Down
38 changes: 17 additions & 21 deletions content/docs/postgresql/postgres-upgrade.md
Original file line number Diff line number Diff line change
Expand Up @@ -40,39 +40,35 @@ At this time, you may also want to apply any specific configurations to your new

Alternatively, you can apply these configurations after migrating your data.

### 2. Upgrade your `psql` client (if applicable)
### 2. Migrate your data using one of the following methods

While it’s not strictly necessary to keep your `psql` client version in sync with your Postgres database version, it’s generally recommended. Upgrading your `psql` client to the corresponding version of Postgres helps ensure you can use the latest features and avoid any potential incompatibility issues.
- **Import Data Assistant**

<Admonition type="note" title="Postgres 17 Compatibility">
When upgrading to **Postgres 17**, you may encounter issues with certain commands, such as `\l` (list databases), if you try to connect to your database with an older `psql` client (e.g., version 15 or 16). Upgrade your `psql` client to avoid this issue.
</Admonition>
For databases under 10GB, Neon's [Import Data Assistant](/docs/import/import-data-assistant) provides the simplest way to migrate between Neon projects with different Postgres versions. Just create a new project with your desired Postgres version, then use the database connection string from your existing Neon project to import the data.

### 3. Migrate your data using one of the following methods
- **Dump and restore**

**Dump and Restore**
Neon supports the following dump and restore options:

Neon supports the following dump and restore options:
- [Migrate data with pg_dump and pg_restore](/docs/import/migrate-from-postgres)

- [Migrate data with pg_dump and pg_restore](/docs/import/migrate-from-postgres)
This method requires dumping data from your current Neon project with `pg_dump` and loading the data into the new Neon project using `pg_restore`. Some downtime will be required between the dump and restore operations.

This method requires dumping data from your current Neon project with `pg_dump` and loading the data into the new Neon project using `pg_restore`. Some downtime will be required between the dump and restore operations.
- [Migrate data from one Neon project to another by piping data from pg_dump to pg_restore](/docs/import/migrate-from-neon)

- [Migrate data from one Neon project to another by piping data from pg_dump to pg_restore](/docs/import/migrate-from-neon)
If your database is small, you can use this method to pipe `pg_dump` output directly to `pg_restore` to save time. While this method is a bit simpler, we recommend it only for small databases, as it is susceptible to failures during lengthy data migrations.

If your database is small, you can use this method to pipe `pg_dump` output directly to `pg_restore` to save time. While this method is a bit simpler, we recommend it only for small databases, as it is susceptible to failures during lengthy data migrations.
- **Logical replication**

**Logical Replication**
The logical replication method can be used to achieve a near-zero downtime migration. Once the data in the new Neon project is synced with the data in the Neon project running the older version of Postgres, you can quickly switch your applications to the database. This method is recommended for active databases that cannot afford much downtime. For instructions, see [Logical Replication](/docs/guides/logical-replication-neon-to-neon).

The logical replication method can be used to achieve a near-zero downtime migration. Once the data in the new Neon project is synced with the data in the Neon project running the older version of Postgres, you can quickly switch your applications to the database. This method is recommended for active databases that cannot afford much downtime. For instructions, see [Logical Replication](/docs/guides/logical-replication-neon-to-neon).
<Admonition type="note" title="Notes">
- Neon does not support the `pg_dumpall` utility. If upgrading via dump and restore, dumps must be performed one database at a time using `pg_dump`.
- Neon does not yet support upgrading using `pg_upgrade`. Support for this utility is being considered for a future release.
- If you choose a dump and restore method, it is recommended that you use `pg_dump` and `pg_store` programs from the newer version of Postgres, to take advantage of any enhancements introduced in the newer version. Current releases of the these programs can read data from all previous Postgres versions supported by Neon.
</Admonition>

<Admonition type="note" title="Notes">
- Neon does not support the `pg_dumpall` utility. If upgrading via dump and restore, dumps must be performed one database at a time using `pg_dump`.
- Neon does not yet support upgrading using `pg_upgrade`. Support for this utility is being considered for a future release.
- If you choose a dump and restore method, it is recommended that you use `pg_dump` and `pg_store` programs from the newer version of Postgres, to take advantage of any enhancements introduced in the newer version. Current releases of the these programs can read data from all previous Postgres versions supported by Neon.
</Admonition>

### 4. Switch over your applications
### 3. Switch over your applications

After the migration is complete and you have verified that your new database is working as expected, you can switch your application over to the database in your new Neon project by swapping out your current database connection details for your new database connection details.

Expand Down