Restore and Download

Available actions appear on each backup record in the database service’s Backups tab. Forge binds every action to the exact workspace, project, environment, service, and database generation recorded for that backup.

Restore Availability

Restore availability depends on the database engine and the capabilities reported by the selected server’s Forge Agent. A blocked or unavailable action is authoritative and must not be bypassed with another service or server.

ClickHouse restore is not currently available. A connected server can restore an engine only after its exact Agent version and recovery capability have been qualified and enabled.

Restore A Backup

1. Open the correct database service and environment.
2. Select Backups and choose the intended backup.
3. Review its source generation, integrity status, restore-test evidence, and destination availability.
4. Create a fresh backup of the current database when possible.
5. Select Restore and complete the required confirmation.
6. Wait for validation and cutover to finish before changing application variables or restarting clients.

Forge prepares and validates a separate recovery candidate before replacing the active database generation. A preflight, integrity, role, permission, or application-login failure leaves the active database unchanged and records the reason.

Restore is still a destructive operation at cutover. Expect a brief client interruption and verify application health, background workers, and data access after completion.

PostgreSQL Recovery Evidence

PostgreSQL backups may depend on roles used for database ownership, schema access, object ownership, and grants. Forge does not classify PostgreSQL recovery as tested unless the isolated candidate reproduces the approved role and permission inventory and proves that the application role can authenticate.

A stored object and matching checksum are not sufficient evidence of PostgreSQL recoverability. Replace older backups that do not contain the required recovery evidence.

Download

Select Download when the backup record shows an accessible retained copy. Forge streams the available backup to the authenticated user without exposing storage credentials.

When the backup exists only in R2, Forge downloads the object from R2 into a temporary file, streams it to the browser, then cleans up the temporary file.

If neither a local file nor an accessible R2 object exists, the backup file cannot be downloaded.

Restore

Restore stages a separate candidate database volume, verifies and loads the backup there, and keeps the active volume unchanged until candidate validation succeeds.

Supported restore paths:

• PostgreSQL and TimescaleDB: recreate manifest-approved role dependencies, then run pg_restore --clean --if-exists with ownership and ACL enforcement.
• MySQL: mysql < backup.sql.
• MongoDB: mongorestore --archive --gzip --drop.
• Redis: replace /data/dump.rdb and restart Redis.

ClickHouse restore is not available yet.

PostgreSQL archives can reference roles used for object ownership and grants. Forge therefore does not classify PostgreSQL recovery as tested when the role-aware drill has not passed, even when the encrypted R2 object and checksums are verified. A failed drill leaves the active database unchanged and opens an actionable recovery incident.

For new local-service backups, Forge validates the encrypted role manifest, recreates policy-approved role stubs before pg_restore, restores the recorded database owner and database-level privileges, restores object ownership and permissions, compares the candidate’s role and permission inventory, rotates the candidate to the current Forge-held managed password, and authenticates through that role before cutover. PostgreSQL 16 and later role memberships retain their exact ADMIN, INHERIT, and SET options, including NOINHERIT application roles. ACL comparison uses canonical sorted privilege entries, so equivalent permissions remain equivalent even when PostgreSQL reconstructs its internal ACL array in a different order. Project roles and their password verifiers, including roles referenced by schema grants, are restored independently. Forge will not drop ACLs or ignore permission failures to manufacture a successful result. Backups created before the complete forge postgres bundle v1 format must be replaced before clean-target restore.

Restore Safety

Cutover replaces the target service’s active database generation. Treat restore as destructive:

• Create a fresh manual backup first when possible.
• Confirm you are on the correct database service.
• Expect client interruption during restore.
• Verify app variables after restoring into a migrated or recreated service.
• Require a successful application-role login and permission check for PostgreSQL before accepting the candidate.

Downloaded backups may contain production data and authentication material. Store them encrypted, restrict access, and delete unnecessary copies according to your retention policy.

Delete

Deleting a backup removes the retained copies tracked by that backup record. This action cannot be undone through Forge.

Before deletion, confirm that the service still has another current, off-site, restore-tested backup. Workspace permissions and protected-action checks apply to backup deletion.

Interpreting Results

• Succeeded means the requested operation completed for the destinations shown.
• Storage verified means the retained bytes passed integrity checks.
• Restore tested means an isolated recovery and its required validation passed.
• Blocked means the exact target, policy, credential, or Agent capability did not permit the operation.
• Failed means Forge attempted the operation but could not complete it; review the recorded cause before retrying.

Never treat a queued operation, a successful upload, or an old restore test as proof that the current database revision is recoverable.