---
component: ROOT
version: "2026.3"
slug: ROOT/operations/recovery
canonical_url: "https://docs.develocity.ai/2026.3/operations/recovery/"
title: "Disaster Recovery"
description: "Restore Develocity from a database backup: the embedded database via develocityctl, and a user-managed PostgreSQL or Amazon RDS via your provider's tools."
keywords:
  - "database backup"
  - "develocityctl"
  - "Amazon RDS"
status: current
---

<!-- llms-index: https://docs.develocity.ai/llms.txt -->

# Disaster Recovery

<a id="preamble"></a>

<a id="recovery-restore"></a>

Restore Develocity to an earlier state from a database backup, for both the embedded database and a user-managed one.

A restore requires downtime, so schedule it as a maintenance window.

> [!IMPORTANT]
> A restore operation overwrites current data. Before proceeding, confirm you have the correct backup archive. Everything Develocity recorded between that backup and now is lost.

<a id="restoring-an-embedded-database"></a>

## Restoring an Embedded Database

If you are using the embedded database, restore it with the [Develocity CLI](https://docs.develocity.ai/develocityctl/1.24/).

<a id="standalone-installations"></a>

### Standalone Installations

1.  **Identify the Backup:** Locate the `.zip` backup archive in `/opt/gradle/backups` (or your custom off-host storage location).
    
2.  **Run the Restore:** Use the following command, replacing the placeholder with your specific filename:
    
    ```shell
    develocityctl backup restore /opt/gradle/backups/backup-«date-time».zip
    ```
    

<a id="kubernetes-installations"></a>

### Kubernetes Installations

1.  **Identify the Backup:** If you have copied backups off-cluster, use one of those. If you need to copy a backup from the cluster, use `develocityctl backup copy`:
    
    ```shell
    develocityctl backup copy ./backup.zip
    ```
    
2.  **Run the Restore:** Use the following command with the path to the backup archive:
    
    ```shell
    develocityctl backup restore ./backup.zip
    ```
    

<a id="monitoring-the-restore"></a>

### Monitoring the Restore

The CLI scales down the Develocity deployments before restoring the data, then scales them back up.

```text
Found Develocity installed in the 'develocity' namespace.
Copying backup
Restarting
deployments.apps/edge-node scaled
deployments.apps/gradle-monitoring scaled
deployments.apps/gradle-enterprise-operator scaled
...
Done. Backup will be restored.
```

> [!NOTE]
> If horizontal scaling is enabled, the restore command resets the replica counts to the values defined in your configuration.

<a id="restoring-a-user-managed-database"></a>

## Restoring a User-Managed Database

For a user-managed database such as PostgreSQL or Amazon RDS, restore the database with your provider’s own tools.

<a id="restore-inplace"></a>

### Scenario A: In-Place Restore

Use this if you are restoring data to the **same** database instance.

1.  **Stop Develocity:** To prevent data corruption, stop the application services.
    
    ```shell
    develocityctl system stop
    ```
    
2.  **Restore Data:** Follow your provider’s instructions (e.g., `pg_restore` or a cloud snapshot restoration).
    
3.  **Verify Permissions:** If you do not provide superuser credentials to Develocity, re-run your database setup scripts. They set the permissions for the application role, which serves requests, and the migrator role, which runs schema migrations.
    
4.  **Start Develocity:**
    
    ```shell
    develocityctl system start
    ```
    

<a id="scenario-b-restore-to-a-new-instance"></a>

### Scenario B: Restore to a New Instance

Use this if you are moving data to a **different** database server.

1.  **Stop Develocity:** Ensure the old instance is no longer receiving traffic via `develocityctl system stop`.
    
2.  **Restore to New Host:** Follow your provider’s instructions to restore your backup data onto the new instance.
    
3.  **Update Configuration:** Configure Develocity with the connection details for the new instance, and the superuser credentials if you provide them. Re-run Helm, or update the `ConfigMap` and `Secret` resources.
    
4.  **Verify Permissions:** If you do not provide superuser credentials to Develocity, run the database setup script (see your installation manual) against the new database. Then confirm that the application and migrator passwords work, either in the configuration UI or in the `Secret` resources.
    
5.  **Start Develocity:** Use `develocityctl system start` to initiate the connection.
    

<a id="troubleshooting-restoration-failures"></a>

## Troubleshooting Restoration Failures

If the system fails to start after a restore:

1.  **Check Logs:** Review the application logs for connection strings or permission errors.
    
    ```shell
    kubectl --namespace=«namespace» logs --selector=app.kubernetes.io/component=enterprise-app
    ```
    
2.  **Verify Network:** If you migrated to a new database instance, verify that the Develocity Pods can reach the new database host and port. You can test connectivity from within the cluster by running a temporary Pod:
    
    ```shell
    kubectl --namespace=«namespace» run --rm -it pg-test --image=busybox --restart=Never -- nc -zv «db-host» «db-port»
    ```
    
3.  **Generate Support Bundle:** If the issue persists, generate a diagnostic bundle and share it with [Develocity support](https://support.gradle.com/).
    
    ```shell
    develocityctl support-bundle
    ```
    

<a id="related-operations"></a>

## Related Operations

*   [Configuring Backup Schedules](https://docs.develocity.ai/2026.3/administration/data-management/database-backups/)
    
*   [Migrating Storage Backends](https://docs.develocity.ai/2026.3/operations/migrations/)