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 for dataguardGroupRef and the Data Guard group list endpoints.

  • All users can read the Data Guard group and member list endpoints. The SOURCE_CONFIG_UPDATE permission is required to update a source config and to run refreshDgRoles.

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, then commit

    • API: POST /resources/json/delphix/environment/{ref}/refresh

  • Run refreshDgRoles on 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

  • name in each member is the member's db_unique_name.

  • role is the member's last known role: PRIMARY, STANDBY, or INVALID. Roles are updated at environment refresh, at dSource link, when you run refreshDgRoles (when the group is enabled), and at SnapSync (when the group is enabled and syncFrom is PRIMARY or STANDBY).

  • current: true marks 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 replaces NO_PREFERENCE with 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 run refreshDgRoles on a linked member while the group is enabled. For a CDB, only a linked PDB in that CDB counts as linked.

  • syncFrom is 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 sets syncFrom to the role of the database that's already linked. When it creates the group while linking a dSource or running refreshDgRoles, it sets syncFrom to the role of the database you link or run refreshDgRoles on.

    Setting syncFrom to NO_PREFERENCE or 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 replaces NO_PREFERENCE with 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 run refreshDgRoles on 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 skipFullSync is true, any policy-triggered SnapSync that detects a new database incarnation (for example, after the database is opened with RESETLOGS) 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 refreshDgRoles operation is only available for Oracle databases.

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 refreshDgRoles, an environment refresh, a dSource link, or a dataguardInfo update.

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

syncFrom

Enum: PRIMARY, STANDBY, NO_PREFERENCE

Set when the group is created: the role of the database being linked, or of the database refreshDgRoles was run on. For a group detected during an environment refresh, the role of a linked member, or NO_PREFERENCE if no member is linked yet. For a CDB, only a linked PDB in that CDB counts as linked.

NO_PREFERENCE if the role can't be determined.

Role that SnapSync continues from. Writable.

enabled

Boolean

true

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.

skipFullSync

Boolean

false

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.

description

String

null

Description of the group. Writable.

name

String

—

Group name. Read-only.

members[]

Array

—

Each member's name (db_unique_name), role, and current flag. Read-only.

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.

Last updated
Nov 19, 2026