adminclient with OCI GoldenGate— Basic operations

Published in

Oracle Developers

7 min readMar 31, 2023

Get back to old style command line GG interface. Operate and Manage OCI GG with scripts and power of terminal.

Long time users of Oracle GoldenGate (OGG) are very comfortable with using ggsci command line utility. This was the only option for managing classic OGG. OGG microservices architecture (OGG MA) introduced adminclient utility. This had several advantages and enhancements over the classic ggsci utility.

Note — OGG classic architecture is deprecated from 21c onwards. OGG MA is the way forward

OCI offers OGG MA as a cloud native service. This implies you can use adminclient with OCI GG deployments. For whatever reasons, I rarely see users pursuing this.

In this post I will discuss advantages of using adminclient over web console. We can use adminclient either via:

Using OCI cloud shell. adminclient is pre-installed by default. We can also use “Launch Admin Client” button on OCI GG console page.
Installing OGG MA software locally.

In either case NW connectivity to your OCI GG endpoint (URL) is a pre-requisite. The product team has an excellent blog post on how to do this.

I will be using the pre-installed adminclient using cloud shell for this article.

Note — Launching adminclient directly from OCI GG console using “Launch” button, limits access only to adminclient. i.e., exiting adminclient will end the cloud shell session. Manually starting adminclient allows you to continue shell session after exiting adminclient

To access adminclient, start Cloud Shell from OCI console. No extra steps are needed to install or configure adminclient. As you can see adminclient location is already configured in PATH variable.

OCI Cloud Shell pre-installed adminclient utility

Next step is to log in to our OCI GG deployment. A good thing about adminclient is that syntax is easily available, in case we wish to verify the syntax.

Note — adminclient commands are not case sensitive. As a convention I will use all CAPS for commands in this article.

jigar_dosh@cloudshell:~ (eu-frankfurt-1)$ adminclient
Oracle GoldenGate Administration Client for Oracle
Version 21.9.0.0.1 OGGCORE_21.9.0.0.0OGGRU_PLATFORMS_230120.0600

Copyright (C) 1995, 2023, Oracle and/or its affiliates. All rights reserved.

Linux, x64, 64bit (optimized) on Feb  7 2023 20:47:42
Operating system character set identified as UTF-8.

OGG (not connected) 1> help CONNECT

CONNECT

Syntax:
| CONNECT <server-url> [ DEPLOYMENT <deployment-name> ]
|                      [ ( AS       <deployment-credentials-name>|                      |   USER     <deployment-user-name> )|                        [ PASSWORD <deployment-password>  ] ]
|                      [ PROXY      <proxy-uri>|                      [ ( AS       <proxy-credentials-name>|                      |   USER     <proxy-user-name>      )|                        [ PASSWORD <proxy-password>       ] ] ] [ ! ]

    You can use this command to
    connect to a Service Manager as well as the Administration Service URI.  ....
 ....
 ....
 CONNECT https://myserver.example.org as oggadmin !

Once you are connected to a deployment, the prompt changes to deployment administration server URL.

Note - Actual Deployment name masked for privacy.

OGG (not connected) 1> connect https://abcdefghijklm.deployment.goldengate.eu-frankfurt-1.oci.oraclecloud.com/ as oggadmin password <secretpassword> !

OGG (https://abcdefghijklm.deployment.goldengate.eu-frankfurt-1.oci.oraclecloud.com/ OCIGGTestDeployment) 2>

Configuring adminclient—

The first thing to do after logging in is to set few parameters to control adminclient behavior. Use SHOW command to view current settings.

OGG (https://../ OCIGGTestDeployment) 2> SHOW

Current directory: /home/jigar_dosh
COLOR            : OFF
DEBUG            : OFF
EDITOR           : vi
PAGER            : more
VERBOSE          : OFF

All the above parameters can be configured using SET command. I prefer to create a OBEY file and have all SET commands in one file.

A summary of commands in the output below —

CD — To change working directory. This is similar to UNIX cd command. However, keep in mind this is adminclient command. We can also use UNIX style auto-complete to provide destination path.
SHELL —To execute OS commands from within adminclient. In the output below, SHELL command is used to execute OS pwd and vi commands.
OBEY — command is used to call a file containing adminclient commands. This is like executing shell scripts. OBEY allows to execute frequently used commands by calling filename. We can also use UNIX style auto-complete to provide filename.

OGG (https://.../ OCIGGTestDeployment) 17> CD PracticalOGG
Command succeeded with no output.
OGG (https://.../ OCIGGTestDeployment) 22> SHELL pwd
/home/jigar_dosh/PracticalOGG
OGG (https://.../ OCIGGTestDeployment) 

OGG (https://.../ OCIGGTestDeployment) 23> SHELL vi SETVAL.oby

OGG (https://.../ OCIGGTestDeployment) 30> SHELL  cat SETVAL.oby 
SET COLOR ON
SET DEBUG OFF
SET VERBOSE ON
SET PAGER vi
SET EDITOR vi
OGG (https://.../ OCIGGTestDeployment) 31> OBEY SETVAL.oby 

OGG (https://.../ OCIGGTestDeployment) 32> SET COLOR ON
Command succeeded with no output.

OGG (https://.../ OCIGGTestDeployment) 33> SET DEBUG OFF
Command succeeded with no output.

OGG (https://.../ OCIGGTestDeployment) 34> SET VERBOSE ON
Command succeeded with no output.

OGG (https://.../ OCIGGTestDeployment) 35> SET PAGER vi
Command succeeded with no output.

OGG (https://.../ OCIGGTestDeployment) 36> SET EDITOR vi
Command succeeded with no output.

PAGER and EDITOR options are used to configure programs for viewing and editing files.

SET COLOR ON makes the adminclient output easier to read.

So far we have configured our environment and ensured our editor is correctly set to vi and not to emacs (Why use emacs?). What else can we do with adminclient?

Starting/Stopping individual processes from the console can be slow and painful if we have several processes. Often there is a need to change a parameter and restart subset of EXTRACT/REPLICAT processes. There is no RESTART option in console. adminclient has all these commands and more.

Using Wildcards -

Wildcards can be used to perform operations, such as start/stop/restart on group of processes. Let’s understand this with some examples.

Task — Start EXTRACT with names starting EHC

OGG (https://.../ OCIGGTestDeployment) 14> START EXTRACT EHC*
2023-03-26T17:02:35Z  INFO    OGG-00975  Extract group EHCNOPK starting.
2023-03-26T17:02:35Z  INFO    OGG-15426  Extract group EHCNOPK started.
2023-03-26T17:02:35Z  INFO    OGG-00975  Extract group EHCPK starting.
2023-03-26T17:02:35Z  INFO    OGG-15426  Extract group EHCPK started.

Task — Start REPLICAT with names ending with PK

OGG (https://.../ OCIGGTestDeployment) 15> START REPLICAT *PK
2023-03-26T17:04:06Z  INFO    OGG-00975  Replicat group RHCPK starting.
2023-03-26T17:04:06Z  INFO    OGG-15445  Replicat group RHCPK started.
2023-03-26T17:04:06Z  INFO    OGG-00975  Replicat group RNOPK starting.
2023-03-26T17:04:06Z  INFO    OGG-15445  Replicat group RNOPK started.

Task — RESTART EXTRACT/REPLICAT containing string PK.

Note that RESTART option does not exist in console.

OGG (https://.../ OCIGGTestDeployment) 19>  RESTART ER *PK*
2023-03-26T17:15:48Z  INFO    OGG-08100  Extract group EHCNOPK is already stopped.
2023-03-26T17:15:48Z  INFO    OGG-08100  Extract group EHCPK is already stopped.
2023-03-26T17:15:48Z  INFO    OGG-00975  Extract group EHCNOPK starting.
2023-03-26T17:15:48Z  INFO    OGG-15426  Extract group EHCNOPK started.
2023-03-26T17:15:48Z  INFO    OGG-00975  Extract group EHCPK starting.
2023-03-26T17:15:48Z  INFO    OGG-15426  Extract group EHCPK started.
2023-03-26T17:15:48Z  INFO    OGG-00975  Replicat group RHCPK starting.
2023-03-26T17:15:48Z  INFO    OGG-15445  Replicat group RHCPK started.
2023-03-26T17:15:48Z  INFO    OGG-00975  Replicat group RNOPK starting.
2023-03-26T17:15:48Z  INFO    OGG-15445  Replicat group RNOPK started.

Note — ER can be used as short code replacement for EXTRACT and REPLICAT with START/STOP/RESTART/INFO/SEND and other commands.

Task — Get statistics for all EXTRACT/REPLICAT containing string HC

OGG (https://.../ OCIGGTestDeployment) 22>  STATS ER *HC*

Task — Get status of all EXTRACT/REPLICAT containing string HC

OGG (https://.../ OCIGGTestDeployment) 24> STATUS ER *HC*
EXTRACT EHCNOPK: ABENDED
EXTRACT EHCPK: STOPPED
REPLICAT RHCPK: STOPPED

Task — Stop all REPLICAT with names starting R

OGG (https://.../ OCIGGTestDeployment) 25> STOP REPLICAT R*
2023-03-26T17:37:39Z  INFO    OGG-08100  Replicat group RHCPK is already stopped.
2023-03-26T17:37:39Z  INFO    OGG-08100  Replicat group RNOPK is already stopped.

Task — Stop all EXTRACT/REPLICAT

OGG (https://.../ OCIGGTestDeployment) 2> STOP ER *
2023-03-27T15:54:12Z  INFO    OGG-08100  Extract group EHCNOPK is already stopped.
2023-03-27T15:54:12Z  INFO    OGG-08100  Extract group EHCPK is already stopped.
2023-03-27T15:54:12Z  INFO    OGG-08100  Replicat group RNOPK is already stopped.
2023-03-27T15:54:12Z  INFO    OGG-08100  Replicat group RTZAD is already stopped.

Using HISTORY —

One of the most useful commands of adminclient is HISTORY and ability to execute the commands using “!” shortcut

In the output below:

HISTORY 5 will show the last 5 executed commands.
HISTORY will list all the commands executed in the session.

OGG (https://...OCIGGTestDeployment) 18> HISTORY 5
   14: versions
   15: VIEW REPORT EHCPK
   16: history
   17: history 5
   18: HISTORY 5

OGG (https://...OCIGGTestDeployment) 19> HISTORY 
    1: connect 
    2: shell vi conn.oby
    3: info all
    4: stop er *
    5: versions
    6: shell ls
    7: OBEY SETVAL.oby
    8: SET COLOR ON
    9: SET DEBUG OFF
   10: SET VERBOSE ON
   11: SET PAGER vi
   12: SET EDITOR vi
   13: history
   14: versions
   15: VIEW REPORT EHCPK
   16: history
   17: history 5
   18: HISTORY 5
   19: HISTORY

We can execute the commands from HISTORY output using ! shortcut:

OGG (https://...OCIGGTestDeployment) 22> HISTORY
 ...
 ...
 ...

   21: VIEW DISCARD EHCPK
   22: help
   23: show
   24: history

OGG (https://...OCIGGTestDeployment) 25> ! -2

Current directory: /home/jigar_dosh/PracticalOGG
COLOR            : ON
DEBUG            : OFF
EDITOR           : vi
PAGER            : vi
VERBOSE          : ON

OGG (https://...OCIGGTestDeployment) 26> ! VIEW
Command succeeded with no output.

! with negative suffix will execute previous n th command. In the example above ! -2, executes 2nd last command.

! with command prefix will execute the first matching command. In the output above ! VIEW executes the first matching VIEW command from the history.

! without any command/option will execute the last executed command.

By now you may have realized a lot of these commands and features are either not available in console or exist only in parts. For example, we can stop all EXTRACT processes but not selected processes using wildcards. Commands such as RESTART/SEND are not even available in the console.

Note — All commands discussed here apply to any OGG MA install, whether OCI or non-OCI

In the next article, I will discuss other complex operations and tricks using adminclient.

I hope this was informative. Share your thoughts and feedback in comments, or join our developer Slack channel to discuss.

Bookmark the repo for latest scripts and examples:

GitHub - GitJig/PracticalOGG: Collection of Oracle GoldenGate script examples and samples

You can't perform that action at this time. You signed in with another tab or window. You signed out in another tab or…

github.com