To help review your data's history, Time Travel lets you connect to any selected point in time within your restore window and then run queries against that connection. This capability is part of Neon's instant restore feature, which maintains a history of changes through Write-Ahead Log (WAL) records.

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 instant 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 with a .50 CU compute size, which has 0.50 vCPU size with 2 GB of RAM. 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.

Restore window

You are only able to run Time Travel queries that fall within your restore 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 restore window.

To change your restore window, see Configure restore window.

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 restore 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 instant restore

Time Travel Assist is also available from the Restore page, as part of the Instant 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:

  1. In the Neon Console, open the SQL Editor.

  2. Use the Time Travel toggle to enable querying against an earlier point in time.

    Time Travel toggle

  3. Use the Date & Time selector to choose a point within your restore window.

  4. Write your read-only query in the editor, then click Run. You don't have to include time parameters in the query; the query is automatically targeted to your selected timestamp.

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 30 seconds after you stop querying.
  • Ephemeral endpoints are created with a .50 CU compute size, which has 0.50 vCPU size with 2 GB of RAM. This is Neon's second smallest compute size. For more about compute sizes in Neon, see How to size your compute. For more about compute usage and billing, see Usage metrics — Compute.