Skip to main content

databases

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

Overview​

Namedatabases
TypeResource
Idoci.database.databases

Fields​

The following fields are returned by SELECT queries:

The database information was retrieved.

NameDatatypeDescription
idstringThe [OCID](/Content/General/Concepts/identifiers.htm) of the database.
characterSetstringThe character set for the database.
compartmentIdstringThe [OCID](/Content/General/Concepts/identifiers.htm) of the compartment.
connectionStringsobjectConnection strings to connect to an Oracle Database.
dataGuardGroupobjectDetails of Data Guard setup that the given database is part of. Also includes information about databases part of this Data Guard group and properties for their Data Guard configuration.
databaseManagementConfigobjectThe configuration of the Database Management service.
databaseSoftwareImageIdstringThe database software image [OCID](/Content/General/Concepts/identifiers.htm)
dbBackupConfigobjectBackup Options 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).
dbHomeIdstringThe [OCID](/Content/General/Concepts/identifiers.htm) of the Database Home.
dbNamestringThe database name.
dbSystemIdstringThe [OCID](/Content/General/Concepts/identifiers.htm) of the DB system.
dbUniqueNamestringA system-generated name for the database to ensure uniqueness within an Oracle Data Guard group (a primary database and its standby databases). The unique name cannot be changed.
dbWorkloadstringDeprecated. The dbWorkload field has been deprecated for Exadata Database Service on Dedicated Infrastructure, Exadata Database Service on Cloud@Customer, and Base Database Service. Support for this attribute will end in November 2023. You may choose to update your custom scripts to exclude the dbWorkload attribute. After November 2023 if you pass a value to the dbWorkload attribute, it will be ignored. The database workload type.
definedTagsobjectDefined tags for this resource. Each key is predefined and scoped to a namespace. For more information, see [Resource Tags](/Content/General/Concepts/resourcetags.htm).
encryptionKeyLocationDetailsobjectTypes of providers supported for managing database encryption keys
freeformTagsobjectFree-form tags for this resource. Each tag is a simple key-value pair with no predefined name, type, or namespace. For more information, see [Resource Tags](/Content/General/Concepts/resourcetags.htm). Example: {"Department": "Finance"}
homeTypestringRepresents database will be under oracle managed home or customer managed home (ORACLE_MANAGED, CUSTOMER_MANAGED)
isCdbbooleanTrue if the database is a container database.
kmsKeyIdstringThe OCID of the key container that is used as the master encryption key in database transparent data encryption (TDE) operations.
kmsKeyVersionIdstringThe 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.
lastBackupDurationInSecondsintegerThe duration when the latest database backup created.
lastBackupTimestampstring (date-time)The date and time when the latest database backup was created.
lastFailedBackupTimestampstring (date-time)The date and time when the latest database backup failed.
lifecycleDetailsstringAdditional information about the current lifecycle state.
lifecycleStatestringThe current state of the database. (PROVISIONING, AVAILABLE, UPDATING, BACKUP_IN_PROGRESS, UPGRADING, CONVERTING, TERMINATING, TERMINATED, RESTORE_FAILED, FAILED)
managedSoftwareUpdateDetailsobjectThe database registered for Oracle Managed Database Software Updates.
ncharacterSetstringThe national character set for the database.
pdbNamestringThe name of the pluggable database. The name must begin with an alphabetic character and can contain a maximum of thirty alphanumeric characters. Special characters are not permitted. Pluggable database should not be same as database name.
sidPrefixstringSpecifies a prefix for the Oracle SID of the database to be created.
sourceDatabasePointInTimeRecoveryTimestampstring (date-time)Point in time recovery timeStamp of the source database at which cloned database system is cloned from the source database system, as described in [RFC 3339](https:​//tools.ietf.org/rfc/rfc3339)
storageSizeDetailsobjectThe database storage size details. This database option is supported for the Exadata VM cluster on Exascale Infrastructure.
systemTagsobjectSystem tags for this resource. Each key is predefined and scoped to a namespace. For more information, see [Resource Tags](/Content/General/Concepts/resourcetags.htm).
timeCreatedstring (date-time)The date and time the database was created.
vaultIdstringThe [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.
vmClusterIdstringThe [OCID](/Content/General/Concepts/identifiers.htm) of the VM cluster.

Methods​

The following methods are available for this resource:

NameAccessible byRequired ParamsOptional ParamsDescription
getselectdatabaseId, regionGets information about the specified database.
listselectcompartmentId, regiondbHomeId, systemId, limit, page, sortBy, sortOrder, lifecycleState, dbNameGets a list of the databases in the specified Database Home.<br />
createinsertregion, sourceopc-retry-token, opc-request-idCreates a new database in the specified Database Home. If the database version is provided, it must match the version of the Database Home. Applies to Exadata and Exadata Cloud@Customer systems.<br />
updateupdatedatabaseId, regionif-matchUpdate the specified database based on the request parameters provided.<br />
deletedeletedatabaseId, regionif-match, performFinalBackup, opc-request-idDeletes the specified database. Applies only to Exadata systems.<br /><br />The data in this database is local to the Exadata system and will be lost when the database is deleted. Oracle recommends that you back up any data in the Exadata system prior to deleting it. You can use the performFinalBackup parameter to have the Exadata system database backed up before it is deleted.<br />
change_encryption_key_locationexecdatabaseId, region, providerTypeif-match, opc-retry-token, opc-request-idUpdate the encryption key management location for the database
convert_to_pdbexecdatabaseId, region, actionif-match, opc-request-idConverts a non-container database to a pluggable database.<br />
disable_database_managementexecdatabaseId, regionopc-retry-token, opc-request-id, if-matchDisables the Database Management service for the database.<br />
enable_database_managementexecdatabaseId, region, credentialDetails, privateEndPointId, serviceNameopc-retry-token, opc-request-id, if-matchEnables the Database Management service for an Oracle Database located in Oracle Cloud Infrastructure. This service allows the database to access tools including Metrics and Performance hub. Database Management is enabled at the container database (CDB) level.
migrate_vault_keyexecdatabaseId, region, kmsKeyIdif-match, opc-retry-token, opc-request-idChanges encryption key management from customer-managed, using the [Vault service](/iaas/Content/KeyManagement/Concepts/keyoverview.htm), to Oracle-managed.
modify_database_managementexecdatabaseId, regionopc-retry-token, opc-request-id, if-matchUpdates one or more attributes of the Database Management service for the database.
reschedule_managed_db_software_updateexecdatabaseId, regionif-match, opc-request-id, opc-retry-tokenReschedule the Managed Database Software Update<br />
restore_databaseexecdatabaseId, regionif-matchRestore a Database based on the request parameters you provide.<br />
rotate_vault_keyexecdatabaseId, regionif-match, opc-retry-token, opc-request-idCreates a new version of an existing [Vault service](/iaas/Content/KeyManagement/Concepts/keyoverview.htm) key.
upgrade_databaseexecdatabaseId, region, actionif-match, opc-request-idUpgrades the specified Oracle Database instance.<br />

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.

NameDatatypeDescription
compartmentIdstringThe compartment [OCID](/Content/General/Concepts/identifiers.htm).
databaseIdstringThe database [OCID](/Content/General/Concepts/identifiers.htm).
regionstringOCI 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)
dbHomeIdstringA Database Home [OCID](/Content/General/Concepts/identifiers.htm).
dbNamestringA filter to return only resources that match the entire database name given. The match is not case sensitive.
if-matchstringFor 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.
lifecycleStatestringA filter to return only resources that match the given lifecycle state exactly.
limitintegerThe maximum number of items to return per page.
opc-request-idstringUnique identifier for the request.
opc-retry-tokenstringA 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).
pagestringThe pagination token to continue listing from.
performFinalBackupbooleanWhether to perform a final backup of the database or not. Default is false. 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. This parameter is used in multiple APIs. Refer to the API description for details on how the operation uses it.
sortBystringThe field to sort by. You can provide one sort order (sortOrder). Default order for TIMECREATED is descending. Default order for DBNAME is ascending. The DBNAME sort order is case sensitive.
sortOrderstringThe sort order to use, either ascending (ASC) or descending (DESC).
systemIdstringThe [OCID](/Content/General/Concepts/identifiers.htm) of the Exadata DB system that you want to filter the database results by. Applies only to Exadata DB systems.

SELECT examples​

Gets information about the specified database.

SELECT
id,
characterSet,
compartmentId,
connectionStrings,
dataGuardGroup,
databaseManagementConfig,
databaseSoftwareImageId,
dbBackupConfig,
dbHomeId,
dbName,
dbSystemId,
dbUniqueName,
dbWorkload,
definedTags,
encryptionKeyLocationDetails,
freeformTags,
homeType,
isCdb,
kmsKeyId,
kmsKeyVersionId,
lastBackupDurationInSeconds,
lastBackupTimestamp,
lastFailedBackupTimestamp,
lifecycleDetails,
lifecycleState,
managedSoftwareUpdateDetails,
ncharacterSet,
pdbName,
sidPrefix,
sourceDatabasePointInTimeRecoveryTimestamp,
storageSizeDetails,
systemTags,
timeCreated,
vaultId,
vmClusterId
FROM oci.database.databases
WHERE databaseId = '{{ databaseId }}' -- required
AND region = '{{ region }}' -- required
;

INSERT examples​

Creates a new database in the specified Database Home. If the database version is provided, it must match the version of the Database Home. Applies to Exadata and Exadata Cloud@Customer systems.<br />

INSERT INTO oci.database.databases (
dbHomeId,
dbVersion,
kmsKeyId,
kmsKeyVersionId,
source,
region,
opc-retry-token,
opc-request-id
)
SELECT 
'{{ dbHomeId }}',
'{{ dbVersion }}',
'{{ kmsKeyId }}',
'{{ kmsKeyVersionId }}',
'{{ source }}' /* required */,
'{{ region }}',
'{{ opc-retry-token }}',
'{{ opc-request-id }}'
RETURNING
id,
characterSet,
compartmentId,
connectionStrings,
dataGuardGroup,
databaseManagementConfig,
databaseSoftwareImageId,
dbBackupConfig,
dbHomeId,
dbName,
dbSystemId,
dbUniqueName,
dbWorkload,
definedTags,
encryptionKeyLocationDetails,
freeformTags,
homeType,
isCdb,
kmsKeyId,
kmsKeyVersionId,
lastBackupDurationInSeconds,
lastBackupTimestamp,
lastFailedBackupTimestamp,
lifecycleDetails,
lifecycleState,
managedSoftwareUpdateDetails,
ncharacterSet,
pdbName,
sidPrefix,
sourceDatabasePointInTimeRecoveryTimestamp,
storageSizeDetails,
systemTags,
timeCreated,
vaultId,
vmClusterId
;

UPDATE examples​

Update the specified database based on the request parameters provided.<br />

UPDATE oci.database.databases
SET 
dbBackupConfig = '{{ dbBackupConfig }}',
dbHomeId = '{{ dbHomeId }}',
definedTags = '{{ definedTags }}',
freeformTags = '{{ freeformTags }}',
managedSoftwareUpdateDetails = '{{ managedSoftwareUpdateDetails }}',
newAdminPassword = '{{ newAdminPassword }}',
newTdeWalletPassword = '{{ newTdeWalletPassword }}',
oldTdeWalletPassword = '{{ oldTdeWalletPassword }}',
storageSizeDetails = '{{ storageSizeDetails }}'
WHERE 
databaseId = '{{ databaseId }}' --required
AND region = '{{ region }}' --required
AND if-match = '{{ if-match}}'
RETURNING
id,
characterSet,
compartmentId,
connectionStrings,
dataGuardGroup,
databaseManagementConfig,
databaseSoftwareImageId,
dbBackupConfig,
dbHomeId,
dbName,
dbSystemId,
dbUniqueName,
dbWorkload,
definedTags,
encryptionKeyLocationDetails,
freeformTags,
homeType,
isCdb,
kmsKeyId,
kmsKeyVersionId,
lastBackupDurationInSeconds,
lastBackupTimestamp,
lastFailedBackupTimestamp,
lifecycleDetails,
lifecycleState,
managedSoftwareUpdateDetails,
ncharacterSet,
pdbName,
sidPrefix,
sourceDatabasePointInTimeRecoveryTimestamp,
storageSizeDetails,
systemTags,
timeCreated,
vaultId,
vmClusterId;

DELETE examples​

Deletes the specified database. Applies only to Exadata systems.<br /><br />The data in this database is local to the Exadata system and will be lost when the database is deleted. Oracle recommends that you back up any data in the Exadata system prior to deleting it. You can use the performFinalBackup parameter to have the Exadata system database backed up before it is deleted.<br />

DELETE FROM oci.database.databases
WHERE databaseId = '{{ databaseId }}' --required
AND region = '{{ region }}' --required
AND if-match = '{{ if-match }}'
AND performFinalBackup = '{{ performFinalBackup }}'
AND opc-request-id = '{{ opc-request-id }}'
;

Lifecycle Methods​

Update the encryption key management location for the database

EXEC oci.database.databases.change_encryption_key_location 
@databaseId='{{ databaseId }}' --required, 
@region='{{ region }}' --required, 
@if-match='{{ if-match }}', 
@opc-retry-token='{{ opc-retry-token }}', 
@opc-request-id='{{ opc-request-id }}' 
@@json=
'{
"providerType": "{{ providerType }}"
}'
;