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

# Backups

> Automatic pre-merge snapshots, manual backups on demand, and restore — including to environments that have been deleted.

Every environment has its own backups. They come in two flavors — **automatic pre-merge** snapshots taken before each [merge](/features/backend/environments/merge), and **manual** snapshots you take on demand. Either kind can be restored into any target, including a new environment that takes over the original's name if it was deleted.

## Backup types

| Type                    | When it's taken                                                             | Why it exists                                                                                     |
| ----------------------- | --------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- |
| **Automatic pre-merge** | Right before every merge runs, on the target environment.                   | A safety net. If a merge succeeds but turns out to be a mistake, restore this snapshot to revert. |
| **Manual**              | Whenever you click **Create backup** in the Backups view (or call the API). | Snapshot before a risky operation, or to capture a known-good state.                              |

Both kinds are full backups — schema **and** data. There's no incremental or schema-only mode.

## What's in a backup

| Component                           | Included                                                                                                            |
| ----------------------------------- | ------------------------------------------------------------------------------------------------------------------- |
| Database schema                     | Yes — every table, column, index, relationship, enum, view.                                                         |
| Row data                            | Yes — every row in every table.                                                                                     |
| RBAC roles and permissions          | Yes — they live in the database.                                                                                    |
| Auth provider configuration         | Provider records are included. **Secrets aren't restored** — they're re-encrypted with each environment's key.      |
| File storage provider configuration | Yes.                                                                                                                |
| Custom API gateway routes           | Yes.                                                                                                                |
| Environment variables               | Yes.                                                                                                                |
| Files in the storage backend        | No — files live in the configured object store and are referenced by ID. The backup captures references, not blobs. |

## Taking a manual backup

<Steps>
  <Step title="Switch to the environment you want to back up">
    Use the environment switcher at the top of the project chrome.
  </Step>

  <Step title="Open Backups">
    From the switcher dropdown, open the **Backups** view.
  </Step>

  <Step title="Click Create backup">
    The backup runs as a background job. The status moves through `pending` → `running` → `completed`.
  </Step>

  <Step title="Optionally name the backup">
    Add a label like `pre-stripe-migration` or `release-v2` to make the snapshot easy to find later.
  </Step>
</Steps>

The backup appears in the list with its type (`Manual`), the user who created it, the timestamp, and the size.

## Restoring a backup

A restore reverts the **entire** environment — schema and data — to the snapshot point. It's not a per-change undo.

<Steps>
  <Step title="Find the backup">
    In the Backups view, locate the entry to restore. Pre-merge backups are linked from the corresponding [history](/features/backend/environments/history) entry.
  </Step>

  <Step title="Pick the target environment">
    By default, restoring puts the snapshot back in the same environment it was taken from. You can also restore into a different environment — including a new environment that takes over a deleted one's name (see below).
  </Step>

  <Step title="Confirm">
    The platform locks the target, drops its current state, and replays the backup. The status transitions through `restoring` and back to `active` when complete.
  </Step>
</Steps>

<Warning>
  A restore replaces the target environment's contents. Anything written to the target after the backup was taken is gone. If you might need that recent data, take a fresh manual backup of the current state first.
</Warning>

## Restoring to a deleted environment

A backup outlives its environment — even if you delete `feature-x`, its backups stick around through the [retention](#retention) window. To restore them, the platform recreates the environment as part of the restore:

<Steps>
  <Step title="Find the backup">
    Backups for deleted environments are still listed in the project's Backups view, with their original environment name shown.
  </Step>

  <Step title="Restore">
    Click Restore. If no environment with that name currently exists, the platform recreates the environment as part of the operation. The new environment inherits the backup's schema, data, and configuration.
  </Step>

  <Step title="Reconfigure secrets">
    Auth provider secrets and OAuth credentials are not in the backup — re-enter them in the recreated environment before exposing it.
  </Step>
</Steps>

This is the recovery path when a deleted environment turns out to have held a critical migration or test fixture you need back.

## Pre-merge backups in the merge flow

Every merge automatically produces one pre-merge backup on the target. The backup ID is recorded in the [history](/features/backend/environments/history) entry alongside the merge — you don't have to hunt for it.

Common pattern: after a merge into `master`, if a regression surfaces, open History → find the merge → follow the `backupId` to the Backups view → restore.

## Retention

Backups are retained for a configurable window per project. Once a backup ages out, it's pruned and can no longer be restored. Manual backups can be marked **retain forever** to opt them out of pruning — useful for capturing release-train snapshots that you want to keep indefinitely.

If you need a long rollback window for a specific merge, promote its automatic pre-merge backup to a retained manual backup before the retention window expires.

## Permissions

Creating, listing, and restoring backups is governed by [Role-Based Access](/features/backend/app-services/role-based-access). Restore is destructive — typically restricted to admin or operator roles. Read access can be granted more widely if you want broader visibility into snapshots without the ability to restore.

## FAQ

<AccordionGroup>
  <Accordion title="Are files in S3 / GCS included in the backup?">
    No. The backup captures the file storage **provider configuration** and the **references** records hold to files (file IDs, paths). The actual blobs stay in the configured object store. Treat your storage provider's own snapshot/versioning as the source of truth for file content.
  </Accordion>

  <Accordion title="Can I take a schema-only backup?">
    Backups are full — schema and data. For schema-only operations, use the [diff](/features/backend/environments/diff) and [merge](/features/backend/environments/merge) tools, or branch a new environment in **System** mode.
  </Accordion>

  <Accordion title="What happens during a restore — is the environment offline?">
    The target is locked while the restore runs. Reads continue from the existing data until the restore completes; mutations are rejected with the environment-locked error. Once complete, the target reflects the snapshot's state and reopens for writes.
  </Accordion>

  <Accordion title="Can I restore a backup from one project to a different project?">
    No. Backups are project-scoped — they reference project-specific identifiers (auth keys, project ID, RBAC role IDs) that don't translate across projects. To clone a project, branch within it.
  </Accordion>

  <Accordion title="What if the restore fails?">
    The target stays in `error` state with a failure reason recorded. The platform doesn't automatically partial-restore — either the backup applies cleanly or the environment is left as it was, in `error`. Recovery is to run the restore again, or restore a different snapshot.
  </Accordion>
</AccordionGroup>