SubmitPreCheck|V4.2.4|OceanBase Migration Service|OMS docs|Distributed Database

SubmitPreCheck

Last Updated：2026-04-14 07:36:49 Updated

This topic describes the SubmitPreCheck operation provided by OceanBase Migration Service (OMS).

Purpose

You can call this operation to perform a precheck on a data migration or synchronization task.

Call description

Limitations

This operation is supported in OMS V4.2.2 and later.

Request path

POST /api/v2?Action=SubmitPreCheck

Request parameters

Parameter	Type	Description
name	string	The name of the task, which cannot contain spaces.
projectId	string	The ID of the data migration or synchronization task.
subProject	boolean	Specifies whether to perform precheck for an increase or decrease task.
type	string	The type of the task. Valid values: `MIGRATION` and `SYNC`.
labelIds	array	A collection of label IDs. At most five IDs are supported.
sourceEndpointId	string	The ID of the source data source. You need to call the `ListDataSource` interface to obtain the ID, in the format of e_****.
sinkEndpointId	string	The ID of the destination data source. You need to call the `ListDataSource` interface to obtain the ID, in the format of e_****.
transferMapping	object	The mapping information about the objects to be transferred.
├─ mode	string	The mapping mode for the objects to be transferred. Valid values: `SPECIFIC` and `WILDCARD`.
├─ databases	object []	The list of database objects. For more information, see Parameters in databases/databasesBlack.
├─ databasesBlack	object []	The blocklist of database objects that match the specified rules. For more information, see Parameters in databases/databasesBlack.
├─ tableAndViewWhiteList	array	The allowlist of wildcard tables and views that match the specified rules.
├─ tableAndViewBlackList	array	The blocklist of wildcard tables and views that match the specified rules.
commonTransferConfig	object	The common settings for transfer.
├─ tableCategory	string	The supported table types. Valid values: `ALL` (all tables), `WITH_UNIQUE_ROW_ID` (tables with a unique row ID), and `WITHOUT_UNIQUE_ROW_ID` (tables without a unique row ID). Default value: `ALL`.
├─ activeActive	boolean	Specifies whether the task is for disaster recovery.
├─ mqSerializerType	string	The JSON serialization type when data is delivered to a message queue. Valid values: DEFAULT, CANAL, DATAWORKS_V2, SHAREPLEX, DEFAULT_WITH_SCHEMA, DEBEZIUM, DEBEZIUMFLATTEN, and DEBEZIUMSMT.
├─ mqPartitionMode	string	The partition routing mode when data is delivered to a message queue. Valid values: ONE (specify a partition), HASH (hash partition by primary key or shard column value), and TABLE (hash partition by database and table name).
├─ mqPartition	integer	When `partitionMode` is `ONE`, this parameter specifies the position of the partition in the current topic.
├─ datahubTopicType	string	The type of the topic when data is delivered to a DataHub instance. Valid values: `TUPLE` and `BLOB`.
├─ rocketMqProducerGroup	string	The name of the producer group. This parameter is effective only when the destination is a RocketMQ database. Default value: OMS.
├─ rocketMqMsgTags	string	The message tags. This parameter is effective only when the destination is a RocketMQ database. Default value: default_tag, which indicates that when the value of this parameter is default, _tag is appended to the value.
├─ rocketMqEnableMsgTrace	boolean	Specifies whether to enable message tracing. This parameter is effective only when the destination is a RocketMQ database.
├─ rocketMqSendMsgTimeout	long	The timeout period for sending messages. This parameter is effective only when the destination is a RocketMQ database.
├─ dataWorksBusinessName	string	The name that identifies the business system. This parameter identifies the business system that originates the data so that you can perform custom processing on the data in the future. This parameter is supported only when the serialization method is DataWorks. The length of the value of this parameter must be 1 to 20 characters.
├─ sinkStoreFormat	string	The storage type for table objects in the destination database. Valid values: Default, Row storage, Column storage, and Hybrid columnar storage. This parameter is effective only if the destination is an OceanBase database V4.3.0 or later and the migration type is Schema Migration or Incremental Synchronization > DDL synchronization.
├─ sourceStoreFormat	string	The storage type for table objects in the source database. Valid values: Default, Row storage, Column storage, and Hybrid columnar storage. This parameter is effective only if the source is an OceanBase database V4.3.0 or later and the migration type is Reverse Increment > DDL synchronization.
enableStructTransfer	boolean	Specifies whether to enable schema transfer.
structTransferConfig	object	The settings for schema transfer.
├─ byteCharConvertStrategy	string	The byte/char conversion strategy. Valid values: `IGNORE_BYTE_IF_BYTE_USED`, `FORCE_CHAR_IF_BYTE_USED`, `EXPAND_LEN_IF_BYTE_USED`, and `DO_NOTHING_IF_BYTE_USED` (default).
├─ deferIndexCreation	boolean	Specifies whether to enable index postplacement. Default value: false.
enableFullTransfer	boolean	Specifies whether to enable full transfer.
enableFullVerify	boolean	Specifies whether to enable full verification.
fullTransferConfig	object	The settings for full transfer.
├─ nonePkUkTruncateDstTable	boolean	Specifies whether to truncate the destination table when the source table has no unique key.
├─ allowDestTableNotEmpty	boolean	The processing strategy to apply when the destination table has records. Valid values: Ignore and Stop Migration. If you set the value to true, OMS ignores the existing data in the destination table when writing data to the table. In other words, if a unique key conflict error is returned when data is synchronized from the source table to the destination table, OMS will ignore the data in the source table and reserve the data in the destination table. Notice If you set the value to Ignore, full verification will use IN mode to pull data, which cannot verify scenarios where the destination table contains data not in the source table. The verification performance will also be degraded to some extent. If you set the value to false, migration is stopped. If the destination table has records, an error is returned during full migration. In this case, clear the existing data in the destination table and try again. Notice After an error is returned, if you click Resume in the dialog box, OMS ignores this error and continues to migrate data. Proceed with caution.
├─ fullTransferSpeedMode	string	The concurrent speed for full transfer. Valid values: STEADY, NORMAL, and FAST.
├─ fullVerifySpeedMode	string	The concurrent speed for full verification. Valid values: STEADY, NORMAL, and FAST.
├─ throttleRps	integer	The maximum transfer rate allowed in the full transfer phase, in terms of the number of records per second. Enter null to indicate no limit on RPS.
├─ throttleIOPS	integer	The maximum transfer traffic allowed in the full transfer phase, in terms of bytes per second. Enter null to indicate no limit on IOPS.
enableIncrTransfer	boolean	Specifies whether to enable incremental synchronization.
enableReverseIncrTransfer	boolean	Specifies whether to enable reverse incremental synchronization.
incrTransferConfig	object	The settings for incremental synchronization.
├─ startTimestamp	string	The starting timestamp of incremental synchronization. This parameter is supported only when incremental synchronization is enabled but full transfer is not enabled.
├─ recordTypeWhiteList	array	The types of incremental data to be synchronized when incremental synchronization is enabled. Valid values: HEARTBEAT, INSERT, UPDATE, DELETE, BEGIN, COMMIT, ROLLBACK, DDL, and ROW.
├─ storeLogKeptHour	integer	The retention period of incremental logs when the incremental log puller is a Store component. Unit: hours. Default value: 7. Maximum value: 365.
├─ enableSequencingWithinTxn	boolean	Specifies whether to enable sequence number allocation within a transaction when the incremental log puller is a Store component.
├─ enableIncrSyncStatistics	boolean	Specifies whether to enable statistics collection for incremental records (DML and DDL operations).
├─ incrOnlineDdlConfig	array	The online DDL tool. Valid values: `GH_OST`, `PT_OSC`, and `ALIYUN_DMS`, representing the tools gh-ost, pt-osc, and Alibaba Cloud Data Management Service (DMS), respectively. This parameter is effective only for forward incremental synchronization. If specified, it takes effect on forward incremental synchronization from a MySQL database to a MySQL-compatible tenant of OceanBase Database. This parameter is effective only for reverse incremental synchronization. If specified, it takes effect on reverse incremental synchronization from a MySQL-compatible tenant of OceanBase Database to a MySQL database.
├─ incrSyncConcurrency	integer	The number of threads for incremental synchronization. Default value: 64.
├─ incrLogPullSpeedMode	string	The incremental log pull speed. Valid values: STEADY (low), NORMAL (medium), FAST (high), and CUSTOM (custom).
├─ incrLogPullSpeedConfig	object	The incremental log pull resource configuration. This parameter only takes effect when `incrLogPullSpeedMode` is set to `CUSTOM`.
├─├─ memory	integer	The memory limit for incremental log pull.
├─ incrLogSyncSpeedMode	string	The incremental data write speed. Valid values: STEADY (low), NORMAL (medium), FAST (high), and CUSTOM (custom).
├─ incrLogSyncSpeedConfig	object	The incremental data write resource configuration. This parameter only takes effect when `incrLogSyncSpeedMode` is set to `CUSTOM`.
├─├─ memory	integer	The memory limit for incremental log write.
├─├─ writerWorkerNum	integer	The number of concurrent workers for incremental log write.
├─ throttleRps	integer	The maximum transfer rate allowed in the incremental synchronization phase, in terms of the number of records per second. Enter null to indicate no limit on RPS.
├─ throttleIOPS	integer	The maximum transfer traffic allowed in the incremental synchronization phase, in terms of bytes per second. Enter null to indicate no limit on IOPS.
├─ supportDDLTypes	array	The supported DDL types. CREATE_TABLE ALTER_TABLE DROP_TABLE RENAME_TABLE TRUNCATE_TABLE CREATE_INDEX DROP_INDEX
reverseIncrTransferConfig	object	The settings for reverse incremental synchronization.
├─ startTimestamp	string	The starting timestamp of reverse incremental synchronization. This parameter is supported only when incremental synchronization is enabled but full transfer is not enabled.
├─ recordTypeWhiteList	array	The types of incremental data to be synchronized when reverse incremental synchronization is enabled. Valid values: HEARTBEAT, INSERT, UPDATE, DELETE, BEGIN, COMMIT, ROLLBACK, DDL, and ROW.
├─ storeLogKeptHour	integer	The retention period of incremental logs when the incremental log puller is a Store component and reverse incremental synchronization is enabled. Unit: hours. Default value: 7. Maximum value: 365.
├─ enableSequencingWithinTxn	boolean	Specifies whether to enable sequence number allocation within a transaction when the incremental log puller is a Store component and reverse incremental synchronization is enabled.
├─ enableIncrSyncStatistics	boolean	Specifies whether to enable statistics collection for incremental records (DML and DDL operations).
├─ incrOnlineDdlConfig	array	The online DDL tool. Valid values: `GH_OST`, `PT_OSC`, and `ALIYUN_DMS`, representing the tools gh-ost, pt-osc, and Alibaba Cloud Data Management Service (DMS), respectively. This parameter is effective only for forward incremental synchronization. If specified, it takes effect on forward incremental synchronization from a MySQL database to a MySQL-compatible tenant of OceanBase Database. This parameter is effective only for reverse incremental synchronization. If specified, it takes effect on reverse incremental synchronization from a MySQL-compatible tenant of OceanBase Database to a MySQL database.
├─ incrSyncConcurrency	integer	The number of threads for reverse incremental synchronization. Default value: 64.
├─ incrLogPullSpeedMode	string	The incremental log pull speed. Valid values: STEADY (low), NORMAL (medium), FAST (high), and CUSTOM (custom).
├─ incrLogPullSpeedConfig	object	The incremental log pull resource configuration. This parameter only takes effect when `incrLogPullSpeedMode` is set to `CUSTOM`.
├─├─ memory	integer	The memory limit for incremental log pull.
├─ incrLogSyncSpeedMode	string	The incremental data write speed. Valid values: STEADY (low), NORMAL (medium), FAST (high), and CUSTOM (custom).
├─ incrLogSyncSpeedConfig	object	The incremental data write resource configuration. This parameter only takes effect when `incrLogSyncSpeedMode` is set to `CUSTOM`.
├─├─ memory	integer	The memory limit for incremental log write.
├─├─ writerWorkerNum	integer	The number of concurrent workers for incremental log write.
├─ throttleRps	integer	The maximum transfer rate allowed in the reverse incremental synchronization phase, in terms of the number of records per second. Enter null to indicate no limit on RPS.
├─ throttleIOPS	integer	The maximum transfer traffic allowed in the reverse incremental synchronization phase, in terms of bytes per second. Enter null to indicate no limit on IOPS.
├─ supportDDLTypes	array	The supported DDL types. CREATE_TABLE ALTER_TABLE DROP_TABLE RENAME_TABLE TRUNCATE_TABLE CREATE_INDEX DROP_INDEX

Parameters in databases/databasesBlack

Parameter	Type	Description
mappedName	string	The name of the destination database.
name	string	The name of the source database.
id	string	The ID of the database.
tables	array	The configurations of table objects to be transferred in the current database. When the value of the `mode` parameter is `WILDCARD`, this parameter indicates the configurations of a specific blocklist or allowlist of tables and views.
├─ mappedName	string	The mapped name of the table.
├─ name	string	The name of the table.
├─ id	string	The ID of the table.
├─ whereClause	string	The `WHERE` clause in the standard SQL statement for configuring row filtering.
├─ filterColumns	array	The filtered column set.
├─ shardColumns	array	The shard column set.
views	array	The configurations of view objects to be transferred in the current database.
├─ mappedName	string	The mapped name of the view.
├─ name	string	The name of the view.
├─ id	string	The ID of the view.
├─ whereClause	string	The `WHERE` clause in the standard SQL statement for configuring row filtering.
├─ filterColumns	array	The filtered column set.
├─ shardColumns	array	The shard column set.
specificTables	array	The configurations of specific table objects. When the value of the `mode` parameter is `WILDCARD`, this parameter indicates the renaming configurations and row filtering settings for specific table objects.
├─ mappedName	string	The mapped name of the table.
├─ name	string	The name of the table.
├─ id	string	The ID of the table.
├─ whereClause	string	The `WHERE` clause in the standard SQL statement for configuring row filtering.
├─ filterColumns	array	The filtered column set.
├─ shardColumns	array	The shard column set.
specificViews	array	The configurations of specific view objects. When the value of the `mode` parameter is `WILDCARD`, this parameter indicates the renaming settings for specific view objects.
├─ mappedName	string	The mapped name of the view.
├─ name	string	The name of the view.
├─ id	string	The ID of the view.
├─ whereClause	string	The `WHERE` clause in the standard SQL statement for configuring row filtering.
├─ filterColumns	array	The filtered column set.
├─ shardColumns	array	The shard column set.

Response parameters

Parameter	Type	Description
success	boolean	Indicates whether the call is successful.
errorDetail	object	The error details.
code	string	The error code.
message	string	The error description.
advice	string	The suggestions.
requestId	string	The ID of the request.
pageNumber	integer	The number of the page returned, which takes effect in a pagination query.
pageSize	integer	The number of entries returned on each page, which takes effect in a pagination query.
totalCount	integer	The total number of pages returned, which takes effect in a pagination query.
cost	string	The time spent in processing the request, in seconds.
data	string	The ID of the precheck task.

Examples

Sample request

{
    "name":"test",
    "projectId":"np_4w3a****",
    "subProject": false,
    "type":"MIGRATION",
    "labelIds":[
        "l_4w****wygjk"
    ],
    "sourceEndpointId":"e_4wg07f****",
    "sinkEndpointId":"e_4wfy2****",
    "transferMapping":{
        "mode":"SPECIFIC",
        "databases":[
            {
                "mappedName":"gez3***",
                "name":"ion1****bmysql",
                "id":null,
                "tables":[
                    {
                        "mappedName":"tion12***20obmysql2",
                        "name":"GRATION129****",
                        "id":null,
                        "whereClause":null,
                        "filterColumns":null,
                        "shardColumns":null,
                    }
                ],
                "views":null,
                "specificTables":null,
                "specificViews":null
            }
        ],
        "databasesBlack":null,
        "tableAndViewWhiteList":null,
        "tableAndViewBlackList":null
    },
    "commonTransferConfig":{
        "tableCategory":null,
        "activeActive":false,
        "mqSerializerType":null,
        "mqPartitionMode":null,
        "mqPartition":0,
        "datahubTopicType":null,
        "rocketMqProducerGroup":null,
        "rocketMqMsgTags":null,
        "rocketMqEnableMsgTrace":null,
        "rocketMqSendMsgTimeout":null,
        "dataWorksBusinessName":null
    },
    "enableStructTransfer":true,
    "structTransferConfig":{
        "byteCharConvertStrategy":"DO_NOTHING_IF_BYTE_USED",
        "deferIndexCreation":true
    },
    "enableFullTransfer":true,
    "enableFullVerify":true,
    "fullTransferConfig":{
        "nonePkUkTruncateDstTable":null,
        "allowDestTableNotEmpty":true,
        "throttleRps": 1000,
        "throttleIOPS": 1000,
        "fullTransferSpeedMode":"NORMAL",
        "fullVerifySpeedMode":"NORMAL"     
    },
    "enableIncrTransfer":true,
    "enableReverseIncrTransfer":true,
    "incrTransferConfig":{
        "startTimestamp":1689201369,
        "storeLogKeptHour":120,
        "recordTypeWhiteList":[
            "DELETE",
            "INSERT",
            "UPDATE"
        ],
        "enableSequencingWithinTxn":true,
        "incrSyncConcurrency":64,
        "incrLogPullSpeedMode":"NORMAL",
        "incrLogPullSpeedConfig":{
            "memory":4
            },
        "incrLogSyncSpeedMode":"CUSTOM",
        "incrLogSyncSpeedConfig":{
            "memory":4,
            "writerWorkerNum":2
            },
        "throttleRps": 1000,
        "throttleIOPS": 1000,
        "enableIncrSyncStatistics":true,
        "supportDDLTypes":[
            "CREATE_TABLE",
            "ALTER_TABLE"
        ],
        "incrOnlineDdlConfig":[
          "GH_OST",
          "PT_OSC",
          "ALIYUN_DMS"
        ]
    },
    "ReverseIncrTransferConfig":{
        "startTimestamp":1689201369,
        "recordTypeWhiteList":[
            "DELETE",
            "INSERT",
            "UPDATE"
        ],
        "storeLogKeptHour":120,
        "incrSyncConcurrency":64,
        "incrLogPullSpeedMode":"NORMAL",
        "incrLogPullSpeedConfig":{
            "memory":4
            },
        "incrLogSyncSpeedMode":"CUSTOM",
        "incrLogSyncSpeedConfig":{
            "memory":4,
            "writerWorkerNum":2
            },
        "throttleRps": 1000,
        "throttleIOPS": 1000,
        "enableIncrSyncStatistics":true,
        "supportDDLTypes":[
            "CREATE_TABLE",
            "ALTER_TABLE"
        ]
    }
}

Sample response

{
    "success": true,
    "errorDetail": null,
    "code": null,
    "message": null,
    "advice": null,
    "requestId": "bf2-9bc9-****",
    "pageNumber": null,
    "pageSize": null,
    "totalCount": null,
    "cost": "269 ms",
    "data": "t_57p****"
}

Customer Stories

Documentation

Enterprise Edition

Community Edition