This command is used to restore from a Database 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. Since this is a new Database, Databases are created with General Purpose Container Profile, which is the default Container Profile.

You’ll need the ID of an existing Backup to use this command. You can find those IDs using the aptible backup:list command or through the Dashboard.

❗️ Warning: If you are restoring a Backup of a GP3 volume, the new Database will be provisioned with the base performance characteristics: 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.


  aptible backup:restore BACKUP_ID [--environment ENVIRONMENT_HANDLE] [--handle HANDLE] [--container-size SIZE_MB] [--disk-size SIZE_GB] [--key-arn KEY_ARN]

  [--handle=HANDLE]            # a name to use for the new database
  [--environment=ENVIRONMENT]  # a different environment to restore to


Restore a Backup

aptible backup:restore "$BACKUP_ID"

Customize the new Database

You can also customize the new Database that will be created from the Backup:

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

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 as long as they are hosted on the same type of Stack. You can only restore Backups from a Dedicated Stack 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:

aptible backup:restore "$BACKUP_ID" \
        --environment "$ENVIRONMENT_HANDLE"

Container Sizes (MB)

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