> ## 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.

# Deleting environments

> Permanently remove an environment, its database, and its scoped configuration. Backups outlive the environment and remain restorable.

Deleting an environment removes its dedicated database, its credentials, and every per-environment configuration block. The action is permanent — the database can't be recovered through normal channels — but [backups](/features/backend/environments/backups) outlive the environment and can be restored to recreate it.

<Warning>
  Deletion drops the environment's database and revokes its credentials. Anything not captured in a backup is gone. Take a manual backup before deleting if you might want the data back.
</Warning>

## Restrictions

Three rules block deletion in the dashboard and the API:

| Rule                                                          | Why                                                                                                               |
| ------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- |
| **`master` cannot be deleted**                                | It's the root of the [environment tree](/features/backend/environments/tree). Every project must have a baseline. |
| **An environment with active children cannot be deleted**     | Its children would lose their parent reference. Delete or archive the children first.                             |
| **An environment in the middle of a merge cannot be deleted** | Wait for the merge to complete (or cancel it) before deleting.                                                    |

## Deleting from the dashboard

<Steps>
  <Step title="Switch to a different environment">
    You can't delete the environment you're currently viewing. Switch to another active environment first.
  </Step>

  <Step title="Open the environment list">
    From the environment switcher dropdown, open the tree or list view.
  </Step>

  <Step title="Choose Delete on the target">
    The delete control surfaces a confirmation dialog with the environment's name and a final warning.
  </Step>

  <Step title="Confirm by typing the name">
    Type the environment's name to confirm — protection against accidental deletion of the wrong row.
  </Step>

  <Step title="Wait for the cleanup">
    Status moves to `archived` briefly while resources are decommissioned, then the environment disappears from the switcher.
  </Step>
</Steps>

## What happens during deletion

The platform runs a cleanup sequence and removes the environment from the project hierarchy:

| Step                       | What it does                                                                                                                            |
| -------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
| 1. Permanent data removal  | The dedicated PostgreSQL database is dropped. Database credentials are revoked.                                                         |
| 2. Configuration cleanup   | Auth provider records, file storage providers, RBAC roles, custom API routes, environment variables, and security policies are removed. |
| 3. API gateway removal     | Any custom API gateway routes scoped to the environment are decommissioned.                                                             |
| 4. Platform unregistration | The environment is removed from the project hierarchy. The `environment` context is no longer routable.                                 |

After deletion, the environment's name is free to be reused — though we recommend not reusing it immediately, since clients with cached endpoints may still try to connect.

## What survives deletion

Two things outlive a deleted environment:

* **Backups** — both manual and pre-merge backups taken while the environment existed remain in the project's Backups view. Restore one to recreate the environment. See [Restoring to a deleted environment](/features/backend/environments/backups#restoring-to-a-deleted-environment).
* **Migration history** — entries in the project-level [history](/features/backend/environments/history) remain. Audit trails don't disappear when environments do.

## Deleting via GraphQL

```graphql theme={null}
mutation DeleteEnvironment($input: DeleteEnvironmentInput!) {
  deleteEnvironment(input: $input) {
    success
    message
  }
}
```

```json theme={null}
{
  "input": {
    "projectId": "f7e4a264-d659-4719-91e8-c2d74654e529",
    "environmentName": "staging"
  }
}
```

The mutation enforces the same restrictions as the dashboard — `master` is rejected, environments with children are rejected, and environments in `merging` status are rejected. On success, the database and configuration are gone.

## FAQ

<AccordionGroup>
  <Accordion title="Can I undo a deletion?">
    Not as an undo. The environment's database is dropped immediately. To recover, restore one of the backups taken while the environment existed — the platform recreates the environment as part of the restore. See [Backups → Restoring to a deleted environment](/features/backend/environments/backups#restoring-to-a-deleted-environment).
  </Accordion>

  <Accordion title="What happens to the children if I delete a parent?">
    You can't. The platform rejects deleting an environment with active children. Delete or archive the children first, then the parent. The [tree view](/features/backend/environments/tree) shows the children to handle.
  </Accordion>

  <Accordion title="What about API keys, integration credentials, and webhooks scoped to the deleted environment?">
    All gone — they're per-environment and cleaned up during deletion. Any external system using credentials issued for that environment will start failing immediately.
  </Accordion>

  <Accordion title="Can I delete an archived environment?">
    Archive is currently a transient state during deletion. Once a deletion completes, the environment disappears entirely.
  </Accordion>

  <Accordion title="What's the right way to retire an environment without losing data?">
    Take a manual backup, mark it **retain forever**, then delete the environment. The backup keeps the data accessible for restore later, while the environment's resources (database, gateway routes, etc.) are released.
  </Accordion>
</AccordionGroup>