Chat now with support
Chat with Support

SharePlex 8.6.6 - Administration Guide

About this Guide Conventions used in this guide Overview of SharePlex Run SharePlex Run multiple instances of SharePlex Execute commands in sp_ctrl SharePlex parameters Prepare an Oracle environment for replication Create a configuration file Configure replication to Open Target targets Configure a replication strategy Configure partitioned replication Configure named queues Configure SharePlex to maintain a change history target Replicate Oracle DDL Set up error handling Transform data Configure SharePlex security features Activate replication in your production environment Monitor SharePlex Prevent and solve replication problems Repair out-of-sync Data Procedures to maintain Oracle high availability Make changes to an active replication environment Apply an Oracle application patch or upgrade Back up Oracle data on the source or target Tune the Capture process Tune the Post process Appendix A: Peer-To-Peer Diagram Appendix B: SharePlex environment variables

How to create a configuration file

Create a configuration file > How to create a configuration file

To configure SharePlex to replicate data, you create a configuration file. This is an ASCII text file in which you specify:

  • The data that you want SharePlex to replicate, including any filtering or partitioning of rows or columns
  • The target name and type
  • The system (and database if applicable) to which the data must be delivered.

Only a SharePlex Administrator or operator has the authority to create a configuration file.

When your configuration file is completed and the SharePlex environment is set up to support your replication objectives, you activate the configuration with the activate config command to begin replication. For more information, see Activate replication in your production environment.

Create a configuration file

You can create a configuration file by hand or, if your data structure supports it, you can automate the creation of a configuration file. For more information, see Build a configuration file using a script.

Create the configuration file on the system from which data is to be replicated, typically the source system, but strategies such as active-active replication require configuration files on more than one system.

To create a configuration file

  1. Run sp_ctrl from the bin sub-directory of the SharePlex product directory.
  2. In sp_ctrl, issue the create config command.

    sp_ctrl> create config config_name

    This command opens a file in the default text editor that is set for the operating system. Note: You can change the default editor that sp_ctrl uses. For more information, see Set a default editor for sp_ctrl.

  3. Complete the configuration file. For more information, see Structure of a configuration file.

    Important! All configurations must reside in the config sub-directory of the SharePlex variable-data directory. Configuration files outside this directory cannot be activated. SharePlex places configurations in this directory by default when you create them through the sp_ctrl interface with the create config command. If you create the configuration directly through a text editor, make certain to save it to the config sub-directory.

Structure of a configuration file

A basic configuration file looks like the following:

# comment: basic SharePlex configuration file

datasource_specification

#source specification

target specification

routing map

source_owner.object1

target_owner.object1

routing_map

source_owner.object2

target_owner.object2

routing_map

source_owner.object3

target_owner.object3

routing_map

The basic components of a configuration file are as follows. For advanced configuration options, see Additional configuration options

Component Description Syntax examples
# Comments Lines that describe the file or provide other information about the contents to viewers, but are not used by SharePlex. Precede each comment line with a pound (#) sign. Comments may be entered anywhere in the configuration file. # This is a comment.
Datasource specification

Syntax that specifies the source database. This component must always be the first non-commented line of a configuration file. It has the following syntax elements, all on the same line with no spaces:

Datasource:o.SID

Source specification

The fully qualified name of a supported source object, in the form of owner.object, or a wildcard substitution that specifies multiple source objects.

See Use Wildcards to specify multiple objects for more information about using wildcards.

src_owner.table

src_owner.sequence

Target specification

The target to which the replicated data is applied. Targets supported by SharePlex are:

  • A table in a relational database, or a wildcard substitution for multiple tables.
  • An Oracle sequence (or wildcard specification).
  • A file that contains XML or SQL records.
  • A JMS queue or topic.
  • A Kafka topic.
  • A change-history table that maintains a record of all changes made to a source table (also known as change data capture)

For more information, see Target specifications in a configuration file.

tgt_owner.table

tgt_owner.sequence

!file[:tgt_owner.table]

!jms[:tgt_owner.table]

!kafka[:tgt_owner.table]

!cdc:tgt_owner.table

Routing map

One or more routes that send the data to the system that contains the target object specified with the target specification. A route consists of the following:

host@o.SID

host@o.PDBalias

host@o.tns_alias

host@r.database_name

host

host@c.SID

Compound routing map:

host@o.SID+host@r.database[...]

Additional configuration options

The following are additional configuration options that can be added to the configuration file:

Option Where to look
Prevent INSERTs, UPDATEs, or DELETEs from being replicated, or prevent sequences and materialized views from being replicated Filter DML operations
Map a source column to a target column Map source and target columns
Define a key for SharePlex to use Define a unique key
Divide, parallelize, and filter data to meet specific requirements Configure partitioned replication
Divide and parallelize data for increased control and throughput Configure named queues

Database specifications in a configuration file

Create a configuration file > Database specifications in a configuration file

A database specification is required in the following components of the configuration file:

  • the datasource (source data store) specification
  • routing map (target data store and location) specification
Database Database type notation* Database Identifiers
Oracle source or target

o.

Depending on the Oracle database configuration, use one of the following. This is the string that SharePlex will use to connect to the database.

  • The Oracle SID of a regular (non-CDB) Oracle database, as in o.ora12.
  • The tns_alias of a pluggable database (PDB) in an Oracle container database (CDB), as in o.pdb1.
  • The global tns_alias of an Oracle RAC cluster, as in o.rac1. SharePlex connects to an Oracle RAC instance through this tns_alias, which is mapped locally on each node to the Oracle SID of the local Oracle instance. For more information about creating this alias, see Configure SharePlex in a Cluster in the SharePlex Installation Guide.

Open Target targets

r.

Use to specify the name of an Open Target (non-Oracle) target database, as in r.mydb. Important! Use the actual database name. Do not use the ODBC datasource name (DNS) or database instance name. If the database name is case-sensitive, specify it that way.

For more information about configuring SharePlex to replicate to a specific Open Target target, see Configure replication to Open Target targets.

Oracle change-history target c.

Use in a routing map to specify the Oracle SID, tns_alias, or global RAC tns_alias of an Oracle change history database, as in c.ORA12CH. In this configuration, SharePlex applies all source transactions as INSERTs to the target tables, to maintain a history of every operation performed.

For more information, see Configure replication to maintain a change history target.

* Note: The dot is required.

Target specifications in a configuration file

Create a configuration file > Target specifications in a configuration file

The following table shows how to specify a target table or non-table target in a configuration file.

Target Target Specification Description
Database table tgt_owner.table

The fully qualified name of a database table.

Database sequence

tgt_owner.sequence

The fully qualified name of a sequence.

File !file[:tgt_owner.table]

The !file designator directs Post to write change operations to a file in SQL or SML format. The file name is applied internally by SharePlex.

Optionally, you can specify the fully qualified name of a target table if the data will be consumed by a process that ultimately applies it to a database table.

See Configure Replication to a SQL or XML file target.

JMS !jms[:tgt_owner.table]

The !jms designator directs Post to write change operations to a JMS queue or topic in XML format. The queue or topic name can be defined by using the target command.

Optionally, you can specify the fully qualified name of a target table if the data will be consumed by a process that ultimately applies it to a database table.

See Configure Replication to a JMS target.

Kafka

!kafka[:tgt_owner.table]

The !Kafka designator directs Post to write change operations to a Kafka topic in XML format. The topic name can be defined by using the target command.

Optionally, you can specify the fully qualified name of a target table if the data will be consumed by a process that ultimately applies it to a database table.

See Configure Replication to a Kafka target.

Change history table

!cdc:tgt_owner.table

The !cdc designator directs Post to insert every data change to the table as a new row, rather than overlay the old data with new data. Specify the fully qualified name of the change history table.

See Configure replication to maintain a change history target.

Routing specifications in a configuration file

Create a configuration file > Routing specifications in a configuration file

The following instructions show you how to build a routing map. A routing map sends replicated data to the correct target on the correct target system.

Replicate to one target

A simple routing map sends replicated data from one source object to one target object.

datasource_specification
src_owner.table tgt_owner.table2 host2[@database_specification]
src_owner.table tgt_owner.table3 host3[@database_specification]

Replicate to multiple targets

A compound routing map sends replicated data from one source object to multiple target objects. It enables you to specify the source and target objects once for all routes, rather than type a separate configuration entry for each route. Only one target specification can be used in a compound routing map, so all of the target objects must be identical as follows:

  • All one type: All the same database object type or all a JMS queue or all a JMS topic or all a Kafka topic, or all a file (but no combination of these).
  • All with the same fully qualified name, including any table specifications in a JMS, Kafka, or file target specification.
  • All having identical column or key mappings, if used (see Define a unique key and Map source and target columns).

NoteS:

  • Certain routing limitations apply when using vertically partitioned replication. See Configure vertically partitioned replication.
  • If any target has a different qualified name from the other targets of the same source object, you must use a simple routing map for that target.
datasource_specification
src_owner.table tgt_owner.table

host1[@database_specification]+host2[@database_specification][...]

Replicate between objects on the same system

You can replicate between objects that are in the same database or in different databases on the same system. You can replicate between objects that have the same name, so long as their owners are different.

When SharePlex replicates between objects on the same system, it does not create Import and Export processes. You can force SharePlex to create Import and Export processes by using the following routing map. If you do not need the Import or Export processes, omit the host* portion of the routing map.

Configuration with replication to objects in the same or different database on the same system
datasource_specification
src_owner.table tgt_owner.table

host*host[@database_specification]

Routing Limitations

  • By default, SharePlex supports replication to a maximum of 19 direct target systems. That is the maximum number of processes that can read the export queue. To replicate to more than 19 targets, use named export queues. With each additional queue that you add, you can replicate to 19 additional targets. See Configure named export queues.
  • Each instance of sp_cop on a system permits a maximum of 1024 different routes. This limitation includes each route that uses a different named post queue (see Configure named post queues.) If your replication strategy requires more than 1024 routes, consider using one or more intermediary systems to divide the routes among multiple sp_cop instances. See Configure replication to share or distribute data).
  • By default, each sp_cop instance allows a total of 25 queues on a system. There will always be one capture queue on a source system and one post queue on a target. Therefore, you can have as many as 24 named export queues on a source system and 24 named post queues on a target system. If a system serves as both a source and target, you will have both a capture queue and a post queue. That allows you to create up to 23 named queues of either type (or a mix of both). If system memory permits, you can change the number of allowed queues by setting the SP_QUE_MAX_QUEUES parameter. See the SharePlex Reference Guide for more information about this parameter.
Related Documents