Backups — Reference
The Backups surface is the recovery plane for an SGEN site. It owns the backup catalog (every snapshot taken of the site, manual or scheduled), the schedule definitions that produce new snapshots on a fixed cadence, the retention policy that decides how long snapshots are kept, the restore flow that brings a snapshot back to live, and the pinning mechanism that protects specific snapshots from retention sweeps. Anything that answers the question can I get this site back the way it was on a given date traces back to a record managed here.
This page is a reference for platform engineers and integrators who need to understand the surface before extending it, scripting against it, or building an external snapshot-sync layer. Customer-facing walkthroughs for taking a manual backup and restoring from one live in the customer docs set; this page describes the shape of the surface, not the steps to drive it.
Overview
Backups live under the Backups module in SG-Admin. The module renders three primary views — the snapshot list, the schedule definition panel, and the restore confirmation flow — and exposes a small set of write operations for snapshot creation, snapshot deletion, schedule edits, retention configuration, pinning, and restore.
The module is paired by convention: one half renders the views and prepares the catalog, the other half handles snapshot writes and restore execution. The pairing matches the broader SG-Admin convention used across other modules.
A second surface — per-post revisions — lives one level down, inside the Posts module. Per-post revisions are scoped to a single record; backups are scoped to the full site. The two surfaces complement each other: per-post revisions cover content-level recovery, backups cover infrastructure-level recovery.
Where it lives in SG-Admin:
- Sidebar: SG-Admin → Backups
- URL prefix:
/sg-admin/backups/ - View templates:
application/views/Admin/Backups/
┌──────────────────────────────────────────────────────────────────────┐│ SG-Admin → Backups [+ Take backup] [Schedule] │├──────────────────────────────────────────────────────────────────────┤│ Taken Type Size Retention Pinned ││ ─────────────── ──────── ──────── ────────── ────── ││ 2026-05-21 06:00 scheduled 412 MB 14 days — ││ 2026-05-20 06:00 scheduled 409 MB 14 days — ││ 2026-05-19 14:32 manual 411 MB 30 days ✔ pre-launch ││ 2026-05-19 06:00 scheduled 408 MB 14 days — ││ 2026-05-18 06:00 scheduled 407 MB 14 days — ││... ││ ││ [⋯ Restore] [⋯ Download.sgen] [⋯ Pin] [⋯ Delete] │└──────────────────────────────────────────────────────────────────────┘Actions
The Backups surface exposes the following operations. Each is described by what it does to the site state, not by its internal method name.
List snapshots
Returns the snapshots in the catalog, paginated, with taken-at, type (manual / scheduled), size, retention window, pinned state, and label columns. Supports column sort and a free-text filter by label. The default view shows the last 60 days; older snapshots surface via the date-range expander.
Take manual backup
Triggers an immediate snapshot. Captures the full site state — database, uploaded media manifest, appearance record, theme templates, custom CSS, custom codes, custom fonts, page records, post records, form records, and the site's general settings — into a single .sgen archive. Returns the new snapshot identifier when the capture completes.
Manual backups run as background jobs. The surface returns a job identifier immediately; the snapshot identifier resolves once the job completes. Long-running captures (large media libraries) surface progress in the snapshot list with a capturing status.Configure schedule
Opens the schedule definition panel. Accepts a frequency (daily, weekly, biweekly, monthly), a time-of-day, a retention window, and a maximum-snapshot-count cap. On submit, the surface validates the combined retention math (count cap × frequency vs storage allowance) and persists the definition. Only one schedule definition lives per site at a time.
Disable schedule
Pauses scheduled backups without deleting the definition. Existing snapshots remain in the catalog and respect their retention windows.
Set retention
A standalone write that sets the default retention window for newly-created snapshots. Independent of the schedule definition — applies to manual snapshots and to scheduled snapshots equally. The site can also configure per-snapshot retention overrides via the pin mechanism.
Pin snapshot
Marks a specific snapshot as protected from retention sweeps. Pinned snapshots carry an optional label (for example, pre-launch or before-migration) and an optional expiration date. Pinned snapshots without an expiration date remain indefinitely.
Unpin snapshot
Removes the pinned state. The snapshot returns to the standard retention window from its taken-at date. If the standard window has already elapsed, the snapshot is queued for deletion on the next retention sweep.
Restore snapshot
Opens the restore confirmation flow. Displays the snapshot's metadata, a diff summary of what will change (database tables affected, media records that will be replaced), and a confirmation prompt. On confirmation, the surface takes an automatic pre-restore snapshot, marks the running site as restoring, applies the chosen snapshot, and surfaces a post-restore verification step.
Download snapshot
Produces a downloadable .sgen archive of the chosen snapshot. The archive is the canonical SGEN backup format — a self-contained file that another SGEN site can import via the platform's site-import path. Used for off-platform retention, for audit submission, or for cross-site migration.
Delete snapshot
Removes a snapshot from the catalog. Pinned snapshots cannot be deleted directly — unpin first. The deletion releases the storage allowance the snapshot occupied; the freed space becomes available on the next allowance check.
Restore from upload
A reverse of download. Accepts an uploaded .sgen archive and treats it as a snapshot for the purpose of the restore flow. Used to bring a backup from another site (for example, staging-to-production) into the current site.
Verify snapshot
A read-only operation that checks the snapshot's archive integrity — the manifest is present, the database dump is well-formed, the media manifest resolves against the archive's contents. Returns a structured pass / fail report with named findings. Used in audit workflows and before high-stakes restores.
Data model
A snapshot record carries the following fields. Field names below are the conceptual shape — the on-disk column names match closely but are not contractually stable across releases.
| Field | Type | Notes |
|---|---|---|
id | integer | Primary key. Stable across edits. |
site_id | integer | Foreign key to the site. |
taken_at | timestamp | Capture-start time. Immutable. |
taken_by_user_id | integer | Foreign key to a user. Nullable for scheduled captures (the platform actor). |
type | enum | manual or scheduled. |
status | enum | capturing, available, restoring, deleted. |
size_bytes | integer | Final archive size. |
retention_until | timestamp | When the retention sweep will delete this snapshot. Nullable for pinned. |
pinned | boolean | True if the snapshot is protected from retention sweeps. |
pin_label | string | Optional. Free-text label for pinned snapshots. |
pin_expires_at | timestamp | Optional. Auto-unpin date. |
archive_path | string | Internal storage reference. Not exposed in read responses. |
manifest | JSON | Top-level contents summary — table counts, media file count, theme assets count, custom code presence flags. |
created_at | timestamp | Immutable. |
updated_at | timestamp | Touched on pin/unpin and on status transitions. |
capturing— the background job is still writing the archive. The snapshot is not yet restorable.available— capture complete. Restorable and downloadable.restoring— a restore from this snapshot is in progress. The snapshot itself remains intact.deleted— soft-deleted; archive removed on the next retention sweep, but the catalog row remains for audit purposes.
manual, an auto-generated label (for example, pre-restore-2026-05-21-1430), and a 30-day retention window. This snapshot is created even if the restore is later aborted.Retention sweep: runs on a fixed cadence (configured platform-side, not in this surface). The sweep deletes archives whose retention_until has elapsed, ignores pinned snapshots, and respects an in-progress restore (a snapshot in restoring state is never swept). The catalog row may survive the archive deletion in deleted status for the audit window.
.sgen archive format: the canonical SGEN backup file format. Filename convention sgen_. The archive is self-contained — restoring on a different SGEN site produces a complete copy of the original site as of the snapshot time.
SNAPSHOT LIFECYCLE┌──────────────┐│ capturing │ ◄── manual trigger OR scheduled cadence└──────┬───────┘│ job completes▼┌──────────────┐│ available │ ◄── default state, restorable + downloadable└──────┬───────┘│├── pin ──► protected from retention sweep│ (optional label, optional expiry)│├── restore triggered ──► transient `restoring` state│ + auto pre-restore snapshot│ (manual, 30d retention)│└── retention_until elapsed│▼┌──────────────┐│ deleted │ archive removed; catalog row kept for audit└──────────────┘Permissions
Access to the Backups surface is gated at two layers.
Layer 1 — admin gate. Every action under SG-Admin passes through the platform's standard admin access check at request entry. An unauthenticated request never reaches the Backups surface.
Layer 2 — per-action capability. Within SG-Admin, each Backups action checks a capability associated with the calling operator's role. The default role configuration ships with three roles — Administrator, Editor, Viewer — and the capability map is:
| Capability | Administrator | Editor | Viewer |
|---|---|---|---|
| List snapshots | ✔ | ✔ | ✔ |
| Take manual backup | ✔ | ✔ | — |
| Configure schedule | ✔ | — | — |
| Disable schedule | ✔ | — | — |
| Set retention | ✔ | — | — |
| Pin snapshot | ✔ | ✔ | — |
| Unpin snapshot | ✔ | ✔ | — |
| Restore snapshot | ✔ | — | — |
| Download snapshot | ✔ | ✔ | — |
| Delete snapshot | ✔ | — | — |
| Restore from upload | ✔ | — | — |
| Verify snapshot | ✔ | ✔ | ✔ |
Self-protection rules. A site cannot delete its most recent available snapshot if no schedule is configured — the surface returns a structured rejection. Restore is gated behind an explicit confirmation prompt that displays the diff summary; the prompt cannot be bypassed via the SG-Admin UI. Restore-from-upload validates the archive's source-site identifier against an allowlist when the platform's cross-site import gate is enabled.
Audit. Every write — snapshot creation, schedule edit, retention change, pin / unpin, restore initiation, restore completion, snapshot deletion — emits an Activity Log entry. The log records the acting operator, the target snapshot, and the change shape. Restores emit two entries: one at initiation (with the pre-restore snapshot ID) and one at completion (with the verification result). Activity Log retention follows the site's general settings.
REQUEST → /sg-admin/backups/...│▼┌────────────────────────┐│ Admin gate │ unauth → reject└──────────┬─────────────┘│ authed▼┌────────────────────────┐│ Role capability check │ role lacks cap → reject└──────────┬─────────────┘│ allowed▼┌────────────────────────┐│ Self-protection rules │ delete-last-snapshot / unconfirmed│ │ restore / cross-site source not│ │ allowlisted → reject└──────────┬─────────────┘│ passes▼┌────────────────────────┐│ Restore path only: │ auto pre-restore snapshot│ pre-restore snapshot │ (manual, 30d retention)└──────────┬─────────────┘│▼action executes│▼Activity Log entry(restores log twice — initiation + completion)Related references
- Settings — Reference. Owns retention defaults, Activity Log retention, and the cross-site import allowlist. Changes there reshape backup behavior.
- Posts — Reference. Per-post revisions cover content-level recovery; backups cover infrastructure-level recovery. The two are complementary.
- Pages — Reference. Page records are captured inside every snapshot. Restore overwrites the pages table from the snapshot.
- Media — Reference. Media files are referenced by manifest inside the archive. Restore re-creates the manifest entries; the underlying file storage is restored from the archive's media section.
- Appearance — Reference. Appearance record is captured inside every snapshot. Restore overwrites the appearance row from the snapshot.
- Custom CSS — Reference. Custom CSS is captured inside every snapshot.
- Custom Codes — Reference. Custom Codes are captured inside every snapshot.
- Activity Log — Reference. Backup writes emit Activity Log entries; the log is the audit trail for the surface.
/docs/backups.