Syntax

add brokerconfig -connect connect_identifier 
                 [-pwd password]  
                 [-gdspool gdspool_name] 
                 [-region region_name] 
                 [-savename]
                 [-force]

Options

Usage Notes

• You must connect to the Global Data Services catalog database as a user with the pool administrator privileges, the GSMUSER database account, using the connect command before running the add brokerconfig command. You should use the CONNECT command to connect to the GSMUSER for the database that you are adding the broker configuration for.

• If a GDS pool already has databases or another configuration, an error is returned. If -region is specified, it defines only the region of primary database. If there is more than one region in catalog, GDS region property of standbys will be unassigned. The user will have to use modify database to specify GDS region.

Examples

Add the Oracle Data Guard broker configuration for the DB1 database to the Global Data Services pool MYREADERFARM and the WEST region.

GDSCTL> add brokerconfig -connect 192.168.1.1:1521:sid -region west -gdspool myreaderfarm

Exceptions or Error Codes

GDSCTL returns the errors listed below if you use this command incorrectly.

Syntax

add cdb -connect connect_identifier
         [-pwd gsmrootuser_pwd]
         [-savename]
         [-cpu_threshold cpu]
         [-disk_threshold disk]
         [-rack rack_id]
         [-force]

Options

Usage Notes

ADD CDB adds metadata about a CDB to a sharding catalog. This command is only necessary if you intend to deploy a PDB as a shard with the -cdb option in the ADD SHARD command. CDBs can support multiple PDB shards from different sharded databases; however, this support is limited to only one PDB shard from a given sharded database for each CDB.

Examples

Adds a CDB called db11 to the shard catalog.

GDSCTL> add cdb -connect db11 -pwd gsmrootuser_pwd

Syntax

add credential -credential credential_name 
               -osaccount account_name
               -ospassword password
              [-windows_domain domain_name]

Options

Usage Notes

This command adds a credential which will be used to execute jobs on sharded hosts in response to administrative commands. The operating system account may be any valid account on the remote host which is in the OSDBA group; the account does not need to be enabled for interactive login unless it is used for other purposes. A specific non-interactive account may be created for use with the remote scheduler, if desired. The OS password must be a valid and current password for the specified account.

If the specified credential already exists, the command returns an error.

Examples

Add a credential named east_region_cred.

GDSCTL> add credential –credential east_region_cred –osaccount agent_user
 –ospassword password

Syntax

add database -connect connect_identifier 
            [-region region_name]
            [-gdspool gdspool_name]
            [-pwd password]
            [-savename]
            [-cpu_threshold cpu] 
            [-disk_threshold disk]

Options

Usage Notes

• You must connect to the Global Data Services catalog database as a user with the pool administrator privileges, using the connect command before running this command.

• If -savename is not specified, then GDSCTL replaces what you specify for the net service name with the full connection string before saving the configuration to the catalog.

• The default for GDSCTL is for autovncr to be enabled for the catalog. If autovncr has been disabled for the catalog, before configuring Global Data Services pools and adding databases to the Global Data Services configuration, the nodes where those databases run must be part of the valid node checking for registration (VNCR) list for database registration. Use the add invitednode (add invitedsubnet) command to define the valid nodes.

Example

Adds database DB1 to the WEST region and Global Data Services pool MYREADERFARM.

GDSCTL> add database -connect 127.0.0.1:1521:db1 -region west -gdspool
   myreaderfarm

Adds a database using myalias instead of the IP address connection string.

GDSCTL> add database -connect myalias -gdspool myreaderfarm

Exceptions or Error Codes

GDSCTL returns the errors listed below if you use this command incorrectly.

Syntax

add file -file file_name 
         -source local_filename

Options

Usage Notes

This command creates a named file object in the catalog and associates the contents of an operating system file with that object by opening the file and storing its contents in the catalog. If the contents of the operating system file change, the MODIFY FILE command can be used to reload the contents into the catalog.

If the specified file object already exists, the command returns an error.

Examples

Add a file named east_region_db_params from the local source file /tmp/dbca_params.txt

GDSCTL> add file -file east_region_db_params -source /tmp/dbca_params.txt

Syntax

add gdspool -gdspool gdspool_name_list 
           [-users user_list]

Options

Usage Notes

• A default GDS pool, DBPOOLORA, will be created automatically when a GDS catalog is created using create gdscatalog.

• You must connect to the Global Data Services catalog database as a user with the Global Data Services administrator privileges, using the connect command before running this command.

• The default for GDSCTL is for autovncr to be enabled for the catalog. If autovncr has been disabled for the catalog, then before configuring Global Data Services pools and adding databases to the Global Data Services configuration, the nodes where those databases run must be part of the valid node checking for registration (VNCR) list for database registration. Use the add invitednode (add invitedsubnet) command to define the valid nodes.

Example

Add a Global Data Services pool named MYREADERFARM to the configuration:

GDSCTL> add gdspool -gdspool myreaderfarm

Syntax

add gsm -gsm gsm_name
        -catalog connect_id
       [-pwd password]
       [-wpwd password]
       [-region region_name]
       [-localons ons_port]
       [-remoteons ons_port]
       [-listener listener_port]
       [-endpoint gmsendpoint]
       [-remote_endpoint remote_endpoint]
       [-trace_level level]

Options

Usage Notes

• You must specify the Global Data Services catalog database when using this command.

• You must run this command, locally, on the computer where you want to add the global service manager.

• You must have operating system privileges on the computer where you want to add the global service manager to run this command.

• When you run this command, GDSCTL connects to the Global Data Services catalog as the GSMCATUSER user and prompts you for the GSMCATUSER password.

Example

Add a global service manager named gsm1, specifying the location of the Global Data Services catalog database, DB1.

GDSCTL> add gsm -gsm gsm1 -catalog 127.0.0.1:1521:db1

Syntax

add {invitednode | invitedsubnet}
            [-group group_name] 
            [-catalog catalog_dbname [-user user_name/password]]
          vncr_id

Options

Usage Notes

• You must connect to the Global Data Services catalog database as a user with the pool administrator privileges, using the connect command before running this command.

• The default for GDSCTL is that autovncr is enabled for the catalog. If autovncr has been disabled for the catalog, before configuring Global Data Services pools and adding databases to the Global Data Services configuration, then the nodes where those databases run must be part of the valid node checking for registration (VNCR) list for database registration. Use the add invitednode (add invitedsubnet) command to define the valid nodes.

• VNCR enables or denies access from specified IP addresses to Oracle services. See Oracle Database Net Services Administrator's Guide for more information about VNCR.

Examples

Add the netmask 255.255.255.248 to the catalog.

GDSCTL> add invitednode 255.255.255.248 

Add the server east1.example.com to the catalog in the alias group EAST_SRV.

GDSCTL> add invitednode east1.example.com

Add the server east2.example.com to the catalog in the alias group EAST_SRV.

GDSCTL> add invitednode east2.example.com

Syntax

add region -region region_list 
          [-buddy region_name]

Options

Usage Notes

• When the Global Data Services catalog is created using the create gdscatalog command, the default REGIONORA region is created automatically.

• You must connect to the Global Data Services catalog database as a user with the Global Data Services administrator privileges, using the command connect before running this command

Example

Add two Global Data Services regions, EAST and WEST to the current configuration:

GDSCTL> add region -region east,west

Syntax

add service
           [-gdspool gdspool_name]
           -service service_name
           (-preferred_all | (-preferred dbname_list [-available dbname_list]))
           [-locality {ANYWHERE | LOCAL_ONLY [-region_failover]}]
           [-role {PRIMARY | PHYSICAL_STANDBY [-failover_primary] | 
              LOGICAL_STANDBY | SNAPSHOT_STANDBY}]
           [-lag {lag_value | ANY}]
           [-notification {TRUE | FALSE}]
           [-rlbgoal {SERVICE_TIME | THROUGHPUT}]
           [-dtp {TRUE | FALSE}]
           [-sql_translation_profile stp_name] 
           [-clbgoal {SHORT | LONG}]
           [-tafpolicy {BASIC | NONE | PRECONNECT}]
           [-policy policy]
           [-failovertype {NONE | SESSION | SELECT | TRANSACTION | AUTO}]
           [-failovermethod {NONE | BASIC}]
           [-failoverretry failover_retries]
           [-failoverdelay failover_delay]
           [-edition edition_name] 
           [-commit_outcome {TRUE | FALSE}]
           [-retention retention_seconds]
           [-session_state {DYNAMIC | STATIC | AUTO}] 
           [-replay_init_time replay_init_time]
           [-pdbname pdbname]
           [-drain_timeout]
           [-stop_option  {NONE,IMMEDIATE, TRANSACTIONAL}]
           [-failover_restore {NONE|LEVEL1|AUTO}]
           [-table_family family]

Options

Usage Notes

Database-specific options cannot be set at this level. The modify service command must be used to set database-specific options.

One of -preferred_all or -preferred must be specified. If -preferred_all is specified, then all databases in the pool are preferred for this global service (databases inserted into the pool will also have this global service added).

In Oracle Sharding, note that when there is no table_family parameter specified, the service is not associated with any table family, and the value of the property is set to NULL. This is the case for user-defined and composite sharding, where there is always only one table family, and can also be the case when there is only one table family in system-managed sharding. When a table family is deleted (that is, the root table of the table family is dropped) the table_family property of the service is reset to NULL.

Examples

Add a service named sales_report to the Global Data Services pool MYREADERFARM with a value of ANYWHERE for the locality.

GDSCTL> add service -gdspool myreaderfarm -service sales_report -locality ANYWHERE

Add a service named daily_sales_rept to the Global Data Services pool MYDGPOOL with preferred instance set to DB1 and the available instances set to DB3 and DB4. The service should use the basic transaction failover policy.

GDSCTL> add service -gdspool mydgpool -s daily_sales_rept -preferred db1 
  -available db3,db4 -tafpolicy BASIC

In a system-managed sharded database, the table family ID parameter is specified as a property of the service.

GDSCTL> add service –gdspool shdpool –table_family sales.customer -service sales –preferred_all -locality ANYWHERE

Syntax

add shard -connect connect_identifier
         [-pwd password]
         [-savename]
         [-region region_name] 
         [-force]
         [-cdb cdb_name] 
         [-cpu_threshold cpu]
         [-disk_threshold disk]
         [{-shardgroup shardgroup_name | -shardspace shardspace_name}]
         [-deploy_as {PRIMARY | STANDBY | ACTIVE_STANDBY}]
         [-rack rack_id]
         [-replace old_db_name]
         [-gg_service (http|https):ogg_host:sm_port/GGHOME_directory]

Options

Usage Notes

Before running add shard, you must validate the shard by running the validateShard procedure as described in Using Oracle Sharding

• The shard will become part of the sharded database after a DEPLOY command is executed, except in the case of -replace.

• Any databases added to a sharding configuration using ADD SHARD must not have ever been deployed as a shard in another configuration (unless -replace is specified). Re-adding a previously deployed shard will cause the ADD SHARD command to succeed, but the shard will be unable to successfully deploy and register with the shard director (GSM) when the DEPLOY command is eventually run.

• ADD SHARD only registers the database (shard) with GDS. Replication is not configured on a newly added database and data from other databases is not distributed to it until DEPLOY is run.

• With Data Guard replication, a shard can be added as a standby to a preexisting Data Guard configuration. There is no need to re-shard the data. It is expected that the shard being added is in a the correct state for configuration; the standbys should be cloned from the primary and have the same DBID. When you run DEPLOY, the existing primary and standby databases are matched with each other, using the DBID to form a broker configuration. If the broker has not been configured, it is configured, otherwise it is validated that it has been configured correctly. Once the broker is configured, Data Guard does its work, and it should be able to perform catch-up on the standbys if needed before bringing them online.

• See Working with Oracle GoldenGate Sharding in the Fusion Middleware Using the Oracle GoldenGate Microservices Architecture guide for more information about using Oracle GoldenGate with Oracle Sharding.

• When using the- replace parameter, see Using Oracle Sharding for more information about its usage.

Examples

Add the shard to shardgroup GROUP1 of the DB11 database.

GDSCTL> add shard –connect db11 –shardgroup group1

Replace shard SH1 with database DB11.

GDSCTL> add shard –replace sh1 –connect db11

Syntax

add shardgroup -shardgroup shardgroup_name 
              [-region region_name] 
              [-shardspace shardspace_name]
              [-deploy_as {PRIMARY | STANDBY | ACTIVE_STANDBY}]
              [-repfactor number]

Options

Usage Notes

This command can only be used with system-managed or composite sharding, not user-defined sharding.

See Working with Oracle GoldenGate Sharding in the Fusion Middleware Using the Oracle GoldenGate Microservices Architecture guide for more information about using Oracle GoldenGate with Oracle Sharding.

Examples

Add the GROUP1 shardgroup in the WEST region within the GOLD shardspace.

GDSCTL> add shardgroup -shardgroup group1 -region west –shardspace gold

Syntax

add shardspace -shardspace shardspace_name 
              [-chunks number] 
              [-protectmode dg_protection_mode]

Options

Usage Notes

The command is applicable to user-defined sharding, composite sharding that assumes multiple shardspaces, and system managed sharding when there are no other shardspaces present in the current configuration.

Examples

Add the GOLD shardspace with Data Guard MAXAVAILABILITY protection mode.

GDSCTL> add shardspace –shardspace gold –protectmode maxavailability

Syntax

config [-support]

Options

Usage Notes

When using the command, it does not matter if the components (except for the catalog database) are started. The configuration data displayed is retrieved from the catalog database.

Example

Display the configuration data for all components defined for the configuration.

GDSCTL> config

Syntax

config cdb [-cdb cdb_name]

Options

Examples

Display information about CDB called cdb1.

GDSCTL> config cdb -cdb cdb1 

Name: tstsdbyb 
Connection string: (DESCRIPTION=(ADDRESS=(PROTOCOL=tcp)(HOST=cdb1host)(PORT=1521))
(CONNECT_DATA=(SERVICE_NAME=cdb1.example.com))) 
SCAN address: 
ONS remote port: 0 
Disk Threshold, ms: 20 
CPU Threshold, %: 75 
Version: 18.0.0.0 
Rack: 

Syntax

config chunks [-support] 
            ( [-shard shd] | [-shardgroup sh] | [-show_reshard] | [-cross_shard] )
            ( [-chunk chunk_id] | [-key key [-superkey superkey] ) 

Options

Usage Notes

The config chunks command lists all of the database shards and the chunks that they contain. Some chunks are listed more than once if there are standbys that contain replicated chunks.

Examples

The output from config chunks is shown below.

GDSCTL> config chunks

Chunks
------------------------
Database                      From      To        
--------                      ----      --        
sh1a                          1         10        
sh1b                          1         10

Syntax

config credential [-support] 

Options

Usage Notes

This command displays all existing remote credentials that can be used to execute sharding jobs.

Examples

Display credentials.

GDSCTL> config credential

Name            Username Windows domain 
--------------- -------- -------------- 
CREDENTIAL_ONE  OraUser  
CREDENTIAL_TWO  OraUser2 

Syntax

config database [-support] 
                [-database db_name] 

Options

Usage Notes

You must connect to the catalog database as a user with the pool administrator privileges, using the connect command before running this command

Examples

Display the static configuration data stored in the catalog for all the databases in the Global Data Services configuration.

GDSCTL> config database

The gdsctl config database command returns information similar to the following:

Name     Pool     Status     Region
----     ----     ------     ------
dbcat    sales    Ok         east
dbcat1   sales    Ok         west
dbcat3   sales    Ok         west

Syntax

config file [-support]
            [-file file_name] 

Options

Usage Notes

If the specified file object does not exist, the command returns an error.

Example

Display the list of files defined in the catalog database.

GDSCTL> config file
Name
------
dbcfg1

Syntax

config gdspool [-support]
               [-gdspool gdspool_name]

Options

Usage Notes

You must connect to the catalog database as a user with the pool administrator privileges, using the connect command before running this command

Example

Display the static configuration data stored in the catalog for all Global Data Services pools.

GDSCTL> config gdspool

The gdsctl config gdspool command returns output similar to the following:

Name          Broker
----          ------ 
dbpoolora     No 
mkt           No 
sales         No 
marketing     No 

The following command shows the configuration detail of Global Data Services pool marketing.

GDSCTL> config gdspool -gdspool marketing

The above example returns output similar to the following:

GDS Pool administrators
------------------------
 
Databases
------------------------
dbcat2                         
dbcat1                         
dbcat3                         
 
 
Services
------------------------
sales_report                 
sales_analysis                 
sales_estimation                 
sales_peragent                 
sales_global

Syntax

config gsm [-gsm gsm_name]
           [-support]

Options

Usage Notes

You must connect to the catalog database as a user with the Global Data Services administrator privileges, using the connect command before running this command

Example

Display the static configuration data stored in the catalog for the global service manager mygsm:

GDSCTL> config gsm -gsm mygsm

The gdsctl config gsm command returns output similar to the following:

Name: mygsm
Endpoint 1: (ADDRESS=(HOST=stcal.us.hq.com)(PORT=1523)(PROTOCOL=tcp))
Endpoint 2: (ADDRESS=(HOST=stcal.us.hq.com)(PORT=1523)(PROTOCOL=tcp))
Local ONS port: 6123
Remote ONS port: 6234
Region: east
Buddy
------------------------

Syntax

config region [-region region_name]
              [-support]

Options

Example

Displays the static configuration data for the specified region.

GDSCTL> config region -region east

Displays the following output:

Name                          Buddy                        
----                          -----                        
east    

Syntax

config sdb [-support]

Options

Examples

The output for config sdb is similar to the following.

GDSCTL> config sdb

GDS Pool administrators
------------------------

Replication Type
------------------------
Data Guard

Shard type
------------------------
System-managed

Shard spaces
------------------------
shardspaceora

Services
------------------------
oltp_ro_srvc
oltp_rw_srvc

Syntax

config service [-gdspool gdspool_name]
               [-service service_name]
               [-support]

Options

Usage Notes

You must connect to the catalog database as a user with the pool administrator privileges, using the connect command before running this command

Examples

Show all the services in the user's Global Data Services pool:

GDSCTL> config service 

The gdsctl config service command returns information similar to the following:

Name        Network name                  Pool     Started Preferred all
----        ------- ----                  ----     ------- --------- ---
sales_svc1  sales_svc1.sales.oradbcloud   sales    Yes     Yes          
sales_svc2  sales_svc2.sales.oradbcloud   sales    NO      Yes          
sales_svc3  sales_svc3.sales.oradbcloud   sales    Yes     Yes          
mkt_svc1    mkt_svc1.mkt.oradbcloud       mkt      NO     Yes          

Display the static configuration data stored in the Global Data Services catalog for sales:

GDSCTL> config service -service sales

Name: sales
Network name: sales.sdhdpool.oradbcloud
Pool: shdpool
Started: Yes
Preferred all: Yes
Locality: ANYWHERE
Region Failover: No
Role: NONE
Primary Failover: No
Lag: ANY
Runtime Balance: SERVICE_TIME
Connection Balance: LONG
Notification: Yes
TAF Policy: NONE
Policy: AUTOMATIC
DTP: No
Failover Method: NONE
Failover Type: NONE
Failover Retries: 
Failover Delay: 
Edition: 
PDB: 
Commit Outcome: 
Retention Timeout: 
Replay Initiation Timeout: 
Session State Consistency: 
SQL Translation Profile:
Stop option: NONE 
Drain timeout: 
Table Family: sales.customer 
 
Supported services
------------------------
Database          Preferred Status    
--------          --------- ------    
shdb              Yes       Enabled   
shdc              Yes       Enabled   

Syntax

config shard -shard shard_name
            [-support]

Options

Examples

GDSCTL> config shard 

Name   Shard Group Status State    Region Availability 
----   ----------- ------ -----    ------ ------------ 
den17b dbs1        Ok     Deployed east   ONLINE
den17c dbs2        Ok     Deployed east   READ ONLY 

The State column in the results can have the following values:

• Created: Indicates that add shard or create shard was run, but deploy has not yet been run for that shard.

• Replicated: Indicates that deploy was run and the Data Guard broker configuration was created. No other metadata (chunks, for example) are on the shard and the shard has not yet registered with the shard director

• Sharded: Indicates that the database has successfully registered with the shard director. Creates chunk metadata for new shards, but does not start any automatic rebalancing. To manually get from Replicated to Sharded and beyond, run GDSCTL sync -database <shard_name>.  This is what is happening internally in this step.

• Deployed: Indicates that all DDL catchup is completed and the shard is ready for operations. At this point, any scheduled chunk moves are begun in the background. A shard can be Deployed without having been rebalanced because rebalancing is a background operation.

Syntax

config shardgroup [-shardgroup shardgroup_name]
                  [-support]

Options

Examples

The config shardgroup command generates the following output.

GDSCTL> config shardgroup –shardgroup northeast

Shard Group Chunks Region Shard space 
----------- ------ ------ ----------- 
dbs1        10     east   shd1 
dbs2        10     east   shd1  

By specifying a shardgroup, you get the following output.

GDSCTL> config shardgroup -shardgroup dbs1 

Shard Group: dbs1 
Chunks: 10 
Replicas: 
Region: east 
Shard space: shd1   
Shards 
------------------------ 
Shard  Chunks 
-----  ------ 
den17b 10 

Syntax

config shardspace [-shardspace shardspace_name]
                  [-support]

Options

Usage Notes

The output varies depending on whether the command is issued on a shardspace configured in a user-defined SDB.

Examples

The config shardspace command generates the following output

GDSCTL> config shardspace 

Shard space Chunks 
----------- ------ 
shd1        10 

When a shardspace is specified, the output is returned in the following format.

GDSCTL> config shardspace -shardspace silver

Shard Group Region Role 
----------- ------ ---- 
dbs1        east   Primary 
dbs2        east   Standby  
PROTECTION_MODE Chunks 
--------------- ------ 
MaxProtection   10 

Syntax

config table family

Examples

The config table family command generates the following output

GDSCTL> config table family 

Schema   Name        ID      Shard Type 
------   -----       -----   ---------- 
sales    customer    1       System
hr       department  25      System

Syntax

config vncr [-group group_name]
            [-support]

Options

Usage Notes

You must connect to the catalog database as a user with the pool administrator privileges, using the connect command before running this command

Example

The config vncr command returns information similar to the following:

GDSCTL> config vncr

Name          Group ID
----          --------
192.0.2.1     group_name

Syntax

configure [-gsmport port]
          [-timeout seconds]
          [-show]
          [-driver {THIN | OCI}] 
          [-resolve {IP | HOSTNAME | QUAL_HOSTNAME}] 
          [-log {ALL|OFF|INFO|FINE|FINER|FINEST|SEVERE|WARNING}]
          [-log_file log_file] 
          [-gsm gsm_name]
          [-showtime ON|OFF]
          [-verbose ON|OFF]
          [-save_config] 
          [-gsmdebug (1|0)]
          [-spool]
          [-width]

Options

Example

Set the mygsm driver to OCI:

configure -driver OCI mygsm

Syntax

connect [user_name[/password]]@connect_identifier

Options

Usage Notes

You must connect to the catalog database as a user with either the Global Data Services administrator or the pool administrator privileges, depending on which command you want to run after you connect

Examples

Connect as the gsmadmin user to the private cloud:

GDSCTL> connect gsmadmin@mycloud
Enter password: 

Connect using a connect descriptor, without specifying a user name and password:

GDSCTL> connect (DESCRIPTION=(ADDRESS=(PROTOCOL=tcp)(HOST=myhost)(PORT=1521)))
Enter username: 

Syntax

create catalog -database db_name 
              [-user user_name[/password] 
              [-region region_name_list]
              [-gdspool gdspool_name_list]
              [-configname confname]
              [-autovncr {ON | OFF}]
              [-force]

Options

Usage Notes

This command is deprecated in Oracle Database 12c Release 2. Use create gdscatalog or create shardcatalog for your specific environment.

The create catalog command generates a pair of PKI public and private keys and stores them in the catalog, along with a fixed string "GSM" that is encrypted with a private key. It uses the GSMCATUSER password.

You must have the Global Data Services administrator privileges on the computer where you want to create the Global Data Services catalog.

Auto VNCR is best used in environments with simple private networks where ease of configuration is the most important consideration. To have the highest level of control over which hosts may participate in a GDS configuration, disable Auto VNCR and explicitly add the IP addresses of each database host to the VNCR configuration.

When —autovncr is enabled, Oracle attempts to find the host name of the target database when it is validated during add shard or add database execution. This host is then automatically added to the VNCR list in the catalog as an invited node. This mechanism is not compatible with all network configurations and may not work in the following cases:

• The catalog or global service manager host does not know how to translate the host name discovered on the target database host to an real IP address. This can happen if they have different names in the hosts file or DNS on the catalog or global service manager host, or if they just do not exist on those hosts.

• The target database host has multiple public network addresses, and Oracle chooses an address that is different than the address used when the database registers with the global service manager. This can happen if the host has multiple network cards or has configured virtual network interfaces.

• The database is running Oracle RAC, and other Oracle RAC instances run on a different subnet. This is not a recommended configuration for Oracle RAC. Refer to the Oracle RAC documentation for recommended configurations. With Oracle RAC, Oracle Database connects to a single database host to validate the target, and returns a subnet mask that includes the entire subnet that the host is on. If other instances are on a different subnet, they have no valid VNCR entry, and registration is rejected.

When —autoVNCR is not enabled, or, if any of the above cases apply, new hosts should be added manually using add invitednode (add invitedsubnet).

Example

Create a Global Data Services catalog for global service management in the database named DB1. Also create the regions EAST and WEST, and the database pool READERFARM.

GDSCTL> create catalog -database db1 -region west,east -gdspool readerfarm

Syntax

create gdscatalog -database db_name 
                 [-user user_name[/password] 
                 [-region region_name_list]
                 [-gdspool gdspool_name_list]
                 [-configname confname]
                 [-autovncr {ON | OFF}]
                 [-force]

Options

Usage Notes

The create gdscatalog command generates a pair of PKI public and private keys and stores them in the catalog, along with a fixed string "GSM" that is encrypted with a private key. It uses the GSMCATUSER password.

You must have the Global Data Services administrator privileges on the computer where you want to create the Global Data Services catalog.

Auto VNCR is best used in environments with simple private networks where ease of configuration is the most important consideration. To have the highest level of control over which hosts can participate in a GDS configuration, disable Auto VNCR and explicitly add the IP addresses of each database host to the VNCR configuration.

When —autovncr is enabled, Oracle attempts to find the host name of the target database when it is validated during add shard or add database execution. This host is then automatically added to the VNCR list in the catalog as an invited node. This mechanism is not compatible with all network configurations and may not work in the following cases:

• The catalog or global service manager host does not know how to translate the host name discovered on the target database host to an real IP address. This can happen if they have different names in the hosts file or DNS on the catalog or global service manager host, or if they just do not exist on those hosts.

• The target database host has multiple public network addresses, and Oracle chooses an address that is different than the address used when the database registers with the global service manager. This can happen if the host has multiple network cards or has configured virtual network interfaces.

• The database is running Oracle RAC, and other Oracle RAC instances run on a different subnet. This is not a recommended configuration for Oracle RAC. Refer to the Oracle RAC documentation for recommended configurations. With Oracle RAC, Oracle Database connects to a single database host to validate the target, and returns a subnet mask that includes the entire subnet that the host is on. If other instances are on a different subnet, they have no valid VNCR entry, and registration is rejected.

When —autoVNCR is not enabled, or, if any of the above cases apply, new hosts should be added manually using add invitednode (add invitedsubnet).

Example

Create a Global Data Services catalog for global service management in the database named DB1. Also create the regions EAST and WEST, and the database pool READERFARM.

GDSCTL> create gdscatalog -database db1 -region west,east -gdspool readerfarm

Syntax

create shard  [{-shardgroup shardgroup_name | –shardspace shardspace_name}]
               [-region region_name] 
               [-deploy_as {primary | standby | active_standby}]
               [-rack rack_id]
               [-gg_service (http|https):ogg_host:sm_port/deployment
                  -gg_password gg_user_password]
                -destination destination_name 
               {-credential credential_name |
                  -osaccount account_name
                  -ospassword password
                 [-windows_domain domain_name]}
               [-dbparam db_parameter_file |
                  -dbparamfile db_parameter_file]
               [-dbtemplate db_template_file |
                  -dbtemplatefile db_template_file]
               [-netparam net_parameter_file |
                  -netparamfile net_parameter_file]
               [-serviceuserpassword pwd] 
               [-sys_password]
               [-system_password]

Options

Usage Notes

CREATE SHARD causes a new database to be created using DBCA and NETCA.

CREATE SHARD only registers the database with GDS. The database is not created and replication is not configured on a newly create database, and data from other databases is not distributed to it until DEPLOY is executed.

The —DEPLOY_AS option can only be specified if a shard is being added to a shardspace. If a shard is being added to a shardgroup, its role will determined by the role of the shardgroup. The role is assigned when the shard gets deployed.

If the —CREDENTIAL option is specified, the credential name must have previously been created with the ADD CREDENTIAL command. If —CREDENTIAL is not specified, then OSACCOUNT and OSPASSWORD (and optionally WINDOWS_DOMAIN) must be specified.

The value for DBPARAM, DBTEMPLATE, or NETPARAM must be the name of a file object as previously specified in the ADD FILE command. The file content specified by the -netparam or -netparamfile parameter in CREATE SHARD is a NETCA response file. Examples can be found in $ORACLE_HOME/assistants/netca. By default, port 1521 is used with a listener name of LISTENER_shard_name. These values can be changed by modifying a sample response file and specifying it using the -netparam or -netparamfile parameters. The file content specified by the -dbtemplate or -dbtemplatefile parameter in CREATE SHARD is a DBCA template file. Examples of template files can be found in $ORACLE_HOME/assistants/dbca/templates. If not specified, the General_Purpose.dbc file located in the above directory on the shard destination host will be used. The format of the file contents specified in the -dbparam or -dbparamfile command is a space-delimited list of DBCA command line parameters and values on one or more lines. For example, the following is an example of a valid parameter file: -gdbName shard1.example.com -initParams sort_area_size=200000. For a complete list of possible DBCA parameters, run dbca -help -createDatabase.

See Working with Oracle GoldenGate Sharding in the Fusion Middleware Using the Oracle GoldenGate Microservices Architecture guide for more information about using Oracle GoldenGate with Oracle Sharding.

Example

Create a shard.

GDSCTL> create shard –shardgroup group1 –destination dbdest –credential group1_cred
 –dbparam group1_db_params

Syntax

{status database | databases} [-gsm gsm_name]
                              [-database db_name]
                              [-gdspool gdspool_name]
                              [-raw|-support|-verbose] 

Options

Usage Notes

You must connect to the catalog database as a user with the pool administrator privileges, using the command connect before running this command.

Example

Display the status of all databases:

GDSCTL> databases

The databases command returns output similar to the following:

Database: "dbcat1" Registered: Y State: Ok ONS: N. Role: PRIMARY Instances: 1
 Region: east
   
   Service: "sales_svc2" Globally started: N Started: N
            Scan: Y Enabled: Y Preferred: Y
   Service: "sales_svc1" Globally started: Y Started: Y
            Scan: N Enabled: Y Preferred: Y
   Registered instances:
     sales%11
Database: "dbcat2" Registered: Y State: Ok ONS: N. Role: PRIMARY Instances: 1
 Region: east
   Service: "sales_svc2" Globally started: N Started: N
            Scan: Y Enabled: Y Preferred: Y
   Service: "sales_svc1" Globally started: Y Started: Y
            Scan: N Enabled: Y Preferred: Y
   Registered instances:
     sales%1

Syntax

delete catalog [-connect [user/[password]@]conn_str]
               [-force]

Options

Usage Notes

You must have the Global Data Services administrator privileges on the computer where the database resides from which you want to delete the Global Data Services catalog

If -connect is not specified, the catalog that belongs to currently connected database (if any) is deleted.

Example

Delete the Global Data Services catalog located in the database named DB1.

GDSCTL> delete catalog -connect db1

Syntax

deploy [-no_rebalance]

Options

Usage Notes

This command is executed after one or more shards have been added to the shard catalog. As the result of the command execution, a certain range of data is associated with a newly added database. If a database is part of a Data Guard Broker configuration, a role (primary or standby) is assigned to it. Then replication and/or migration of data to from other databases to newly deployed databases are initiated.

• Deploy runs almost entirely in parallel, and mostly in the background, and will not deploy any shards which do not have all their counterparts in other shardgroups. All undeployed shards that can be deployed are deployed as the result of execution of this command.

• Before configuring replication, this command cross-checks parameters of all databases included into the replication configuration. An error is returned if the cross-check finds inconsistency or ambiguity, for example, no primary shardgroup in a shardspace with Data Guard replication.

• If a CREATE SHARD command had previously been issued, these new shards will be created during deployment and added to the shard catalog. If a shard needs to be created, DEPLOY runs a job for each database which requires a remote credential (see add credential and create shard). This credential must be valid at the time of deployment.

• The NO_REBALANCE option allows to skip automatic rebalancing of chunks across shards during incremental DEPLOY. Use the move chunk command to perform manual chunk migration.

Examples

Deploy the sharded database.

GDSCTL> deploy

Syntax

disable service [-gdspool gdspool_name]
                [-service service_name_list]
                [-database db_name |[-override -connect conn_str [-pwd password]]]

Options

Usage Notes

You must connect to the catalog database as a user with the pool administrator privileges, using the connect command before running this command

A running service cannot be disabled. If -override is specified, the command is executed without going to the GDS catalog. Use this option when the GDS catalog is unavailable. It is not recommended for use under normal operation.

Example

Disable and stop the service G_SALES_REPORT on all databases in the database pool READERFARM.

GDSCTL> disable service -gdspool readerfarm -service g_sales_report -database db1

Syntax

enable service [-gdspool gdspool_name]
               [-service service_name_list]
               [-database db_name|[-override -connect conn_str [-pwd password]]]

Options

Usage Notes

You must connect to the catalog database as a user with the pool administrator privileges, using the connect command before running this command

ENABLE SERVICE will start the global service if it is preferred_all or cardinality is not reached.

If -override is specified, the command is executed without going to the GDS catalog. Use this option when the GDS catalog is unavailable. It is not recommended for use under normal operation.

Example

Enable the service G_SALES_REPORT on the database DB1 in the database pool READERFARM.

GDSCTL> enable service -gdspool readerfarm -service g_sales_report -database  db1

Syntax

quit | exit

Syntax

export catalog [-force] source

Options

Usage Notes

You must connect to the catalog database as a user with GDS Administrator privileges before running this command.

It is recommended that you validate the catalog, using the validate catalog command before exporting it.

Example

Save the catalog backup to your home directory.

GDSCTL> export catalog /home/user/cat-201307.backup

Syntax

help [gdsctl_command]

Options

Syntax

import catalog [-database catalog_db_name]
               [-catpwd gsmcatusrpwd]
               [-user gsmadminname[/password]]
               source

Options

Usage Notes

If -database is not specified, the GDS catalog that the current global service manager is associated with will be used. The -catpwd option should be specified in case you need to perform cleanup of databases in the existing catalog that are not found in imported file.

When restoring to a new catalog database, catalog must be created first, using the create gdscatalog command.

You must connect to the catalog database as a user with GDS Administrator privileges before running this command.

The import procedure can be considered finished only when there are no pending requests after import. Use the config command to get the list of pending requests.

Example

Load the catalog backup from your home directory.

GDSCTL> import catalog /home/user/cat-201307.backup

Syntax

modify catalog [-autovncr {ON | OFF}] 
               [-oldpwd oldpassword -newpwd newpassword] 
               [-pwd password -newkeys]
               [-agent_password password]
               [-agent_port port] 
               [-region region]
               [-recover]

Options

Usage Notes

To use this command, there must be a least one global service manager running and a connection with the catalog database must have already been established (see the connect command).

You must connect to the catalog database as a user with the Global Data Services administrator privileges, using the connect command before running this command.

Auto VNCR is best used in environments with simple private networks where ease of configuration is the most important consideration. To have the highest level of control over which hosts may participate in a GDS configuration, disable Auto VNCR and explicitly add the IP address(es) of each database host to the VNCR configuration.

The GSMCATUSER password should be updated regularly for security reasons. Use the following command to perform this operation.

modify catalog -oldpwd oldpassword -newpwd newpassword

This command fetches the encrypted private key and encryption string, decrypts them using the old password, re-encrypts them with the new password and stores them again.

If the GSMCATUSER password is changed, you must execute MODIFY CATALOG to update catalog security scheme, with -newpwd and -oldpwd specified.

The PKI keys must be updated regularly, which is done using modify catalog -oldpwd oldpassword -newkeys. This command generates a new PKI key pair and replaces the corresponding fields in the database.

If you decide to replace the PKI keys, or just after the patchset upgrade from Oracle Database 12c Release 1 (12.1) on the catalog database, run this command:

modify catalog -pwd **  -newkeys

An arbitrary password can be stipulated for remote agent registration. If an agent registration password already exists, it will be overridden with the new password. In order to successfully execute the GDSCTL CREATE SHARD command, an agent password must be set using the CREATE SHARDCATALOG or MODIFY CATALOG command.

Examples

Turn off autovncr mode for the catalog database.

connect gsmadmin@mycloud 
GDSCTL> modify catalog -autovcnr off

Specify the remote Scheduler agent registration password.

connect gsmadmin@mycloud 
GDSCTL> modify catalog –agent_password mypass

Update catalog security scheme.

GDSCTL> modify catalog -autovncr OFF -oldpwd opwd -newpwd npwd -pwd pwd -newkeys

Syntax

modify cdb -shard cdbname_list
            [-connect connect_identifier]
            [-pwd gsmrootuser_pwd]
            [-scan scan_address [-ons port]]
            [-savename]

Options

Usage Notes

Some parameters are not supported after the CDB contains shards or contains shards that have been deployed.

Examples

Change a password on a CDB.

GDSCTL> modify cdb -shard cdb1 -pwd new_gsmrootuser_password

Syntax

modify credential -credential credential_name 
                  -osaccount account_name
                  -ospassword password
                 [-windows_domain domain_name]

Options

Usage Notes

This command modifies credentials which will be used to execute jobs on sharded hosts in response to administrative commands.

If the specified credential does not exist, the command returns an error.

Examples

Modify a credential named east_region_cred.

GDSCTL> modify credential –credential east_region_cred –osaccount agent_user
 –ospassword newpass

Syntax

modify database -database db_name_list
               [-gdspool gdspool_name]
               [-shard shard_name]
               [-deploy_as PRIMARY|STANDBY]
               [-region region_name]
               [-pwd password]
               [-connect connect_identifier]
               [-scan scan_address]
               [-ons port]]
               [-savename]
               [-cpu_threshold cpu] 
               [-disk_threshold disk]
               [-rack rack_id]
               [-NETPARAM net_parameter_file | -NETPARAMFILE net_parameter_file]
               [-DBPARAM db_parameter | -DBPARAMFILE db_parameter_file]
               [-DBTEMPLATE db_template | -DBTEMPLATEFILE db_template_file]   

Options

Usage Notes

You can multiple databases if the region property is specified.

For all parameters except for the GDS region, first the appropriate changes must be done by the database administrator and then the modify database command must be run to update the modified parameters in the GDS catalog. Alternatively, you can use the sync database (synchronize database)command for this purpose.

You must connect to the catalog database as a user with the pool administrator privileges, using the connect command before running this command

Example

Change the region of databases DB1 and DB3 to EAST.

GDSCTL> modify database -database db1,db3 -region east

Syntax

modify file -file file_name
            -source local_filename

Options

Usage Notes

This command updates a named file object in the catalog by reloading the contents of an operating system file into the catalog.

Examples

Update a file named east_region_db_params with content from the local source file /tmp/dbca_params.txt

GDSCTL> modify file -file east_region_db_params -source /tmp/dbca_params.txt

Syntax

modify gdspool -gdspool gdspool_name_list 
              [-removeuser user_name | -adduser user_name]

Options

Usage Notes

You must connect to the catalog database as a user with the pool administrator privileges, using the connect command before running this command

Example

Add PETER to the list of database pool administrators for the pool MYREADERFARM:

GDSCTL> modify gdspool -gdspool myreaderfarm -adduser peter

Syntax

modify gsm -gsm gsm_name
          [-catalog connect_id [-pwd password]]
          [-region region_name]
          [-localons ons_port]
          [-remoteons ons_port]
          [-endpoint gmsendpoint [-remote_endpoint remote_endpoint]]
          [-listener listener_port]
          [-wpwd wallet_password]

Options

Usage Notes

• You must run this command locally on the computer where you want to modify the global service manager.

• This command can be run only by the operating system user who started the global service manager.

• When you run this command, GDSCTL connects to the Global Data Services catalog as the GSMCATUSER user and prompts you for the GSMCATUSER password.

Example

Modify the global service manager named gsm1 so that it is in the EAST region.

GDSCTL> modify gsm -gsm gsm1 -region east

Syntax

modify region -region region_name_list
             [-buddy region_name]
             [-weights weight]

Options

Usage Notes

You must connect to the catalog database as a user with the Global Data Services administrator privileges, using the connect command before running this command.

To clear buddy region or weight, call MODIFY REGION and specify empty quotes as the value. If WEIGHTS is specified, dynamic load balancing is replaced by static (not recommended).

Example

Modify two regions, EAST and WEST, as follows:

GDSCTL> modify region -region west -buddy east

Syntax

To add more preferred or available databases to a global service:

modify service [-gdspool gdspool_name]
                -service service_name
               {-preferred db_name_list | -available db_name_list}

To modify the attributes of a global service:

modify service [-gdspool gdspool_name]
                -service service_name 
               [-locality {ANYWHERE | LOCAL_ONLY}]
               [-region_failover]
               [-role {PRIMARY | PHYSICAL_STANDBY [-failover_primary] | 
                       LOGICAL_STANDBY | SNAPSHOT_STANDBY}]
               [-lag {lag_value | ANY}]
               [-notification {TRUE | FALSE}] 
               [-rlbgoal {SERVICE_TIME | THROUGHPUT}]
               [-clbgoal {SHORT | LONG}] 
               [-tafpolicy {BASIC | NONE | PRECONNECT}]
               [-policy policy] 
               [-failovertype {NONE | SESSION | SELECT | TRANSACTION}]
               [-failovermethod {NONE | BASIC}] 
               [-dtp {TRUE | FALSE}] 
               [-sql_translation_profile stp_name] 
               [-failoverretry failover_retries]
               [-failoverdelay failover_delay] 
               [-edition edition_name]
               [-commit_outcome {TRUE | FALSE}] 
               [-retention retention_seconds]
               [-session_state {DYNAMIC | STATIC}]
               [-replay_init_time replay_init_time]]
               [-table_family family]

To move a global service from one database to another database:

modify service [-gdspool gdspool_name]
                -service service_name
                -old_db db_name
                -new_db db_name
               [-force]

To change an available database to a preferred database for a service:

MODIFY SERVICE [-gdspool gdspool_name]
                -service service_name
                -available db_name_list
                -preferred

To change databases between preferred and available status:

modify service [-gdspool gdspool_name]
                -service service_name
               {-preferred_all |
                {-modifyconfig -preferred db_name_list [-available db_name_list]}}

To modify properties for a global service that are specific to an Oracle RAC database:

modify service [-gdspool gdspool_name]
                -service service_name
                -database db_name
               [-server_pool server_pool_name |
                 {-add_instances|-modify_instances} -preferred inst_list
                  -available inst_list |
                  -drop_instances inst_list
                -cardinality {UNIFORM | SINGLETON}

Options

Usage Notes

You must connect to the catalog database as a user with the pool administrator privileges, using the connect command before running this command.

Use this command to:

• Add databases to the preferred or available lists for the service

• Move a service from one database to another database

• Change an available database to a preferred database or a preferred database to an available database

• Modify the high availability attributes of the service

If you want to temporarily move a service from one database to a different database, then use the relocate service command.

Examples

Add the database DB3 as a preferred database for the service G_SALES_REPORT in the database pool MYREADERFARM.

GDSCTL> modify service -gdspool myreaderfarm -service g_sales_report -preferred db3

Modify the service G_DAILY_SALES_REPT in the database pool MYREADERFARM to change the run-time load balancing goal to THROUGHPUT.

GDSCTL> modify service -gdspool myreaderfarm -service g_daily_sales_rept
  -rlbgoal THROUGHPUT

Move the service G_SALES_REPORT in the database pool MYREADERFARM from the database DB1 to DB4.

GDSCTL> modify service -gdspool myreaderfarm -service g_sales_report
  -old_db db1 -new_db db4

Upgrade the DB3 database from an available database to a preferred database for the service G_SALES_REPORT in the database pool READFARM.

GDSCTL> modify service -gdspool readfarm -service g_sales_report
  -available db3 -preferred

Assume the service G_SALES_REPORT currently has the databases DB1 and DB2 assigned as preferred databases, and the database DB3 assigned as an available database. Exchange the preferred and available databases DB1 and DB3, and remove the DB2 database for the service SALES_REPORT in the database pool READFARM.

GDSCTL> modify service -gdspool readfarm -service g_sales_report -modifyconfig
  -available db3 -preferred db1

Modify the properties of the service G_SALES_REPORT in the database pool READFARM to specify that it should run only in the server pool named SALESPOOL for the policy-managed Oracle RAC database DB1.

GDSCTL> modify service -gdspool readfarm -service g_sales_report -database db1
-server_pool salespool

Supply the preferred and available instances for the given service on the given database.

GDSCTL> modify service –gdspool mypool –service mysvc –database mydb –add_instances
 –preferred inst1,inst2 –available inst3,inst4

In a system-managed sharded database, the table family ID parameter is specified as a property of the service.

GDSCTL> modify service –GDSPOOL shdpool –table_family sales.customer -service sales

Syntax

modify shard -shard shname_list
            [-region region_name]
            [-connect connect_identifier]
            [-pwd password]
            [-scan scan_address [-ons port]]
            [-savename]
            [-cpu_threshold cpu]
            [-disk_threshold disk]
            [-destination destination_name]
            [-credential credential_name | 
             [[-osaccount account_name]
              [-ospassword password] 
              [-windows_domain domain_name]]]

Options

Usage Notes

The REGION parameter cannot be modified for a shard that belongs to a shardgroup. The modification has to be done at the shardgroup level.

The DESTINATION and CREDENTIAL parameters are only modifiable when the shard has not yet been deployed, since these parameters only have meaning for the deployment process and are no longer referenced once deployment has completed successfully.

Examples

GDSCTL> modify shard -shard shard1 -ons 23222

Syntax

modify shardgroup -shardgroup shardgroup_name
                 [-region region_name]
                 [-shardspace shardspace_name]
                 [-repfactor number]
                 [-deploy_as {PRIMARY | STANDBY | ACTIVE_STANDBY}] 

Options

Usage Notes

All shardgroup attributes, except for DEPLOY_AS, can only be modified when the shardgroup does not contain any deployed shards. DEPLOY_AS can be modified at any time because it does not affect shards that were already added to the shardgroup.

Examples

Modify the GROUP1 shardgroup to have a replication factor of 3.

GDSCTL> modify SHARDGROUP –SHARDGROUP group1 –REPFACTOR 3  

Syntax

modify shardspace –shardspace shardspace_name
                 [-chunks number]
                 [-protectmode dg_protection_mode]   

Options

Usage Notes

The number of chunks can only be modified if a shardspace does not contain deployed shards.

Examples

Modify the GOLD shardspace to have 6000 chunks.

GDSCTL> modify shardspace –shardspace gold –chunks 6000  

Syntax

move chunk -chunk {chunk_id_list | ALL}
           -source shard_name
          [-target shard_name]
          [-timeout]
          [-verbose]

Options

Usage Notes

This command can only be used with the system-managed sharding method.

Chunks cannot be moved between shards that belong to different shardgroups.

If -chunk ALL is specified without the -target option, all of the chunks are removed from the source shard and distributed to all of the remaining shards in a round-robin manner.

Examples

Move chunks 3 and 4 from SALE1 to SALE3.

GDSCTL> move chunk -chunk 3,4 –source sale1 –target sale3  

Move all chunks from sale1 and distribute evenly among the remaining shards.

GDSCTL> move chunk -chunk ALL -source sale1

Syntax

quit | exit

Syntax

recover shard -gdspool pool
              -shard shard_name
             [-skip_first|-ignore_first]
             [-full]

Options

Usage Notes

Use SKIP_FIRST to skip first DDL. This is typically required after manual fix done by database administrator. For example, if CREATE TABLE statement fails because of a lack of space, the database administrator fixes the issue and re-executes CREATE TABLE. To avoid ORA-39151 (table exists) in RECOVER SHARD the database administrator must specify -SKIP_FIRST.

Use IGNORE_FIRST to mark the first DDL as obsolete. This is required when the wrong DDL statement was specified and failed on all shards. In this case, you need to mark it down as obsolete. FULL mode performs a complete recovery, including DDL operations, failed chunk migration, tablespace sets reconstruction, and database parameters.

Examples

Recover shard shd1.

GDSCTL> recover shard -shard shd1

Syntax

relocate service [-gdspool gdspool_name]
                  -service service_name
                  -old_db db_name
                  -new_db db_name
                 [-force]
                 [-override [-oldpwd oldpassword] [-newpwd newpassword]]

Options

Usage Notes

Unlike using the modify service command to change the location of a service, this command does not change the underlying configuration. This command temporarily relocates a service to run on another database.

If -force is not specified, then the global service must have been started on the old database and not running on the new database prior to command execution. If -force is not specified, then sessions already connected to this global service stay connected, but new sessions cannot be established.

If -override is specified the command will be executed without going to the GDS catalog. Use this option when the GDS catalog is unavailable. It is not recommended for use under normal operation.

If you attempt to use this command on a service that was previously configured with the -preferred_all option, then GDSCTL returns an error.

You must connect to the catalog database as a user with the pool administrator privileges, using the command connect before running this command

Example

Relocate the service SALES_REPORT in the READFARM database pool from the DB2 database to the DB3 database.

GDSCTL> relocate service -gdspool readfarm -service sales_report -old_db db1
 -new_db db3

Syntax

remove brokerconfig [-gdspool gdspool_name]

Options

Usage Notes

You must connect to the catalog database as a user with the pool administrator privileges, using the command connect before running this command.

If a GDS pool does not contain a Data Guard Broker configuration, an error is returned.

Example

Remove the Oracle Data Guard broker configuration from the database pool MYDGPOOL.

GDSCTL> remove brokerconfig -gdspool myreaderfarm

Syntax

remove cdb -cdb {cdb_name_list | ALL}
           [-force] 

Options

Examples

Remove the cdb named cdb1.

GDSCTL> remove cdb -cdb cdb1 

Syntax

remove credential -credential credential_name 

Options

Usage Notes

This command removes an existing credential. When the credential is removed, the catalog may no longer be able to execute jobs on sharded hosts in response to administrative commands.

If the specified credential does not exist, the command returns an error.

Examples

Remove a credential named east_region_cred.

GDSCTL> remove credential –credential east_region_cred

Syntax

remove database [-gdspool gdspool_name]
                {-all | -database db_name_list}
                [-force]

Options

Usage Notes

You must connect to the catalog database as a user with the pool administrator privileges, using the command connect before running this command.

If a pool already contains a Data Guard Broker configuration, an error is returned because a database must be removed through DGMGRL in this case.

With Oracle Sharding, only an undeployed database can be removed. If a database is offline or inaccessible, it has to be first undeployed with the -force option and then removed with the -force option.

Example

Remove the database DB1 from the global service management configuration.

GDSCTL> remove database -database db1 -gdspool pool1

Syntax

remove file -file file_name

Options

Usage Notes

If the specified file object does not exist, the command returns an error.

Examples

Remove a file named east_region_db_params.

GDSCTL> remove file -file east_region_db_params

Syntax

remove gdspool -gdspool gdspool_name_list

Options

Usage Notes

You must connect to the catalog database as a user with the Global Data Services administrator privileges, using the command connect before running this command.

Example

Remove the GDS pools tempreaders and myfarm from the Global Data Services framework.

GDSCTL> remove gdspool -gdspool tempreaders,myfarm

Syntax

remove gsm [-gsm gsm_name]

Options

Usage Notes

The removal of a global service manager requires at least one global service manager to be running to perform cleanup of Global Data Services databases. If there is only one global service manager in the Global Data Services configuration, then it has to be running to be removed.

You must connect to the catalog database as a user with the Global Data Services administrator privileges, using the command connect before running this command.

Example

Remove the global service manager named gsm5 from the configuration.

GDSCTL> remove gsm -gsm gsm5

Syntax

remove invitednode {[-group group_name]|vncr_id}

Options

Usage Notes

You must connect to the catalog database as a user with the pool administrator privileges, using the command connect before running this command

Examples

Remove the invitednode 198.51.100.22 from the catalog.

GDSCTL> remove invitednode 198.51.100.22

Remove the VNCR alias group EAST_SRV from the catalog.

GDSCTL> remove invitednode -group east_srv

Syntax

remove region -region region_list

Options

Usage Notes

You must connect to the catalog database as a user with the Global Data Services administrator privileges, using the connect command before running this command.

Example

Remove the region named SOUTH from the configuration.

GDSCTL> remove region -region south

Syntax

remove service [-gdspool gdspool_name]
                -service service_name

Options

Usage Notes

You must connect to the catalog database as a user with the pool administrator privileges, using the command connect before running this command

Example

Remove the service sales_report from the database pool MYREADERFARM.

GDSCTL> remove service -gdspool myreaderfarm -service sales_report

Syntax

remove shard {-shard {shard_name_list | ALL} | 
                 -shardspace shardspace_list | 
                 -shardgroup shardgroup_list}
             [-force] 

Options

Examples

Remove the shards from shardgroup GROUP1.

GDSCTL> remove shard –shardgroup group1

Syntax

remove shardgroup -shardgroup shardgroup_name

Options

Usage Notes

Only a shardgroup that does not contain any shards can be removed.

Examples

Remove the GROUP1 shardgroup.

GDSCTL> remove shardgroup –shardgroup group1

Syntax

remove shardspace -shardspace shardspace_name

Options

Usage Notes

Only a shardspace that does not contain any shards or shardgroups can be removed.

Examples

Remove the GOLD shardspace.

GDSCTL> remove shardspace –shardspace gold

Syntax

[status service | services] [-gsm gsm_name]
                            [-service service_name]
                            [-raw | -verbose | -support]

Options

Usage Notes

You must run this command on the host where the global service manager for which you want to retrieve service information resides.

You must have the privileges of the user who started the global service manager to run this command.

If -service is not specified, then information for all global services is displayed.

Example

Display information about the services registered with global service manager mygsm:

GDSCTL> services -gsm mygsm

The gdsctl services command returns output similar to the following:

GDSCTL>services -gsm mygsm
Service "localsvc.dbpoolora.oradbcloud" has 2 instance(s). Affinity: LOCALPREF
   Instance "dbpoolora%1", name: "gdscat", db: "gdscat", region: "regionora",
 status: ready.
   Instance "dbpoolora%11", name: "gdscat2", db: "gdscat2", region: "regionora",
 status: ready.
Service "sales_report1.dbpoolora.oradbcloud" has 2 instance(s). Affinity:
 LOCALONLY
   Instance "dbpoolora%1", name: "gdscat", db: "gdscat", region: "regionora",
 status: ready.
   Instance "dbpoolora%11", name: "gdscat2", db: "gdscat2", region: "regionora",
 status: ready.
Service "sales_report2.dbpoolora.oradbcloud" has 2 instance(s). Affinity: ANYWHERE
   Instance "dbpoolora%1", name: "gdscat", db: "gdscat", region: "regionora",
 status: ready.
   Instance "dbpoolora%11", name: "gdscat2", db: "gdscat2", region: "regionora",
 status: ready.

Display the status of mthly_report service:

GDSCTL>services -service mthly_report.sales.oradbcloud

Returns output similar to the following:

Service "mthly_report.sales.oradbcloud" has 1 instance(s). Affinity:
ANYWHERE
    Instance "sales%1", name: "debug", db: "debug", region: "eastcoast",
status: ready.

This command establishes to which global service manager the successive commands apply. The specified global service manager name is resolved in the gsm.ora configuration file.

Syntax

set gsm -gsm gsm_name

Options

Usage Notes

You must run this command on the host where the global service manager that you want to set for the current session resides.

You must have the privileges of the user who started the global service manager to run this command.

Example

Set the global service manager for the current session to gsm1.

GDSCTL> set gsm -gsm gsm1

Syntax

set inbound_connect_level [-gsm gsm_name]
                       timeout_value

Options

Usage Notes

• You must run this command on the host where the global service manager for which you want to set the INBOUND_CONNECT_LEVEL listener parameter resides

• You must have the privileges of the user who started the global service manager to run this command

Example

Set the INBOUND_CONNECT_LEVEL listener parameter for mygsm to time out in 60 seconds:

GDSCLTL> set inbound_connect_level -gsm mygsm 60

Syntax

set inbound_connect_timeout timeout_value
                            [-gsm gsm_name]
                            [-save_config | -config_only]

Options

Usage Notes

• You must run this command on the host where the global service manager for which you want to set the INBOUND_CONNECT_TIMEOUT listener parameter resides

• You must have the privileges of the user who started the global service manager to run this command

• By default, parameter values changes remain in effect until the global service manager is shut down.

Example

Set the INBOUND_CONNECT_TIMEOUT listener parameter for mygsm to time out in 60 seconds:

GDSCLTL> set inbound_connect_timeout -gsm mygsm 60

Syntax

set log_level [-gsm gsm_name]
              log_level

Options

Usage Notes

• You must run this command on the host where the global service manager for which you want to set the listener log level resides

• You must have the privileges of the user who started the global service manager to run this command

Example

Set logging on for global service manager mygsm:

GDSCTL> set log_level -gsm mygsm ON

Syntax

set log_status ON|OFF
               [-gsm gsm_name]
               [-save_config | -config_only]

Options

Usage Notes

• You must run this command on the host where the global service manager for which you want to set the LOG_STATUS listener parameter resides

• You must have the privileges of the user who started the global service manager to run this command

• By default, parameter values changes remain in effect until the global service manager is shut down.

Example

Set the LOG_STATUS listener parameter to ON.

GDSCLTL> set log_status on -save_config

Syntax

set outbound_connect_level [-gsm gsm_name]
                           timeout_value

Options

Usage Notes

• You must run this command on the host where the global service manager for which you want to set the timeout value of outbound connections for the listener resides.

• You must have the privileges of the user who started the global service manager to run this command.

Example

Set timeout value for all outbound connections:

GDSCTL> set outbound_connect_level 60 

Syntax

set outbound_connect_timeout timeout_value
                            [-gsm gsm_name]
                            [-save_config | -config_only]

Options

Usage Notes

• You must run this command on the host where the global service manager for which you want to set the OUTBOUND_CONNECT_TIMEOUT listener parameter resides

• You must have the privileges of the user who started the global service manager to run this command

• By default, parameter values changes remain in effect until the global service manager is shut down.

Example

Set the OUTBOUND_CONNECT_TIMEOUT listener parameter for mygsm to time out in 60 seconds:

GDSCLTL> set outbound_connect_timeout -gsm mygsm 60

Syntax

set trace_level [-gsm gsm_name]
                trace_level

Options

Usage Notes

• You must run this command on the host where the global service manager for which you want to set the listener trace level resides.

• You must have the privileges of the user who started the global service manager to run this command.

Example

Set the trace level for all listeners associated with mygsm to ADMIN

GDSCTL> set trace_level -gsm mygsm ADMIN

Syntax

set trc_level trace_level
              [-gsm gsm_name]
              [-save_config | -config_only]

Options

Usage Notes

• You must run this command on the host where the global service manager for which you want to set the LOG_STATUS listener parameter resides

• You must have the privileges of the user who started the global service manager to run this command

• By default, parameter values changes remain in effect until the global service manager is shut down.

Example

Set the TRC_LEVEL listener parameter to SUPPORT.

GDSCLTL> set trc_level support

Syntax

show ddl {[-ddl ddl_id] [-count cnt] | [-failed_only]}
          [-support]

Options

Usage Notes

If -DDL and -COUNT are both unspecified, the command returns only the last 10 DDL statements.

If -DDL is specified but -COUNT is not, the command returns detailed information about the DDL statement. The -COUNT option defines the maximum number of DDLs to display.

Examples

GDSCTL> show ddl -count 20

Syntax

split chunk -chunk chunk_id_list
           [-shardspace shard_space_list]

Options

Usage Notes

This command can only be used with system-managed sharding. For user-defined sharding, ALTER TABLE is used to split a partition of the root (parent) table.

Merging of chunks is not supported.

Examples

Split chunks 3, 4, and 5.

GDSCTL> split chunk -chunk 3,4,5

Syntax

sql "sql_statement"

Options

Usage Notes

This command can only be executed against a sharded GDS pool. The statements are executed in the GDS catalog database and are then broadcast to all shards in the pool. Since there can be only one sharded pool in a GDS configuration, all SQL statements executed on the catalog database are applied to this pool, if it exists.

Database objects created by this command in the catalog database are used as a schema of the sharded database and are not intended to store user data. The only exception is tables duplicated on all shards (reference tables) – they are populated with data in the catalog database.

SELECT statements are not allowed as the parameter.

The SQL statement or PL/SQL stored procedure to be executed must be enclosed in double quotation marks.

If the string that GDSCTL passes to PL/SQL contains a filename, then the filename must be enclosed in single quotation marks.

Do not include a semi-colon (;) after the SQL statement to be executed.

Examples

Using the gdsctl sql command.

GDSCTL> sql “CREATE TABLESPACE SET ts1 IN SHARDGROUP sgr1"

Syntax

start gsm [-gsm gsm_name]

Options

Usage Notes

• You must run GDSCTL on the same host where the global service manager you want to start is located.

• You must have operating system privileges on the computer where you want to start the global service manager to run this command.

Example

Start the global service manager gsm1 on the local host.

GDSCTL> start gsm -gsm gsm1

Syntax

start observer -database db_name
              [-timeout seconds]

Options

Usage Notes

TIMEOUT (default 15) represents the time between when the shard director/global service manager receives requests and starts the observer. See Using Oracle Sharding for the automatic rules for choosing the right region for the shard director (global service manager) server to start the observer. If shard director servers are not running in this region, the observer is not started.

Example

GDSCTL> start observer -database mydb

Syntax

start service [-gdspool gdspool_name]
               -service service_name
             [{-database db_name | 
                 -override [-pwd password] -connect connect_identifier}]

Options

Usage Notes

You must connect to the catalog database as a user with the pool administrator privileges, using the command connect before running this command.

Before starting services which run on administrator-managed databases, they must be modified for those databases to stipulate which instances should run the service. Please refer to the -modify_instances parameter of the modify service command.

Example

Start the service SALES_REPORT, located in the READERFARM database pool.

GDSCTL> start service -gdspool readerfarm -service sales_report

Syntax

status [-gsm gsm_name] [-raw|-verbose|-support]                       

Options

Example

GDSCTL> status

The command returns output similar to the following.

Alias MYGSM
Version 12.1.0.0.2
Start Date 03-JUL-2012 16:48:54
Trace Level support
Listener Log File /u01/ORACLE/mygsm/alert/log.xml
Listener Trace File /u01/ORACLE/mygsm/trace/ora_14816_47568108067776.trc
Endpoint summary (ADDRESS=(HOST=mymv.us.hq.com)(PORT=1523)(PROTOCOL=tcp))
GSMOCI Version 0.1.8
Mastership Y
Connected to GDS catalog Y
Process Id 14818
Number of reconnections 0
Pending tasks. Total 0
Tasks in process. Total 0
Regional Mastership TRUE
Total messages published 28599
Time Zone -07:00
Orphaned Buddy Regions:
None
GDS region regionora

Syntax

{status database | databases} [-gsm gsm_name]
                              [-database db_name]
                              [-gdspool gdspool_name]
                              [-raw | -support | -verbose] 

Options

Usage Notes

You must connect to the catalog database as a user with the pool administrator privileges, using the command connect before running this command.

This command requires a locally started global service manager. If -gsm is not specified for STATUS DATABASE, then the currently connected global service manager name is used by default.

Example

Display the status of all databases:

GDSCTL> status database

The gdsctl status database command returns output similar to the following:

Database: "dbcat1" Registered: Y State: Ok ONS: N. Role: PRIMARY Instances: 1
 Region: east
   
   Service: "sales_svc2" Globally started: N Started: N
            Scan: Y Enabled: Y Preferred: Y
   Service: "sales_svc1" Globally started: Y Started: Y
            Scan: N Enabled: Y Preferred: Y
   Registered instances:
     sales%11
Database: "dbcat2" Registered: Y State: Ok ONS: N. Role: PRIMARY Instances: 1
 Region: east
   Service: "sales_svc2" Globally started: N Started: N
            Scan: Y Enabled: Y Preferred: Y
   Service: "sales_svc1" Globally started: Y Started: Y
            Scan: N Enabled: Y Preferred: Y
   Registered instances:
     sales%1

Syntax

status (gsm)? [-gsm gsm_name]
              [-raw | -verbose | -support]

Options

Usage Notes

You must run GDSCTL on the same host where the global service manager for which you want to display the status is located.

You must have operating system privileges on the computer where you want to display the global service manager status to run this command.

Example

Display status of mygsm:

GDSCTL> status gsm -gsm mygsm

The gdsctl status gsm command returns output similar to the following:

Alias MYGSM
Version 12.1.0.0.2
Start Date 03-JUL-2012 16:48:54
Trace Level support
Listener Log File /u01/ORACLE/mygsm/alert/log.xml
Listener Trace File /u01/ORACLE/mygsm/trace/ora_14816_47568108067776.trc
Endpoint summary (ADDRESS=(HOST=mymv.us.hq.com)(PORT=1523)(PROTOCOL=tcp))
GSMOCI Version 0.1.8
Mastership Y
Connected to GDS catalog Y
Process Id 14818
Number of reconnections 0
Pending tasks. Total 0
Tasks in process. Total 0
Regional Mastership TRUE
Total messages published 28599
Time Zone -07:00
Orphaned Buddy Regions:
None
GDS region regionora

Syntax

{status service | services} [-gsm gsm_name]
                            [-service service_name]
                            [{-raw|-verbose|-support}]

Options

Usage Notes

• You must connect to the catalog database as a user with the pool administrator privileges, using the command connect before running this command.

• This command is similar to services.

Example

Display the status of service sales_report1.sales.oradbcloud:

GDSCTL> status service -service sales_report1.sales.oradbcloud

The gdsctl status service command returns output similar to the following:

Service "sales_report1.sales.oradbcloud" has 3 instance(s). Affinity: ANYWHERE
   Instance "sales%1", name: "dbcat2", db: "dbcat2", region: "east",
 status: ready.
   Instance "sales%11", name: "dbcat1", db: "dbcat1", region: "west",
 status: ready.
   Instance "sales%31", name: "dbcat3", db: "dbcat3", region: "east",
 status: ready.

Syntax

stop gsm [-gsm gsm_name]

Options

Usage Notes

• You must run GDSCTL on the same host where the global service manager that you want to stop is located.

• You must have operating system privileges on the computer where you want to start the global service manager to run this command.

Example

Stop the global service manager gsm1 on the local host.

GDSCTL> stop gsm -gsm gsm1

Syntax

stop service [-gdspool gdspool_name]
             [-service service_name_list]
             [{-database db_name |
                 -override -connect connect_identifier [-pwd password]}]
             [-force]
             [-drain_timeout time]
             [-stop_option {NONE|IMMEDIATE|TRANSACTIONAL}]

Options

Usage Notes

You must connect to the catalog database as a user with the pool administrator privileges, using the command connect before running this command.

If -service is not specified, all global services of GDS pool are stopped.

If -database is not specified, the global services are stopped on all of the databases.

If -force is specified, all sessions are disconnected, requiring the session using the global service to reconnect (potentially to another instance). If -force is not specified, then sessions already connected to this global service stay connected, but new sessions cannot be established to the global service.

If -override is specified, the command is executed without connecting to the GDS catalog. Use this option when the GDS catalog is unavailable. It is not recommended for use under normal operation.

Example

Stop the service SALES_REPORT, on all databases in the database pool READERFARM.

GDSCTL> stop service -gdspool readerfarm -service sales_report

Syntax

sync[hronize] brokerconfig [-gdspool gdspool_name]
                           [-database db_name]

Options

Usage Notes

You must connect to the catalog database as a user with the pool administrator privileges, using the command connect before running this command.

Example

Synchronize the Oracle Data Guard broker configuration in the database pool MYREADERFARM with the configuration stored in the Global Data Services catalog.

GDSCTL> sync brokerconfig -gdspool myreaderfarm

Syntax

sync[hronize] database [-gdspool gdspool_name]
                       [-database database_name]

Options

Usage Notes

• If database has no GDS region assigned, an error is returned.

• If a GDS pool is specified and the database option is not specified, then each database in the pool is synchronized.

Example

Synchronize a database in the default database pool with the database mydb.

GDSCTL> sync database -database mydb

Syntax

validate [catalog] 
         [-gsm gsm_name]
         [ {-config | -database db_name} ] 
         [-catpwd cpwd]
         [-dbpwd dpwd]

Options

Usage Notes

Because the execution of this command involves accessing all databases in a Global Data Services configuration, the GSMCATUSER password is required run it. The password is stored in the wallet of any global service manager that is part of the Global Data Services configuration. Therefore, if you run the command from the ORACLE_HOME of any of the global service managers, the password is automatically extracted from the wallet and does not have to be provided. Otherwise, you must provide the GSMCATUSER password using the -catpwd command option. Alternatively, if all databases in the Global Data Services configuration have the same GSMUSER password, you can specify the password instead of the GSMCATUSER password by using the -dbpwd option.