8 XStream In Concepts

Overview of Inbound Servers

An inbound server is an optional Oracle background process that receives LCRs from a client application. Specifically, a client application can attach to an inbound server and send row changes, DDL changes, and procedure calls encapsulated in LCRs.

An external client application connects to the inbound server using the OCI or the Java interface. After the connection is established, the client application acts as the capture agent for the inbound server by streaming LCRs to it.

A client application can create multiple sessions. Each session can attach to only one inbound server, and each inbound server can serve only one session at a time. However, different client application sessions can connect to different inbound servers or outbound servers. A client application can detach from the inbound server whenever necessary.

Figure 8-1 shows an inbound server configuration.

Figure 8-1 XStream In Inbound Server

Description of "Figure 8-1 XStream In Inbound Server"

Data Types Applied by Inbound Servers

When applying row LCRs resulting from DML changes to tables, an inbound server applies changes made to columns of the following data types:

• VARCHAR2

• NVARCHAR2

• NUMBER

• FLOAT

• LONG

• DATE

• BINARY_FLOAT

• BINARY_DOUBLE

• TIMESTAMP

• TIMESTAMP WITH TIME ZONE

• TIMESTAMP WITH LOCAL TIME ZONE

• INTERVAL YEAR TO MONTH

• INTERVAL DAY TO SECOND

• RAW

• LONG RAW

• UROWID

• CHAR

• NCHAR

• CLOB with BASICFILE or SECUREFILE storage

• NCLOB with BASICFILE or SECUREFILE storage

• BLOB with BASICFILE or SECUREFILE storage

• XMLType stored as CLOB, object relational, or as binary XML

• Object types

• The following Oracle-supplied types: ANYDATA, SDO_GEOMETRY, and media types

If XStream is replicating data for an object type, then the replication must be unidirectional, and all replication sites must agree on the names and data types of the attributes in the object type. You establish the names and data types of the attributes when you create the object type. For example, consider the following object type:

CREATE TYPE cust_address_typ AS OBJECT
     (street_address     VARCHAR2(40), 
      postal_code        VARCHAR2(10), 
      city               VARCHAR2(30), 
      state_province     VARCHAR2(10), 
      country_id         CHAR(2));
/

At all replication sites, street_address must be VARCHAR2(40), postal_code must be VARCHAR2(10), city must be VARCHAR2(30), and so on.

LCR Processing Options for Inbound Servers

An inbound server can either apply LCRs directly or send LCRs to an apply handler for processing. Your options for LCR processing depend on whether the LCR received by an inbound server is a row LCR or a DDL LCR.

By default, an inbound server applies LCRs directly. The inbound server executes the change in the LCR on the database object identified in the LCR. The inbound server either successfully applies the change in the LCR or, if a conflict or an apply error is encountered, tries to resolve the error with a conflict handler or a user-specified procedure called an error handler.

If a conflict handler can resolve the conflict, then it either applies the LCR or it discards the change in the LCR. If an error handler can resolve the error, then it should apply the LCR, if appropriate. An error handler can resolve an error by modifying the LCR before applying it. If the conflict handler or error handler cannot resolve the error, then the inbound server places the transaction, and all LCRs associated with the transaction, into the error queue.

Instead of applying LCRs directly, you can process LCRs in a customized way with apply handlers. When you use an apply handler, an inbound server passes an LCR to a collection of SQL statements or to a user-defined PL/SQL procedure for processing. An apply handler can process the LCR in a customized way.

There are several types of apply handlers. This section uses the following categories to describe apply handlers:

The following sections describe different types of apply handlers and considerations for using them:

• DML Handlers

• Error Handlers

• DDL Handlers

• Precommit Handlers

Inbound Servers and RESTRICTED SESSION

When restricted session is enabled during system startup by issuing a STARTUP RESTRICT statement, inbound servers do not start, even if they were running when the database shut down. When the restricted session is disabled, each inbound server that was not stopped is started.

When restricted session is enabled in a running database by the SQL statement ALTER SYSTEM ENABLE RESTRICTED SESSION, it does not affect any running inbound servers. These inbound servers continue to run and send LCRs to an XStream client application. If a stopped inbound server is started in a restricted session, then the inbound server does not actually start until the restricted session is disabled.

Inbound Server Components

An inbound server consists of the following subcomponents:

• A reader server that receives LCRs from an XStream client application. The reader server is a process that computes dependencies between logical change records (LCRs) and assembles LCRs into transactions. The reader server then returns the assembled transactions to the coordinator process.

  You can view the state of the reader server for an inbound server by querying the V$XSTREAM_APPLY_READER dynamic performance view. See Oracle Database Reference.

• A coordinator process that gets transactions from the reader server and passes them to apply servers. The coordinator process name is APnn, where nn can include letters and numbers. The coordinator process is an Oracle background process.

  You can view the state of a coordinator process by querying the V$XSTREAM_APPLY_COORDINATOR dynamic performance view. See Oracle Database Reference.

• One or more apply servers that apply LCRs to database objects as DML or DDL statements or that pass the LCRs to their appropriate apply handlers. Apply servers can also enqueue LCRs into the persistent queue portion of a queue specified by the DBMS_APPLY_ADM.SET_ENQUEUE_DESTINATION procedure. Each apply server is a process. If an apply server encounters an error, then it then tries to resolve the error with a user-specified conflict handler or error handler. If an apply server cannot resolve an error, then it rolls back the transaction and places the entire transaction, including all of its LCRs, in the error queue.

  When an apply server commits a completed transaction, this transaction has been applied. When an apply server places a transaction in the error queue and commits, this transaction also has been applied.

  You can view the state of each apply server for an inbound server by querying the V$XSTREAM_APPLY_SERVER dynamic performance view. See Oracle Database Reference.

The reader server and the apply server process names are ASnn, where nn can include letters and numbers. If a transaction being handled by an apply server has a dependency on another transaction that is not known to have been applied, then the apply server contacts the coordinator process and waits for instructions. The coordinator process monitors all of the apply servers to ensure that transactions are applied and committed in the correct order.

Considerations for Inbound Servers

The following are considerations for XStream inbound servers:

• You can control a DML or DDL trigger's firing property using the SET_TRIGGER_FIRING_PROPERTY procedure in the DBMS_DDL package. This procedure lets you specify whether a trigger always fires, fires once, or fires for inbound server changes only. When a trigger is set to fire once, it fires for changes made by a user process, but it does not fire for changes made by an inbound server. A trigger's firing property works the same for apply processes and inbound servers. See Oracle Streams Concepts and Administration.

• An inbound server ignores the setting for the ignore_transaction apply parameter because LCRs sent to the inbound server by the client application might not have transaction ID values.

• An inbound server ignores the setting for the maximum_scn apply parameter because LCRs sent to the inbound server by the client application might not have SCN values.

  See Also:

  Oracle Database PL/SQL Packages and Types Reference for more information about apply parameters

The Error Queue for an Inbound Server

The error queue contains all of the current apply errors for a database. If there are multiple inbound servers in a database, then the error queue contains the apply errors for each inbound server.

Trusted users can view apply errors by querying the DBA_APPLY_ERROR data dictionary view or by using Oracle Enterprise Manager Cloud Control. The DBA_APPLY_ERROR data dictionary view enables the trusted user to see information about apply errors for other users. Untrusted users can view apply errors by querying the ALL_APPLY_ERROR data dictionary view. This view shows only apply errors for the untrusted user.

Also, trusted users can view more detailed information about apply errors by querying the DBA_APPLY_ERROR_MESSAGES data dictionary view. Untrusted users can view more detailed information about apply errors by querying the ALL_APPLY_ERROR_MESSAGES data dictionary view. These views include information about the row that caused the error in an error transaction.

The error queue stores information about transactions that could not be applied successfully by the inbound server running in a database. A transaction can include many LCRs. When an unhandled error occurs during apply, an inbound server automatically moves all of the LCRs in the transaction that satisfy the inbound server's rule sets to the error queue.

You can correct the condition that caused an error and then reexecute the transaction that caused the error. For example, you might modify a row in a table to correct the condition that caused an error.

When the condition that caused the error has been corrected, you can either reexecute the transaction in the error queue using the EXECUTE_ERROR or EXECUTE_ALL_ERRORS procedure, or you can delete the transaction from the error queue using the DELETE_ERROR or DELETE_ALL_ERRORS procedure. These procedures are in the DBMS_APPLY_ADM package.

When you reexecute a transaction in the error queue, you can specify that the transaction be executed either by the user who originally placed the error in the error queue or by the user who is reexecuting the transaction. Also, the current tag for the inbound server is used when you reexecute a transaction in the error queue.

A reexecuted transaction uses any relevant apply handlers and conflict resolution handlers. If, to resolve the error, a row LCR in an error queue must be modified before it is executed, then you can configure a procedure DML handler to process the row LCR that caused the error in the error queue. In this case, the DML handler can modify the row LCR to avoid a repetition of the same error. The row LCR is passed to the DML handler when you reexecute the error containing the row LCR. For example, a statement DML handler might insert different values than the ones present in an insert row LCR, while a procedure DML handler might modify one or more columns in the row LCR to avoid a repetition of the same error.

Optimizing XStream In Performance for Large Transactions

For small transactions, XStream In does not begin to apply the logical change records (LCRs) until the inbound server receives a commit LCR for the transaction from the source. As a performance optimization, an inbound server can use eager apply to begin to apply large transactions before it receives the commit LCR. The eager_size apply parameter controls the minimum number of LCRs received by the inbound server before eager apply begins. When the number of LCRs in a transaction exceeds the value of the eager_size apply parameter, the inbound server begins to apply the LCRs. The default value for this parameter is 9500. You can modify the parameter value to optimize XStream In performance in your environment.

Large transactions may require additional apply servers to apply the LCRs. After eager apply starts for a transaction, an inbound server can automatically create additional apply servers to apply the LCRs. The max_parallelism apply parameter controls the maximum number of apply servers for an inbound server.

If an inbound server automatically creates additional apply servers, and some of them are idle for a period of time, then XStream In determines that they are no longer necessary and removes them automatically. However, the number of apply servers never goes below the value specified by the parallelism apply parameter. Any statistics for these apply servers are aggregated as apply server 0 (zero).

For an inbound server to use eager apply for large transactions, the value of the eager_size apply parameter must be less than the value of the txn_lcr_spill_threshold apply parameter. When the value of txn_lcr_spill_threshold is lower than eager_size, a transaction spills to disk before eager apply begins, and a an inbound server cannot use eager apply for a transaction that has spilled to disk.

Avoiding Potential Bottlenecks in Transaction Tracking

XStream In keeps track of the changes it is applying to the database to avoid reapplying transactions when an inbound server is restarted. When the optimize_progress_table apply parameter is set to TRUE, the default, XStream In tracks its progress in the redo log. Use of the redo log avoids the potential bottleneck and contention caused by DML changes in the progress table.

When the optimize_progress_table parameter is set to FALSE, XStream In uses a table for tracking. In high volume environments, this table can be a potential bottleneck.

The apply database must be in archive log mode before apply tracking can be done in the redo log. If the optimize_progress_table parameter is set to TRUE but the apply database is not in archive log mode, then the setting of optimize_progress_table is ignored and XStream In uses a table for tracking.

Optimizing Transaction Apply Scheduling

When the constraints on the target tables match the constraints on the source tables, you can optimize dependency computation by setting the compute_lcr_dep_on_arrival apply parameter for an inbound server to Y. If the constraints do not match, then set this apply parameter to N, the default.

If this apply parameter is set to Y, then the dependencies are computed as the LCRs for the transaction are received. If this apply parameter is set to N, then the dependencies are computed only after all the LCRs for a committed transaction are received.

Regardless of compute_lcr_dep_on_arrival apply parameter setting, the before image of the key columns must be available in the LCRs received by the inbound server. Key columns include primary key columns, foreign key column, and unique constraint columns. In an XStream configuration in which an inbound server applies changes captured by a capture process in an XStream Out configuration, supplemental logging ensures that the required information is in the LCRs.

The XStream In Client Application and Security

XStream In allows an application to send LCRs to an inbound server, and an inbound server can apply the database changes in the LCRs to the database. Java and OCI client applications must connect to an Oracle database before attaching to an XStream inbound server created on that database. The connected user must be the same as the apply user configured for the inbound server. Otherwise, an error is raised.

The XStream Java layer API relies on Oracle JDBC security because XStream accepts the Oracle JDBC connection instance created by client applications in the XStream attach method in the XStreamIn class. The connected user is validated as an XStream user.

XStream In Component-Level Security

All the components of the XStream In configuration run as the same user. This user is the apply user for the inbound server. This user can be either a trusted user with a high level of privileges or it can be an untrusted user that has only the privileges necessary for performing certain tasks.

The security model of the XStream administrator also determines the data dictionary views that this user can query to monitor the XStream configuration. The trusted administrator can monitor XStream with DBA_ views. The untrusted administrator can monitor XStream with ALL_ views.

You create an XStream administrator using the GRANT_ADMIN_PRIVILEGE procedure in the DBMS_XSTREAM_AUTH package. When you run this procedure to create an XStream administrator for XStream In, the privilege_type parameter determines the type of privileges granted to the user:

• Specify APPLY for the privilege_type parameter if the XStream administrator manages only an XStream In configuration on the database.

• Specify * for the privilege_type parameter if the XStream administrator manages both an XStream Out and an XStream In configuration on the database.

The GRANT_ADMIN_PRIVILEGE procedure grants privileges for Oracle-supplied views and packages that are required to run components in an XStream In or XStream Out configuration. This procedure does not grant privileges on database objects owned by users. If such privileges are required, then they must be granted separately.

Privileges Required by the Apply User for an Inbound Server

An inbound server applies LCRs in the security domain of its apply user. The inbound server receives LCRs from an XStream client application and applies the LCRs that satisfy the inbound server's rule sets. The apply user can apply LCRs directly to database objects. In addition, the apply user runs all custom rule-based transformations specified by the rules in these rule sets. The apply user also runs user-defined apply handlers. XStream In does not assume that the apply user for the inbound server is trusted.

The apply user must have the necessary privileges to apply changes, including the following privileges:

• The required privileges to apply data manipulation language (DML) changes to tables in other schemas (when the inbound server receives DML changes to tables in other schemas)

• The required privileges to apply data definition language (DDL) changes to the database (when the inbound server receives DDL changes)

• EXECUTE privilege on the rule sets used by the inbound server

• EXECUTE privilege on all custom rule-based transformation functions specified for rules in the positive rule set

• EXECUTE privilege on any apply handlers

An inbound server can be associated with only one user, but one user can be associated with many inbound servers.

Grant privileges to the apply user with the DBMS_XSTREAM_AUTH package by specifying APPLY for the privilege_type parameter in the GRANT_ADMIN_PRIVILEGE procedure.

XStream In and Oracle Real Application Clusters

You can configure an inbound server to apply changes in an Oracle Real Application Clusters (Oracle RAC) environment. The inbound server runs in the Oracle RAC instance where you connected. In the event that this instance fails, you can connect to a surviving instance and start the inbound server again.

XStream In and Flashback Data Archive

Inbound servers can apply changes encapsulated in logical change records (LCRs) to tables in a flashback data archive.

Inbound servers also support the following DDL statements:

• CREATE FLASHBACK ARCHIVE

• ALTER FLASHBACK ARCHIVE

• DROP FLASHBACK ARCHIVE

• CREATE TABLE with a FLASHBACK ARCHIVE clause

• ALTER TABLE with a FLASHBACK ARCHIVE clause

XStream In and Transportable Tablespaces

This section describes how to import data into databases involved in an XStream replication environment using transportable tablespaces.The instructions in this section apply when the following conditions are met:

• The replication configuration is one in which an inbound server applies changes captured by a capture process in an XStream Out configuration.

• The data being imported with transportable tablespaces must be included in each database in the replication environment.

• After the import operation is complete, changes to the imported data will be replicated.

In addition, the rules should instruct the replication environment to avoid replicating tagged LCRs.

When these conditions are met, complete the following steps:

1. Stop replication.

2. Use transportable tablespaces to import the data into each database in the replication environment.

3. Restart replication.

XStream In and a Multitenant Environment

A multitenant environment enables an Oracle database to contain a portable set of schemas, objects, and related structures that appears logically to an application as a separate database. This self-contained collection is called a pluggable database (PDB). A multitenant container database (CDB) contains PDBs. This section assumes that you understand multitenant architecture concepts. See Oracle Database Concepts for information.

In a CDB, the inbound server is restricted to receiving LCRs from one source database and only executing changes in the current container (one PDB or the root). A single inbound server cannot apply changes to more than one container in a CDB.

When the inbound server is in the root, the apply user must be a common user. When the inbound server is in a PDB, the apply user can be a common user or a local user.