From a4e402c9f65e03528f7e3b58e1b74c54875e8754 Mon Sep 17 00:00:00 2001 From: Philip Olson Date: Tue, 5 May 2026 13:27:58 -0700 Subject: [PATCH] docs: add branch recovery docs --- content/docs/guides/backup-restore.md | 2 + content/docs/guides/branch-expiration.md | 2 +- content/docs/introduction/branch-restore.md | 1 + content/docs/introduction/restore-window.md | 2 +- content/docs/manage/branches.md | 61 ++++++++++++++++++++- content/docs/manage/orgs-manage.md | 2 + content/docs/manage/projects.md | 4 +- content/docs/reference/cli-branches.md | 2 + content/docs/reference/cli-projects.md | 2 + 9 files changed, 73 insertions(+), 5 deletions(-) diff --git a/content/docs/guides/backup-restore.md b/content/docs/guides/backup-restore.md index e59d9d48ec..6fbc2d2d10 100644 --- a/content/docs/guides/backup-restore.md +++ b/content/docs/guides/backup-restore.md @@ -514,4 +514,6 @@ Use this option if you need to inspect the restored data before you switch over - Instant restore (PITR) is currently not supported on branches created from a snapshot restore. If you restore a snapshot to create a new branch, you cannot perform point-in-time restore on that branch at this time. Attempting to do so will return an error: `restore from snapshot on target branch is still ongoing`. - **Reset from parent is unavailable on child branches for up to 24 hours after restoring a parent from a snapshot.** When you restore a branch from a snapshot, any child branches of that restored branch cannot use the [Reset from parent](/docs/guides/reset-from-parent) feature for up to 24 hours. +For deleted branches, see [Recover a deleted branch](/docs/manage/branches#recover-a-deleted-branch). That's a separate recovery path from the point-in-time and snapshot features on this page. + diff --git a/content/docs/guides/branch-expiration.md b/content/docs/guides/branch-expiration.md index fadd355561..fe915240f1 100644 --- a/content/docs/guides/branch-expiration.md +++ b/content/docs/guides/branch-expiration.md @@ -68,7 +68,7 @@ When you set an expiration timestamp on a branch: 3. If you reset a branch from its parent, the TTL countdown restarts using the original interval -Branch deletion is permanent and cannot be recovered. All associated data and compute endpoints are also deleted. Verify expiration times carefully before setting them. +Branches are soft-deleted by default, and enter a 7-day [deletion recovery period](/docs/manage/branches#recover-a-deleted-branch) before being permanently removed. All associated data and compute endpoints are also deleted. Verify expiration times carefully before setting them. ## Setting branch expiration diff --git a/content/docs/introduction/branch-restore.md b/content/docs/introduction/branch-restore.md index f63f4c8c0a..6387ffb177 100644 --- a/content/docs/introduction/branch-restore.md +++ b/content/docs/introduction/branch-restore.md @@ -24,6 +24,7 @@ updatedOn: '2026-02-06T22:07:33.086Z' Configure restore window + Recover a deleted branch diff --git a/content/docs/introduction/restore-window.md b/content/docs/introduction/restore-window.md index 3b3a6e2c6d..5a9bbc21f6 100644 --- a/content/docs/introduction/restore-window.md +++ b/content/docs/introduction/restore-window.md @@ -118,7 +118,7 @@ The restore window determines what's available for these features: - [Snapshots](/docs/guides/backup-restore): Capture and restore from specific points -The restore window is for branch point-in-time recovery (PITR), which restores data to a previous state. This is different from the deletion recovery period, which allows you to recover (undelete) a deleted project. For information about recovering deleted projects, see [Project recovery](/docs/manage/projects#recover-a-deleted-project). +The restore window is for branch point-in-time recovery (PITR), which restores data to a previous state. This is different from the deletion recovery period, which allows you to recover (undelete) a deleted project or branch. See [Project recovery](/docs/manage/projects#recover-a-deleted-project) and [Branch recovery](/docs/manage/branches#recover-a-deleted-branch). diff --git a/content/docs/manage/branches.md b/content/docs/manage/branches.md index 72557c698c..097ceb1ff9 100644 --- a/content/docs/manage/branches.md +++ b/content/docs/manage/branches.md @@ -195,7 +195,7 @@ You can use the Neon Console, CLI, or API. For more details, see [Instant restor ## Delete a branch -Deleting a branch is a permanent action. Deleting a branch also deletes the databases and roles that belong to the branch as well as the compute associated with the branch. You cannot delete a branch that has child branches. The child branches must be deleted first. +Deleting a branch removes the branch along with its databases, roles, and associated compute. You cannot delete a branch that has child branches. The child branches must be deleted first. To delete a branch: @@ -209,6 +209,65 @@ To delete a branch: For temporary branches, consider setting an expiration date when creating them to automate cleanup and reduce manual deletion overhead. +## Recover a deleted branch + +Branches are soft-deleted by default, and enter a 7-day deletion recovery period before being permanently removed. To bypass the recovery period and delete immediately, use `hard_delete=true`. + + +This is different from [instant restore](/docs/introduction/branch-restore), which rolls back a branch to an earlier point in time. + +To recover a deleted project, see [Recover a deleted project](/docs/manage/projects#recover-a-deleted-project). + + +### What's recovered + +When you recover a deleted branch: + +- Branch data and configuration are restored +- Endpoints return to an idle state +- Connection strings remain valid + +### Recovery API + +To list deleted branches that can be recovered, use `include_deleted=true`: + +```http +GET /projects/{project_id}/branches?include_deleted=true +``` + +**Example:** + +```bash +curl 'https://console.neon.tech/api/v2/projects/dry-heart-13671059/branches?include_deleted=true' \ + -H 'Accept: application/json' \ + -H "Authorization: Bearer $NEON_API_KEY" | jq +``` + +Each deleted branch includes a `recovery` object with `deleted_at`, `recoverable_until`, and `deletion_method` fields. + +To recover a deleted branch: + +```http +POST /projects/{project_id}/branches/{branch_id}/recover +``` + +**Example:** + +```bash +curl -X POST \ + 'https://console.neon.tech/api/v2/projects/dry-heart-13671059/branches/br-curly-wave-af4i4oeu/recover' \ + -H 'Accept: application/json' \ + -H "Authorization: Bearer $NEON_API_KEY" | jq +``` + +The API returns a `200` status code with the restored branch object. + +To skip the recovery window, add `hard_delete=true` to the delete request: + +```http +DELETE /projects/{project_id}/branches/{branch_id}?hard_delete=true +``` + ## Check the data size You can check the logical data size for the databases on a branch by viewing the **Data size** value on the **Branches** page or page in the Neon Console. Alternatively, you can run the following query on your branch from the [Neon SQL Editor](/docs/get-started/query-with-neon-sql-editor) or any SQL client connected to your database: diff --git a/content/docs/manage/orgs-manage.md b/content/docs/manage/orgs-manage.md index ae915459cf..b89cece7f4 100644 --- a/content/docs/manage/orgs-manage.md +++ b/content/docs/manage/orgs-manage.md @@ -87,6 +87,8 @@ All Members can create new projects from the Organization's **Projects** page; h - Any Member can create a project under the organization's ownership. - Only Admins can delete projects owned by the organization. +Projects are soft-deleted by default, and enter a 7-day [deletion recovery period](/docs/manage/projects#recover-a-deleted-project) before being permanently removed. + ## Manage billing When you create a new organization, you'll choose a plan (Launch, Scale, or Scale) for that organization. Each organization manages its own billing and plan. diff --git a/content/docs/manage/projects.md b/content/docs/manage/projects.md index d7217d7b00..894ac50981 100644 --- a/content/docs/manage/projects.md +++ b/content/docs/manage/projects.md @@ -394,7 +394,7 @@ After enabling logical replication, the next steps involve creating publications ### Delete a project -Deleting a project is a permanent action, which also deletes any computes, branches, databases, and roles that belong to the project. +Deleting a project removes all its computes, branches, databases, and roles. Deleted projects can be [recovered within 7 days](#recover-a-deleted-project). To delete a project: @@ -897,7 +897,7 @@ For attribute definitions, find the [Delete project](https://api-docs.neon.tech/ If you accidentally delete a project, you can recover it within 7 days. This **deletion recovery period** allows you to restore deleted projects with all their data and configuration intact. -The deletion recovery period is different from the [restore window](/docs/introduction/restore-window). The restore window enables point-in-time recovery (PITR) for branch data, while the deletion recovery period allows you to recover (undelete) an entire deleted project. +The deletion recovery period is different from the [restore window](/docs/introduction/restore-window). The restore window enables point-in-time recovery (PITR) for branch data, while the deletion recovery period allows you to recover (undelete) an entire deleted project. To recover a deleted branch, see [Recover a deleted branch](/docs/manage/branches#recover-a-deleted-branch). ### What's recovered diff --git a/content/docs/reference/cli-branches.md b/content/docs/reference/cli-branches.md index 9db1c2ace2..19ac24bb28 100644 --- a/content/docs/reference/cli-branches.md +++ b/content/docs/reference/cli-branches.md @@ -725,6 +725,8 @@ neon branches delete br-rough-sky-158193 └─────────────────────┴─────────────────┴──────────────────────┴──────────────────────┘ ``` +Branches are soft-deleted by default, and enter a 7-day [deletion recovery period](/docs/manage/branches#recover-a-deleted-branch) before being permanently removed. + ## get This subcommand allows you to retrieve details about a branch. diff --git a/content/docs/reference/cli-projects.md b/content/docs/reference/cli-projects.md index 9ad3ad4c0a..2fba501bb7 100644 --- a/content/docs/reference/cli-projects.md +++ b/content/docs/reference/cli-projects.md @@ -316,6 +316,8 @@ neon projects delete muddy-wood-859533 Information about the deleted project is displayed. You can verify that the project was deleted by running `neon projects list`. +Projects are soft-deleted by default, and enter a 7-day [deletion recovery period](/docs/manage/projects#recover-a-deleted-project) before being permanently removed. + ### recover