Home / Repstance User Guide / PROCESS CONFIGURATION COMMANDS / Prepare Apply Process

Prepare Apply Process

The prepare command creates an Apply Process. It only stores the configuration: it does not connect to the Target Database, does not look for the Capture Process or its trail files, and nothing is applied until the process is run (see Run any Capture or Apply Processes). To find out whether the process can run use Validate Process. The rules that all the configuration commands share, the id, the parameters of the database and the messages, are on PROCESS CONFIGURATION COMMANDS.

Only process, id and dbtype are needed to create the process. The name of the Capture Process and the connection parameters can be added later with Alter Process, but the process cannot run without them.

Command line (repcli)

repcli prepare process=apply id=applyID \
dbtype={mssql|oracle|postgresql|mysql|snowflake|redshift|s3} \
capturename=captureName \
[connection parameters of the Target Database] \
autostart={0|1} \
ddlprocessing={native|dictionary|map} \
ddlcreate=objectMask:options \
ddldrop=objectMask:options \
map=mapID,mappingClause \
filter=filterID,rule=(filterRule) \
skiploopback=skipLoopbackMask \
[other parameters] preview={0|1}

Parameter	Description
process	apply. Required.
id	The number of the process, from 1 to 99999. It is unique among the Apply Processes and it cannot be changed. Required.
dbtype	The type of the Target Database: mssql, oracle, postgresql, mysql, snowflake, redshift or s3. Required.
capturename	The name of the Capture Process whose trail files the process reads. It cannot be changed once it is set.
server, port, user, password, dbname and the other connection parameters	The connection to the Target Database. They depend on the database: SQL Server Apply Parameters, Oracle Apply Parameters, PostgreSQL Apply Parameters, MySQL Apply Parameters, Snowflake Apply Parameters, Redshift Apply Parameters and AWS S3 Apply Parameters.
autostart	1 runs the process when it is created and every time the Repstance service starts. The default is 0.
ddlprocessing	How a replicated DDL statement is carried out: native takes the text of the Source Database, dictionary rebuilds the statement for the Target Database and map also applies the transformation rules. The default is native for SQL Server and Oracle and dictionary for the other databases.
ddlcreate	What to do with a replicated CREATE TABLE for the tables that match a mask: skip it when the table exists, or recreate the table. For example dbo.%:skip.
ddldrop	Replays a replicated DROP TABLE for the tables that match a mask only if the table exists in the Target Database, without an error when it is gone already. For example dbo.%:skip.
map=mapID,mappingClause	A local transformation rule of this Apply Process. See Objects Mapping and Possible Transforms.
filter=filterID,rule=(…)	A filter that skips operations or rows. See Objects Filtering.
skiploopback	Skips the changes that Apply Processes of Repstance have made, so that a two-way replication does not loop: all, none or the ids of the Apply Processes. The default is none.
cleanuptrail	How long the trail files are kept after they have been applied: 0 deletes them at once (the default), a number keeps them that many days, -1 never deletes them. An incremental data comparison reads the changes from these files and fails if they have been deleted, so keep them longer than the time between two comparisons (see Data Comparison).
restartattempts, notification, debuglevel and the other parameters	The automatic restarts of a failed process, the e-mail channels, the detail of the log and the rest are listed with their defaults on the pages of the parameters.
preview	1 lists the tables and the rules that the settings give and saves nothing, see Alter Process.

Create an Apply Process for a SQL Server database that reads the trail files of the Capture Process SQLServerCap2:

repcli prepare process=apply id=2 dbtype=mssql capturename=SQLServerCap2 server=db-tgt.example.com port=1433 user=repuser password=Passw0rd123 dbname=testDB
[Completed]: Apply 2 has been added

Create an Apply Process for an Oracle database that reads the trail files of the Capture Process ORACap3:

repcli prepare process=apply id=3 dbtype=oracle capturename=ORACap3 connectiontype=ezconnect server=ora-tgt.example.com port=1521 servicename=ORA1 user=scott password=tiger
[Completed]: Apply 3 has been added

Create an Apply Process for a PostgreSQL database that reads the trail files of SQLServerCap2 and renames the schema dbo to public. ddlprocessing=map makes the rule work for the DDL statements and for the Initial Load too:

repcli prepare process=apply id=4 dbtype=postgresql capturename=SQLServerCap2 server=pg-tgt.example.com port=5432 user=repuser password=Passw0rd123 dbname=testDB ddlprocessing=map map=1,rule=(dbo.%:public.%)
[Completed]: Apply 4 has been added

Create an Apply Process for Snowflake that reads the trail files of SQLServerCap2 and renames the schema dbo to sqldata:

repcli prepare process=apply id=5 dbtype=snowflake capturename=SQLServerCap2 account=ab12345 warehouse=DEMO_WH dbname=DWH region=eu-west-2.aws user=repuser password=Passw0rd123 ddlprocessing=map map=1,rule=(dbo.%:sqldata.%)

Create an Apply Process for Amazon S3 that reads the trail files of ORACap3:

repcli prepare process=apply id=6 dbtype=s3 capturename=ORACap3 s3.accessKeyID=ACCESS_KEY_ID s3.secretAccessKey=SECRET_ACCESS_KEY s3.bucketname=ora2s3

A parameter of another database is refused, and the answer lists the parameters that can be used:

repcli prepare process=apply id=9 dbtype=mssql capturename=SQLServerCap2 s3.bucketname=mybucket
[Failed]: An invalid parameter [s3.bucketname] has been supplied. It is a parameter of redshift, s3, not of mssql.
Valid parameters for an apply process, target database mssql:
  ...

REST API

Endpoint: https://repstance_url/configure/process
Method: POST
Header: Content-Type: application/json and X-Token: token

The body of the request. A transformation rule or a filter is one pair whose name carries its id, for example ["map=1", "rule=(dbo.%:public.%)"] or ["filter=1", "rule=(scott.logs;DELETE;\"\")"]:

{
  "command": "prepare",
  "parameters": [
    ["process", "apply"],
    ["id", "4"],
    ["dbtype", "postgresql"],
    ["capturename", "SQLServerCap2"],
    ["server", "pg-tgt.example.com"],
    ["port", "5432"],
    ["user", "repuser"],
    ["password", "Passw0rd123"],
    ["dbname", "testDB"],
    ["ddlprocessing", "map"],
    ["map=1", "rule=(dbo.%:public.%)"]
  ]
}

The body of the answer has the status and the message, for example {"Status": "Completed", "Message": "Apply 4 has been added"}.

HTTP code	Meaning
200	The request is valid and has been processed. The body has the status Completed and the message; for validate the status is Valid or Invalid.
401	The token is invalid.
422	The request is invalid or cannot be carried out: the JSON, the command, a parameter or the id of the process is wrong, or the process is running (remove). The body has the status Failed and the message.

What happens

The configuration is stored on the Repstance server and the process is initialised. Until it is run its state is INITIALISED (Completed).
The command checks the parameters, not the database, the Capture Process or the trail files. Use Validate Process to check that the process can run.
When the process is run for the first time it starts with the first transaction in the trail files of its Capture Process. To start from another transaction use reset (see Reset Process).

Web UI

Click “Add Apply” on the dashboard. The form “Apply Process Configuration” asks for the id, the name of the Capture Process and the options of the process (notification, debug level and autostart); “Database Settings” holds the connection to the Target Database. The tab “Process Parameters” has the fields of the most used parameters, for example “Cleanup Trail Files” (cleanuptrail), “DDL mapping” (ddlprocessing) and “Restart Attempts” (restartattempts), “Transformation Rules” holds the rules and “Data Filter” the filters. The parameters that are not on the form are entered in “Advanced Settings”. The steps are shown in Setup First Replication, the form in Edit Replication Processes and the rules in the Replication Object Wizard.

Initial Load

SQL Server Apply Parameters