Command-line options

OBDUMPER allows you to specify the information required for export in command-line options. For more information about the options and their scenarios and examples, see Options and Scenarios and examples.

Options

Connection options

OBDUMPER can read data from and write data to an OceanBase database only after connecting to the database. You can connect to an OceanBase database by specifying the following options:

• -h host_name , --host= host_name

  The host IP address for connecting to ODP or a physical OceanBase Database node.
  
  

• -P port_num , --port= port_num

  The host port for connecting to ODP or a physical OceanBase Database node.
  
  

• -c cluster_name , --cluster= cluster_name

  The OceanBase cluster to connect to. If this option is not specified, the physical node of the database is connected. Relevant options such as -h and -P specify the IP address and port number of the physical node of the database. When this option is specified, ODP is connected. Relevant options such as -h and -P specify the IP address and port number of ODP.
  
  

• -t tenant_name , --tenant= tenant_name

  The OceanBase Database tenant to connect to. For more information about tenants, see the official OceanBase documentation.
  
  

• -u user_name , --user= user_name

  The username for connecting to OceanBase Database. If you specify an incorrect username, OBDUMPER cannot connect to OceanBase Database.
  
  

• -p ' password' , --password=' password'

  The user password for connecting to OceanBase Database. If no password is set for the current database account, you do not need to specify this option. To specify this option on the command line, you must enclose the value in single quotation marks (' '). For example, -p'******'.

  Note
  If you are using Windows OS, enclose the value in double quotation marks (" "). This rule also applies to string values of other options.

• -D database_name , --database= database_name

  Exports database object definitions and table data from the specified database.
  
  

• --sys-user sys_username

  The username of a user with required privileges under the sys tenant, for example, root or proxyro. OBDUMPER requires such a user to query metadata in system tables. Default value: root.
  
  

• --sys-password ' sys_password'

  The password of a user with required privileges under the sys tenant. This option is used along with --sys-user. By default, the password of the root user under the sys tenant is left empty. When you specify this option on the command line, enclose the value in single quotation marks (' '). Example: --sys-password '******'.

  Note
  If this option is not specified, OBDUMPER cannot query metadata in system tables, and the export features and performance may be greatly affected.

• --public-cloud

  Exports database object definitions and table data from the database in limited mode when --sys-user and --sys-password cannot be specified. However, the data export features and performance may be affected. For example, data in the specified partition cannot be exported, table comments and indexes cannot be exported, and parallel export cannot be enabled.

  Notice
  In limited mode, OBDUMPER does not support exporting table indexes of OceanBase Oracle 2.2.30 and earlier versions.

Feature options

• -f ' file_path ' , --file-path= ' file_path '

  The absolute path on a local disk for storing data files.
  
  

• --file-encoding ' encode_name '

  The character set used during file export, which is not the database character set. When you specify this option on the command line, enclose the value in single quotation marks (' '). Example: --file-encoding 'GBK'. Default value: UTF-8.
  
  

• --ctl-path ' control_path '

  The absolute path on a local disk for storing control files. 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 (' '). 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.
  
  

• --ddl

  Exports DDL files. A DDL file stores database object definitions. The file is named in the format of object name-schema.sql. When this option is specified, only the database object definitions are exported, and table data is not exported. We recommend that you set the --thread option to a value less than 4 for exporting the definitions of multiple table objects. High concurrency affects access to internal views under the sys tenant, resulting in timeout errors during data export.
  
  

• --sql

  Exports data files in the SQL format. In an SQL file, data is stored in the format of INSERT statements. The file is named in the format of table name.sql. Each line of table data corresponds to an executable INSERT statement in an SQL file. An SQL file is different from a DDL file in terms of content format. We recommend that you use this option together with the --table option. When it is used together with the --all option, OBDUMPER exports only table data but not database object definitions.
  
  

• --csv

  Exports data files in the CSV format. In a CSV file, data is stored in the standard CSV format. The file is named in the format of table name.csv. For CSV format specifications, see the definitions in RFC 4180. Delimiter errors are the most common errors that occur in CSV files. Single or double quotation marks are usually used as the delimiter. If data in the file contains the delimiter, you must specify escape characters. For more information, see symbol options in the CSV format. We strongly recommend that you use the CSV format. We recommend that you use this option together with the --table option. When it is used together with the --all option, OBDUMPER exports only table data but not database object definitions.
  
  

• --cut

  Exports data files in the CUT format. A CUT file is a format that uses a character string as the separator string. A CUT file is named in the format of table name.dat. We recommend that you use this option together with the --table option. When it is used together with the --all option, OBDUMPER exports only table data but not database object definitions.

  Notice
  In a CUT file, each data record is stored in an entire line. If the data to be exported contains special characters such as separator strings, carriage returns, or line breaks, OBDUMPER replaces or escapes these special characters.

• --table-group '*table_group_name [,table_group_name...]*'|--table-group '*'

  Exports table group definitions. This option is similar to the --table option, except that this option does not support data export.
  
  

• --all

  Exports all database object definitions and table data. When this option is used in combination with --ddl, all database object definitions are exported. When this option is used in combination with --csv, --sql, or --cut, data in all tables is exported in the specified format. To export all database object definitions and table data, you can specify --all and --ddl along with a data format option.

  Notice
  The --all option is mutually exclusive with any database object options. It cannot be specified together with other database object options. If both the --all option and a database object option are specified, the --all option will be executed first.

• --table ' table_name [,table_name...] ' | --table ' * '

  Exports table definitions or table data. When this option is used in combination with --ddl, only table definitions are exported. When this option is used in combination with any data format option, only table data is exported. To specify multiple tables, separate the table names with commas (,). By default, the names of tables that are exported from Oracle tenants are in uppercase, and the names of tables that are exported from MySQL tenants are in lowercase. For example, in Oracle mode, both --table 'test' and --table 'TEST' indicate the table named TEST. In MySQL mode, both --table 'test' and --table 'TEST' indicate the table named test. If table names are case-sensitive, enclose them in brackets ([ ]). For example, --table '[test]' indicates the table named test, while --table '[TEST]' indicates the table named TEST. If the table name is specified as an asterisk (*), all table definitions or table data is exported.
  
  

• --view ' view_name [, view_name...] ' | --view ' * '

  Exports view definitions. This option is similar to the --table option, except that this option does not support data export.
  
  

• --trigger ' trigger_name [, trigger_name...] ' | --trigger ' * '

  Exports trigger definitions. This option is similar to the --table option, except that this option does not support data export.
  
  

• --sequence ' sequence_name [, sequence_name...] ' | --sequence ' * '

  Exports sequence definitions. This option is similar to the --table option, except that this option does not support data export. This option is supported only for OceanBase Database in Oracle mode.
  
  

• --synonym ' synonym_name [, synonym_name...] ' | --synonym ' * '

  Exports synonym definitions. This option is similar to the --table option, except that this option does not support data export. This option is supported only for OceanBase Database in Oracle mode.
  
  

• --type ' type_name [, type_name...] ' | --type ' * '

  Exports type definitions. This option is not supported for now.
  
  

• --type-body ' typebody_name [, typebody_name...] ' | --type-body ' * '

  Exports type body definitions. This option is similar to the --table option, except that this option does not support data export. This option is supported only for OceanBase Database in Oracle mode.
  
  

• --package ' package_name [, package_name...] ' | --package ' * '

  Exports package definitions. This option is similar to the --table option, except that this option does not support data export. This option is supported only for OceanBase Database in Oracle mode.
  
  

• --package-body ' packagebody_name [, packagebody_name...] ' | --package-body ' * '

  Exports package body definitions. This option is similar to the --table option, except that this option does not support data export. This option is supported only for OceanBase Database in Oracle mode.
  
  

• --function ' function_name [, function_name...] ' | --function ' * '

  Exports function definitions. This option is similar to the --table option, except that this option does not support data export.
  
  

• --procedure ' procedure_name [, procedure_name...] ' | --procedure ' * '

  Exports stored procedure definitions. This option is similar to the --table option, except that this option does not support data export.
  
  

• --drop-object

  Inserts a DROP statement before the database object creation statement for the export of a DDL file. This option can be used only in combination with the --ddl option.
  
  

• --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.
  
  

• --where ' where_condition_string '

  Exports data that satisfies the specified conditions. This option can only be used together 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 together with a data format option and cannot be used in combination with the --query-sql option.
  
  

• --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 specify any table name for the --table option.
  
  

• --flashback-scn ' scn_number '

  Exports data after a system change number (SCN) transaction point. This option can only be used 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.
  
  

• --flashback-timestamp ' timestamp_string '

  Exports data after a flashback point in time. This option can only be used 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. This option does not indicate to export data of the DATE type in the specified format. Default value: yyyy-MM-dd HH:mm:ss.
  
  

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

  The nls_timestamp_formatsession variable in Oracle mode. This option does not indicate to export data of the TIMESTAMP type in the specified format. Default value: yyyy-MM-dd HH:mm:ss.SSSSSS.
  
  

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

  The nls_timestamp_tz_format session variable in Oracle mode. This option does not indicate to export data of the TIMESTAMP WITH TIME ZONE type in the specified format. Default value: yyyy-MM-dd HH:mm:ss.SSSSSS TZR.
  
  

• --retry

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

  Notice
  The CHECKPOINT.bin file is a savepoint file generated when the tool runs, and is located in the directory specified in the -f option. You cannot use this option if the CHECKPOINT.bin file does not exist.

• --distinct

  Filters duplicate data in a table. This option is used only in combination with the --cut option.

  Notice
  This option is discarded. Do not use it.

• --weak-read

  Exports data from the follower replica. OBDUMPER of versions earlier than 3.1.0 can be used only with ODP 3.1.2 and later. For OBDUMPER 3.1.0 and later versions, you need to modify ob.proxy.route.policy=follower_first in the conf/session.properties file. For the usage of thesession.properties file, see Set session-level variables in Scenarios and examples under OBDUMPER.
  
  

• --file-name ' file_name '

  Merges subfiles exported from a table into one large file.

  Examples:

• --max-file-size int_num

  The maximum size of a file. Data export stops when the size of the exported data reaches the limit.
  
  

• --skip-check-dir

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

• --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 you use 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.

• --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.
  
  

• --add-extra-message

  Exports table definitions with additional information in DDL files. Example: tablegroup.
  
  

• --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 export of data.
  
  

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

  Includes the specified columns in the export of table data. Data of the columns is exported in the specified order.
  
  

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

  Excludes the specified columns from 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 structure.

• --skip-header

  Skips headers of CSV files when the files are exported. This option can be used only in combination with the --csv option.
  
  

• --trail-delimiter

  Truncates the last column separator in a line. This option can be used only in combination with the --cut or --csv option.
  
  

• --null-string ' null_replacer_string '

  Replaces a specified character with NULL. This option can be used only in combination with the --cut or --csv option. Default value: \N.
  
  

• --empty-string ' empty_replacer_string '

  Replaces a specified character with an empty string (' '). This option can be used only in combination with the --csv option. Default value: \E.
  
  

• --line-separator ' line_separator_string '

  The custom line break for the data file. The default value of this option varies with the system platform. Valid values: \r, \n, and \r\n.
  
  

• --column-separator ' column_separator_char '

  The column separator. This option can be used only in combination with the --csv option and supports a single character only. Default value: comma (,).
  
  

• --escape-character ' escape_char '

  The escape character. This option can be used only in combination with the --cut or --csv option and supports a single character only. Default value: backslash ().
  
  

• --column-delimiter ' column_delimiter_char '

  The column delimiter. This option can be used only in combination with the --csv option and supports a single character only. Default value: single quotation mark (').
  
  

• --column-splitter ' split_string '

  The column separator string. This option can be used only in combination with the --cut option.
  
  

• --oss-point ' oss_endpoint_string '

  The endpoint to access the OSS bucket. This option must be used in combination with --access-key and --secret-key for the access to OSS.
  
  

• --access-key ' access_key_string '

  The AccessKey ID used to access the OSS bucket. This option must be used in combination with --oss-endpoint and --secret-key for access to the OSS bucket.
  
  

• --secret-key ' secret_key_string '

  The AccessKey secret used to access the OSS bucket. This option must be used in combination with --oss-endpoint and --access-key for access to the OSS bucket.
  
  

• --bucket-uri ' bucket_uri_string '

  The URI of the OSS bucket. This option must be used in combination with --oss-endpoint, --access-key, and secret-key for access to the OSS bucket.
  
  

• --date-value-format

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

• --time-value-format

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

• --datetime-value-format

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

• --timestamp-value-format

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

• --timestamp-tz-value-format

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

• --timestamp-ltz-value-format

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

• --exclude-virtual-columns

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

• --no-sys Identifies the scenario of a private cloud environment without the sys tenant password. The option distinguishes from the --public-cloud option, which identifies the scenario of a public cloud environment.
  
  

• --logical-database

  Specifies to export data by using ODP (Sharding).

Performance options

• --page-size int_num

  The page size in a query statement executed during export. Default value: 1000000.
  
  

• --thread int_num

  The number of concurrent export threads allowed. This option corresponds to the number of export threads. Default value: Number of CPU cores x 2. 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 blocks with this specified size. Default value: 1GB.
  
  

• --parallel-macro int_num

  The number of macroblocks that can be processed by each export thread. Default value: 8.

Other options

• -h, --help

  Shows the help information about the tool.
  
  

• --version

  Shows the version of the tool.