srvctl add service

Adds services to a database and assigns them to instances. If you have multiple instances of a cluster database on the same node, then always use only one instance on that node for all of the services that node manages.

Note:

The srvctl add service command does not accept placement parameters for Oracle RAC One Node databases.

Syntax and Parameters

Use the srvctl add service command with one of the following syntax models:

To add a service to a policy-managed database:

srvctl add service -db db_unique_name -service service_name [-eval] 
   -serverpool server_pool [-cardinality {UNIFORM | SINGLETON}] 
   [-edition edition_name] [-netnum network_number]
   [-role "[PRIMARY][,PHYSICAL_STANDBY][,LOGICAL_STANDBY][,SNAPSHOT_STANDBY]"
   [-policy {AUTOMATIC | MANUAL}] [-notification {TRUE | FALSE}] 
   [-clbgoal {SHORT | LONG}] [-failovertype {NONE|SESSION|SELECT|TRANSACTION}]
   [-rlbgoal {NONE | SERVICE_TIME | THROUGHPUT}] [-dtp {TRUE | FALSE}]
   [-failovermethod {NONE | BASIC}] [-failoverretry failover_retries]
   [-failoverdelay failover_delay] [-pdb pluggable_database] 
   [-sql_translation_profile sql_translation_profile] 
   [-global {TRUE | FALSE}] [-maxlag max_lag_time] [-commit_outcome {TRUE|FALSE}]
   [-retention retention_time] [-replay_init_time replay_initiation_time]
   [-session_state {STATIC | DYNAMIC}] [-pqservice pq_service] 
   [-pqpool pq_pool_list] [-force]

To add a service to an administrator-managed database:

srvctl add service -database db_unique_name -service service_name [-eval]
   -preferred preferred_list -available available_list] [-netnum network_number]
   [-tafpolicy {BASIC | NONE | PRECONNECT}] [-edition edition_name]
   [-role "[PRIMARY][,PHYSICAL_STANDBY][,LOGICAL_STANDBY][,SNAPSHOT_STANDBY]"
   [-policy {AUTOMATIC | MANUAL}] [-notification {TRUE | FALSE}] 
   [-clbgoal {SHORT | LONG}] [-failovertype {NONE|SESSION|SELECT|TRANSACTION}]
   [-rlbgoal {NONE | SERVICE_TIME | THROUGHPUT}] [-dtp {TRUE | FALSE}]
   [-failovermethod {NONE | BASIC}] [-failoverretry failover_retries]
   [-failoverdelay failover_delay] [-pdb pluggable_database] 
   [-sql_translation_profile sql_translation_profile] 
   [-global {TRUE | FALSE}] [-maxlag max_lag_time] [-commit_outcome {TRUE|FALSE}]
   [-retention retention_time] [-replay_init_time replay_initiation_time]
   [-session_state {STATIC|DYNAMIC}] [-pqservice pq_service] 
   [-pqpool pq_pool_list] [-force] [-verbose]

To update the preferred and available lists of an existing service:

srvctl add service -db db_unique_name -service service_name 
   -update {-prefered preferred_list | -available available_list} [-force] 
   [-verbose]

Table A-18 lists and describes all the srvctl add service parameters and whether they can be used when adding a service to either an Oracle RAC database or noncluster database.

Table A-18 srvctl add service Parameters

Parameter Description
-db db_unique_name

Unique name for the database.

-service service_name

The service_name.service_domain should be unique within the cluster unless you want to spread connections across multiple databases that offer the same service. If you do not specify the service domain as part of the service name (such as sales.example.com), then the DB_DOMAIN database attribute is appended to the service name.

Note: The -service parameter has a 4 kilobyte (KB) limit for its value. Therefore, the total length of the names of all services assigned to an instance cannot exceed 4 KB.

-eval

Use this parameter to hypothetically evaluate the impact of the command on the system.

Note: You can only use this parameter with a policy-managed service.

-edition edition_name

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.

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

-sql_translation_profile
 profile_name

Use this parameter 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 parameter 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 srvctl config service command to display the SQL translation profile.

See Also: Oracle Database Migration Guide for more information about SQL translation

-preferred preferred_list

A list of preferred instances on which the service runs when the database is administrator managed.

The list of preferred instances must be mutually exclusive with the list of available instances.

Note: This parameter can be used only with Oracle RAC and only for administrator-managed databases.

-available available_list

A list of available instances to which the service fails over when the database is administrator managed.

The list of available instances must be mutually exclusive with the list of preferred instances.

Note: This parameter can be used only with Oracle RAC and only for administrator-managed databases.

-serverpool server_pool

The name of a server pool used when the database is policy managed.

Note: This parameter can be used only with Oracle RAC and only for policy-managed databases.

-cardinality {UNIFORM | SINGLETON}

The cardinality of the service, either UNIFORM (offered on all instances in the server pool) or SINGLETON (runs on only one instance at a time).

Notes:

  • This parameter can be used only with Oracle RAC and only for policy-managed databases.

  • For policy-managed Oracle RAC One Node databases, all services must be SINGLETON.

-netnum network_number

Use this parameter to determine on which network this service is offered. The service is configured to depend on VIPs from the specified network.

Note: This parameter can be used only with Oracle RAC and Oracle RAC One Node database configurations.

-tafpolicy {BASIC | NONE
 | PRECONNECT}

TAF policy specification (for administrator-managed databases only).

Note: You can only use PRECONNECT when you specify the -preferred and -available parameters.

-role "[PRIMARY][,PHYSICAL_STANDBY]
[,LOGICAL_STANDBY][,SNAPSHOT_STANDBY]"

The service role. You can specify one or more roles in a comma-delimited list.

Use this option to indicate that the service should only be automatically started upon database open when the Oracle Data Guard database role matches one of the specified service roles.

Using SRVCTL to manually start a service is not affected by the service role.

Note:

The -role parameter is only used at database startup and by the Oracle Data Guard Broker. All manual service startup must specify the name of the service to be started by the user.
See Also:
-policy {AUTOMATIC | MANUAL}

Service management policy.

If AUTOMATIC (the default), then the service is automatically started upon restart of the database, either by a planned restart (with SRVCTL) or after a failure. Automatic restart is also subject to the service role, however (the -role parameter).

If MANUAL, then the service is never automatically restarted upon planned restart of the database (with SRVCTL). A MANUAL setting does not prevent Oracle Clusterware from monitoring the service when it is running and restarting it if a failure occurs.

Note: Using CRSCTL to stop and start the Oracle Clusterware restarts the service in the same way that a failure does.

-notification {TRUE | FALSE}

Enable Fast Application Notification (FAN) for OCI connections.

-dtp {TRUE | FALSE}

Indicates whether Distributed Transaction Processing should be enabled for this service. This service will either be a singleton service in a policy-managed database or a preferred service on a single node in an administrator-managed database.

Note: This parameter can be used only with Oracle RAC.

-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 per node for the service.

-rlbgoal {NONE |
 SERVICE_TIME | THROUGHPUT}

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

-failovertype {NONE | SESSION |
 SELECT | TRANSACTION}

Failover type.

To enable Application Continuity for Java, set this parameter to TRANSACTION. To enable TAF for OCI, set this parameter to SELECT or SESSION.

Note: If you set -failovertype to TRANSACTION, then you must set -commit_outcome to TRUE.

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

Note: This parameter can be used only with Oracle RAC.

-failoverretry failover_retries

For Application Continuity and TAF, this parameter determines the number of attempts to connect after an incident.

-failoverdelay failover_delay

For Application Continuity and TAF, this parameter specifies the time delay (in seconds) between reconnect attempts per incident at failover.

-pdb pluggable_database

The name of the pluggable database (PDB).

Note: You can specify a PDB property when you create or modify a service. The PDB property associates the service with the specified PDB. You can view the PDB property for a service by querying the ALL_SERVICES data dictionary view or, when using the SRVCTL utility, by running the srvctl config service command.

When create or modify a service with the specified PDB, SRVCTL does not check if the PDB exists.Before running this command, you must ensure that the PDB exists.

-global {TRUE | FALSE}

Indicates whether this is a Global Data Services service.

Note: This parameter can only be used with Global Data Services.

-maxlag maximum_lag_time

Maximum replication lag time in seconds. Must be a non-negative integer. The default value is ANY.

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

-retention retention_time

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.

-replay_init_time
 replay_initialization_time

For Application Continuity, this parameter specifies the difference between the time, in seconds, of original execution of the first operation of a request and the time that the replay is ready to start after a successful reconnect. Application Continuity will not replay after the specified amount of time has passed. This parameter is intended to avoid the unintentional execution of a transaction when a system is recovered after a long period. The default is 5 minutes (300). The maximum value is 24 hours (86400).If the -failover_type parameter is not set to TRANSACTION, then you cannot use this parameter.

-session_state {STATIC | DYNAMIC}

For Application Continuity, this parameter specifies whether the session state that is not transactional is changed by the application. Oracle recommends a setting of DYNAMIC for most applications.

Note: This parameter is considered only if -failovertype is set to TRANSACTION for Application Continuity. It describes how non-transactional is changed during a request. Examples of session state are NLS settings, optimizer preferences, event settings, PL/SQL global variables, temporary tables, advanced queues, LOBs, and result cache. If non-transactional values change after the request starts, then use the default, DYNAMIC. Most applications should use DYNAMIC mode. If you are unsure, then use DYNAMIC mode.

-pqservice pq_service

A comma-delimited list of parallel query service names.

-pqpool pq_pool_list

A comma-delimited list of parallel query server pool names

-update {-preferred
 new_preferred_instance |
 -available
 new_available_instance}

Add a new preferred or available instance to the service configuration. -preferred specifies the name of the instance to add to the list of preferred instances for the service. -available specifies the name of the instance to add to the list of available instances for the service.

-verbose

Display verbose output.

-force

Force the add operation even though a listener is not configured for a network.

Examples

Use this example syntax to add the gl.example.com service to the my_rac database with Fast Application Notification enabled for OCI connections, a failover method of BASIC, a Connection Load Balancing Goal of LONG, a failover type of SELECT, and 180 failover retries with a failover delay of 5 seconds:

srvctl add service -db my_rac -service gl.example.com -notification TRUE \
-failovermethod BASIC -failovertype SELECT -failoverretry 180 -failoverdelay 5 \
-clbgoal LONG

Use this example syntax to add a named service to a database with preferred instances and available instances and enabled for TAF:

srvctl add service -db crm -service sales -preferred crm01,crm02 -available crm03\
 -tafpolicy BASIC