db_homes

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

Overview

Name	db_homes
Type	Resource
Id	oci.database.db_homes

Fields

The following fields are returned by SELECT queries:

get

The Database Home.

Name	Datatype	Description
id	string	The [OCID](/Content/General/Concepts/identifiers.htm) of the Database Home.
compartmentId	string	The [OCID](/Content/General/Concepts/identifiers.htm) of the compartment.
databaseSoftwareImageId	string	The database software image [OCID](/Content/General/Concepts/identifiers.htm)
dbHomeLocation	string	The location of the Oracle Database Home.
dbSystemId	string	The [OCID](/Content/General/Concepts/identifiers.htm) of the DB system.
dbVersion	string	The Oracle Database version.
definedTags	object	Defined tags for this resource. Each key is predefined and scoped to a namespace. For more information, see [Resource Tags](/Content/General/Concepts/resourcetags.htm).
displayName	string	The user-provided name for the Database Home. The name does not need to be unique.
freeformTags	object	Free-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"}
homeType	string	Represents database home will be managed by oracle or customer (ORACLE_MANAGED, CUSTOMER_MANAGED)
kmsKeyId	string	The OCID of the key container that is used as the master encryption key in database transparent data encryption (TDE) operations.
lastPatchHistoryEntryId	string	The [OCID](/Content/General/Concepts/identifiers.htm) of the last patch history. This value is updated as soon as a patch operation is started.
lifecycleDetails	string	Additional information about the current lifecycle state.
lifecycleState	string	The current state of the Database Home. (PROVISIONING, AVAILABLE, UPDATING, TERMINATING, TERMINATED, FAILED)
oneOffPatches	array	List of one-off patches for Database Homes.
systemTags	object	System tags for this resource. Each key is predefined and scoped to a namespace. For more information, see [Resource Tags](/Content/General/Concepts/resourcetags.htm).
timeCreated	string (date-time)	The date and time the Database Home was created.
vmClusterId	string	The [OCID](/Content/General/Concepts/identifiers.htm) of the VM cluster.

list

A directory where Oracle Database software is installed. A bare metal or Exadata DB system can have multiple Database Homes<br />and each Database Home can run a different supported version of Oracle Database. A virtual machine DB system can have only one Database Home.<br />For more information, see [Bare Metal and Virtual Machine DB Systems](/Content/Database/Concepts/overview.htm) and [Exadata DB Systems](/Content/Database/Concepts/exaoverview.htm).<br /><br />To use any of the API operations, you must be authorized in an IAM policy. If you're not authorized, talk to an<br />administrator. If you're an administrator who needs to write policies to give users access,<br />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 Database Home.
compartmentId	string	The [OCID](/Content/General/Concepts/identifiers.htm) of the compartment.
databaseSoftwareImageId	string	The database software image [OCID](/Content/General/Concepts/identifiers.htm)
dbHomeLocation	string	The location of the Oracle Database Home.
dbSystemId	string	The [OCID](/Content/General/Concepts/identifiers.htm) of the DB system.
dbVersion	string	The Oracle Database version.
definedTags	object	Defined tags for this resource. Each key is predefined and scoped to a namespace. For more information, see [Resource Tags](/Content/General/Concepts/resourcetags.htm).
displayName	string	The user-provided name for the Database Home. The name does not need to be unique.
freeformTags	object	Free-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"}
homeType	string	Represents database home will be managed by oracle or customer (ORACLE_MANAGED, CUSTOMER_MANAGED)
kmsKeyId	string	The OCID of the key container that is used as the master encryption key in database transparent data encryption (TDE) operations.
lastPatchHistoryEntryId	string	The [OCID](/Content/General/Concepts/identifiers.htm) of the last patch history. This value is updated as soon as a patch operation is started.
lifecycleDetails	string	Additional information about the current lifecycle state.
lifecycleState	string	The current state of the Database Home. (PROVISIONING, AVAILABLE, UPDATING, TERMINATING, TERMINATED, FAILED)
oneOffPatches	array	List of one-off patches for Database Homes.
systemTags	object	System tags for this resource. Each key is predefined and scoped to a namespace. For more information, see [Resource Tags](/Content/General/Concepts/resourcetags.htm).
timeCreated	string (date-time)	The date and time the Database Home was created.
vmClusterId	string	The [OCID](/Content/General/Concepts/identifiers.htm) of the VM cluster.

Methods

The following methods are available for this resource:

Name	Accessible by	Required Params	Optional Params	Description
get	select	dbHomeId, region		Gets information about the specified Database Home.
list	select	compartmentId, region	dbSystemId, vmClusterId, backupId, dbVersion, limit, page, sortBy, sortOrder, lifecycleState, displayName	Lists the Database Homes in the specified DB system and compartment. A Database Home is a directory where Oracle Database software is installed.<br />
create	insert	region	opc-retry-token	Creates a new Database Home in the specified database system based on the request parameters you provide. Applies to bare metal DB systems, Exadata systems, and Exadata Cloud@Customer systems.<br />
update	update	dbHomeId, region	if-match	Patches the specified Database Home.
delete	delete	dbHomeId, region	if-match, performFinalBackup	Deletes a Database Home. Applies to bare metal DB systems, Exadata Cloud Service, and Exadata Cloud@Customer systems.<br /><br />Oracle recommends that you use the performFinalBackup parameter to back up any data on a bare metal DB system before you delete a Database Home. On an Exadata Cloud@Customer system or an Exadata Cloud Service system, you can delete a Database Home only when there are no databases in it and therefore you cannot use the performFinalBackup parameter to back up data.<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.

Name	Datatype	Description
compartmentId	string	The compartment [OCID](/Content/General/Concepts/identifiers.htm).
dbHomeId	string	The Database Home [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)
backupId	string	The [OCID](/Content/General/Concepts/identifiers.htm) of the backup. Specify a backupId to list only the DB systems or DB homes that support creating a database using this backup in this compartment.
dbSystemId	string	The DB system [OCID](/Content/General/Concepts/identifiers.htm). If provided, filters the results to the set of database versions which are supported for the DB system.
dbVersion	string	A filter to return only DB Homes that match the specified dbVersion.
displayName	string	A filter to return only resources that match the entire display name given. The match is not case sensitive.
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-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.
performFinalBackup	boolean	Whether 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.
sortBy	string	The field to sort by. You can provide one sort order (sortOrder). Default order for TIMECREATED is descending. Default order for DISPLAYNAME is ascending. The DISPLAYNAME sort order is case sensitive.
sortOrder	string	The sort order to use, either ascending (ASC) or descending (DESC).
vmClusterId	string	The [OCID](/Content/General/Concepts/identifiers.htm) of the VM cluster.

SELECT examples

get

Gets information about the specified Database Home.

SELECT
id,
compartmentId,
databaseSoftwareImageId,
dbHomeLocation,
dbSystemId,
dbVersion,
definedTags,
displayName,
freeformTags,
homeType,
kmsKeyId,
lastPatchHistoryEntryId,
lifecycleDetails,
lifecycleState,
oneOffPatches,
systemTags,
timeCreated,
vmClusterId
FROM oci.database.db_homes
WHERE dbHomeId = '{{ dbHomeId }}' -- required
AND region = '{{ region }}' -- required
;

list

Lists the Database Homes in the specified DB system and compartment. A Database Home is a directory where Oracle Database software is installed.<br />

SELECT
id,
compartmentId,
databaseSoftwareImageId,
dbHomeLocation,
dbSystemId,
dbVersion,
definedTags,
displayName,
freeformTags,
homeType,
kmsKeyId,
lastPatchHistoryEntryId,
lifecycleDetails,
lifecycleState,
oneOffPatches,
systemTags,
timeCreated,
vmClusterId
FROM oci.database.db_homes
WHERE compartmentId = '{{ compartmentId }}' -- required
AND region = '{{ region }}' -- required
AND dbSystemId = '{{ dbSystemId }}'
AND vmClusterId = '{{ vmClusterId }}'
AND backupId = '{{ backupId }}'
AND dbVersion = '{{ dbVersion }}'
AND limit = '{{ limit }}'
AND page = '{{ page }}'
AND sortBy = '{{ sortBy }}'
AND sortOrder = '{{ sortOrder }}'
AND lifecycleState = '{{ lifecycleState }}'
AND displayName = '{{ displayName }}'
;

INSERT examples

create

Creates a new Database Home in the specified database system based on the request parameters you provide. Applies to bare metal DB systems, Exadata systems, and Exadata Cloud@Customer systems.<br />

INSERT INTO oci.database.db_homes (
databaseSoftwareImageId,
definedTags,
displayName,
freeformTags,
isDesupportedVersion,
kmsKeyId,
kmsKeyVersionId,
source,
region,
opc-retry-token
)
SELECT 
'{{ databaseSoftwareImageId }}',
'{{ definedTags }}',
'{{ displayName }}',
'{{ freeformTags }}',
{{ isDesupportedVersion }},
'{{ kmsKeyId }}',
'{{ kmsKeyVersionId }}',
'{{ source }}',
'{{ region }}',
'{{ opc-retry-token }}'
RETURNING
id,
compartmentId,
databaseSoftwareImageId,
dbHomeLocation,
dbSystemId,
dbVersion,
definedTags,
displayName,
freeformTags,
homeType,
kmsKeyId,
lastPatchHistoryEntryId,
lifecycleDetails,
lifecycleState,
oneOffPatches,
systemTags,
timeCreated,
vmClusterId
;

Manifest

# Description fields are for documentation purposes
- name: db_homes
props:
  - name: region
    value: "{{ region }}"
    description: Required parameter for the db_homes resource.
  - name: databaseSoftwareImageId
    value: "{{ databaseSoftwareImageId }}"
    description: |
      The database software image [OCID](/Content/General/Concepts/identifiers.htm)
  - name: definedTags
    value: "{{ definedTags }}"
    description: |
      Defined tags for this resource. Each key is predefined and scoped to a namespace.
      For more information, see [Resource Tags](/Content/General/Concepts/resourcetags.htm).
  - name: displayName
    value: "{{ displayName }}"
    description: |
      The user-provided name of the Database Home.
  - name: freeformTags
    value: "{{ freeformTags }}"
    description: |
      Free-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"}`
  - name: isDesupportedVersion
    value: {{ isDesupportedVersion }}
    description: |
      If true, the customer acknowledges that the specified Oracle Database software is an older release that is not currently supported by OCI.
  - name: kmsKeyId
    value: "{{ kmsKeyId }}"
    description: |
      The OCID of the key container that is used as the master encryption key in database transparent data encryption (TDE) operations.
  - name: kmsKeyVersionId
    value: "{{ kmsKeyVersionId }}"
    description: |
      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.
  - name: source
    value: "{{ source }}"
    description: |
      The source of database: NONE for creating a new database. DB_BACKUP for creating a new database by restoring from a database backup.
    valid_values: ['NONE', 'DB_BACKUP', 'DATABASE', 'VM_CLUSTER_BACKUP', 'VM_CLUSTER_NEW', 'VM_CLUSTER_DATABASE']
    default: NONE
  - 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

Patches the specified Database Home.

UPDATE oci.database.db_homes
SET 
dbVersion = '{{ dbVersion }}',
definedTags = '{{ definedTags }}',
freeformTags = '{{ freeformTags }}',
oneOffPatches = '{{ oneOffPatches }}'
WHERE 
dbHomeId = '{{ dbHomeId }}' --required
AND region = '{{ region }}' --required
AND if-match = '{{ if-match}}'
RETURNING
id,
compartmentId,
databaseSoftwareImageId,
dbHomeLocation,
dbSystemId,
dbVersion,
definedTags,
displayName,
freeformTags,
homeType,
kmsKeyId,
lastPatchHistoryEntryId,
lifecycleDetails,
lifecycleState,
oneOffPatches,
systemTags,
timeCreated,
vmClusterId;

DELETE examples

delete

Deletes a Database Home. Applies to bare metal DB systems, Exadata Cloud Service, and Exadata Cloud@Customer systems.<br /><br />Oracle recommends that you use the performFinalBackup parameter to back up any data on a bare metal DB system before you delete a Database Home. On an Exadata Cloud@Customer system or an Exadata Cloud Service system, you can delete a Database Home only when there are no databases in it and therefore you cannot use the performFinalBackup parameter to back up data.<br />

DELETE FROM oci.database.db_homes
WHERE dbHomeId = '{{ dbHomeId }}' --required
AND region = '{{ region }}' --required
AND if-match = '{{ if-match }}'
AND performFinalBackup = '{{ performFinalBackup }}'
;