Neon’s restore functionality is actually a clever application of its branching and historical data capabilities, rather than a traditional point-in-time recovery (PITR) system.
Let’s see it in action. Imagine you have a database mydb with a primary branch main. You’ve made a few commits, and now you want to go back to an earlier state.
# List your branches and their latest commit IDs
neon_cli branch list
# Output might look like:
# Branch Name | Latest Commit ID | ...
# main | abc123def456 | ...
# feature-x | ghi789jkl012 | ...
Now, let’s say you want to restore mydb to the state it was in at commit abc123def456. You don’t "restore" in the sense of overwriting. Instead, you create a new branch pointing to that historical commit.
neon_cli branch create restore-point-abc \
--from-commit abc123def456 \
--db mydb
This command doesn’t touch your main branch. It creates a brand new branch named restore-point-abc that, when you access it, will show you the exact data and schema as it existed at abc123def456. You can then query this branch, or if you decide this is the state you want to move forward from, you can promote it or merge it back into main.
The core problem Neon’s restore solves is the need for rapid, non-destructive recovery and experimentation with historical data states. Traditional PITR often involves downtime and a full data rebuild. Neon, by leveraging its immutable, append-only storage and the concept of branches as pointers to specific states in that history, allows you to "restore" by simply creating a new, independent view of your data.
Internally, Neon stores data in layers. When you make a commit, you’re essentially creating a new layer that references previous layers. A branch is just a named pointer to a specific commit (or more accurately, to the top-most layer of a specific timeline). When you create a branch from an old commit, you’re creating a new pointer that points to that exact historical commit. The storage system then efficiently reconstructs the database state by accessing the necessary layers up to that commit. You control this by choosing which commit ID to branch from. The neon_cli is your primary tool for interacting with these branches and commits.
The most surprising thing is that even though you’re "restoring" to an old state, the underlying data isn’t copied. Neon uses copy-on-write semantics. When you create a new branch pointing to an older commit, it reuses all the unchanged data blocks from the history. Only new data written to this restored branch would consume new storage.
The next step is understanding how to manage these historical branches and their associated storage lifecycle.