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

Prepare Capture Process

The prepare command creates a Capture Process. It only stores the configuration: Repstance does not connect to the Source Database and does not start to capture the tables until the process is run (see Run any Capture or Apply Processes). With autostart=1 the process is run as soon as it is created. The rules that all the configuration commands share, the id, the name, 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 and the connection parameters can be added later with Alter Process, but the process cannot run without them: use Validate Process to see what is missing.

Command line (repcli)

repcli prepare process=capture id=captureID \
dbtype={mssql|oracle|mysql|postgresql} \
name=captureName \
[connection parameters of the Source Database] \
autostart={0|1} \
dmlinclude=objectsMask dmlexclude=objectsMask \
ddlinclude=objectsMask ddlexclude=objectsMask \
loadinclude=objectsMask loadexclude=objectsMask \
map=mapID,mappingClause \
skiploopback=skipLoopbackMask \
[other parameters] preview={0|1}

Parameter	Description
process	capture. Required.
id	The number of the process, from 1 to 99999. It is unique among the Capture Processes and it cannot be changed. Required.
dbtype	The type of the Source Database: mssql, oracle, mysql or postgresql (MySQL and PostgreSQL since version 6, in Repstance Advanced Edition only). Required.
name	The name of the process: letters, digits, _ and -. It is unique, it is the prefix of the trail files and the Apply Processes name it with capturename. It cannot be changed once it is set.
server, port, user, password, dbname and the other connection parameters	The connection to the Source Database. They are different for every type of database. For MySQL and PostgreSQL (since version 6, in Repstance Advanced Edition only) see MySQL Capture Parameters and PostgreSQL Capture Parameters; for SQL Server and for Oracle see SQL Server Capture Parameters and Oracle Capture Parameters.
autostart	1 runs the process when it is created and every time the Repstance service starts. The default is 0.
dmlinclude, dmlexclude	The tables whose data changes are captured, and the tables that are left out. See Capture Objects Specification.
ddlinclude, ddlexclude	The tables whose DDL statements are captured, and the tables that are left out. See Capture Objects Specification.
loadinclude, loadexclude	The tables that are copied in full when the process is run for the first time (Initial Load). See Initial Load.
map=mapID,mappingClause	A transformation rule that is applied to all the Apply Processes of the Capture Process. See Objects Mapping and Possible Transforms.
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 all.
debuglevel and the other parameters	The detail of the log, the notification, the restart attempts and the rest are listed with their defaults on MySQL Capture Parameters, PostgreSQL Capture Parameters, SQL Server Capture Parameters and Oracle Capture Parameters.
preview	1 lists the tables that the settings select and saves nothing, see Alter Process.

Create a Capture Process for a SQL Server database that extracts the DML and DDL changes of all the tables of the schema dbo:

repcli prepare process=capture id=2 dbtype=mssql name=SQLServerCap2 server=db-src.example.com port=1433 user=repuser password=Passw0rd123 dbname=testDB dmlinclude=dbo.% ddlinclude=dbo.%
[Completed]: Capture 2 has been added

The new process is not running, its state is INITIALISED (see Status of any Capture or Apply Processes):

repcli status process=capture id=2
Capture Process 2, Name: SQLServerCap2, DB: testDB, Server: db-src.example.com
  INITIALISED (Completed), Waiting for the Next Command

Create a Capture Process for an Oracle database that extracts the DML changes of the schema scott by reading the log files through the database directory (directlogmode=1):

repcli prepare process=capture id=3 dbtype=oracle name=ORACap3 connectiontype=ezconnect server=ora-src.example.com port=1521 servicename=ORA1 user=scott password=tiger dmlinclude=scott.% directlogmode=1
[Completed]: Capture 3 has been added

Create a Capture Process for a MySQL database (since version 6, in Repstance Advanced Edition only) that extracts the DML and DDL changes of the database sales and copies its tables at the first start:

repcli prepare process=capture id=11 dbtype=mysql name=MySQLCap11 server=mysql-src.example.com port=3306 user=repuser password=Passw0rd123 dmlinclude=sales.% ddlinclude=sales.% loadinclude=sales.%:C
[Completed]: Capture 11 has been added

Create a Capture Process for a PostgreSQL database (since version 6, in Repstance Advanced Edition only). The parameter dbname is required:

repcli prepare process=capture id=12 dbtype=postgresql name=PGCap12 server=pg-src.example.com port=5432 dbname=salesdb user=repuser password=Passw0rd123 dmlinclude=public.% ddlinclude=public.%
[Completed]: Capture 12 has been added

The command is refused when the id or the name is in use, when the type of the database is missing or when a parameter is wrong:

repcli prepare process=capture id=2 dbtype=mssql name=Another
[Failed]: Process id=2 already exists

repcli prepare process=capture id=7 dbtype=mssql name=SQLServerCap2
[Failed]: [SQLServerCap2] is already user by 2 capture

repcli prepare process=capture id=7
[Failed]: Missed dbtype parameter
  Valid values: mssql | oracle | mysql | postgresql | redshift | snowflake | s3 | kafka

repcli prepare process=capture id=7 dbtype=mssql name=Cap7 port=70000
[Failed]: An invalid value [70000] has been supplied for parameter [port].
  port                   TCP port of the source SQL Server. [1-65535; default 1433]

REST API

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

The body of the request:

{
  "command": "prepare",
  "parameters": [
    ["process", "capture"],
    ["id", "2"],
    ["dbtype", "mssql"],
    ["name", "SQLServerCap2"],
    ["server", "db-src.example.com"],
    ["port", "1433"],
    ["user", "repuser"],
    ["password", "Passw0rd123"],
    ["dbname", "testDB"],
    ["dmlinclude", "dbo.%"],
    ["ddlinclude", "dbo.%"]
  ]
}

A transformation rule is one pair whose name carries the id of the rule: ["map=1", "rule=(dbo.%:report.%),description=\"sample 1\""]. The body of the answer:

{
  "Status": "Completed",
  "Message": "Capture 2 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).
Nothing is created or changed in the Source Database. The database is prepared with prepare database (see Prepare Source Database), and the Capture Process creates what it needs for the tables when it is run for the first time (see Run any Capture or Apply Processes).
The command checks the parameters, not the database: a wrong password or a server that cannot be reached is found by Validate Process or when the process is run.

Web UI

Click “Add Capture” on the dashboard. The form “Capture Process Configuration” asks for the id, the name and the options of the process (notification, debug level and autostart); “Database Settings” holds the connection to the Source Database, “Replication Object Settings” and “Transformation Rules” the tables and the rules, and “Advanced Settings” the parameters that are not on the form. The steps are shown in Setup First Replication, the form in Edit Replication Processes and the choice of the tables in the Replication Object Wizard.

PROCESS CONFIGURATION COMMANDS

SQL Server Capture Parameters