> ## Documentation Index
> Fetch the complete documentation index at: https://docs.stardeck.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# History & rewind

> Snapshots, point-in-time restore, retention windows, and how app reverts can rewind your data too

Every database store keeps a rolling history of every change. You can jump back to any moment inside the retention window—either by restoring a named snapshot you took earlier, or by picking an arbitrary timestamp. Rewinds are non-destructive: the pre-rewind state is always preserved as a `backup-*` branch, so nothing is actually thrown away.

New here? Start with [Overview](/data-stores/overview). For the plumbing side (connecting, access levels, branch routing), see [Connecting & routing](/data-stores/connecting).

<Note>
  History and rewind apply to **database** stores only. Storage stores don't have branches or
  history—see the [note below](#storage-stores-and-history) for how to handle point-in-time needs
  for files.
</Note>

## Retention window

Every database store has a retention window that controls how far back you can rewind. It's configured per store and ranges from 6 hours up to 7 days.

To change it, go to **Dashboard → Data Stores → \[your store] → Rewind** and pick a new value from the **Retention** dropdown at the top:

| Option   | Rewind window |
| -------- | ------------- |
| 6 hours  | last 6 hours  |
| 12 hours | last 12 hours |
| 1 day    | last 24 hours |
| 3 days   | last 72 hours |
| 7 days   | last 7 days   |

<Warning>
  **Shortening retention invalidates older history immediately.** If you drop from 7 days to 6
  hours, everything older than 6 hours is gone—and extending retention back to 7 days later does
  not bring it back. Only change retention downward when you're sure you won't want to rewind
  further.
</Warning>

A longer window costs more storage, so most stores are fine with 1 day unless you want a wider safety net for manual recovery.

## Snapshots

A **snapshot** is a named capture of a branch at a moment in time. Snapshots are cheap—they pin a restore point inside the retention window without copying data. Think of them as bookmarks rather than backups.

**To create a snapshot:**

1. Go to **Dashboard → Data Stores → \[your store] → Rewind**
2. Use the branch picker at the top-right to select the branch you want to capture
3. Type a name in the **Snapshot name** field and click **Create**

**To restore a snapshot:** each snapshot row has a **Restore** button. Restoring opens a confirmation dialog that asks you to type the branch name before it proceeds—so you can't misfire. The branch is restored in place, and the pre-restore state is kept as a backup branch (see [Backup branches](#backup-branches) below).

<Tip>
  Take a snapshot before risky migrations, bulk edits, or anything you're asking the agent to do
  that might clobber data. It's the cheapest "are you sure?" you'll ever buy.
</Tip>

<Note>
  Snapshots expire with retention. If you shorten the retention window past a snapshot's capture
  time, that snapshot can no longer be restored—even though it still shows up in the list until
  you delete it.
</Note>

## Point in time

Sometimes you don't have a snapshot and need to rewind to a specific moment anyway. The **Point in time** section on the Rewind page lets you pick any datetime inside the retention window with a date picker. The picker is bounded at `now − retention` on the low end and `now` on the high end, so you can't accidentally pick a moment Stardeck can't restore to.

After you pick a moment, click **Rewind to this moment** to open the same type-to-confirm dialog, and the branch is restored in place.

## Backup branches

Every rewind—whether from a snapshot, a point-in-time pick, or an app revert—creates a new branch named `backup-<iso-timestamp>` containing the pre-rewind state of the branch you just restored. Rewinds are never destructive; they're a swap, not a delete.

Backup branches:

* Appear in the store's branch list alongside your normal branches
* Are hidden from the Rewind page's branch picker (you shouldn't rewind a backup)
* Are hidden from the app-revert rewind checklist for the same reason
* Share the store's connection string with the branch they were backed up from
* Are **not** auto-cleaned—delete them by hand from the branches list when you're sure you don't need them

**Recovering from a backup branch** gives you two options:

1. Point your sandbox at the backup branch via **Branch routing** and inspect the data directly in the dashboard
2. Ask the agent to copy specific rows back: *"copy all rows from the `backup-2026-04-14T13-52-53Z` branch of my shared-db store into `main`"*

## Rewinding alongside an app revert

When you revert a chat message in an app, the **Revert to Previous State** dialog includes an opt-in **"Also rewind data stores"** checklist of every linked data store and its branches. This exists because rolling back code without rolling back the data it touched usually leaves you in a broken state.

For each branch the checklist shows:

* The branch name
* **Environment badges** indicating which environments consume it (production, preview, sandbox)
* Whether the branch is within the retention window—branches outside the window are disabled and the checkbox hover tells you why

Branches you tick get rewound to the target commit's timestamp. On **chat-only reverts**—when you're reverting to a message with no code commits after it—branches are rewound to the target message's timestamp instead. This is deliberate: the agent can mutate stores via tool calls without ever producing a code commit, so "no commits after" doesn't mean "the data didn't change."

<Note>
  Failures in data store rewinds **do not** roll back the code revert. If a rewind fails (for
  example, because the target moment just fell outside the retention window), the dialog reports
  the failure inline so you can retry that branch from the store's Rewind page. The code revert
  has already landed either way.
</Note>

Every rewound branch still gets its own `backup-*` branch, same as manual rewinds, so you can always walk an app revert back.

## Storage stores and history

<Note>
  Rewind and snapshots are database-only. Storage stores don't have history or branches—every
  environment sees the same files. If you need point-in-time for uploaded files, use versioned
  filenames (e.g. `invoice-2026-04-14.pdf`) or keep a separate archive store.
</Note>

## FAQ

**Q: How far back can I rewind a database store?**

A: Up to the retention window, which is configured per store and ranges from 6 hours to 7 days. Shortening retention invalidates older history immediately.

**Q: What's a `backup-*` branch in my branches list?**

A: Stardeck auto-creates one every time a branch is rewound, containing the pre-rewind state. It's safe to delete once you're sure you don't need to recover from it.

**Q: If I revert my app, will my data go back too?**

A: Only if you opt in. The revert dialog has a per-branch checklist; selected branches are rewound to the revert's timestamp, and the current state is preserved as a backup branch per rewound branch.

**Q: Do snapshots take up storage?**

A: Snapshots are cheap—they pin a restore point inside the existing retention window, they don't copy data. The storage cost is covered by retention itself, which is what you pay for when you bump the window wider.

**Q: Can the agent take a snapshot before it makes changes?**

A: No. Snapshots are user-initiated. If you want a snapshot before letting the agent loose, create it yourself first, then tell the agent to proceed.