Add a Distribution Path

A Distribution path sends the transaction of data from an Extract to a Replicat.

Related Topics

When to use a Distribution Path

Use a Distribution Path when you need to replicate data in a distributed deployment environment. A Distribution Path sends the transaction of data from the Extract to the Replicat. Creating and running a Distribution Path automatically creates a Receiver Path in the target deployment's Receiver service. The Receiver Path receives the transaction of data from the source deployment's Distribution service.

The source deployment is the deployment where you create the Distribution Path. The target deployment is the deployment to which the extracted data and Trails are sent.

Before you begin

Ensure that you create GoldenGate connections for each deployment you want to connect to, and then assign them to the deployment from which the path originates. For example, the deployment where you create the Distribution Path or target-initiated Receiver Path.

Otherwise, in IAM-enabled deployments, you'll encounter the error:

The network connection could not be established: 'OGG-08654' - 'Invalid or missing OAuth
      resource - audiencescope in Client application'.

Create and run a Distribution Path (21c)

Add a Credential that allows a source deployment (the deployment where you create this Path) to connect to a target deployment:
  1. In the target deployment console, log in, and then access the Administrator page from the navigation menu.
  2. Click Add User, and then create a user that the source deployment can use to connect to the target deployment. Assign this user the Operator role.
  3. Open the source deployment console, and then navigate to the Configuration page.
  4. Under the Database tab, click Add Credential, and then complete the following:
    • Credential Domain: Enter a name for this connection
    • Credential Alias: Enter an alias
    • User ID: Enter the name of the user created in step 2.
    • Password and Verify Password: Enter the password associated with this user from step 2.
  5. Click Submit.
To add a Distribution Path:
  1. In the OCI GoldenGate deployment console, click Distribution Service.
  2. On the Distribution Service Overview page, click Add Path (plus icon).
  3. On the Add Path page, complete the fields as follows:
    1. For Path Name, enter a name for the path.
    2. (Optional) For Description, enter a brief description of this path's purpose.
    3. (Optional) Enable Reverse proxy enabled to connect to the target using a reverse proxy.
    4. For Source, select the Extract name from the dropdown.
    5. For Trail Name, select the Extract trail from the dropdown.
    6. For Generated Source URI, the URI is automatically generated based on the Extract information provided. Click Edit (pencil icon) to modify the URI, if needed.
    7. For Target Authentication Method, select the authentication method for the target URI:
      • OAuth: Select this option if the source and target deployments are IAM enabled. This option uses the client credentials for authentication from the Distribution Service to Receiver Service.

        Note:

        In IAM enabled tenancies, select OAuth when connecting to another IAM-enabled deployment.
      • UserID Alias: This option uses a UserID Alias that you can create on the target Oracle GoldenGate to establish a connection.

        Note:

        Create a credential using the IAM user when connecting to an IAM-enabled deployment from a GoldenGate credential store deployment. Ensure that the user exists in the IAM Identity Stripe.
    8. For Target, select a data transfer protocol from the dropdown:
      • wss: Web socket secure is the default option. If selected, you must complete the following fields:
        • Target Host
        • Port Number
        • Trail Name
        • Deployment Name (reverse proxy enabled)
        • URI Path (reverse proxy enabled)
        • Domain
        • Alias
      • ogg: If select, you must complete the following fields:
        • Target Host
        • Port Number
        • Trail Name
        • Deployment Name (reverse proxy enabled)
        • URI Path (reverse proxy enabled)
      • ws: If selected, you must complete the following fields:
        • Target Host
        • Port Number
        • Trail Name
        • Deployment Name (reverse proxy enabled)
        • URI Path (reverse proxy enabled)
        • Domain
        • Alias
    9. For Generated Target URI, the URI is automatically populated from the information provided. Click Edit (pencil icon) to modify the URI, if needed.
    10. For Target Encryption Algorithm, select an encryption algorithm for the target trail:
      • None
      • AES128
      • AES192
      • AES256
    11. For Enable Network Compression, select this option to set the Compression Threshhold.
    12. For Sequence Length, enter the length of the trail sequence number.
    13. For Trail Size (MB), enter the maximum size fo a file in a trail.
    14. For Configure Trail Format, enable this option if you want to configure the trail file format, and then complete the additional fields as needed.
  4. Under the Encryption Profile section, complete the following fields as needed:
    1. Profile Name
    2. Encryption Profile Type
    3. Masterkey Name
    4. For Begin, select where to log data:
      • Now
      • Custom Time
      • Position in Log (default)
    5. For Source Sequence Number, select the sequence number of the trail file source deployment Extract.
    6. For Source RBA Offset, enter the Relative Byte Address (RBA) in the trail file where you want the process to start.
    7. For Critical, set this option to True if the distribution path is critical to the deployment. The default is False.
    8. For Auto Restart, set this option to True if you want the distribution path to restart automatically if it's terminated.
    9. For Auto Restart Options, indicate the number of retries to retart the path process and the delay duration interval between retries.
  5. Under Rule-set Configuration, complete the following fields as needed:
    1. For Enable Filtering, if selected, click Add Rule, and then complete the additional fields.
  6. Under More Options, complete the following fields as needed:
    1. EOF Delay: end of file delay before searching for source data
    2. Checkpoint Frequency: frequency in seconds for routine checkpoints
    3. App Options
      • TCP Flush Bytes: Flush size
      • TCP Flush Seconds: Flush interval
    4. TCP Options
      • DSCP: network differentiated services
      • TOS term of service
      • TCP_NODELAY: disables use of Nagle's algorithm if enabled
      • Quick ACK: sends acknowledgement if enabled
      • TCP_CORK: enables use of Nagle's algorithm
      • System Send buffer Size
      • System Receive Buffer Size
      • Keep Alive: timeout for keep alive
  7. Click Create and Run.
You return to the Overview page where you can view the status of the Path process.

Create and run a Distribution Path (23ai)

Add a Credential that allows a source deployment (the deployment where you create this Path) to connect to a target deployment:
  1. In the target deployment console, log in, and then access the User Adminstration page from the left navigation.
  2. Click Add New User, and then complete the following:
    • Authenticated By: Select Password from the dropdown.
    • Role: Select Operator from the dropdown.
    • Username: Enter your username.
    • Password and Verify Password: Enter the password associated with this user.
  3. Open the source deployment console, and then navigate to the Path Connections in the left navigation menu.
  4. Under the Database tab, click Add Path Connection, and then complete the following:
    • Credential Alias: Enter an alias.
    • User ID: Enter the name of the user created in step 2.
    • Password and Verify Password: Enter the password associated with this user from step 2.
  5. Click Submit.
To add a Distribution Path in GoldenGate 23ai:
  1. In the OCI GoldenGate deployment console, click Distribution Service.
  2. On the Home page, click Add Distribution Path (plus icon).
  3. In the Add Path panel, complete the Path Information fields as needed, and then click Next:
    1. Enter the Path Name, enter a name for the path.
    2. (Optional) Enter a Description, to describe this path's purpose and list the Extract and Replicats involved.
  4. On the Source Options page, enter the fields as needed, and then click Next:
    • Select the Source Extract from the dropdown.
    • Enter the Trail Name
    • Enter the Subdirectory, if you expect the Trail to be in a location other than the default.
    • The Generated Source URI is automatically generated based on the information provided. Click Edit (pencil icon) to modify the URI, if needed.
    • Select an Encryption Profile. The Local Wallet profile is selected by default if an encryption profile wasn't created.
    • For Begin, select the starting point for data processing:
      • Position in Log
      • Now
      • Custom Time
      • CSN (at or after)
    • Enter the Sequence Number.
    • Enter the RBA Offset.
  5. On the Target Options page, complete the fields as needed, and then click Next:
    • Select a Target Protocol:
      • ws
      • wss
      • ogg
    • (Optional) Enable Reverse proxy enabled to connect to the target using a reverse proxy.
    • Target type (ogg Target Protocol only)
      • Manager
      • Collector
      • Receiver Service
    • Enter the Target Host.
    • Enter the Port Number of the target deployment.
    • Enter the Trail Name for the target Trail file.
    • Enter the Subdirectory, if the Trail is located somewhere other than the default location.
    • Enter the maximum Trail Size.
    • Select a Target Encryption Algorithm used to send the Trail to the target deployment:
      • NONE
      • AES128
      • AES192
      • AES256
    • Enable Change Encryption to allow changes the encryption algorithm.
    • Generated Target URI is automatically generated based on the information provided. Click Edit (pencil icon) to modify the URI, if needed.
    • Select a Target Authentication Method (wss Target Protocol only)
      • UserID Alias

        Note:

        Create a credential using the IAM user when connecting to an IAM-enabled deployment from a GoldenGate credential store deployment. Ensure that the user exists in the IAM Identity Stripe.
      • OAuth

        Note:

        In IAM enabled tenancies, select OAuth when connecting to another IAM-enabled deployment.
      • Certificate
    • Select a Domain.
    • Select the Alias that has the Oracle GoldenGate UserID and Password.
    • Select a Target Type:
      • GGFormat (default)
      • SQL
      • XML
      • Plain Text
  6. On the Advanced Options page, complete the fields as needed, and then click Next:
    • Enable Enable Network Compression, to set the Compression Threshold.
    • Select EOF Delay.

      Note:

      On Linux platforms, the default settings can be retained. However, on non-Linux platforms, you may need to adjust this setting for high bandwidth, high latency networks, or for networks that have Quality of Service (QoS) settings (DSCP and Time of Service (ToS))
    • Select the Checkpoint Frequency to set the frequency of the path that is taking the checkpoint (in seconds).
    • Enter the TCP Flush Bytes (in bytes).
    • Enter the TCP Flush Seconds (in seconds).
    • Select the Differentiated Services Code Point (DSCP).
    • Select the Type of Service (TOS).
    • Enable TCP_NODELAY, to prevent delay when using the Nagle’s option.
    • Enable Quick ACK, to send quick acknowledgment after receiving data.
    • Enable TCP_CORK, to allow using the Nagle’s algorithm cork option.
    • Enter the System Send Buffer Size to set the value for the send buffer size for flow control.
    • Enter the System Receive Buffer Size, to set the value for the receive buffer size for flow control.
    • Set the timeout for Keep Alive.
  7. On the Filtering Options page, complete the following fields as needed, and then click Next:
    • Enter a Rule Name.
    • Select a Rule Action:
      • Exclude filters out data based on the selected options.
      • Include include data based on specified options.
    • Select a Filter Type:
      • Object Type: Select from three object types: DML, DDL, and Procedure
      • Object Names: Select this option to provide an existing object name. A 3–part naming convention depends on whether you are using CDB. With CDB, you need to use a 3–part naming convention, otherwise a 2–part convention is mandatory. 3–part convention includes container, schema, object. 2–part convention includes schema, object name.
      • Procedure Feature Name: Select this option to filter, based on existing procedure feature name.
      • Column Based: If you select this option, you are presented with the option to enter the table and column name to which the rule applies. You can filter out using column value with LT, GT, EQ, LE, GE, NE conditions. You can also specify if you want to have before image or after image in filtered data.
      • Tag: Select this option to set the filter based on tags.
      • Chunk ID: Displays the configuration details of database shards, however, the details can’t be edited.
    • Select Negate, to negate any existing rule.
    • Click Add to add the rule.
  8. On the Managed Options page, complete the optional fields as needed.
    • Enable Critical to configure this Path for high availability.
    • Enable Auto Restart to adjust Auto restart retries and Auto restart delay options.
  9. Click Create and Run to run your Path immediately. Click Create to run your Path manually at a later time.
You return to the Home page where you can view the status of the Path process.

Learn more

Interested in learning more about the Distribution Path process? Refer to the following resources:

Known issues

To create Distribution Paths to send data to or pull data from Oracle Cloud Infrastructure GoldenGate, ensure that you add the root certificate to Certificate Management or your client wallet

To send data to or pull data from OCI GoldenGate, you must create a Distribution Server Path or a target initiated path on the Receiver Server in your on-premises or Marketplace Oracle GoldenGate, respectively. You must also add the OCI GoldenGate root certificate or self-signed certificate to your Oracle GoldenGate Certificate Management (Oracle GoldenGate 21c or higher) or client wallet (Oracle GoldenGate 19c). This creates a trusted connection between your Oracle GoldenGate and OCI GoldenGate deployments. Only WebSocket Secure (WSS) protocol is supported for Distribution and Receiver Server Paths between Oracle GoldenGate and OCI GoldenGate.

A change in the OCI GoldenGate root certificate will cause the Distribution Server Path or a target initiated path on the Receiver Server in your on-premises or Marketplace Oracle GoldenGate to fail and produce the following error: 

ERROR   OGG-10390  Oracle GoldenGate Receiver Service:  Generic error -1 noticed for endpoint
      wss://<deployment URL>:443/services/v2/sources?trail=<trail name>. Error description - SSL
      connection unexpectedly closed.

Workaround: To fix this issue, update the certificate in the client wallet or Service Manager's Certificate Management screen to use the OCI GoldenGate Deployment Console root certificate. In some cases, when the OCI GoldenGate deployment’s certificate is not signed directly by the root certificate but by intermediate one(s) for example, it might be necessary to also add the intermediate CA certificate(s).

Learn more:

Only Digest Authentication is currently supported

Oracle Cloud Infrastructure GoldenGate doesn't currently support certificate-based authentication when you use Oracle Cloud Infrastructure GoldenGate as the Distribution Path target.

Workaround: None.