Branch Restore

Learn how to revert changes or recover lost data using Neon Branch Restore with Time Travel Assist

With Neon's branch restore capability, you can easily restore a branch to an earlier state in its own or another branch's history. You can use Time Travel Assist to connect to a specific point in your history retention window, where you can run read-only queries to pinpoint the exact moment you need to restore to. You can also use Schema Diff to get a side-by-side, Github-style visual comparison of your selected branches before restoring.

How branch restore works

Restore from history

The restore operation lets you revert the state of a selected branch to an earlier point in time in its own or another branch's history, using time and date or Log Sequence Number (LSN). For example, you can revert to a state just before a data loss occurred.

branch restore to timestamp

The default history retention for a Neon project differs by plan. You can revert a branch to any time within your configured retention window, down to the millisecond.

A few key points to keep in mind about the restore operation:

Restore backups are created automatically in case you make a mistake
Current data is overwritten
All databases on a branch are restored
Connections to the selected branch are temporarily interrupted

Automatic backups

In case you need to rollback a restore, Neon preserves the branch's final state before the restore operation in an automatically created backup branch, which takes the following format:

{branch_name}_old_{head_timestamp}

You can use this backup to rollback the restore operation if necessary. The backup branches are listed on the Branches page in the Neon Console among your other branches.

Can you delete a backup branch?

Unfortunately, not at this time. A backup branch is the parent of a restored branch, and you cannot delete a parent branch without first removing its child branches. Support for deleting backup branches is expected in a future release.

In the meantime, if you're certain you no longer need a backup branch, you can free up its storage space by connecting to the branch and dropping its databases or tables. Be sure to connect to the correct branch when doing this. You can connect to a backup branch like any other branch via the Neon SQL Editor or an SQL client like psql.

If backup branches clutter your Branches page, consider renaming them. For example, you can prefix their names with a z to move them to the bottom of the list. See Rename a branch for details.

This backup becomes the parent of your original branch, which makes rolling back the restore operation simple: Reset from parent.

Backup branch as parent to original

Overwrite, not a merge

It is important to understand that whenever you restore a branch, you are performing a complete overwrite, not a merge or refresh. Everything on your current branch, data and schema, is replaced with the contents from the historical source. All data changes from the selected restore point onwards are excluded from the branch.

Changes apply to all databases

A reminder that in Neon's object hierarchy, a branch can include any number of databases. Keep this in mind when restoring branches. For example, let's say you want to restore lost data in a given database. If you restore your branch to an earlier point in time before the data loss occurred, the operation applies to all databases on the branch, not just the one you are troubleshooting. You can expect the restore operation to last a few seconds.

In general, Neon recommends that you avoid creating too many databases in a single Neon project. If you have multiple, distinct applications, each one deserves its own Neon project. A good rule of thumb: use one Neon project per source code repository.

Connections temporarily interrupted

Existing connections to the selected branch are temporarily interrupted during the restore operation. However, your connection details do not change. Applications can automatically re-establish their database connections as soon as the restore operation is finished.

Technical details

Neon is open source and built in public, so if you are interested in understanding the technical implementation of a branch restore operation, see the details below.

View technical details

Similar to the manual restore operation using the Neon Console and API described here, the Restore operation performs a similar set of actions, but automatically:

On initiating a restore action, Neon builds a new point-in-time branch by matching your selected timestamp to the corresponding LSN of the relevant entries in the shared WAL record.
The compute for your initial branch is moved to this new branch so that your connection string remains stable.
We rename your new branch to the exact name as your initial branch, so the effect is seamless; it looks and acts like the same branch.
Your initial branch, which now has no compute attached to it, is renamed to branch_name_old_head_timestamp to keep the pre-restore branch available should you need to roll back. Note that the initial branch was the parent for your new branch, and this is reflected when you look at your branch details.

Time Travel Assist

Use Time Travel Assist to make sure you've targetted the correct restore point before you restore your branch.

See Time Travel Assist to learn more.

How to use branch restore

You can use the Neon Console, CLI, or API to restore branches.

To make sure you choose the right restore point, we encourage you to use Time Travel Assist before running a restore job, but the backup branch is there if you need it. If you do need to revert your changes, you can Reset from parent since that is your branch's relationship to the restore point backup.

Billing considerations

There are minimal impacts to billing from the branch restore and Time Travel Assist features:

Branch Restore — The backups created when you restore a branch do add to your total number of branches, but since they do not have a compute attached they do not add to consumption costs.
Time Travel Assist — Costs related to Time Travel queries are minimal. See Billing considerations.

Limitations

You cannot delete a backup branch without first removing the child branch. See the note above.
Once you restore a branch, Reset from parent restores from the restore backup branch, not the original parent.

For example, let's say you have a main branch with a child development branch dev/alex. You are working on dev/alex and decide to restore to an earlier point in time to fix something during development. At this point, dev/alex's parent switches from main to the backup dev/alex_old_timestamp. A day later, you want to refresh dev/alex with the latest data from main. You can't use Reset from parent, since the backup is now the parent. Instead, use Branch Restore and select the original parent main as the source.