Cloning a database

This section describes how to restore a database from a backup by creating a new database. This approach has an advantage over in-place restore where an existing database state is reverted back in time because the original database is not modified or deleted during the restore operation. To restore a database, a new database (referred to as clone) is created from a successful backup (referred to as the restore source).

Restore database from backup#

The cloned database state is restored from the data in the backup and the supplied configuration is merged with the one stored in the backup. NuoDBaaS automatically infers database volume sizes from the backup or validates that the supplied values satisfy the restore. The DBA password in the database archive is changed to match the desired value of the new database by using the previous password stored in the backup. Database restore operation fails if the supplied backup can not be restored or if the original database configuration is incompatible with the clone.

Create a database clone#

Set the restoreFrom.backup field of the clone to the restore source. The backup’s fully-qualified name is used in the form of <org>/<proj>/<db>/<backup> as a restore source. If some prefix is omitted, it is taken from the clone database. For example, when creating a cloned database acme/messaging/clone with backup source demo/20241004095616, the system will assume that the backup exists in organization acme and project messaging. The cloned database can be created in any organization or project that the user has access. The user creating the clone must have read permission to the backup used as a restore source.

Create a new database clone and supply the backup to restore it from. In this example, a database named clone is created in the same organization and project as the original one.

nuodb-cp database create acme/messaging/clone \
 --restore-from-backup demo/20241004095616 \
  --dba-password changeIt

curl -X PUT -H 'Content-Type: application/json' \
 $NUODB_CP_URL_BASE/databases/acme/messaging/clone \
    -d '{"dbaPassword": "changeIt", "restoreFrom": {"backup": "demo/20241004095616"}}'

resource "nuodbaas_database" "db" {
 organization = nuodbaas_project.proj.organization
 project      = nuodbaas_project.proj.name
 name         = "clone"
 dba_password = "changeIt"
 restore_from = {
   backup = "acme/messaging/demo/20241004095616"
 }
}

Restore operation#

A database restore operation is performed asynchronously. The following prerequisites are enforced by the system:

• The backup used as a restore source must exist in the Kubernetes cluster along with the corresponding snapshots on the cloud provider’s storage system
• The snapshots must be in a state that allows new volumes to be created. Most storage providers allow changing the snapshot storage tier to achieve lower costs but with minimum archival and longer data retrieval times.
• The backup must be in Succeeded state
• Archive and journal volume sizes of the clone must be greater than or equal to the values of the original one
• If the original database was configured with an external journal, the clone must also have an external journal
• The NuoDB product version of the database clone must be greater than or equal to the product version of the original database

After the database is Available, the DBA password stored in the restored archive is replaced with the newly supplied password. This happens immediately after the database is ready to accept SQL connections, however, it may take several seconds before you can connect to the database.

Troubleshooting restore failures#

Any failures during the restore operation will prevent the database from starting. The status.message field provides more information about the failure.

Missing snapshot#

The restore fails because some of the snapshots are not found on the cloud provider’s storage system.

failed to restore backup acme-messaging-demo-20241008094059:
 snapshots not imported after 65ms: volume snapshot nuodb-cp-system/archive-volume-sm-acme-messaging-demo-zfb77wc-0-acme-messaging-demo-20241008094059-c8b8b48 failed:
 Failed to check and update snapshot content:
 failed to list snapshot for content snapcontent-archive-volume-sm-acme-messaging-demo-zfb77wc-0-acme-messaging-demo-20241008094059-c8b8b48-snap-0909778ab5d3fb463-44cz4d7: rpc error: code = Internal desc = Could not get snapshot ID "snap-0909778ab5d3fb463":
 InvalidSnapshot.NotFound: The snapshot 'snap-0909778ab5d3fb463' does not exist.
 status code: 400, request id: 768cc232-23a6-44ce-a1ac-a4f583c796c3

Incorrect volume size#

The restore fails because the supplied archive volume size is smaller than the one in the backup.

failed to restore database data:
 failed to use snapshot \"nuodb-cp-system/archive-volume-sm-acme-messaging-demo-zfb77wc-0-acme-messaging-demo-20240901000000-cz9v2zv\" for archive volume:
 configured storage size 2Gi is less than restored data size 5Gi

External journal enabled#

The restore fails because the external journal is enabled on the clone but not on the original database.

failed to restore database data: no snapshot for the journal volume found in backup

Database does not start#

The database state is reported as Restoring but the processes can not start on the restored data.

unhealthy components: [storageManagers transactionEngines];
 unhealthy resources: [deployment/te-acme-messaging-clone-dw7w9w7 statefulset/sm-acme-messaging-clone-dw7w9w7]