> ## Documentation Index
> Fetch the complete documentation index at: https://www.aptible.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# aptible backup:restore

This command is used to [restore from a Database Backup](/docs/core-concepts/managed-databases/managing-databases/database-backups#restoring-from-a-backup). This command creates a new database: it **does not overwrite your existing database.** In fact, it doesn't interact with your existing database at all. By default, all newly restored Databases are created as a 1GB [General Purpose (M) Container Profile](/docs/core-concepts/scaling/container-profiles#default-container-profile), however you can specify both container size and profile using the options.

You'll need the ID of an existing [Backup](/docs/core-concepts/managed-databases/managing-databases/database-backups) to use this command. You can find those IDs using the [`aptible backup:list`](/docs/reference/aptible-cli/cli-commands/cli-backup-list) command or through the Dashboard.

<Warning> Warning: If you are restoring a Backup of a GP3 volume, the new Database will be provisioned with the base [performance characteristics](/docs/core-concepts/scaling/database-scaling#throughput-performance): 3,000 IOPs and 125MB/s throughput. If the original Database's performance was scaled up, you may need to modify the restored Database if you wish to retain the performance of the source Database. </Warning>

# Synopsis

```
Usage:
  aptible backup:restore BACKUP_ID [flags]

Flags:
      --container-profile string   Container profile (e.g. m, c, r)
      --container-size int32       Container size in MB
      --disk-size int32            Disk size in GB
  -e, --env string                 Destination environment handle (alias)
      --environment string         Destination environment handle
      --handle string              Handle for restored database (auto-generated if not set)
      --iops int32                 Provisioned IOPS
```

# Examples

## Restore a Backup

```shell theme={null}
aptible backup:restore "$BACKUP_ID"
```

## Customize the new Database

You can also customize the new [Database](/docs/core-concepts/managed-databases/overview) that will be created from the Backup:

```shell theme={null}
aptible backup:restore "$BACKUP_ID" \
        --handle "$NEW_DATABASE_HANDLE" \
        --container-size "$CONTAINER_SIZE_MB" \
        --disk-size "$DISK_SIZE_GB"
```

If no handle is provided, it will default to `$DB_HANDLE-at-$BACKUP_DATE` where `$DB_HANDLE` is the handle of the Database the backup was taken from. Database handles must:

* Only contain lowercase alphanumeric characters,`.`, `_`, or `-`
* Be between 1 to 64 characters in length
* Be unique within their [Environment](/docs/core-concepts/architecture/environments)

Therefore, there are two situations where the default handle can be invalid:

* The handle is longer than 64 characters. The default handle will be 23 characters longer than the original Database's handle.
* The default handle is not unique within the Environment. Most likely, this would be caused by restoring the same backup to the same Environment multiple times.

## Restore to a different Environment

You can restore Backups across [Environments](/docs/core-concepts/architecture/environments) as long as they are hosted on the same type of [Stack](/docs/core-concepts/architecture/stacks). You can only restore Backups from a [Dedicated Stack](/docs/core-concepts/architecture/stacks#dedicated-stacks) in another Dedicated Stack and backups from a Shared Stack in another Shared Stack. Since Environments are globally unique, you do not need to specify the Stack in your command:

```shell theme={null}
aptible backup:restore "$BACKUP_ID" \
        --environment "$ENVIRONMENT_HANDLE"
```

## Disk Resizing Note

When specifying a disk size, note that the restored database can only be resized up (i.e., you cannot shrink your Database Disk). If you need to scale a Database Disk down, you can either dump and restore to a smaller Database or create a replica and failover. Refer to our [Supported Databases](/docs/core-concepts/managed-databases/supported-databases/overview) documentation to see if replication and failover is supported for your Database type.

#### Container Sizes (MB)

**General Purpose(M)**: 512, 1024, 2048, 4096, 7168, 15360, 30720, 61440, 153600, 245760