add service

Adds a global service to a Global Data Services pool.

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 | TRUE_CACHE}]
           [-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]
           [-failover_restore {NONE|LEVEL1|AUTO}]
           [-reset_state {NONE|LEVEL1}]

Options

Table 2-12 GDSCTL add service Options

Option	Description
-available dbname_list	Specify a comma-delimited list of available databases on which the service runs if the preferred databases are not available. You cannot specify a list of available instances, only databases. You can use the modify service command with the -server_pool parameter to specify instance-level preferences. The list of available databases must be mutually exclusive with the list of preferred databases. You cannot use this option with the -preferred_all option. For True Cache implementations, specify a comma-delimited list of available databases or True Caches on which the service runs if the preferred ones are not available. You can't specify a list of available instances, only databases and True Caches. You can use the modify service command with the -server_pool parameter to specify instance-level preferences. The list of available databases or True Caches must be mutually exclusive with the list of preferred ones. You cannot use this option with the -preferred_all option.
-clbgoal {SHORT | LONG}	Connection Load Balancing Goal. Use a value of SHORT for this parameter for run-time load balancing, or if using an integrated connection pool. Use a value of LONG for this parameter for long running connections, such as batch jobs, that you want balanced by the number of sessions for each node for the service. The default value for this option, if not specified, is SHORT. For True Cache services, set the connection load balancing goal to SHORT for runtime load balancing.
-commit_outcome {TRUE | FALSE}	Enable Transaction Guard; when set to TRUE, the commit outcome for a transaction is accessible after the transaction's session fails due to a recoverable outage.
—drain_timeout	Set drain time in seconds.
-dtp {TRUE | FALSE}	Indicates whether Distributed Transaction Processing should be enabled for this service. This service can either be a service in a policy-managed database or a preferred service on a single node in an administrator-managed database.
-edition edition_name	Specify the initial session edition of the service. When an edition is specified for a service, all subsequent connections that specify the service use this edition as the initial session edition. However, if a session connection specifies a different edition, then the edition specified in the session connection is used for the initial session edition. GDSCTL does not validate the specified edition name. During connection, the connect user must have USE privilege on the specified edition. If the edition does not exist or if the connect user does not have USE privilege on the specified edition, then an error is raised.
-failover_primary	If you set the -role option to PHYSICAL_STANDBY, then you can use this option to enable the service for failover to the primary database. If the -role is TRUE_CACHE, you can use this option to enable the service to failover to the primary database if no True Caches are available. Also include the primary database in the -preferred or -available list, or use the -preferred_all option.
-failoverdelay failover_delay	For Application Continuity and TAF, this parameter specifies the time delay (in seconds) between reconnect attempts for each incident at failover.
-failovermethod {NONE | BASIC}	TAF failover method (for backward compatibility only). If the failover type (-failovertype) is set to a value other than NONE, then you should choose BASIC for this parameter.
-failoverretry failover_retries	For Application Continuity and TAF, this parameter determines the number of attempts to connect after an incident.
-failovertype {NONE | SESSION | SELECT | TRANSACTION}	Specify the failover type. To enable Application Continuity for Java, set this parameter to TRANSACTION. To enable Transparent Application Failover (TAF) for OCI, set this parameter to SELECT or SESSION.
-gdspool gdspool_name	Specify the name of the Global Data Services pool to which you want to add a service. If the pool name is not specified and there is only one gdspool with access granted to the user, then this the gdspool with access granted is used as the default gdspool.
-lag {lag_value | ANY}	Specify the lag for the service in seconds. You can use the keyword ANY to indicate that there is no upper threshold on the lag time. This parameter specifies the maximum lag that a provider of this service may have. The service cannot be provided by a database whose lag exceeds this value. If a True Cache falls behind the primary database beyond the specified lag time, the service stop forwarding requests to that True Cache until it catches up. The default value for lag, if not specified, is ANY.
-locality {ANYWHERE | LOCAL_ONLY}	Specify the service region locality. If you do not specify this option, then GDSCTL uses the default value of ANYWHERE for the service. For True Cache services, set the locality to LOCAL_ONLY. This indicates that GDS only routes to True Caches in the same region, regardless of load. Use this option together with -region_failover so that client connections and requests are routed to another region if all True Caches in a region have failed.
-notification {TRUE | FALSE}	Enable Fast Application Notification (FAN) for OCI connections.
-pdbname pdb_name	Specify the pluggable database name.
-policy {AUTOMATIC | MANUAL}	Specify the management policy for the service. If you specify AUTOMATIC (the default), then the service automatically starts when the database restarts, either by a planned restart or after a failure. Automatic restart is also subject to the service role. If you specify MANUAL, then the service is never automatically restarted upon planned restart of the database. A MANUAL setting does not prevent the global service manager from monitoring the service when it is running and restarting it if a failure occurs.
-preferred dbname_list	Specify a comma-delimited list of preferred databases or True Caches on which the service runs. You can't specify preferred instances, only databases and True Caches. You can use the modify service command to specify instance-level preferences. The list of preferred databases must be mutually exclusive with the list of available databases. You cannot use this option with the -preferred_all option.
-preferred_all	Specifies that all the databases in the Global Data Services pool are preferred databases. Any databases you later add to the pool are configured as preferred databases for this service. You cannot use this option with the -preferred and -available options. For True Cache services, indicates that this service will be started on all existing and future True Caches and, if used with - failover_primary, the primary database.
-region_failover	Indicates that the service is enabled for region failover. You can only use this option when you specify LOCAL_ONLY for the -locality option.
-replay_init_time replay_init_time	For Application Continuity, this parameter specifies the time (in seconds) after which replay cannot be initiated. The default value is 300 seconds.
-retention retention_seconds	If commit_outcome is set to TRUE, then this parameter determines the amount of time (in seconds) that the commit outcome is retained in the database.
-rlbgoal {SERVICE_TIME | THROUGHPUT}	Run-time Load Balancing Goal (for the Load Balancing Advisory). Set this parameter to SERVICE_TIME to balance connections by response time. Set this parameter to THROUGHPUT to balance connections by throughput. For True Cache services, set the runtime load balancing goal to SERVICE_TIME to balance connections by response time instead of by throughput. If you do not use this option, then the value defaults to SERVICE_TIME for the run-time load balancing goal.
-role {[PRIMARY] | [PHYSICAL_STANDBY|TRUE_CACHE] [-failover_primary] | [LOGICAL_STANDBY] |[SNAPSHOT_STANDBY]}	Specify the database role that the database must be for this service to start on that database. This applies only to Global Data Services pools that contain an Oracle Data Guard broker configuration. For True Cache services, use TRUE_CACHE. This ensure that the service only runs on other True Caches, not on the primary database See Also: Oracle Data Guard Concepts and Administration for more information about database roles
-service service_name	Specify the name of the global service. The service name specified in the add service command can be domain qualified (for example, sales.example.com) or not (for example, sales). If the specified name is not domain qualified, the service is created with the default domain name <GDS_pool_name>.<GDS_configuration_name>, however the shorter non-domain qualified name can be used with subsequent gdsctl commands to manage the service. If the specified name is domain qualified, the full domain qualified service name must be used in all subsequent gdsctl commands used to manage the service. A global service name must be unique within a GDS pool and when qualified by domain, must also be unique within a GDS configuration. A global service cannot be created at a database if a local or global service with the same name already exists at that database. A global service name can contain alphanumeric characters, underscore (_), and period (.). The first character must be alphanumeric. The maximum length of a global service name is 64 characters. The maximum length of a domain qualified global service name is 250 characters. An Oracle Net connect descriptor used to connect to a global service must contain a domain qualified service name.
-session_state {DYNAMIC | STATIC}	For Application Continuity, this parameter specifies whether the session state that is not transactional is changed by the application. A setting of DYNAMIC is recommended for most applications.
-sql_translation_profile stp_name	Use this option to specify a SQL translation profile for a service that you are adding after you have migrated applications from a non-Oracle database to an Oracle database. This option corresponds to the SQL translation profile parameter in the DBMS_SERVICE service attribute. Notes: Before using the SQL translation feature, you must migrate all server-side application objects and data to the Oracle database. Use the command config service to display the SQL translation profile. See Also: Oracle AI Database SQL Translation and Migration Guide for more information about SQL translation
—stop_option	Set the default stop option to NONE, IMMEDIATE, or TRANSACTIONAL
-table_familyfamily	Specifies the name of the table family as a property of the service. This parameter takes one of the table family values (root table schema.name) as shown in the CONFIG TABLE FAMILY output. If the schema name or the table name is case-sensitive, use two-level quotes (single quotes outside, double quotes inside) around the whole string, for example, '"TESTUSER1.Customers6"'. No quotes are needed if neither name is case sensitive. If this parameter is not specified, but there is currently only one table family, the service created with the add service command is automatically associated with that table family.
-tafpolicy {BASIC | NONE }	TAF policy specification (for administrator-managed databases only).
-failover_restore	Session state restoration for Application Continuity (NONE | LEVEL1 | AUTO)
-reset_state	Reset session state (NONE -default | LEVEL1 | AUTO)

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).

Services cannot be added to systems that run Clusterware unless Clusterware is started on the system, even if the target database is not under CRS control. Ensure that Clusterware is started on Clusterware enabled systems before adding a new global service.

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

Note:

Starting with Oracle AI Database 26ai, the session attribute values FAILOVER_TYPE = TRANSACTION with SESSION_STATE_CONSISTENCY = STATIC are no longer a supported service attribute combination. Instead use one of the following combinations in the service configuration: FAILOVER_TYPE = AUTO with SESSION_STATE_CONSISTENCY = AUTO or FAILOVER_TYPE = TRANSACTION with SESSION_STATE_CONSISTENCY = DYNAMIC These configurations enforce session state tracking in the Oracle database ensuring that session state is preserved at session migration and session failover.

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