Common Options in ybtools ​

The Java-based client tools share many common options. These options define connectivity settings, logging behavior, and security credentials for loading, unloading, backing up, and restoring data. For information about options that are specific to a type of operation, see:

• ybload Options
• ybunload Options
• ybbackup Options
• ybrestore Options

General Options ​

-?, --help

Return basic usage information and command options.

--help-advanced

Return usage information for more advanced command options.

--java-version

Return the Java version that is running on the client system. The client tools require the 64-bit version of Java 8 (also known as Java 1.8). Java 9 and 10 are not supported.

--version

Display the version of each tool you are running (as part of ybtools). This option is not intended to be combined with other options. For example:

$ ybunload --version
ybunload version 5.4.0-20220228155915
...
$ ybload --version
ybload version 5.4.0-20220228155915

Connectivity Options ​

See also Setting Up a Database Connection.

--dbname, -d

Name of the database used for the connection. The default is yellowbrick.

--host

Host name. See Setting Up a Database Connection.

--initial-connection-timeout NUMBER

Number of seconds to wait for initial connections to the database. The default is 120. This timeout option ensures that an operation does not wait too long when there is a basic problem with incorrect connection parameters, or a firewall is preventing connection errors from reaching the client. To allow an unlimited wait time, set this option to 0.

-p, --port

Specify the database server port. Alternatively, set this value with the YBPORT environment variable. Default: 5432

-U, --username

Specify the database user running the restore. Alternatively, set this value with the YBUSER environment variable.

If this option is not specified, the default user is the current OS user on the client system. Users who connect to tools such as ybload via Kerberos SSO, for example, can do so directly without specifying a username or a password.

Note: Do not run bulk loads as a superuser. The user must have INSERT privileges on the target table but does not have to own the table.

-W, --password

Interactively prompt for the database user's password. Do not enter a password on the command line if you use this option. For non-interactive password entry, set the YBPASSWORD environment variable. See Setting Up a Database Connection.

Logging Options ​

--log-level OFF | ERROR | WARN | INFO | DEBUG | TRACE

Specify the logging level for the default console output. The default level is INFO. (Use the --logfile-log-level option to specify the logging level for a named log file.)

--logfile STRING

Specify the name and location of a log file. If the specified file already exists, it will be truncated. If this option is not specified, no log file is written. When you specify this --logfile option, also specify a --logfile-log-level value other than OFF.

Note: When object storage is used for loading or unloading data, logs must be written to the local file system. Specifying a log file in an object storage location, such as an S3 bucket, is not supported.

--logfile-log-level OFF | ERROR | WARN | INFO | DEBUG | TRACE

Specify the logging level for a given log file (as defined with the --logfile option). If the level is not specified, it defaults to the --log-level value. You must specify a --logfile-log-level value other than OFF when you specify the --logfile option.

-q, --quiet

Do not write any output to the screen. This option is suitable for cron invocations. If this option is specified, you must also specify --logfile and --logfile-log-level.

Security Options ​

--cacert STRING

Customize trust with secured communication; use this option in combination with the --secured option. Enter the file name of a custom PEM-encoded certificate or the file name and password for a Java KeyStore (JKS).

For PEM format, the file must be named with a .pem, .cert, .cer, .crt, or .key extension. For example:

--cacert cacert.pem

For JKS format, files are always password-protected. Use the following format:

--cacert yellowbrick.jks:changeit

where the : character separates the file name from the password of the keystore.

See also Enabling and Verifying SSL/TLS Encryption and

Secure Connections for Java-based ybtools.

--disable-trust, -k

Disable SSL/TLS trust when using secured communications. Trust is enabled by default. See also Enabling and Verifying SSL/TLS Encryption.

Important: This option is not supported for use on production systems and is only recommended for testing purposes. It may be useful to disable trust during testing, then enable it when a formal signed certificate is installed on the cluster.

--secured

Use SSL/TLS to secure all communications. The default is not secured. See also Enabling and Verifying SSL/TLS Encryption.

Setting Up a Database Connection ​

To run the client tools, you have to start a database session on the server where the target database, tables, and other objects reside. This session requires connection information that you can provide either as command-line options or as current values for environment variables:

Parent topic:ybload Command