Neon CLI command: snapshots

The snapshots command creates, lists, updates, deletes, and restores snapshots of your Neon branches, and manages the automatic backup schedule of a branch. A snapshot captures the state of a branch at a point in time, so you can restore it later. For background on the feature, plans, and limits, see Backup and restore.

If --project-id is omitted, the CLI resolves it from your context file, auto-selects when your account has only one project, and prompts otherwise.

neon snapshots create

Creates a snapshot from a branch. By default, it snapshots the head of the branch from your context or the project's default branch. Use --lsn or --timestamp to capture an earlier point within the branch's history window; the two options are mutually exclusive.

neon snapshots create [options]

Snapshot the head of a branch with a name:

neon snapshots create --branch main --name pre-migration

Snapshot a branch at a specific LSN and set an expiration:

neon snapshots create --branch main --lsn 0/1F3C8A0 --expires-at 2027-12-31T23:59:59Z

Snapshot a branch at a point in time:

neon snapshots create --branch main --timestamp 2025-01-01T00:00:00Z

Timestamps and expiration times use RFC 3339 format. --timestamp must be in the past and --expires-at in the future. Omit --expires-at to keep the snapshot until you delete it; a manual snapshot's expiration has no maximum, unlike the 35-day cap on scheduled snapshots. Snapshot names must be unique within a project.

neon snapshots list

Lists the snapshots in a project.

neon snapshots list [options]

neon snapshots list

neon snapshots get

Retrieves a snapshot by ID or name.

neon snapshots get <id> [options]

neon snapshots get snap-1234

neon snapshots update

Renames a snapshot or changes its expiration. Use --clear-expiration to keep a snapshot indefinitely; it's mutually exclusive with --expires-at.

neon snapshots update <id> [options]

Rename a snapshot:

neon snapshots update snap-1234 --name pre-migration

Clear a snapshot's expiration:

neon snapshots update snap-1234 --clear-expiration

neon snapshots delete

Deletes a snapshot by ID or name.

neon snapshots delete <id> [options]

neon snapshots delete snap-1234

neon snapshots restore

Restores a snapshot into a branch. By default, the restore is left un-finalized so you can inspect the restored branch first, then swap it in with snapshots finalize. Pass --finalize to move computes onto the restored branch and swap it in for the target immediately.

neon snapshots restore <id> [options]

Restore a snapshot to a new branch:

neon snapshots restore snap-1234 --name recovered

Restore onto an existing branch un-finalized to preview, then finalize:

neon snapshots restore snap-1234 --target-branch main

Restore onto a branch and swap it in immediately:

neon snapshots restore snap-1234 --target-branch main --finalize

neon snapshots finalize

Finalizes a previewed snapshot restore, swapping the restored branch in for the target. Use this after running snapshots restore without --finalize. The argument is the ID of the restored branch that snapshots restore created, not the target branch. The restore command prints the exact finalize command to run.

neon snapshots finalize <branch> [options]

neon snapshots finalize br-summer-water-au2msxjn

The replaced (old) branch is kept under an auto-generated name unless you set one with --name.

Snapshot schedule

The snapshots schedule subcommands get and set the automatic snapshot (backup) schedule of a branch.

neon snapshots schedule get

Gets a branch's automatic snapshot schedule.

neon snapshots schedule get [options]

neon snapshots schedule get --branch main

neon snapshots schedule set

Sets a branch's automatic snapshot schedule. Build a single-entry schedule with --frequency and its companion flags, or pass a full JSON schedule with --schedule for a multi-entry schedule (this overrides the single-entry flags).

Pick one --frequency; that choice determines which of --day and --hour you must also set. The supported frequencies are:

The server enforces these combinations, so a schedule missing a value its frequency needs is rejected with an error such as daily schedules must specify the hour of the day.

Use --retention with any frequency to set how long each snapshot is kept.

neon snapshots schedule set [options]

Of the options above, --month is the exception: none of the supported frequencies read it, so setting it has no effect on when snapshots are taken.

Set a daily 03:00 snapshot kept for 7 days (604800 seconds):

neon snapshots schedule set --branch main --frequency daily --hour 3 --retention 604800

Set a weekly snapshot on Mondays at 04:00:

neon snapshots schedule set --branch main --frequency weekly --day 1 --hour 4

Set a multi-entry schedule with JSON:

neon snapshots schedule set --branch main --schedule '[{"frequency":"daily","hour":3},{"frequency":"weekly","day":1,"hour":4}]'

--retention is in seconds, from 3600 (1 hour) to 3024000 (35 days). Omit it and scheduled snapshots are kept for 35 days, the maximum. Manual snapshots created with snapshots create follow the opposite rule: they never expire unless you set --expires-at. See Snapshot retention.