backups

Creates, updates, deletes, gets or lists a backups resource.

Overview

Name	backups
Type	Resource
Id	oci.database.backups

Fields

The following fields are returned by SELECT queries:

get

The database backup information was retrieved.

Name	Datatype	Description
id	string	The [OCID](/Content/General/Concepts/identifiers.htm) of the backup.
availabilityDomain	string	The name of the availability domain where the database backup is stored.
backupDestinationType	string	Type of the backup destination. (OBJECT_STORE, DBRS, AWS)
compartmentId	string	The [OCID](/Content/General/Concepts/identifiers.htm) of the compartment.
databaseEdition	string	The Oracle Database Edition that applies to all the databases on the DB system. Exadata DB systems and 2-node RAC DB systems require ENTERPRISE_EDITION_EXTREME_PERFORMANCE. (STANDARD_EDITION, ENTERPRISE_EDITION, ENTERPRISE_EDITION_HIGH_PERFORMANCE, ENTERPRISE_EDITION_EXTREME_PERFORMANCE, ENTERPRISE_EDITION_DEVELOPER)
databaseId	string	The [OCID](/Content/General/Concepts/identifiers.htm) of the database.
databaseSizeInGBs	number (double)	The size of the database in gigabytes at the time the backup was taken.
displayName	string	The user-friendly name for the backup. The name does not have to be unique.
encryptionKeyLocationDetails	object	Types of providers supported for managing database encryption keys
isUsingOracleManagedKeys	boolean	True if Oracle Managed Keys is required for restore of the backup.
kmsKeyId	string	The OCID of the key container that is used as the master encryption key in database transparent data encryption (TDE) operations.
kmsKeyVersionId	string	The OCID of the key container version that is used in database transparent data encryption (TDE) operations KMS Key can have multiple key versions. If none is specified, the current key version (latest) of the Key Id is used for the operation. Autonomous AI Database Serverless does not use key versions, hence is not applicable for Autonomous AI Database Serverless instances.
lifecycleDetails	string	Additional information about the current lifecycle state.
lifecycleState	string	The current state of the backup. (CREATING, ACTIVE, DELETING, DELETED, FAILED, RESTORING, UPDATING)
retentionPeriodInDays	integer	The retention period of the long term backup in days.
retentionPeriodInYears	integer	The retention period of the long term backup in years.
secondaryKmsKeyIds	array	List of OCIDs of the key containers used as the secondary encryption key in database transparent data encryption (TDE) operations.
shape	string	Shape of the backup's source database.
timeEnded	string (date-time)	The date and time the backup was completed.
timeExpiryScheduled	string (date-time)	Expiration time of the long term database backup.
timeStarted	string (date-time)	The date and time the backup started.
type	string	The type of backup. (INCREMENTAL, FULL, VIRTUAL_FULL)
vaultId	string	The [OCID](/Content/General/Concepts/identifiers.htm) of the Oracle Cloud Infrastructure [vault](/Content/KeyManagement/Concepts/keyoverview.htm#concepts). This parameter and secretId are required for Customer Managed Keys.
version	string	Version of the backup's source database

list

A database backup.<br />To use any of the API operations, you must be authorized in an IAM policy. If you're not authorized, talk to an administrator. If you're an administrator who needs to write policies to give users access, see [Getting Started with Policies](/Content/Identity/Concepts/policygetstarted.htm).<br /><br />Warning: Oracle recommends that you avoid using any confidential information when you supply string values using the API.<br />

Name	Datatype	Description
id	string	The [OCID](/Content/General/Concepts/identifiers.htm) of the backup.
availabilityDomain	string	The name of the availability domain where the database backup is stored.
backupDestinationType	string	Type of the backup destination. (OBJECT_STORE, DBRS, AWS)
compartmentId	string	The [OCID](/Content/General/Concepts/identifiers.htm) of the compartment.
databaseEdition	string	The Oracle Database Edition that applies to all the databases on the DB system. Exadata DB systems and 2-node RAC DB systems require ENTERPRISE_EDITION_EXTREME_PERFORMANCE. (STANDARD_EDITION, ENTERPRISE_EDITION, ENTERPRISE_EDITION_HIGH_PERFORMANCE, ENTERPRISE_EDITION_EXTREME_PERFORMANCE, ENTERPRISE_EDITION_DEVELOPER)
databaseId	string	The [OCID](/Content/General/Concepts/identifiers.htm) of the database.
databaseSizeInGBs	number (double)	The size of the database in gigabytes at the time the backup was taken.
displayName	string	The user-friendly name for the backup. The name does not have to be unique.
encryptionKeyLocationDetails	object	Types of providers supported for managing database encryption keys
isUsingOracleManagedKeys	boolean	True if Oracle Managed Keys is required for restore of the backup.
kmsKeyId	string	The OCID of the key container that is used as the master encryption key in database transparent data encryption (TDE) operations.
kmsKeyVersionId	string	The OCID of the key container version that is used in database transparent data encryption (TDE) operations KMS Key can have multiple key versions. If none is specified, the current key version (latest) of the Key Id is used for the operation. Autonomous AI Database Serverless does not use key versions, hence is not applicable for Autonomous AI Database Serverless instances.
lifecycleDetails	string	Additional information about the current lifecycle state.
lifecycleState	string	The current state of the backup. (CREATING, ACTIVE, DELETING, DELETED, FAILED, RESTORING, UPDATING)
retentionPeriodInDays	integer	The retention period of the long term backup in days.
retentionPeriodInYears	integer	The retention period of the long term backup in years.
secondaryKmsKeyIds	array	List of OCIDs of the key containers used as the secondary encryption key in database transparent data encryption (TDE) operations.
shape	string	Shape of the backup's source database.
timeEnded	string (date-time)	The date and time the backup was completed.
timeExpiryScheduled	string (date-time)	Expiration time of the long term database backup.
timeStarted	string (date-time)	The date and time the backup started.
type	string	The type of backup. (INCREMENTAL, FULL, VIRTUAL_FULL)
vaultId	string	The [OCID](/Content/General/Concepts/identifiers.htm) of the Oracle Cloud Infrastructure [vault](/Content/KeyManagement/Concepts/keyoverview.htm#concepts). This parameter and secretId are required for Customer Managed Keys.
version	string	Version of the backup's source database

Methods

The following methods are available for this resource:

Name	Accessible by	Required Params	Optional Params	Description
get	select	backupId, region		Gets information about the specified backup.
list	select	region	databaseId, compartmentId, limit, page, shapeFamily, version, type, lifecycleState, timeExpiryScheduledGreaterThanOrEqualTo, timeExpiryScheduledLessThan, backupDestinationType	Gets a list of backups based on the databaseId or compartmentId specified. Either one of these query parameters must be provided.<br />
create	insert	region, databaseId, displayName	opc-retry-token	Creates a new backup in the specified database based on the request parameters you provide. If you previously used RMAN or dbcli to configure backups and then you switch to using the Console or the API for backups, a new backup configuration is created and associated with your database. This means that you can no longer rely on your previously configured unmanaged backups to work.<br />
update	update	backupId, region	if-match, opc-request-id	Updates database backup details.
delete	delete	backupId, region	if-match	Deletes a full backup. You cannot delete automatic backups using this API.

Parameters

Parameters can be passed in the WHERE clause of a query. Check the Methods section to see which parameters are required or optional for each operation.

Name	Datatype	Description
backupId	string	The backup [OCID](/Content/General/Concepts/identifiers.htm).
region	string	OCI region identifier (e.g. us-ashburn-1, ap-sydney-1); resolves from OCI_REGION when not supplied in the query. (default: us-ashburn-1, x-stackQL-envVar: OCI_REGION)
backupDestinationType	string	A filter to return only resources that match the given backup destination type.
compartmentId	string	The compartment [OCID](/Content/General/Concepts/identifiers.htm).
databaseId	string	The [OCID](/Content/General/Concepts/identifiers.htm) of the database.
if-match	string	For optimistic concurrency control. In the PUT or DELETE call for a resource, set the if-match parameter to the value of the etag from a previous GET or POST response for that resource. The resource will be updated or deleted only if the etag you provide matches the resource's current etag value.
lifecycleState	string	A filter to return only resources that match the given lifecycle state exactly.
limit	integer	The maximum number of items to return per page.
opc-request-id	string	Unique identifier for the request.
opc-retry-token	string	A token that uniquely identifies a request so it can be retried in case of a timeout or server error without risk of executing that same action again. Retry tokens expire after 24 hours, but can be invalidated before then due to conflicting operations (for example, if a resource has been deleted and purged from the system, then a retry of the original creation request may be rejected).
page	string	The pagination token to continue listing from.
shapeFamily	string	If provided, filters the results to the set of database versions which are supported for the given shape family.
timeExpiryScheduledGreaterThanOrEqualTo	string (date-time)	The start of date-time range of expiration for the long term backups to be fetched.
timeExpiryScheduledLessThan	string (date-time)	The end of date-time range of expiration for the long term backups to be fetched.
type	string	A filter to return only backups that matches with the given type of Backup.
version	string	A filter to return only resources that match the given database version.

SELECT examples

get

Gets information about the specified backup.

SELECT
id,
availabilityDomain,
backupDestinationType,
compartmentId,
databaseEdition,
databaseId,
databaseSizeInGBs,
displayName,
encryptionKeyLocationDetails,
isUsingOracleManagedKeys,
kmsKeyId,
kmsKeyVersionId,
lifecycleDetails,
lifecycleState,
retentionPeriodInDays,
retentionPeriodInYears,
secondaryKmsKeyIds,
shape,
timeEnded,
timeExpiryScheduled,
timeStarted,
type,
vaultId,
version
FROM oci.database.backups
WHERE backupId = '{{ backupId }}' -- required
AND region = '{{ region }}' -- required
;

list

Gets a list of backups based on the databaseId or compartmentId specified. Either one of these query parameters must be provided.<br />

SELECT
id,
availabilityDomain,
backupDestinationType,
compartmentId,
databaseEdition,
databaseId,
databaseSizeInGBs,
displayName,
encryptionKeyLocationDetails,
isUsingOracleManagedKeys,
kmsKeyId,
kmsKeyVersionId,
lifecycleDetails,
lifecycleState,
retentionPeriodInDays,
retentionPeriodInYears,
secondaryKmsKeyIds,
shape,
timeEnded,
timeExpiryScheduled,
timeStarted,
type,
vaultId,
version
FROM oci.database.backups
WHERE region = '{{ region }}' -- required
AND databaseId = '{{ databaseId }}'
AND compartmentId = '{{ compartmentId }}'
AND limit = '{{ limit }}'
AND page = '{{ page }}'
AND shapeFamily = '{{ shapeFamily }}'
AND version = '{{ version }}'
AND type = '{{ type }}'
AND lifecycleState = '{{ lifecycleState }}'
AND timeExpiryScheduledGreaterThanOrEqualTo = '{{ timeExpiryScheduledGreaterThanOrEqualTo }}'
AND timeExpiryScheduledLessThan = '{{ timeExpiryScheduledLessThan }}'
AND backupDestinationType = '{{ backupDestinationType }}'
;

INSERT examples

create

Creates a new backup in the specified database based on the request parameters you provide. If you previously used RMAN or dbcli to configure backups and then you switch to using the Console or the API for backups, a new backup configuration is created and associated with your database. This means that you can no longer rely on your previously configured unmanaged backups to work.<br />

INSERT INTO oci.database.backups (
databaseId,
displayName,
retentionPeriodInDays,
retentionPeriodInYears,
region,
opc-retry-token
)
SELECT 
'{{ databaseId }}' /* required */,
'{{ displayName }}' /* required */,
{{ retentionPeriodInDays }},
{{ retentionPeriodInYears }},
'{{ region }}',
'{{ opc-retry-token }}'
RETURNING
id,
availabilityDomain,
backupDestinationType,
compartmentId,
databaseEdition,
databaseId,
databaseSizeInGBs,
displayName,
encryptionKeyLocationDetails,
isUsingOracleManagedKeys,
kmsKeyId,
kmsKeyVersionId,
lifecycleDetails,
lifecycleState,
retentionPeriodInDays,
retentionPeriodInYears,
secondaryKmsKeyIds,
shape,
timeEnded,
timeExpiryScheduled,
timeStarted,
type,
vaultId,
version
;

Manifest

# Description fields are for documentation purposes
- name: backups
props:
  - name: region
    value: "{{ region }}"
    description: Required parameter for the backups resource.
  - name: databaseId
    value: "{{ databaseId }}"
    description: |
      The [OCID](/Content/General/Concepts/identifiers.htm) of the database.
  - name: displayName
    value: "{{ displayName }}"
    description: |
      The user-friendly name for the backup. The name does not have to be unique.
  - name: retentionPeriodInDays
    value: {{ retentionPeriodInDays }}
    description: |
      The retention period of the long term backup in days.
  - name: retentionPeriodInYears
    value: {{ retentionPeriodInYears }}
    description: |
      The retention period of the long term backup in years.
  - name: opc-retry-token
    value: "{{ opc-retry-token }}"
    description: A token that uniquely identifies a request so it can be retried in case of a timeout or server error without risk of executing that same action again. Retry tokens expire after 24 hours, but can be invalidated before then due to conflicting operations (for example, if a resource has been deleted and purged from the system, then a retry of the original creation request may be rejected). 
    description: A token that uniquely identifies a request so it can be retried in case of a timeout or server error without risk of executing that same action again. Retry tokens expire after 24 hours, but can be invalidated before then due to conflicting operations (for example, if a resource has been deleted and purged from the system, then a retry of the original creation request may be rejected). 

UPDATE examples

update

Updates database backup details.

UPDATE oci.database.backups
SET 
retentionPeriodInDays = {{ retentionPeriodInDays }},
retentionPeriodInYears = {{ retentionPeriodInYears }}
WHERE 
backupId = '{{ backupId }}' --required
AND region = '{{ region }}' --required
AND if-match = '{{ if-match}}'
AND opc-request-id = '{{ opc-request-id}}'
RETURNING
id,
availabilityDomain,
backupDestinationType,
compartmentId,
databaseEdition,
databaseId,
databaseSizeInGBs,
displayName,
encryptionKeyLocationDetails,
isUsingOracleManagedKeys,
kmsKeyId,
kmsKeyVersionId,
lifecycleDetails,
lifecycleState,
retentionPeriodInDays,
retentionPeriodInYears,
secondaryKmsKeyIds,
shape,
timeEnded,
timeExpiryScheduled,
timeStarted,
type,
vaultId,
version;

DELETE examples

delete

Deletes a full backup. You cannot delete automatic backups using this API.

DELETE FROM oci.database.backups
WHERE backupId = '{{ backupId }}' --required
AND region = '{{ region }}' --required
AND if-match = '{{ if-match }}'
;