Time Travel

To help review your data's history, Time Travel lets you connect to any selected point in time within your history retention window and then run queries against that connection.

You can use Time Travel from two places in the Neon Console, and from the Neon CLI:

SQL Editor — Time Travel is built into the SQL editor letting you switch between queries of your current data and previous iterations of your data in the same view.
Restore — Time Travel Assist is also built into the Branch Restore flow where it can help you make sure you've targeted the correct restore point before you restore a branch.
Neon CLI — Use the Neon CLI to quickly establish point-in-time connections for automated scripts or command-line-based data analysis.

How Time Travel works

Time Travel leverages Neon's instant branching capability to create a temporary branch and compute at the selected point in time, which are automatically removed once you are done querying against this point-in-time connection. The computes are ephemeral: they are not listed on the Branches page or in a CLI or API list branches request.

However, you can see the history of operations related to the creation and deletion of branches and ephemeral computes on the Operations page:

start_compute
create_branch
delete_timeline
suspend_compute

How long do ephemeral endpoints remain active

The ephemeral endpoints are created according to your configured default compute size. An ephemeral compute remains active for as long as you keep running queries against it. After 30 seconds of inactivity, the timeline is deleted and the endpoint is removed.

History retention

You are only able to run Time Travel queries that fall within your history retention window, which starts at 24 hours for Free Plan users, up to 7 days for Launch, 14 days for Scale, and 30 days for Business plan users.

You cannot select a time outside your current retention window.

To change your retention period, see Configure history retention.

Data integrity

Time Travel only allows non-destructive read-only queries. You cannot alter historical data in any way. If you try to run any query that could alter historical data, you will get an error message like the following:

time travel error message

Time Travel with the SQL Editor

Time Travel in the SQL Editor offers a non-destructive way to explore your database's historical data through read-only queries. By toggling Time Travel in the editor, you switch from querying your current data to querying against a selected point within your history retention window.

You can use this feature to help with scenarios like:

Investigating anomolies
Assessing the impact of new features
Troubleshooting
Compliance auditing

Here's an example of a completed Time Travel query.

time travel from sql editor

Time Travel Assist with Branch Restore

Time Travel Assist is also available from the Restore page, as part of the Branch Restore feature. Before completing a restore operation, it's a good idea to use Time Travel Assist to verify that you've targetted the correct restore point.

An SQL editor is built into the Restore page for this purpose. When you make your branch and timestamp selection to restore a branch, this selection can also be used as the point-in-time connection to query against.

Here is an example of a completed query:

Time travel assist

How to use Time Travel

Here is how to use Time Travel from both the SQL Editor and from the Restore page:

Billing considerations

The ephemeral endpoints used to run your Time Travel queries do contribute to your consumption usage totals for the billing period, like any other active endpoint that consumes resources.

A couple of details to note:

The endpoints are shortlived. They are suspended 10 seconds after you stop querying.
Since these endpoints are created according to your default compute size (which applies to all new branch computes you create), you may want to reduce this default if you're performing a lot of time-travel queries for troubleshooting.