Command-line options

• --ctl-path ' control_path '

  The absolute path for storing control files on the local disk. You can configure built-in preprocessing functions in a control file. Data will be preprocessed by these functions before being exported. For example, the functions can perform case conversion and check the data for empty values. For the use of control files, see Data processing. When you specify this option on the command line, enclose the value in single quotation marks (' '), for example, --ctl-path '/home/controls/'.
  
  

• --log-path ' log_path '

  The output directory for the operational logs of OBDUMPER. If this option is not specified, OBDUMPER operational logs are stored in the directory specified by the -f option. Redirection is not required for log output, unless otherwise specified.
  
  

• --no-nested-dir

  Exports all files to the directory specified by the -f or --storage-uri option without generating nested subdirectories.

Other options

• -H, --help

  Shows the help information of the tool.
  
  

• -V, --version

  Shows the version of the tool.

Advanced options

Feature options

Timestamp format

• --flashback-timestamp ' timestamp_string '

  Exports data after a flashback point in time. This option can only be used in combination with a data format option and cannot be used in combination with the --query-sql option. This option is supported only for OceanBase Database in Oracle mode.
  
  

• --nls-date-format ' date-format-string '

  The nls_date_format session variable in Oracle mode of OceanBase Database. This option does not indicate to export data of the DATE data type in the specified format. Default value: YYYY-MM-DD HH24:MI:SS.
  
  

• --nls-timestamp-format ' timestamp-format-string '

  The nls_timestamp_format session variable in Oracle mode of OceanBase Database. This option does not indicate to export data of the TIMESTAMP data type in the specified format. Default value: YYYY-MM-DD HH24:MI:SS:FF9.
  
  

• --nls-timestamp-tz-format ' timestamp-tz-format-string '

  The nls_timestamp_tz_format session variable in Oracle mode of OceanBase Database. This option does not indicate to export data of the TIMESTAMP WITH TIME ZONE data type in the specified format. Default value: YYYY-MM-DD HH24:MI:SS:FF9 TZR.

• --date-value-format

  The export format of the DATE data type. By default, data of the DATE type is exported in the yyyy-MM-dd format in MySQL mode of OceanBase Database and in the yyyy-MM-dd HH:mm:ss format in Oracle mode of OceanBase Database.

  Note

  • This option can be used only in combination with the --cut or --csv option.
  • In MySQL mode of OceanBase Database, you cannot specify this option when the DATE value is zero.

• --time-value-format

  The export format of the TIME data type. By default, data of the TIME type is exported in the HH:mm:ss format in MySQL mode of OceanBase Database. The precision is the same as that in the table definition.

  Note

  • This option can be used only in combination with the --cut or --csv option.
  • In MySQL mode of OceanBase Database, you cannot specify this option when the TIME value is zero.

• --datetime-value-format

  The export format of the DATETIME data type. By default, data of the DATETIME type is exported in the yyyy-MM-dd HH:mm:ss format in MySQL mode of OceanBase Database. The precision is the same as that in the table definition.

  Note

  • This option can be used only in combination with the --cut or --csv option.
  • In MySQL mode of OceanBase Database, you cannot specify this option when the DATETIME value is zero.

• --timestamp-value-format

  The export format of the TIMESTAMP data type. By default, data of the TIMESTAMP type is exported in the yyyy-MM-dd HH:mm:ss.SSSSSS format in MySQL and Oracle modes of OceanBase Database. The precision is the same as that in the table definition.

  Note

  • This option can be used only in combination with the --cut or --csv option.
  • In MySQL mode of OceanBase Database, you cannot specify this option when the TIMESTAMP value is zero.

• --timestamp-tz-value-format

  The export format of the TIMESTAMP WITH TIME ZONE data type. By default, data of the TIMESTAMP WITH TIME ZONE type is exported in the yyyy-MM-dd HH:mm:ss.SSSSSS format in Oracle mode of OceanBase Database. The precision is the same as that in the table definition.

  Note

  This option can be used only in combination with the --cut or --csv option.

• --timestamp-ltz-value-format

  The export format of the TIMESTAMP WITH LOCAL TIME ZONE data type. By default, data of the TIMESTAMP WITH LOCAL TIME ZONE type is exported in the yyyy-MM-dd HH:mm:ss format in Oracle mode of OceanBase Database. The precision is the same as that in the table definition.

  Note

  This option can be used only in combination with the --cut or --csv option.

• --preserve-zero-datetime

  Specifies to preserve the raw format of zero values of date and time types during export. If this option is specified, NULL values in date and time columns with the NOT NULL constraint are exported as 0, and NULL values in date and time columns without the NOT NULL constraint are still exported as NULL. You can specify this option for DATE, DATETIME, and TIMESTAMP data types in MySQL mode of OceanBase Database.

Allowlist- and blocklist-based filtering

• Allowlist- and blocklist-based table filtering

  • --exclude-table 'table_name [, table_name...]'

    Excludes the specified tables from the export of table definitions or table data. Fuzzy match on table names is supported.

    Example: --exclude-table 'test1,test*,*test,te*st'

    The preceding example specifies to exclude the following tables from the export of table definitions and table data:

    • test1

    • All tables with the table name starting with test

    • All tables with the table name ending with test

    • All tables with the table name starting with te and ending with st

  • --exclude-data-types 'datatype [, datatype...]'

    Excludes the specified data types from the data export.

  • --add-extra-message

    Exports additional information in table definitions. For example, if you specify the --add-extra-message option on the command line to export table definitions, OBDUMPER exports the name of the table group to which each table belongs. By default, OBDUMPER does not export the additional information contained in table definitions.

    Notice

    If you specify the --add-extra-message option to export table definitions, OBDUMPER exports the name of the table group to which each table belongs. This option depends on privileges of the sys tenant. If OBDUMPER does not have privileges of the sys tenant, do not specify this option.

  • --retain-empty-files

    Generates an empty file for each empty table. If this option is not specified, no file is generated for an empty table during data export.

• Allowlist- and blocklist-based column filtering

  • --include-column-names 'column_name [, column_name...]'

    Exports the specified columns in the specified order.

  • --exclude-column-names 'column_name [, column_name...]'

    Excludes the specified columns during the export of table data. Fuzzy match on column names is not supported.

    Notice

    The letter case of the specified column name must be the same as that of the column name in the table definition.

  • --where 'where_condition_string'

    Exports data that satisfies the specified conditions. This option can be used only in combination with a data format option and cannot be used in combination with the --query-sql option.
    
    

  • --partition 'partition_name [, partition_name...]'

    Exports data of specified partitions. The option specifies the partition names. Separate multiple partition names with commas (,). This option can only be used in combination with a data format option and cannot be used in combination with the --query-sql option.

    Notice

    • When you specify a partition to export, you must specify the subpartition name for a subpartitioned table. You cannot export a partition by specifying only the partition name. For a template-based subpartition, its name is in the format of partition name+s+subpartition name.
    • When you specify the --partition option on the command line to export data in a partition, you need to specify the name of the subpartition for a composite partitioned table. OBDUMPER cannot export data in a partition of a composite partitioned table. If the specified partition name does not exist, OBDUMPER returns an error.

  • --query-sql 'select_statement'

    Exports the result set of a custom query statement. This option cannot be used in combination with the --partition or --where option. You must ensure the correctness and query performance of the custom query statement. When you export the result set of a large query, you may wait for a long time before the database responds. To preprocess data to be exported by using a control file, you need to use the --table and --ctl-path options. The --table option must be set to the table name exactly the same as that specified in --ctl-path. If preprocessing is not required, you can set the --table option to any table name.
    
    

  • --exclude-virtual-columns

    Specifies not to export the data of generated columns. By default, the data of generated columns is exported.
    
    

  • --enable-hidden-pk

    Enables tables without a primary key to use a hidden primary key in __pk_increment to accelerate export. If you specify this option in OceanBase Database of a version earlier than V4.0.0, a special user is needed for export. Here is an example:

    # In MySQL mode of OceanBase Database, create a special user as the root user and grant privileges to this user.
    create user '__oceanbase_inner_drc_user'@'%' IDENTIFIED BY 'u*******';
    grant ALL on *.* to '__oceanbase_inner_drc_user' WITH GRANT OPTION;
    
    # In Oracle mode of OceanBase Database, create a special user as the SYS user and grant privileges to this user.
    create user '__OCEANBASE_INNER_DRC_USER'@'%' IDENTIFIED BY u*******;
    grant ALL to '__OCEANBASE_INNER_DRC_USER';
    

  • --fetch-size 'int_num'

    The number of rows read from the database cursor in Oracle mode of OceanBase Database. The default value is 1000. For more information, see OceanBase FetchSize.

    Note

    To use this option, you must install the OceanBase JDBC driver.

Error handling

• --retry

  Resumes the export task from the location of the last export failure.

  Notice

  The dump.ckpt file is a savepoint file generated when the tool runs and is located in the directory specified by the -f option. You cannot use this option if the dump.ckpt file does not exist.

• --weak-read

  Exports data from the follower replica. For more information about weak-consistency read, see Weak-consistency read.

• --max-file-size int_num

  The maximum size of data that a process can export. Data export stops when the size of the exported file exceeds this value.
  
  

• --skip-check-dir

  Skips checking on whether the data export directory is empty. If the export directory is not empty, the tool stops exporting.

  Note

  • If this option is not specified, OBDUMPER checks whether the export directory is empty. If the export directory is not empty, OBDUMPER returns an error and exits.
  • If this option is specified, OBDUMPER skips the check. In this case, an exported file may overwrite an existing file with the same name in this directory.

• --remove-newline

  Forcibly deletes carriage returns or line breaks in the data before the data export. For example, ***\r***, ***\n***, and \r\n will be deleted. This option only modifies the data retrieved to the memory, and does not modify the data in the source table. This option can be used only in combination with the --cut option.

  Notice

  If data in the source table contains carriage returns or line breaks, the data exported with this option specified will be inconsistent with that in the source table. Before using this option, ensure that the removal of \r, \n, and \r\n does not affect the business. If you do not need to delete carriage returns or line breaks in the data, to avoid data inconsistency, do not specify this option in the command.

• --snapshot

  Exports data of a historical version. This option can be used only in combination with a data format option. You can export data of a historical version to ensure the global consistency of the exported data. If this option is not specified, the real-time data exported from the memory may not be a globally consistent data snapshot.

Performance options

• --page-size int_num

  The page size. This option is used in OBDUMPER V4.0.0 and later versions. The default value is 1000000.

• --thread int_num

  The number of concurrent threads allowed. This option corresponds to the number of export threads. The default value is the value of the number of CPU cores multiplied by 2. If the number of CPU cores is greater than 16, the maximum value is 32. We recommend that you set the --thread option to a value within 4 for exporting the definitions of multiple database objects. High concurrency affects access to system tables under the sys tenant, resulting in timeout errors during data export.

• --block-size int_num

  The block size for a file to be exported. If the size of the data file to be exported exceeds the value of this option, the file will be split into logical sub-files. When specifying this option, you do not need to explicitly specify the unit. The default unit is MB. Default value: 1024MB. This option does not take effect for ORC and Parquet formats. OBDUMPER V4.1.0 and later allow you to specify the maximum number of rows in each sub-file for data file splitting. The unit of --block-size can be MB or ROW. For example, --block-size 256MB indicates that the size of a file cannot exceed 256 MB, and --block-size 256ROW indicates that the size of a file cannot exceed 256 rows.
  
  

• --parallel-macro int_num

  The number of macroblocks that can be processed by each export thread. The default value is 8.

Options