SimpleBackups

How to Backup Neon Database

Last updated on

Originally posted on

What is Neon?

Before getting started, let's introduce Neon!

Neon is a serverless open-source alternative to AWS Aurora Postgres. It separates storage and compute and substitutes the PostgreSQL storage layer by redistributing data across a cluster of nodes. This architecture allows Neon to scale horizontally and provide high availability and fault tolerance.

When do you need a Neon database backup?

Neon has strong built-in recovery. Instant restore, Time Travel and snapshots can rewind a branch to any moment inside your history window, and Neon documents them in its backups overview. What they share is where they live: inside the same Neon project as your data.

Here's why a pg_dump copy outside Neon still matters:

  • Redundancy: a deleted project, a locked account or a lost credential takes Neon's history and snapshots with it. A dump in your own storage survives all three.
  • Retention: scheduled snapshots are kept for 35 days at most. A dump can be kept for as long as your policy says.
  • Portability: a dump restores into any Postgres host, not only Neon.
  • Compliance: auditors usually ask for an off-site copy and a tested restore.

The full list, and when Neon's native recovery is enough on its own, is in what Neon's native backup doesn't cover.

Below is a straightforward way to back up your Neon database by hand. If you want it on a schedule without writing a script, SimpleBackups for Neon runs the dumps and sends them to Amazon S3, Google Cloud Storage or any other storage you own.

With that being said, let's get started!

How to backup Neon database

In order to backup your Neon database, you'll need to use the pg_dump command.

Make sure you have the Postgres client tools installed on your machine, in a version that matches your Neon project's Postgres version.

No local install? Follow the instructions on the official PostgreSQL website, or run the client from a container as shown in our guide to PostgreSQL on Docker.

For Ubuntu, simply install it via the command line:

sudo apt-get install postgresql-15

Backup your Neon database with pg_dump

While we won't go deep into how pg_dump works, here's a quick overview of the command.

For those who want to understand more about pg_dump, we wrote a complete guide on how to backup PostgreSQL database that goes into more detail.

You can read our guide to figure out how to create a backup user and grant the necessary permissions to it in our Neon Documentation

The format of a Neon PostgreSQL connection string is similar to a standard PostgreSQL connection string. It typically includes the following components:

postgresql://myuser:mypassword@db.myproject.eu-central-1.aws.neon.tech/mydatabase

Copy it from the Neon Console with connection pooling turned off. Neon's pg_dump guide is explicit that pooled connections are not supported for dumps and will cause errors. The unpooled host is the one without -pooler in its name.

Remember to replace myuser, mypassword, myproject.eu-central-1.aws.neon.tech, and mydatabase with your actual database credentials and details. Also, ensure that your connection string is kept secure and not exposed in your application code or any public repositories.

In the Neon backups we run, the failure that repeats most is not pg_dump at all. It is authentication: a role's password changes in the Neon Console, and every scheduled run fails until the stored connection string is updated. If you script this yourself, give the backup its own role, and make sure a failed run alerts someone.

Now, let's execute the pg_dump command to backup your Neon database:

Using credentials:

pg_dump --inserts --column-inserts --username=myuser --host=myproject.eu-central-1.aws.neon.tech --port=5432 mydatabase > database-dump.sql

Or using the connection string:

pg_dump 'postgresql://myuser:mypassword@myproject.eu-central-1.aws.neon.tech/mydatabase' > database-dump.sql

This command will connect to your Neon database and create a dump file called database-dump.sql in your current directory.

Or in custom format, which is what Neon's docs recommend:

pg_dump -Fc -v -d 'postgresql://myuser:mypassword@myproject.eu-central-1.aws.neon.tech/mydatabase' -f database-dump.dump

-Fc writes a compressed archive that pg_restore can read, including restoring single tables from it. Use a pg_dump version that matches your Neon project's Postgres version; check yours with pg_dump -V.

Restore your Neon database with pg_restore

Now that you have a backup of your Neon database, you can restore it using the methods shown below. Which one depends on the format you dumped in. For every restore path on Neon, including instant restore and snapshots, see how to restore a Neon database.

A plain SQL dump, using psql:

psql -U username -d dbname < database-dump.sql

A custom-format dump, using pg_restore:

pg_restore -U username -d dbname -1 database-dump.dump

pg_restore only reads custom, directory and tar archives. A plain .sql file goes through psql. The PostgreSQL restore guide covers the errors you are likely to hit.

If you want to restore your Neon backup onto Neon itself, just use the proper connection string and credentials.

psql 'postgresql://myuser:mypassword@myproject.eu-central-1.aws.neon.tech/mydatabase' < database-dump.sql

And that's it! You now know how to backup and restore your Neon database.

To run this on a schedule without maintaining a script, follow the step-by-step setup in automating Neon backups to your own storage.

Want to trust your Neon backups are running well without hassle?

Try SimpleBackups Now →


This article is part of the complete guide to Neon backup: instant restore, snapshots, pg_dump, and the copy that lives outside Neon.