## Problem
When a project is paused, in a failed state, or about to be deleted,
users have no obvious way to take a logical backup of their data before
proceeding. This is particularly risky at deletion time — once deleted,
data is gone.
## Solution
Introduce a new `LogicalBackupCliInstructions` component that surfaces
ready-to-run `supabase db dump` commands pre-filled with the project's
direct connection details.
### Where it appears
| State | How |
|---|---|
| Project paused (restorable) | Inline in `ProjectPausedState` with a
note to resume first |
| Pause failed | Dialog via "Download backup" button when no backup is
available |
| Restore failed | Dialog via "Download backup" button when no backup is
available |
| Delete project modal | Inline in `DeleteProjectModal` for all plans |
Not shown in `PauseDisabledState` (project paused 90+ days, compute
stopped — `pg_dump` would fail anyway).
### What the component does
- Fetches the project's direct connection settings via
`useProjectSettingsV2Query`
- Builds a connection URI with a `[YOUR-PASSWORD]` placeholder (password
is never stored or displayed)
- Shows three shell commands to dump roles, schema, and data separately
— mirroring the [logical backup
docs](https://supabase.com/docs/guides/platform/backups)
- Optionally shows a **Reset database password** button (gated on
`UPDATE projects` permission); shown in the paused state, hidden
elsewhere via `showResetPassword={false}`
- Includes inline guidance to percent-encode special characters in the
password
### Shell safety
The generated `--db-url` values are wrapped in single quotes to prevent
shell metacharacter expansion when users paste and run the commands.
`npx supabase login` is intentionally omitted — the `--db-url` flag
authenticates directly against Postgres and does not require a Supabase
account.
### Backup button behaviour in failed states
The "Download backup" button in `PauseFailedState` and
`RestoreFailedState` now always stays enabled:
- **Backup available** — downloads immediately (unchanged)
- **No backup / physical backups** — opens a dialog with CLI
instructions instead of silently failing
## How to test
**Delete project flow**
1. Open any project → Settings → General → Delete project
2. Verify the CLI backup section appears with the project's host, port,
user, and db name pre-filled
3. Verify no Reset database password button is shown
**Paused project**
1. Open a paused project (`ProjectPausedState`) — verify CLI
instructions appear with the "Your project must be resumed before
running these commands." note
2. Open a project paused for 90+ days (`PauseDisabledState`) — verify
CLI instructions do not appear
**Failed states**
1. Simulate a pause-failed or restore-failed state
2. If a downloadable backup exists — "Download backup" downloads it
directly
3. Block the backup API or use a project with physical backups —
"Download backup" should open the CLI instructions dialog
**Error state**
1. Block the project settings API call (DevTools → Network → block
request)
2. Verify an error message appears with a link to Database settings
3. Verify a loading skeleton shows while the request is in flight
---------
Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
