Reference for OBClient command-line options

This topic provides a complete reference for all options of the OBClient command-line client.

Options

OBClient supports the following options:

-?, --help

Displays help information and exits.

-I, --help

Synonym for -?.

--abort-source-on-error

Aborts the operation on 'source filename' if an error occurs.

--auto-rehash

Enables automatic rehashing. This option is enabled by default and allows database, table, and column name completion. Use --disable-auto-rehash, --no-auto-rehash, or skip-auto-rehash to disable rehashing. Disabling rehashing makes OBClient start faster, but if you want to use name completion, you must issue a rehash command. To complete a name, enter the first part and press Tab. If the name is unique, OBClient will complete it. Otherwise, you can press Tab again to see the possible names that start with what you have entered so far. No completion occurs if there is no default database.

-A, --no-auto-rehash

Does not perform automatic rehashing. You must use 'rehash' to get table and field completion. This makes OBClient start faster and disables rehashing upon reconnect.

--auto-vertical-output

If the result is wider than the terminal width, automatically switches to vertical output mode.

-B, --batch

Prints results with tabs as column separators, with each line on a new line. When using this option, OBClient does not use history files. Batch processing mode results in non-table output formats and escape of special characters. You can disable escaping by using raw mode; see the description of the --raw option. (Enable --silent.)

--binary-mode

By default, ASCII '\0' is not allowed, and \r\n is converted to \n. This switch disables both features and, in non-interactive mode (for input passed to obclient via a pipeline or loaded using the 'source' command), also disables parsing of all client commands except for \C and DELIMITER. This is necessary when processing mysqlbinlog output that may contain blobs.

--character-sets-dir=name

The directory for character set files.

--column-names

Writes column names in the results. (ON by default; disabled with --skip-column-names.)

--column-type-info

Displays column type information.

-c, --comments

Retains comments. Sends comments to the server. The default is --skip-comments (discards comments); use --comments to enable it.

-C, --compress

If both the client and server support compression, compress all information sent between them.

--connect-expired-password

Inform the server that this client is ready to handle expired password sandbox mode, even if --batch is specified.

--connect-timeout=num

The number of seconds before a connection times out. Default is 0.

-D, --database=name

The database to use.

-``[options], --debug[=options]

Write debug logs on the debug version. A typical debug_options string is d:t:o,file_name. The default is d:t:o,/tmp/mysql.trace.

--debug-check

Check memory and open file usage upon exit.

-T, --debug-info

Print some debug information upon exit.

--default-auth=plugin

The default authentication client plugin to use.

--default-character-set=name

Set the default character set. A common issue occurs when the operating system uses utf8 or another multibyte character set: OBClient may output incorrectly because it defaults to using the latin1 character set. Typically, this can be resolved by forcing the client to use the system character set using this option. If set to auto, the character set is obtained from the client environment (e.g., LC_CTYPE on Unix).

--defaults-extra-file=file

Read this file after reading the global file. It must be specified as the first option.

--defaults-file=file

Read default options only from the given file. It must be specified as the first option.

--defaults-group-suffix=suffix

Read groups with this suffix in addition to the given group.

--delimiter=name

The delimiter to use. Default is a semicolon (;).

--enable-cleartext-plugin

This option is deprecated and is for MySQL compatibility only.

--error-sql

Specifies whether to include adjacent SQL context in the output when an SQL error occurs during batch script execution or multi-statement operations using source. This helps you locate the issue by comparing the script. For details on values like xxx, top0, and topN, see the dedicated topic: --error-sql option (script error context).

-e, --execute=name

Execute the statement and exit. This option disables --force and historical files. The default output format is similar to that produced by using --batch.

-f, --force

Continue even if an SQL error occurs. Sets --abort-source-on-error to 0.

-h, --host=host

Connect to the host.

-H, --html

Generate HTML output.

-U, --i-am-a-dummy

Synonym for the --safe-updates and -U options.

-i, --ignore-spaces

Ignore spaces after function names. Allows spaces (including tabs and line breaks) between the function name and the '('. The downside is that this can cause built-in functions to become reserved words.

--init-command=str

The SQL command to execute when connecting to the OceanBase server. It is automatically re-executed upon reconnect.

--line-numbers

Write line numbers for errors. (Default is ON; disabled by using --skip-line-numbers.)

--local-infile

Enable or disable the LOCAL feature of LOAD DATA INFILE. When no value is specified, this option enables LOCAL. It can be set to --local-infile=0 or --local-infile=1 to explicitly disable or enable LOCAL. Enabling LOCAL is ineffective if the server does not support it.

--max-allowed-packet=num

The maximum packet length that can be sent to or received from the server. The default value is 16 MB, and the maximum value is 1 GB.

--max-join-size=num

The automatic limit on rows in a connection when using --safe-updates. The default value is 1000000.

-G, --named-commands

Enable named commands. Named commands are internal commands of OBClient (see below). After enabling, named commands can be used from any line of a query; otherwise, they can only be used from the first line, before pressing Enter. This allows long-form commands as well as short-form ones. For example, both quit and \q are recognized. To disable this, use --disable-named-commands. This option is disabled by default.

--net-buffer-length=num

The buffer size for TCP/IP and socket communications. The default value is 16 KB.

-b, --no-beep

Disable the beep sound on errors.

--no-defaults

Do not read default options from any option file. This must be the first option provided.

-o, --one-database

Ignore statements unless the default database is specified on the command line. This filtering is limited to USE statements. This is useful for skipping updates from other databases in binary logs.

--pager[=name]

The pager used to display results (Unix only). If you do not provide an option, the default pager is obtained from your ENV variable PAGER. Valid pagers include less, more, cat [> filename], etc. See also interactive help (\h). This option does not work in batch mode. To disable it, use --disable-pager. This option is disabled by default.

-p, --password[=password]

The password used to connect to the server. If you use the short option form (-p), there must be no space between the option and the password. If you omit the password value after the --password or -p option on the command line, OBClient will prompt you to enter one. Specifying a password on the command line is considered insecure. You can use an option file to avoid providing the password on the command line.

--plugin-dir=name

The directory for client plugins.

-P, --port=num

The port number to use for the connection. 0 indicates the default value is determined by the following sources, in order of priority: my.cnf, $MYSQL_TCP_PORT, /etc/services, and the built-in default value.

--print-defaults

Print the list of program parameters and exit. This must be the first option provided.

--prompt=name

Set the OBClient prompt to this value. For options, see the prompt command.

--protocol=name

The protocol used for the connection (tcp, socket, pipe, or memory).

-q, --quick

Do not cache results; print them line by line. If output is paused, this may slow down the server. Do not use history files.

-r, --raw

For table outputs, the "boxes" around columns distinguish one column value from another. For non-table outputs (such as those generated in batch mode or when using the --batch or --silent option), special characters are escaped in the output so they can be easily recognized. Line breaks, tabs, NULs, and backslashes are written as \n, \t, \0, and \\. The --raw option disables this character escaping.

--reconnect

If the connection is lost, reconnect. This option is enabled by default. To disable it, use --disable-reconnect or skip-reconnect.

-U, --safe-updates

Allows only UPDATE and DELETE statements that specify the rows to modify using key values. If you set this option in an options file, you can override it by using --safe-updates on the command line. For more information, see Use the --safe-updates option.

-s, --silent

quieter. This option can be specified multiple times to produce progressively less output. It causes non-table output formats and special character escapes to be disabled. You can disable escaping by using the raw mode; see the description of the --raw option.

--skip-auto-rehash

disable automatic rehashing. See --auto-rehash.

-N, --skip-column-names

do not write column names in the results. See --column-names.

--skip-comments

discard comments. The default setting. To enable this, see --comments.

-L, --skip-line-numbers

do not write line numbers for errors. See --line-numbers.

--skip-reconnect

if the connection is lost, do not reconnect. See --reconnect.

-S, --socket=name

for connections to localhost, the name of the Unix socket file to use, or on Windows, the name of the named pipe to use. The socket file may be located in different places depending on the configuration. Common locations include:

• Debian-based, Ubuntu: /var/run/mysqld/mysqld.sock
• SUSE: /var/run/mysql/mysql.sock
• Red Hat: /var/lib/mysql/mysql.sock
• Other: /tmp/mysql.sock

--ssl

enable TLS. Even if this option is not set, TLS is enabled when certain other TLS options are set. The --ssl option does not enable server certificate verification by default. To verify the server certificate, you must specify the --ssl-verify-server-cert option.

--ssl-ca=name

define the path to a PEM file containing one or more trusted Certificate Authorities (CAs) X509 certificates for TLS. This option requires you to use an absolute path, not a relative path. This option implies the --ssl option.

--ssl-capath=name

define the directory path that contains one or more PEM files, each containing a trusted Certificate Authority (CA) X509 certificate, for TLS. This option requires you to use an absolute path, not a relative path. The specified directory needs to be run through the openssl rehash command. This option is only supported when the client is built with OpenSSL or yaSSL. If the client is built with GnuTLS or Schannel, this option is not supported. This option implies the --ssl option.

--ssl-cert=name

define the path to the X509 certificate file used for TLS. This option requires you to use an absolute path, not a relative path. This option implies the --ssl option.

--ssl-cipher=name

List of allowed passwords or cipher suites for TLS. This option implies the --ssl option.

--ssl-crl=name

Defines the path to a PEM file that contains one or more revoked X509 certificates for TLS. This option requires you to use an absolute path, not a relative path. This option is only supported when the client is built with OpenSSL or Schannel. If the client is built with yaSSL or GnuTLS, this option is not supported.

--ssl-crlpath=name

Defines the directory path that contains one or more PEM files, each containing a revoked X509 certificate, for TLS. This option requires you to use an absolute path, not a relative path. The specified directory must be run through the openssl rehash command. This option is only supported when the client is built with OpenSSL. If the client is built with yaSSL, GnuTLS, or Schannel, this option is not supported.

--ssl-key=name

Defines the path to the private key file for TLS. This option requires you to use an absolute path, not a relative path. This option implies the --ssl option.

--ssl-verify-server-cert

Enables server certificate verification. This option is disabled by default; specify it explicitly when server-side certificate verification is required. Use --disable-ssl-verify-server-cert to ensure verification is disabled.

-t, --table

Displays output in tabular format. This is the default for interactive use, but can also be used to generate tabular output in batch mode.

--tee=name

Appends all content to the output file. See also interactive help (\h). Does not work in batch mode. Use --disable-tee to disable it. This option is disabled by default.

--tls-version=name

This option accepts a comma-separated list of TLS protocol versions. A TLS protocol version is enabled only if it appears in this list. All other TLS protocol versions will not be allowed.

--ssl-fp=name

Server certificate fingerprint (implies --ssl).

--ssl-fplist=name

File containing accepted server certificate fingerprints, one per line (implies --ssl).

-n, --unbuffered

Refreshes the buffer after each query.

-u, --user=name

Username for login. If no Unix socket is specified and a TCP connection is used, and no user is specified via the command line or configuration file, OBClient uses the default user root@sys.

-v, --verbose

Writes more information. (-v -v -v produces tabular output format.)

-V, --version

Output the version information and exit.

-E, --vertical

Print query output vertically (by row). If this option is not enabled, use the \G separator for specific statements.

-w, --wait

If a connection cannot be established, wait and retry instead of aborting.

-X, --xml

Generate XML output.

References

• Overview of OBClient
• --error-sql (script error context)
• Reference for interactive commands of OBClient