Use the Delphix Engine CLI or REST API to view and configure the Data Guard group for an Oracle dSource, refresh member roles, and list all Data Guard groups and members. For an explanation of Data Guard groups and how Delphix detects them, see Oracle Data Guard groups.
You manage Data Guard groups through the Delphix Engine API and CLI only. The Continuous Data UI does not support Data Guard groups. Data Guard support in DCT (API and UI) will be available in the DCT 2026.6.0 release.
The examples in this topic use the source configs DBOMPR5F392E (the primary database) and DBOMST5F392E (the physical standby database). Replace them with your own source config names and references.
Before you begin
-
API version 1.11.50 or later is required for
dataguardInfo. API version 1.11.52 or later is required fordataguardGroupRefand the Data Guard group list endpoints. -
All users can read the Data Guard group and member list endpoints. The
SOURCE_CONFIG_UPDATEpermission is required to update a source config and to runrefreshDgRoles.
Create the Data Guard group for a dSource linked before the upgrade
Upgrading to 2026.6.0.0 doesn't create Data Guard groups for dSources that were already linked. Until a group exists, dataguardInfo is null and SnapSync continues from the linked database as before. To create the group, do one of the following:
-
Refresh the environment of the linked database. This requires the environment OS user to be a member of the OSDBA or OSBACKUPDBA group.
-
CLI:
/environment select "<environment name>" refresh, thencommit -
API:
POST /resources/json/delphix/environment/{ref}/refresh
-
-
Run
refreshDgRoleson the linked dSource's source config. See Refresh member roles on demand.
Run refreshDgRoles on the linked database, not on the standby. If you run it on the unlinked standby, syncFrom is set to STANDBY, and the next SnapSync moves the dSource to the standby. Likewise, if you link a dSource to the standby before the group exists, syncFrom is set to STANDBY.
For SnapSync to move the dSource to another member, that member's environment must also be added to the Delphix Engine.
Then check the result with get dataguardInfo (see View the Data Guard group for a dSource), and set syncFrom if you want a different role.
View the Data Guard group for a dSource
The dataguardInfo block on a source config shows the group settings and a members array. dataguardInfo is null when the source config does not belong to a Data Guard group. It is returned only when you get a single source config, not by the source config list endpoint.
Using the CLI
> /sourceconfig select DBOMPR5F392E get dataguardInfo
type: OracleDgGroupView
name: DATAGUARD_GROUP-DBOMPR5F392E-DBOMST5F392E
description: (unset)
enabled: true
members:
0:
type: OracleDgGroupMemberView
name: DBOMST5F392E
current: false
role: STANDBY
1:
type: OracleDgGroupMemberView
name: DBOMPR5F392E
current: true
role: PRIMARY
skipFullSync: false
syncFrom: PRIMARY
Using the REST API
GET /resources/json/delphix/sourceconfig/{ref} returns the dataguardInfo block. For example (excerpt):
"dataguardInfo": {
"type": "OracleDgGroupView",
"name": "DATAGUARD_GROUP-DBOMPR5F392E-DBOMST5F392E",
"description": null,
"enabled": true,
"syncFrom": "PRIMARY",
"skipFullSync": false,
"members": [
{
"type": "OracleDgGroupMemberView",
"name": "DBOMST5F392E",
"role": "STANDBY",
"current": false
},
{
"type": "OracleDgGroupMemberView",
"name": "DBOMPR5F392E",
"role": "PRIMARY",
"current": true
}
]
}
Interpreting the response
-
namein each member is the member'sdb_unique_name. -
roleis the member's last known role:PRIMARY,STANDBY, orINVALID. Roles are updated at environment refresh, at dSource link, when you runrefreshDgRoles(when the group is enabled), and at SnapSync (when the group is enabled andsyncFromisPRIMARYorSTANDBY). -
current: truemarks the member that corresponds to the source config you queried. For a PDB, it marks the PDB's CDB.
To get the reference of the source config's Data Guard group (API 1.11.52 or later), use the read-only dataguardGroupRef field:
> /sourceconfig select DBOMPR5F392E get dataguardGroupRef
ORACLE_DG_GROUP-5
Change the SnapSync role preference
Set dataguardInfo.syncFrom to PRIMARY, STANDBY, or NO_PREFERENCE.
Using the CLI
> /sourceconfig select DBOMPR5F392E update
sourceconfig 'DBOMPR5F392E' update *> set dataguardInfo.syncFrom=STANDBY
sourceconfig 'DBOMPR5F392E' update *> commit
Using the REST API
Request:
POST /resources/json/delphix/sourceconfig/{ref}
Request body:
{
"type": "OracleSIConfig",
"dataguardInfo": {
"type": "OracleDgGroupView",
"syncFrom": "STANDBY"
}
}
Set type to the source config's type: OracleSIConfig, OracleRACConfig, or OraclePDBConfig.
What happens next
-
The dSource does not move when you commit the change. The next SnapSync detaches the dSource and reattaches it to the member that holds the chosen role.
-
With
NO_PREFERENCE, the dSource stays on its current member, even after a role change. However, if a member of the group is linked as a dSource, Delphix replacesNO_PREFERENCEwith the current role of a linked member the next time it detects the group during an environment refresh, when a dSource is linked, or when you runrefreshDgRoleson a linked member while the group is enabled. For a CDB, only a linked PDB in that CDB counts as linked. -
syncFromis a preference, not a guarantee. If no member holds the chosen role, SnapSync continues from the current member. The job does not show a warning. -
For dSources linked before upgrading to 2026.6.0.0, Delphix creates the Data Guard group the next time you refresh the environment, link another dSource in the same Data Guard configuration, or run
refreshDgRoles. It doesn't do this during the upgrade or at SnapSync. When Delphix creates the group during an environment refresh, it setssyncFromto the role of the database that's already linked. When it creates the group while linking a dSource or runningrefreshDgRoles, it setssyncFromto the role of the database you link or runrefreshDgRoleson.Setting
syncFromtoNO_PREFERENCEor disabling the group takes effect immediately but does not last. A disabled group is re-enabled the next time Delphix detects the group during an environment refresh. Linking a dSource to a database that Delphix hasn't yet added to the group can also re-enable it; linking a database that's already in the group does not. If a member of the group is linked as a dSource, Delphix also replacesNO_PREFERENCEwith the current role of a linked member the next time it detects the group during an environment refresh, when a dSource is linked, or when you runrefreshDgRoleson a linked member while the group is enabled. For a CDB, only a linked PDB in that CDB counts as linked.
Errors
A null value for syncFrom, enabled, or skipFullSync is rejected by input validation with the message "The field has to be set." An invalid value is also rejected by input validation before it reaches the engine. For example:
{
"type": "ErrorResult",
"status": "ERROR",
"error": {
"type": "APIError",
"details": {
"dataguardInfo": {
"syncFrom": {
"details": "Invalid value. Valid values are: PRIMARY, STANDBY, NO_PREFERENCE",
"id": "exception.validation.enum.invalid"
}
}
},
"action": "Check your input parameters and try again.",
"id": "exception.validation.bad.input"
}
}
Enable or disable Data Guard-aware SnapSync
Set dataguardInfo.enabled to false to disable Data Guard-aware SnapSync for the group. When a group is disabled, SnapSync behaves as if the group does not exist. The default is true.
> /sourceconfig select DBOMPR5F392E update
sourceconfig 'DBOMPR5F392E' update *> set dataguardInfo.enabled=false
sourceconfig 'DBOMPR5F392E' update *> commit
You can set dataguardInfo.description in the same way.
A disabled group is re-enabled the next time Delphix detects the group during an environment refresh. Linking a dSource to a database that Delphix hasn't yet added to the group can also re-enable it; linking a database that's already in the group does not. While a group is disabled, running refreshDgRoles on a database in the group fails with the error: DataGuard group "<name>" is disabled and cannot be refreshed.
Prevent an automatic full backup when the database incarnation changes
Set dataguardInfo.skipFullSync to true to stop policy-triggered SnapSyncs from running a full backup when they detect a new database incarnation. The default is false. This setting applies only when the group is enabled, and not to a dSource linked to a CDB.
> /sourceconfig select DBOMPR5F392E update
sourceconfig 'DBOMPR5F392E' update *> set dataguardInfo.skipFullSync=true
sourceconfig 'DBOMPR5F392E' update *> commit
-
When the group is enabled and
skipFullSyncistrue, any policy-triggered SnapSync that detects a new database incarnation (for example, after the database is opened withRESETLOGS) fails instead of running a full backup. This applies to non-multitenant and PDB dSources; it does not apply to a dSource linked to a CDB. -
A manual SnapSync always proceeds with a full backup, regardless of
skipFullSync.
Errors
When skipFullSync blocks a SnapSync, the SnapSync job fails with this error:
SnapSync of database "<dSource name>" of Data Guard group "<group name>" requires a full backup due to resetlogs, however the Data Guard group is configured to skip full backup and only take incremental backups.
Action: Either allow full backup for this Data Guard group or perform a manual SnapSync which will take a full backup.
Refresh member roles on demand
Run refreshDgRoles after a switchover or failover to update member roles before the next SnapSync. refreshDgRoles updates member roles and group membership. It does not move the dSource. It takes no parameters and returns the full source config with the refreshed dataguardInfo.
If no Data Guard group exists yet, and the database or another database in its Data Guard configuration is linked as a dSource (for a CDB, a PDB in that CDB is linked), refreshDgRoles reads the Data Guard configuration and creates the group. At least two members must be reachable. The new group's syncFrom is set to the role of the database you ran refreshDgRoles on, even if that database isn't linked. For example, if your dSource is linked to the primary and you run refreshDgRoles on the unlinked standby, syncFrom is set to STANDBY, so the next SnapSync moves the dSource to the standby. To avoid this, run refreshDgRoles on the linked database.
If a member can't be reached, the result shows its role as INVALID, but its saved role is not changed. Members whose environments have not been added to the Delphix Engine are not queried; they are listed with their last known role.
Using the CLI
> /sourceconfig select DBOMPR5F392E refreshDgRoles
sourceconfig 'DBOMPR5F392E' refreshDgRoles *> commit
type: OracleSIConfig
name: DBOMPR5F392E
...
dataguardGroupRef: ORACLE_DG_GROUP-5
dataguardInfo:
type: OracleDgGroupView
name: DATAGUARD_GROUP-DBOMPR5F392E-DBOMST5F392E
description: (unset)
enabled: true
members:
0:
type: OracleDgGroupMemberView
name: DBOMPR5F392E
current: true
role: PRIMARY
1:
type: OracleDgGroupMemberView
name: DBOMST5F392E
current: false
role: STANDBY
skipFullSync: false
syncFrom: PRIMARY
...
Using the REST API
Request:
POST /resources/json/delphix/sourceconfig/{ref}/refreshDgRoles
Request body:
{}
Errors
|
Cause |
Error message |
Action |
|---|---|---|
|
The source config is not an Oracle database. |
Database "<name>" is not an Oracle database. The |
Use the reference of an Oracle database. |
|
The database is not part of a Data Guard configuration with at least two databases, including itself; fewer than two of those databases could be reached, so no group was created; or the refresh left fewer than two members, so Delphix removed the group. |
Database "<name>" is not associated with any DataGuard group. |
Verify the database is correctly configured for DataGuard. |
|
No group exists yet, and neither the database nor any other database in its Data Guard configuration is linked as a dSource. For a CDB, only a linked PDB in that CDB counts; a dSource linked to the CDB itself does not. |
Cannot refresh DataGuard roles for database "<name>" because it is not linked. |
Link the database and try the refresh operation again. |
|
The group is disabled. |
DataGuard group "<name>" is disabled and cannot be refreshed. |
Enable the DataGuard group and try the refresh operation again. |
|
Delphix can't read the database's Data Guard configuration. If no group exists yet, this includes when Delphix can't connect to the database. |
DataGuard refresh could not be completed for database "<name>" because an error occurred while querying the database. |
Resolve the error on the database (for example connectivity, credentials, or availability) and try the refresh operation again. |
|
Another operation is using the same group, for example another |
Another operation is already in progress for DataGuard group "<name>". |
Wait for the in-progress operation to complete and try again. |
|
The group was removed while the refresh was running, for example because a member's dSource was deleted. |
DataGuard group "<name>" was concurrently removed. |
Verify the database's current DataGuard membership by inspecting the source configuration and try the operation again if needed. |
List all Data Guard groups and members
Listing groups and members requires API version 1.11.52 or later.
Using the CLI
> /sourceconfig oracle dataguardgroup list
NAME ENABLED SYNCFROM SKIPFULLSYNC
ORACLE_DG_GROUP-5 true PRIMARY false
ORACLE_DG_GROUP-6 true PRIMARY false
> /sourceconfig oracle dataguardgroupmember list
NAME DGGROUP CONFIG ROLE
ORACLE_DG_GROUP_MEMBER-9 ORACLE_DG_GROUP-5 DBOMST5F392E STANDBY
ORACLE_DG_GROUP_MEMBER-10 ORACLE_DG_GROUP-5 DBOMPR5F392E PRIMARY
In both list commands, the NAME column shows the object reference (for example, ORACLE_DG_GROUP-5), not the name value that the API returns (for example, DATAGUARD_GROUP-DBOMPR5F392E-DBOMST5F392E). Use the DGGROUP and CONFIG columns to match members to groups and source configs.
Using the REST API
GET /resources/json/delphix/sourceconfig/oracle/dataguardgroup
GET /resources/json/delphix/sourceconfig/oracle/dataguardgroupmember
Role change detection
For when Delphix re-reads member roles and when it moves the dSource, see "When roles are re-read and when the dSource moves" in Oracle Data Guard groups.
If LogSync raises the WARNING fault "LogSync DG role mismatch detected (pending SnapSync)", run a SnapSync or wait for the next policy SnapSync. Until then, LogSync continues to read from the database it is connected to. The SnapSync reattaches the dSource to the member that holds the configured role and clears the fault.
LogSync does not raise this fault when syncFrom is NO_PREFERENCE. If the group is disabled, SnapSync does not move the dSource, and LogSync keeps raising this fault even if a SnapSync clears it; enable the group, or set syncFrom to NO_PREFERENCE. For a dSource linked to a CDB, SnapSync does not move it, so this fault can continue after the PDB dSources move.
dataguardInfo reference
|
Field |
Type |
Default |
Description |
|---|---|---|---|
|
|
Enum: |
Set when the group is created: the role of the database being linked, or of the database
|
Role that SnapSync continues from. Writable. |
|
|
Boolean |
|
Turns Data Guard-aware SnapSync on or off. Writable. A disabled group is re-enabled the next time Delphix detects the group during an environment refresh. Linking a dSource to a database that Delphix hasn't yet added to the group can also re-enable it; linking a database that's already in the group does not. |
|
|
Boolean |
|
Fails policy-triggered SnapSyncs that detect a new database incarnation instead of running a full backup. Applies only when the group is enabled, and not to a dSource linked to a CDB. Writable. |
|
|
String |
|
Description of the group. Writable. |
|
|
String |
— |
Group name. Read-only. |
|
|
Array |
— |
Each member's |
The source config also has a read-only dataguardGroupRef field (API 1.11.52 or later) that holds the reference of its Data Guard group.