OpenText Analytics Database 26.2.x – VCluster commands

Admin: add_node

Mon, 01 Jan 0001 00:00:00 +0000

Adds one or more user-specified hosts as nodes to an existing database. You cannot add nodes to a sandboxed subcluster.

Syntax

vcluster add_node options

Required options

--catalog-path string: The absolute path to the catalog directory.

{ -c | --config } string: The path to the configuration file. If a configuration file is present in the default location (automatically generated by create_db), you do not need to specify this option.
Default: /opt/vertica/config/vertica_cluster.yaml

--new-hosts hostname_or_ip [,...]: A comma-separated list of hosts to add to the database.

Options

--add-node-timeout int: The time, in seconds, to wait for the specified nodes to be added.
Default: 300

--cert-file string: The absolute path to the certificate file. If you specify this option, you must also specify --key-file. You should only use --cert-file and --key-file if you have configured the Node Management Agent (NMA) to use custom certificates.

--data-path string: The absolute path to the data directory. This should be the same for all nodes in the database.

--depot-path string: [Eon only] The absolute path to depot directory.

--depot-size string: [Eon only] Size of depot in one of the following formats:

integer{K|M|G|T}, where K is kilobytes, M is megabytes, G is gigabytes, and T is terabytes.
integer%, which expresses the depot size as a percentage of the total disk size.

--force-removal: Whether to delete any existing database directories in the new hosts before attempting to add them.

{ -h | --help }: Prints help text.

--ipv6: Specifies if the hosts use IPv6 addresses.
Default: IPv4

--key-file string: Path to the key file. If you specify this option, you must also specify --cert-file. You should only use --cert-file and --key-file if you have configured the Node Management Agent (NMA) to use custom certificates.

{ -l | --log-path } string: The absolute path for debug logs.
Default: /opt/vertica/log/vcluster.log

--node-names string: [Use only with support guidance] A comma-separated list of node names that exist in the cluster.

{ -p | --password } string: The database password.

--password-file string: The absolute path to a file containing the database password.
If you pass a dash(-) (that is, `--password-file -`), the password is read from STDIN.

Important
Your database password cannot include single quotes.

--read-password-from-prompt: Prompts the user to enter the password.

--skip-rebalance-shards: [Eon only] Whether to skip shard rebalancing.

--subcluster string: [Eon only] The name of the subcluster to which the host(s) should be added. This string must conform to the format used for database names.
Default: Default subcluster

--verbose: Shows the details of VCluster run in the console.

Examples

To add the node 192.2.0.4:

$ vcluster add_node --new-hosts 192.2.0.4

To add multiple nodes:

$ vcluster add_node --new-hosts 192.2.0.4,192.2.0.5

Admin: add_subcluster

Mon, 01 Jan 0001 00:00:00 +0000

Adds a new subcluster to an Eon Mode database. For details, see Creating subclusters.

Syntax

vcluster add_subcluster options

Required options

--catalog-path string: The absolute path to the catalog directory.

{ -c | --config } string: The path to the configuration file. If a configuration file is present in the default location (automatically generated by create_db), you do not need to specify this option.
Default: /opt/vertica/config/vertica_cluster.yaml

--subcluster string: The name of the new subcluster. This string must conform to the format used for database names.

Options

--ca-cert-file string: The path to the trusted CA certificate file.
Default: /opt/vertica/config/https_certs/rootca.pem

--cert-file string: The absolute path to the certificate file. If you specify this option, you must also specify --key-file. You should only use --cert-file and --key-file if you have configured the Node Management Agent (NMA) to use custom certificates.

--control-set-size int: The number of control nodes in the subcluster.
Default: -1 (All nodes in the subcluster are control nodes)
--create-storage-locations: Indicates whether the sandbox can create its own storage locations.

--data-path string: The absolute path to the data directory. This should be the same for all nodes in the database.

{ -d | --db-name } string: The name of the database. You should only use this option if you want to override the database name in your configuration file. This string must conform to the format used for database names.

--depot-path string: [Eon only] The absolute path to depot directory.

--depot-size string: [Eon only] Size of depot in one of the following formats:

integer{K|M|G|T}, where K is kilobytes, M is megabytes, G is gigabytes, and T is terabytes.
integer%, which expresses the depot size as a percentage of the total disk size.

--for-upgrade: Indicates whether the sandbox is used for an online upgrade.

--force-removal: Whether to delete any existing database directories in the new hosts before attempting to add them.

{ -h | --help }: Prints help text.

--hosts strings: A comma-separated list of hosts in the database.

--ipv6: Specifies if the hosts use IPv6 addresses.
Default: IPv4

--is-primary: Whether the new subcluster should be a primary subcluster. If this option is omitted, new subclusters are secondary.
--isolate-metadata: Specifies whether to isolate the metadata of the sandboxed subcluster.

--key-file string: Path to the key file. If you specify this option, you must also specify --cert-file. You should only use --cert-file and --key-file if you have configured the Node Management Agent (NMA) to use custom certificates.

--like string: Clones the configuration from an existing subcluster. Cannot be used with --is-primary or --control-set-size.

{ -l | --log-path } string: The absolute path for debug logs.
Default: /opt/vertica/log/vcluster.log

--new-hosts string[,...]: A comma-separated list of hosts or IP addresses to add to the subcluster.

{ -p | --password } string: The database password.

--password-file string: The absolute path to a file containing the database password.
If you pass a dash(-) (that is, `--password-file -`), the password is read from STDIN.

Important
Your database password cannot include single quotes.

--read-password-from-prompt: Prompts the user to enter the password.

--sandbox string: Name of the sandbox where the subcluster will be added.
--save-restore-point: Indicates whether a restore point should be saved when creating the sandbox.

--skip-rebalance-shards: [Eon only] Whether to skip shard rebalancing.

--tls-mode string: Sets the TLS validation mode. Valid options are enable, verify-ca, verify-full.
Default: enable

--use-password-for-sql-client-only: Use the password for the NMA SQL client only.

--verbose: Shows the details of VCluster run in the console.

Examples

To add a subcluster with a config file:

  vcluster add_subcluster --subcluster sc1 \
    --config /opt/vertica/config/vertica_cluster.yaml \
    --is-primary --control-set-size 1 \
    --password "PASSWORD"

To add a subcluster with user input:

  vcluster add_subcluster --subcluster sc1 --db-name test_db \
    --hosts 192.0.2.0,192.0.2.1,192.0.2.2 \
    --is-primary --control-set-size -1 \
    --password "PASSWORD"

To add a subcluster and new nodes in the subcluster with a config file:

  vcluster add_subcluster --subcluster sc1 \
    --config /opt/vertica/config/vertica_cluster.yaml \
    --is-primary --control-set-size 1 --new-hosts 192.0.2.3 \
    --password "PASSWORD"

To add a subcluster and new nodes in the subcluster with user input:

  vcluster add_subcluster --subcluster sc1 --db-name test_db \
    --hosts 192.0.2.0,192.0.2.1,192.0.2.2 \
    --is-primary --control-set-size -1 --new-hosts 192.0.2.3 \
    --password "PASSWORD"

To clone properties from an existing subcluster (empty to empty):

vcluster add_subcluster --subcluster sc2 --like sc1

To clone properties and add a single node (must match source node count):

cluster add_subcluster --subcluster sc2 --like sc1 --new-hosts 192.0.2.5

To clone properties and add multiple nodes (must match source node count):

vcluster add_subcluster --subcluster sc2 --like sc1 --new-hosts 192.0.2.5,192.0.2.6

Admin: completion

Mon, 01 Jan 0001 00:00:00 +0000

Creates a tab-completion script for a specified shell.

A tab-completion script for your default shell is automatically generated and configured when you install OpenText™ Analytics Database, so completion is only necessary in cases where you either change shells or want to use vcluster from a non-OpenText™ Analytics Database node.

Syntax

vcluster completion subcommand

Subcommands options

shell

The shell for which to generate a completion script, one of the following:

bash
fish
powershell
zsh

Examples

For example, to configure tab-completion for bash on Linux, generate the tab-completion script, redirecting its output to a new file vcluster_tab_completion:

$ vcluster completion bash > /etc/bash_completion.d/vcluster

Similarly, for bash on macOS:

$ vcluster completion bash > $(brew --prefix)/etc/bash_completion.d/vcluster

Admin: create_db

Mon, 01 Jan 0001 00:00:00 +0000

Creates a new database and its associated configuration file for use with other vcluster commands.

Syntax

vcluster create_db { options }

Required options

--catalog-path string: The absolute path to the catalog directory.

--data-path string: The absolute path to the data directory. This should be the same for all nodes in the database.

{ -d | --db-name } string: The name of the database. You should only use this option if you want to override the database name in your configuration file. This string must conform to the format used for database names.

--hosts strings: A comma-separated list of hosts in the database.

Eon options

The following options are required for creating Eon Mode databases, the database mode primarily supported by vcluster:

--communal-storage-location string: [Eon only] The absolute path of your communal storage location.

--shard-count int: [Eon only] The number of shards in the database.

Options

--broadcast

Configures Spread to use UDP broadcast traffic between nodes on the same subnet. Do not combine this option with --point-to-point.

Up to 80 Spread daemons are supported by broadcast traffic. You can exceed the 80-node limit by using large cluster mode, which only installs the Spread daemon on a subset of your nodes.

Default: Disabled

--cert-file string: The absolute path to the certificate file. If you specify this option, you must also specify --key-file. You should only use --cert-file and --key-file if you have configured the Node Management Agent (NMA) to use custom certificates.

{ -c | --config } string: The path to write the configuration file.
Default: /opt/vertica/config/vertica_cluster.yaml

--config-param PARAMETER=VALUE[,...]

A comma-separated list of PARAMETER=VALUE pairs. Parameters specified with this option override the ones in configuration files, if any, and take the following parameters:

AWSAuth
AWSEndpoint
AWSEnableHttps
AWSRegion

--depot-path string: [Eon only] The absolute path to depot directory.

--depot-size string: [Eon only] Size of depot in one of the following formats:

integer{K|M|G|T}, where K is kilobytes, M is megabytes, G is gigabytes, and T is terabytes.
integer%, which expresses the depot size as a percentage of the total disk size.

--force-cleanup-on-failure

Deletes directories created by create_db upon failure.

--force-overwrite-file

Overwrites the current configuration file, if any.

--force-removal-at-creation

Deletes existing database directories before attempting to create the database.

--get-aws-credentials-from-env-vars

[Eon only] Retrieves AWS credentials from the following environment variables:

$AWS_ACCESS_KEY_ID
$AWS_SECRET_ACCESS_KEY

{ -h | --help }: Prints help text.

--ipv6: Specifies if the hosts use IPv6 addresses.
Default: IPv4

--key-file string: Path to the key file. If you specify this option, you must also specify --cert-file. You should only use --cert-file and --key-file if you have configured the Node Management Agent (NMA) to use custom certificates.

--large-cluster int: Enables the large cluster layout and sets the number of control nodes. The effect of this option is slightly different on Enterprise and Eon databases. For details, see Enabling large cluster.
Default: -1 (Disabled)
--license string: The absolute path to a license file. The path to this license must be the same on all nodes.

{ -l | --log-path } string: The absolute path for debug logs.
Default: /opt/vertica/log/vcluster.log

{ -p | --password } string: The database password.

--password-file string: The absolute path to a file containing the database password.
If you pass a dash(-) (that is, `--password-file -`), the password is read from STDIN.

Important
Your database password cannot include single quotes.

--point-to-point

Configures Spread to use point-to-point communication between all OpenText™ Analytics Database nodes. You should use this option if your nodes are not on the same subnet and for virtual environments. Do not combine this option with --broadcast.

Up to 80 Spread daemons are supported by point-to-point communication. You can exceed the 80-node limit by using large cluster mode, which only installs the Spread daemon on a subset of your nodes.

Default: Enabled

--read-password-from-prompt: Prompts the user to enter the password.

--skip-package-install: Skips installing the packages in /opt/vertica/packages.
Default: Disabled
--startup-timeout int: The time, in seconds, to wait for the nodes to start after database creation.
Default: 300

--verbose: Shows the details of VCluster run in the console.

Examples

Create a database with the nodes 192.0.2.0, 192.0.2.1, and 192.0.2.2 with the password in /password.txt:

$ vcluster create_db --db-name vertica_db \
    --hosts 192.0.2.0,192.0.2.1,192.0.2.2 \
    --catalog-path /data --data-path /data \
    --password-file password.txt

Admin: drop_db

Mon, 01 Jan 0001 00:00:00 +0000

Drops a stopped database. The effects this command has on your data differs slightly between database modes:

Enterprise: Deletes the database data (including catalog, data, and depot directories) from all nodes.
Eon: Deletes non-communal storage data. Dropped Eon Mode databases can be revived.

The data deleted by this operation cannot be recovered.

Syntax

vcluster drop_db [options]

Required options

{ -c | --config } string: The path to the configuration file. If a configuration file is present in the default location (automatically generated by create_db), you do not need to specify this option.
Default: /opt/vertica/config/vertica_cluster.yaml

Options

--cert-file string: The absolute path to the certificate file. If you specify this option, you must also specify --key-file. You should only use --cert-file and --key-file if you have configured the Node Management Agent (NMA) to use custom certificates.

{ -h | --help }: Prints help text.

--ipv6: Specifies if the hosts use IPv6 addresses.
Default: IPv4

--key-file string: Path to the key file. If you specify this option, you must also specify --cert-file. You should only use --cert-file and --key-file if you have configured the Node Management Agent (NMA) to use custom certificates.

{ -l | --log-path } string: The absolute path for debug logs.
Default: /opt/vertica/log/vcluster.log

--verbose: Shows the details of VCluster run in the console.

Examples

To drop a database:

$ vcluster drop_db --db-name test_db

Admin: help

Mon, 01 Jan 0001 00:00:00 +0000

Prints the help text for any command or subcommand. This is the same as using the --help option.

Syntax

vcluster help command

Commands

command: The command to print help text for.

Options

{ -h | --help }: Prints help text.

Admin: install_packages

Mon, 01 Jan 0001 00:00:00 +0000

Installs the packages in /opt/vertica/packages. This is useful in cases where packages weren't installed during the database installation (either due to --skip-package-install or an error) or if your existing packages are corrupt.

Syntax

vcluster install_packages options

Required options

{ -c | --config } string: The path to the configuration file. If a configuration file is present in the default location (automatically generated by create_db), you do not need to specify this option.
Default: /opt/vertica/config/vertica_cluster.yaml

Options

--ca-cert-file string: The path to the trusted CA certificate file.
Default: /opt/vertica/config/https_certs/rootca.pem

--cert-file string: The absolute path to the certificate file. If you specify this option, you must also specify --key-file. You should only use --cert-file and --key-file if you have configured the Node Management Agent (NMA) to use custom certificates.

{ -d | --db-name } string: The name of the database. You should only use this option if you want to override the database name in your configuration file. This string must conform to the format used for database names.

--force-reinstall: Install the packages even if they are already installed.

{ -h | --help }: Prints help text.

--hosts strings: A comma-separated list of hosts in the database.

--ipv6: Specifies if the hosts use IPv6 addresses.
Default: IPv4

--key-file string: Path to the key file. If you specify this option, you must also specify --cert-file. You should only use --cert-file and --key-file if you have configured the Node Management Agent (NMA) to use custom certificates.

{ -l | --log-path } string: The absolute path for debug logs.
Default: /opt/vertica/log/vcluster.log

{ -o | --output-file } string: Writes the output to the specified file instead of STDOUT.
Default: STDOUT

--package string: Select packages using all, default, specific package name, or comma-separated list of package names.
Default: all

{ -p | --password } string: The database password.

--password-file string: The absolute path to a file containing the database password.
If you pass a dash(-) (that is, `--password-file -`), the password is read from STDIN.

Important
Your database password cannot include single quotes.

--read-password-from-prompt: Prompts the user to enter the password.

--tls-mode string: Sets the TLS validation mode. Valid options are enable, verify-ca, verify-full.
Default: enable

--use-password-for-sql-client-only: Use the password for the NMA SQL client only.

--verbose: Shows the details of VCluster run in the console.

Examples

To install default packages (when no --package flag is specified):

vcluster install_packages

To install default packages:

vcluster install_packages --package "default"

To install all packages:

vcluster install_packages --package "all"

To install a specific package:

vcluster install_packages --package ComplexTypes

To install multiple packages (comma-separated):

vcluster install_packages --package "ComplexTypes,kafka,logsearch"

To install default packages with user input:

  vcluster install_packages --db-name test_db \
    --hosts 192.0.2.0,192.0.2.1,192.0.2.2 \
    --password "PASSWORD"

To force (re)install default packages with config file

  vcluster install_packages --db-name test_db --force-reinstall \
    --config /opt/vertica/config/vertica_cluster.yaml \
    --password "PASSWORD"

Admin: list_all_nodes

Mon, 01 Jan 0001 00:00:00 +0000

Returns the following information on all nodes:

IP address
Name
State
Catalog path
Subcluster
Sandbox
Whether the subcluster is primary
Database version

The major states a node can be in are UP and DOWN. Other states are largely transitional.

Note

list_all_nodes returns the state UNKNOWN for nodes separated by a sandbox.

Syntax

vcluster list_all_nodes options

Required options

{ -c | --config } string: The path to the configuration file. If a configuration file is present in the default location (automatically generated by create_db), you do not need to specify this option.
Default: /opt/vertica/config/vertica_cluster.yaml

Options

--cert-file string: The absolute path to the certificate file. If you specify this option, you must also specify --key-file. You should only use --cert-file and --key-file if you have configured the Node Management Agent (NMA) to use custom certificates.

{ -h | --help }: Prints help text.

--ipv6: Specifies if the hosts use IPv6 addresses.
Default: IPv4

--key-file string: Path to the key file. If you specify this option, you must also specify --cert-file. You should only use --cert-file and --key-file if you have configured the Node Management Agent (NMA) to use custom certificates.

{ -l | --log-path } string: The absolute path for debug logs.
Default: /opt/vertica/log/vcluster.log

{ -o | --output-file } string: Writes the output to the specified file instead of STDOUT.
Default: STDOUT

{ -p | --password } string: The database password.

--password-file string: The absolute path to a file containing the database password.
If you pass a dash(-) (that is, `--password-file -`), the password is read from STDIN.

Important
Your database password cannot include single quotes.

--read-password-from-prompt: Prompts the user to enter the password.

--verbose: Shows the details of VCluster run in the console.

Examples

To list the status of nodes for a password-protected database:

$ vcluster list_allnodes --password testpassword \
  --config /opt/vertica/config/vertica_cluster.yaml

Admin: list_packages

Mon, 01 Jan 0001 00:00:00 +0000

Lists all available packages and their installation status. It automatically detects the database state:

Database UP: Displays the installation status of each package.
Database DOWN: Lists only the packages available on the filesystem.

Syntax

vcluster list_packages options

Options

--ca-cert-file string: The path to the trusted CA certificate file.
Default: /opt/vertica/config/https_certs/rootca.pem

--cert-file string: The path to the certificate file.
Default: /opt/vertica/config/https_certs/{username}.pem

{ -c | --config } string: The path to the configuration file. If a configuration file is present in the default location (automatically generated by create_db), you do not need to specify this option.
Default: /opt/vertica/config/vertica_cluster.yaml

{ -d | --db-name } string: The name of the database. You should only use this option if you want to override the database name in your configuration file. This string must conform to the format used for database names.

{ -h | --help }: Prints help text.

--hosts strings: A comma-separated list of hosts in the database.

--ipv6: Specifies if the hosts use IPv6 addresses.
Default: IPv4

--key-file string: Path to the key file. If you specify this option, you must also specify --cert-file. You should only use --cert-file and --key-file if you have configured the Node Management Agent (NMA) to use custom certificates.

{ -l | --log-path } string: The absolute path for debug logs.
Default: /opt/vertica/log/vcluster.log

{ -o | --output-file } string: Writes the output to the specified file instead of STDOUT.
Default: STDOUT

--package string: Select packages using all, default, specific package name, or comma-separated list of package names.
Default: all

{ -p | --password } string: The database password.

--password-file string: The absolute path to a file containing the database password.
If you pass a dash(-) (that is, `--password-file -`), the password is read from STDIN.

Important
Your database password cannot include single quotes.

--read-password-from-prompt: Prompts the user to enter the password.

--tls-mode string: Sets the TLS validation mode. Valid options are enable, verify-ca, verify-full.
Default: enable

--use-password-for-sql-client-only: Use the password for the NMA SQL client only.

--verbose: Shows the details of VCluster run in the console.

Examples

To list all the available packages:

vcluster list_packages

To list all the packages with installation status for a database:

vcluster list_packages --db-name test_db \
    --hosts 192.0.2.0,192.0.2.1,192.0.2.2 \
    --password <PASSWORD>

To list specfic packages with status:

vcluster list_packages \
    --package default \
    --config <config_file_path> \
    --password <PASSWORD>

Admin: manage_config

Mon, 01 Jan 0001 00:00:00 +0000

Displays the contents of or recreates the VCluster configuration file. The configuration file (/opt/vertica/config/vertica_cluster.yaml) is automatically generated when you use create_db.

Syntax

vcluster manage_config subcommand

Subcommands

recover: Recreates the VCluster configuration file based on the configuration of the database.
show: Shows the contents of the current configuration file.

Admin: re_ip

Mon, 01 Jan 0001 00:00:00 +0000

Updates the catalog with the IP addresses of your nodes when the database is stopped. You should run this command when the IP address for a node changes. For details, see Reconfiguring node messaging.

You should always stop the database before running re_ip.

Caution

Do not use re_ip when the database is up without support guidance. Improper use of this command can corrupt the catalog.

Syntax

vcluster re_ip options

Required options

{ -c | --config } string: The path to the configuration file. If a configuration file is present in the default location (automatically generated by create_db), you do not need to specify this option.
Default: /opt/vertica/config/vertica_cluster.yaml

--re-ip-file string

Path to a .json file that maps the old IP addresses to the new IP addresses. This file should only include the IP addresses of nodes that you want to update. This file has the following format:

[
  {"from_address": "10.20.30.40", "to_address": "10.20.30.41"},
  {"from_address": "10.20.30.42", "to_address": "10.20.30.43"}
]

Options

--cert-file string: The absolute path to the certificate file. If you specify this option, you must also specify --key-file. You should only use --cert-file and --key-file if you have configured the Node Management Agent (NMA) to use custom certificates.

--config-param PARAMETER=VALUE[,...]

A comma-separated list of PARAMETER=VALUE pairs. Parameters specified with this option override the ones in configuration files, if any, and take the following parameters:

AWSAuth
AWSEndpoint
AWSEnableHttps
AWSRegion

{ -h | --help }: Prints help text.

--ipv6: Specifies if the hosts use IPv6 addresses.
Default: IPv4

--key-file string: Path to the key file. If you specify this option, you must also specify --cert-file. You should only use --cert-file and --key-file if you have configured the Node Management Agent (NMA) to use custom certificates.

{ -l | --log-path } string: The absolute path for debug logs.
Default: /opt/vertica/log/vcluster.log

--verbose: Shows the details of VCluster run in the console.

Examples

To update the IP addresses with the information in /data/re_ip_map.json:

$ vcluster re_ip --db-name vertica_db --re-ip-file /data/re_ip_map.json

Admin: remove_node

Mon, 01 Jan 0001 00:00:00 +0000

Removes one or more nodes from a database.

You cannot remove nodes from a sandboxed subcluster.

Syntax

vcluster remove_node options

Required options

{ -c | --config } string: The path to the configuration file. If a configuration file is present in the default location (automatically generated by create_db), you do not need to specify this option.
Default: /opt/vertica/config/vertica_cluster.yaml

--remove strings[,...]: A comma-separated list of hosts to remove from the database.

Options

--cert-file string: The absolute path to the certificate file. If you specify this option, you must also specify --key-file. You should only use --cert-file and --key-file if you have configured the Node Management Agent (NMA) to use custom certificates.

--depot-path string: [Eon only] The absolute path to depot directory.

{ -h | --help }: Prints help text.

--ipv6: Specifies if the hosts use IPv6 addresses.
Default: IPv4

--key-file string: Path to the key file. If you specify this option, you must also specify --cert-file. You should only use --cert-file and --key-file if you have configured the Node Management Agent (NMA) to use custom certificates.

{ -l | --log-path } string: The absolute path for debug logs.
Default: /opt/vertica/log/vcluster.log

{ -p | --password } string: The database password.

--password-file string: The absolute path to a file containing the database password.
If you pass a dash(-) (that is, `--password-file -`), the password is read from STDIN.

Important
Your database password cannot include single quotes.

--read-password-from-prompt: Prompts the user to enter the password.

--verbose: Shows the details of VCluster run in the console.

Examples

To remove the nodes at 192.0.2.0 and 192.0.2.1:

$ vcluster remove_node --db-name vertica_db \
  --remove 192.0.2.0,192.0.2.1 \

Admin: remove_sucluster

Mon, 01 Jan 0001 00:00:00 +0000

Removes a non-sandboxed subcluster and its nodes from an Eon Mode database.

Syntax

vcluster remove_subcluster options

Required options

{ -c | --config } string: The path to the configuration file. If a configuration file is present in the default location (automatically generated by create_db), you do not need to specify this option.
Default: /opt/vertica/config/vertica_cluster.yaml

--subcluster string: Name of subcluster to remove.

Options

--cert-file string: The absolute path to the certificate file. If you specify this option, you must also specify --key-file. You should only use --cert-file and --key-file if you have configured the Node Management Agent (NMA) to use custom certificates.

--data-path string: The absolute path to the data directory. This should be the same for all nodes in the database.

--depot-path string: [Eon only] The absolute path to depot directory.

{ -h | --help }: Prints help text.

--ipv6: Specifies if the hosts use IPv6 addresses.
Default: IPv4

--key-file string: Path to the key file. If you specify this option, you must also specify --cert-file. You should only use --cert-file and --key-file if you have configured the Node Management Agent (NMA) to use custom certificates.

{ -l | --log-path } string: The absolute path for debug logs.
Default: /opt/vertica/log/vcluster.log

{ -p | --password } string: The database password.

--password-file string: The absolute path to a file containing the database password.
If you pass a dash(-) (that is, `--password-file -`), the password is read from STDIN.

Important
Your database password cannot include single quotes.

--read-password-from-prompt: Prompts the user to enter the password.

--verbose: Shows the details of VCluster run in the console.

Examples

To remove the subcluster sc1:

$ vcluster remove_subcluster --subcluster sc1 \
  --config /opt/vertica/config/vertica_cluster.yaml

Admin: replace_node

Mon, 01 Jan 0001 00:00:00 +0000

Replaces an existing database node with a new node on a different host. This command can be used to recover from a node failure or to migrate a node to another host. It is recommended to back up the database before running replace_node.

Syntax

vcluster replace_node options

Required options

--new-host string: The host that will replace the old host.
--original-host string: The original node being replaced.

Options

--ca-cert-file string: The path to the trusted CA certificate file.
Default: /opt/vertica/config/https_certs/rootca.pem

--cert-file string: The absolute path to the certificate file. If you specify this option, you must also specify --key-file. You should only use --cert-file and --key-file if you have configured the Node Management Agent (NMA) to use custom certificates.

{ -c | --config } string: The path to the configuration file. If a configuration file is present in the default location (automatically generated by create_db), you do not need to specify this option.
Default: /opt/vertica/config/vertica_cluster.yaml

--data-path string: The absolute path to the data directory. This should be the same for all nodes in the database.

{ -d | --db-name } string: The name of the database. You should only use this option if you want to override the database name in your configuration file. This string must conform to the format used for database names.

--depot-path string: [Eon only] The absolute path to depot directory.

--existing-hosts-ports string[,...]: A comma-separated list of node_address=port pairs to specify custom client ports for different nodes in the database.

{ -h | --help }: Prints help text.

--hosts strings: A comma-separated list of hosts in the database.

--ipv6: Specifies if the hosts use IPv6 addresses.
Default: IPv4

--is-numa: Indicates whether the database is configured with NUMA architecture.

--key-file string: Path to the key file. If you specify this option, you must also specify --cert-file. You should only use --cert-file and --key-file if you have configured the Node Management Agent (NMA) to use custom certificates.

{ -l | --log-path } string: The absolute path for debug logs.
Default: /opt/vertica/log/vcluster.log

{ -p | --password } string: The database password.

--password-file string: The absolute path to a file containing the database password.
If you pass a dash(-) (that is, `--password-file -`), the password is read from STDIN.

Important
Your database password cannot include single quotes.

--read-password-from-prompt: Prompts the user to enter the password.

--sandbox string: Specifies the name of the sandbox. Required when the original host belongs to a sandbox.

--timeout int: The time (in seconds) to wait for nodes to start up. Extend this value to allow additional time (for example, 3600 for one hour).
Default: 300

--tls-mode string: Sets the TLS validation mode. Valid options are enable, verify-ca, verify-full.
Default: enable

--use-password-for-sql-client-only: Use the password for the NMA SQL client only.

--verbose: Shows the details of VCluster run in the console.

Examples

To replace a database node:

  vcluster replace_node --original-host 10.20.30.43 \
    --new-host 10.20.30.44

To replace a database node with a database configuration file:

  vcluster replace_node --original-host 10.20.30.43 \
    --new-host 10.20.30.44 \
    --config /opt/vertica/config/vertica_cluster.yaml

To replace a database node in a sandbox:

  vcluster replace_node --original-host 10.20.30.43 \
    --new-host 10.20.30.44 \
    --sandbox sand

Admin: return_epoch

Mon, 01 Jan 0001 00:00:00 +0000

Returns the last good epoch.

Syntax

vcluster return_epoch options

Options

--ca-cert-file string: The path to the trusted CA certificate file.
Default: /opt/vertica/config/https_certs/rootca.pem

--catalog-path string: The absolute path to the catalog directory.

--cert-file string: The path to the certificate file.
Default: /opt/vertica/config/https_certs/{username}.pem

{ -c | --config } string: The path to the configuration file. If a configuration file is present in the default location (automatically generated by create_db), you do not need to specify this option.
Default: /opt/vertica/config/vertica_cluster.yaml

{ -d | --db-name } string: The name of the database. You should only use this option if you want to override the database name in your configuration file. This string must conform to the format used for database names.

--db-user string: The username for connecting to the database.

{ -h | --help }: Prints help text.

--hosts strings: A comma-separated list of hosts in the database.

--key-file string: Path to the key file. If you specify this option, you must also specify --cert-file. You should only use --cert-file and --key-file if you have configured the Node Management Agent (NMA) to use custom certificates.

{ -l | --log-path } string: The absolute path for debug logs.
Default: /opt/vertica/log/vcluster.log

{ -p | --password } string: The database password.

--password-file string: The absolute path to a file containing the database password.
If you pass a dash(-) (that is, `--password-file -`), the password is read from STDIN.

Important
Your database password cannot include single quotes.

--read-password-from-prompt: Prompts the user to enter the password.

--tls-mode string: Sets the TLS validation mode. Valid options are enable, verify-ca, verify-full.
Default: enable

--use-password-for-sql-client-only: Use the password for the NMA SQL client only.

--verbose: Shows the details of VCluster run in the console.

Examples

To return the last good epoch:

vcluster return_epoch

Admin: revive_db

Mon, 01 Jan 0001 00:00:00 +0000

Revives or restores an Eon Mode database. You cannot revive sandboxes with this command.

Note

After you revive your database, the next command you run should be start_db unless otherwise directed by the customer support team.

Syntax

vcluster revive_db options

Required options

If access to communal storage requires access keys, you must provide the keys with the --config-param option.

--communal-storage-location string: [Eon only] The absolute path of your communal storage location.

{ -d | --db-name } string: The name of the database. You should only use this option if you want to override the database name in your configuration file. This string must conform to the format used for database names.

--hosts strings: Comma-separated list of hosts in the database. The number of hosts that you provide must match the number of hosts in the existing database. You can omit the hosts only if --display-only is specified.

Options

--cert-file string: The absolute path to the certificate file. If you specify this option, you must also specify --key-file. You should only use --cert-file and --key-file if you have configured the Node Management Agent (NMA) to use custom certificates.

{ -c | --config } string: The path to write the configuration file.
Default: /opt/vertica/config/vertica_cluster.yaml

--config-param PARAMETER=VALUE[,...]

A comma-separated list of PARAMETER=VALUE pairs. Parameters specified with this option override the ones in configuration files, if any, and take the following parameters:

AWSAuth
AWSEndpoint
AWSEnableHttps
AWSRegion

--display-only: Shows information about the database in communal storage. If you specify this option, you can omit --hosts.
--force-removal: Deletes any existing database directories before reviving, excluding user storage directories.

{ -h | --help }: Prints help text.

--ignore-cluster-lease: Do not check for the existence of other clusters running on shared storage. If another system is using the same communal storage, using this option results in data corruption.
Default: Disabled

--ipv6: Specifies if the hosts use IPv6 addresses.
Default: IPv4

--key-file string: Path to the key file. If you specify this option, you must also specify --cert-file. You should only use --cert-file and --key-file if you have configured the Node Management Agent (NMA) to use custom certificates.

--load-catalog-timeout uint: The timeout, in seconds, for loading the remote catalog.
Default: 3600

{ -l | --log-path } string: The absolute path for debug logs.
Default: /opt/vertica/log/vcluster.log

{ -o | --output-file } string: Writes the output to the specified file instead of STDOUT.
Default: STDOUT

--restore-point-archive string: The name of the restore point archive to use for bootstrapping. If you specify this option, you must also specify --restore-point-id or -restore-point-index.
--restore-point-id string: The identifier of the restore point in the restore archive.
--restore-point-index int: The index of the restore point in the restore archive to restore from. Restore point indexes are one-indexed.

--verbose: Shows the details of VCluster run in the console.

Examples

To revive the database and write the configuration file to /opt/vertica/config/vertica_cluster.yaml:

$ vcluster revive_db --db-name vertica_db \
  --hosts 192.0.2.0,192.0.2.1,192.0.2.2 \
  --communal-storage-location /communal \
  --config /opt/vertica/config/vertica_cluster.yaml

To restore the database using the restore point archive db at index 1:

$ vcluster revive_db --db-name vertica_db \
  --hosts 192.0.2.0,192.0.2.1,192.0.2.2 \
  --communal-storage-location /communal \
  --config /opt/vertica/config/vertica_cluster.yaml --force-removal \
  --restore-point-archive db --restore-point-index 1

Admin: sandbox_subcluster

Mon, 01 Jan 0001 00:00:00 +0000

Sandboxes a subcluster in an Eon Mode database. All hosts in the subcluster must be up. When you sandbox a subcluster, its hosts immediately shut down and restart; the subcluster becomes sandboxed after the hosts start back up.

A sandbox can contain multiple subclusters, and subclusters in the sandbox can interact with each other. If you want to isolate subclusters, they must be in separate sandboxes.

Note

Subcluster sandboxing should be used for testing database changes or upgrades in a safe, isolated environment and should not be used for production subclusters. For example, you can create sandboxes and then upgrade OpenText™ Analytics Database in those sandboxes.

Syntax

vcluster sandbox_subcluster options

Required options

{ -c | --config } string: The path to the configuration file. If a configuration file is present in the default location (automatically generated by create_db), you do not need to specify this option.
Default: /opt/vertica/config/vertica_cluster.yaml

--sandbox string: The name of the sandbox. This string must conform to the format used for database names.
--subcluster string: The name of the subcluster to sandbox.

Options

--cert-file string: The absolute path to the certificate file. If you specify this option, you must also specify --key-file. You should only use --cert-file and --key-file if you have configured the Node Management Agent (NMA) to use custom certificates.

{ -h | --help }: Prints help text.

--ipv6: Specifies if the hosts use IPv6 addresses.
Default: IPv4

--key-file string: Path to the key file. If you specify this option, you must also specify --cert-file. You should only use --cert-file and --key-file if you have configured the Node Management Agent (NMA) to use custom certificates.

{ -l | --log-path } string: The absolute path for debug logs.
Default: /opt/vertica/log/vcluster.log

{ -p | --password } string: The database password.

--password-file string: The absolute path to a file containing the database password.
If you pass a dash(-) (that is, `--password-file -`), the password is read from STDIN.

Important
Your database password cannot include single quotes.

--read-password-from-prompt: Prompts the user to enter the password.

--verbose: Shows the details of VCluster run in the console.

Examples

To sandbox a subcluster sc1:

$ vcluster sandbox_subcluster --subcluster sc1 --sandbox sand \
  --hosts 192.0.2.0,192.0.2.1,192.0.2.2 --db-name test_db

Admin: scrutinize

Mon, 01 Jan 0001 00:00:00 +0000

Runs the scrutinize utility to collect diagnostic information about a database. The cusotmer support team might request you to run this utility when resolving a case.

By default, diagnostics are stored in a /tmp/scrutinize/VerticaScrutinize.timestamp.tar.

For details, see Running scrutinize.

Note

To run VCluster CLI commands from a different database node, use vcluster manage_config recover to create or refresh the vertica_cluster.yaml file on that host.

Syntax

vcluster scrutinize options

Required options

{ -c | --config } string: The path to the configuration file. If a configuration file is present in the default location (automatically generated by create_db), you do not need to specify this option.
Default: /opt/vertica/config/vertica_cluster.yaml

Options

--cert-file string: The absolute path to the certificate file. If you specify this option, you must also specify --key-file. You should only use --cert-file and --key-file if you have configured the Node Management Agent (NMA) to use custom certificates.

--db-slow: This is used when the database is very slow or when vsql is not responsive. This is equivalent to --type basic --vsql-off --log-limit 3 --log_age_hours 24 --no-active-queries --no-containers. Explicitly passed options take precedence over the default value passed in the wrapper argument.
--db-user string: The username of a database user.
--exclude-active-queries: Exclude information affected by currently running queries.
--exclude-containers: Excludes information in system tables that can scale with the number of ROS containers.
--external-tables: Debugging prest for external tables, database in Eon mode, and data lake. This is equivalent to --type context --external_table_details --log-limit 5 --log_age_hours 24 --save-system-table-as-parquet. Explicitly passed options take precedence over the default value passed in the wrapper argument.

{ -h | --help }: Prints help text.

--hot_deep: Second pass deep diagnostics on identified problem nodes. This is equivalent to --type context --log-limit 2 --log_age_hours 12 --no-containers --with-active-queries --save-system-table-as-parquet --hosts <node list>. Explicitly passed options take precedence over the default value passed in the wrapper argument.
--hot_min: Fastest possible diagnostic collection for very large clusters during P1 incidents. This is equivalent to --diagnostics --log-limit 1 --log_age_hours 6 --no-containers --no-active-queries --ignore-unreachable-nodes. Explicitly passed options take precedence over the default value passed in the wrapper argument.
--hot_sample: This is used when full cluster collection is too slow. Only selected nodes are scanned. This is equivalent to --diagnostics --log-limit 1 --log_age_hours 6 --no-containers --no-active-queries --hosts <node list>. Explicitly passed options take precedence over the default value passed in the wrapper argument.
--incident_min: Incident-minimal preset. logs + basic system outputs; avoids DB-heavy queries. This is equivalent to scrutinize --type basic --diagnostics --log-limit 2 --log_age_hours 12 --no-active-queries --no-containers. Explicitly passed options take precedence over the default value passed in the wrapper argument.
--incident_std: Incident-standard preset. support-friendly with controlled size. It includes system tables and some DATA_COLLECTOR tables. This is equivalent to --type context -X MemoryReportLog --log-limit 5 --log_age_hours 24 --by-minute=yes --no-containers --with-active-queries --save-system-table-as-parquet. Explicitly passed options take precedence over the default value passed in the wrapper argument.
--include-external-table-details: Include information about external tables. This option is computationally expensive.
--include-ros: Include information about ROS containers.
--include-udx-details: Include information describing all UDX functions. This option can be computationally expensive for Eon Mode databases.

--ipv6: Specifies if the hosts use IPv6 addresses.
Default: IPv4

--kafka: Focused diagnostic bundle for debugging Kafka pipelines. This is equivalent to --type context -X UdxLog,MemoryReportLog --log-limit 3 --log_age_hours 24 --no-containers. Explicitly passed options take precedence over the default value passed in the wrapper argument.

--key-file string: Path to the key file. If you specify this option, you must also specify --cert-file. You should only use --cert-file and --key-file if you have configured the Node Management Agent (NMA) to use custom certificates.

--log-age-hours int: The maximum age, in hours, of archived database log files to collect.
Default: 24
--log-age-newest-time YYYY-MM-DD HH [+|-XX]: Timestamp of the minimum age of archived database log files to collect with an optional UTC hour offset [+|-XX].
--log-age-oldest-time YYYY-MM-DD HH [+|-XX]: Timestamp of the maximum age of archived database log files to collect with an optional UTC hour offset [+/-XX].

{ -l | --log-path } string: The absolute path for debug logs.
Default: /opt/vertica/log/vcluster.log

--log-time-range="START" ["END"]: Collects logs only within a specific time range to reduce unnecessary data collection. This is equivalent to --udx --log-time-range="2026-03-01 10:00:00" "2026-03-01 11:00:00" -o /tmp/output. The format is "YYYY-MM-DD HH:MM:SS" ["YYYY-MM-DD HH:MM:SS"].

{ -p | --password } string: The database password.

--password-file string: The absolute path to a file containing the database password.
If you pass a dash(-) (that is, `--password-file -`), the password is read from STDIN.

Important
Your database password cannot include single quotes.

--perf: Performance diagnostics preset. Analyze query performance, system load, and runtime behavior while controlling the bundle size. This is equivalent to --type profiling --log-limit 5 --log_age_hours 24 --with-active-queries --by-minute=yes --no-containers --save-system-table-as-parquet. Explicitly passed options take precedence over the default value passed in the wrapper argument.
--perf_bysec: Performance diagnostics with per-second DC data for spike correlation. This is equivalent to scrutinize --type profiling --log-limit 5 --log_age_hours 12 --by-second --no-containers. Explicitly passed options take precedence over the default value passed in the wrapper argument.

--read-password-from-prompt: Prompts the user to enter the password.

--skip-collect-libraries: Skips gathering linked and catalog-shared libraries.
--split=SIZE: Splits large Scrutinize output tar files into smaller chunks for easier handling and reliable uploads. Using this option disables automatic S3 upload. SIZE must include an unit: B (bytes), M (MB), or G (GB). This is equivalent to --perf --split=2G -o /tmp/output. An example is --split 2G.
--storage: Analyze disk usage, ROS containers, and projection layout. This is equivalent to --type context -X Query --include-ros-info --no-active-queries --log-limit 3 --log_age_hours 24 --save-system-table-as-parquet. Explicitly passed options take precedence over the default value passed in the wrapper argument.
--tarball-name string: Name of the generated .tar.
Default: VerticaScrutinize.timestamp.tar
--udx: Focused diagnostic bundle for debugging user-defined extensions (UDx). This is equivalent to --type basic -X DC,SystemTable,CatalogObject,Query,KafkaLog,MemoryReportLog --log-limit 3 --log_age_hours 24. Explicitly passed options take precedence over the default value passed in the wrapper argument.

--verbose: Shows the details of VCluster run in the console.

Examples

Runs scrutinize on all nodes in the database:

$ vcluster scrutinize --db-name vertica_db --db-user dbadmin \
  --password testpassword --config /opt/vertica/config/vertica_cluster.yaml

Admin: show_restore_points

Mon, 01 Jan 0001 00:00:00 +0000

Shows restore points.

Syntax

vcluster show_restore_points options

Required options

{ -c | --config } string: The path to the configuration file. If a configuration file is present in the default location (automatically generated by create_db), you do not need to specify this option.
Default: /opt/vertica/config/vertica_cluster.yaml

Options

--cert-file string: The absolute path to the certificate file. If you specify this option, you must also specify --key-file. You should only use --cert-file and --key-file if you have configured the Node Management Agent (NMA) to use custom certificates.

--communal-storage-location string: [Eon only] The absolute path of your communal storage location.

--config-param PARAMETER=VALUE[,...]

A comma-separated list of PARAMETER=VALUE pairs. Parameters specified with this option override the ones in configuration files, if any, and take the following parameters:

AWSAuth
AWSEndpoint
AWSEnableHttps
AWSRegion

--end-timestamp string

Shows restore points up to and including the specified UTC timestamp in either date-time or date-only format. For example:

"2006-01-02 15:04:05"
"2006-01-02"
"2006-01-02 15:04:05.000000000"

{ -h | --help }: Prints help text.

--ipv6: Specifies if the hosts use IPv6 addresses.
Default: IPv4

--key-file string: Path to the key file. If you specify this option, you must also specify --cert-file. You should only use --cert-file and --key-file if you have configured the Node Management Agent (NMA) to use custom certificates.

{ -l | --log-path } string: The absolute path for debug logs.
Default: /opt/vertica/log/vcluster.log

{ -p | --password } string: The database password.

--password-file string: The absolute path to a file containing the database password.
If you pass a dash(-) (that is, `--password-file -`), the password is read from STDIN.

Important
Your database password cannot include single quotes.

--read-password-from-prompt: Prompts the user to enter the password.

--restore-point-archive string

Filter for restore point names that include the specified string.

--restore-point-id string

Filter for restore point IDs that include the specified ID.

--restore-point-index string

Filter for restore points indices that include the specified index.

--start-timestamp string

Shows restore points after and including the specified UTC timestamp in either date-time or date-only format. For example:

"2006-01-02 15:04:05"
"2006-01-02"
"2006-01-02 15:04:05.000000000"

--verbose: Shows the details of VCluster run in the console.

Examples

Show all restore points:

$ vcluster show_restore_points --db-name vertica_db \
  --config /opt/vertica/config/vertica_cluster.yaml

Show all restore points on an Eon Mode database:

$ vcluster show_restore_points --db-name vertica_db \
  --hosts 192.0.2.0,192.0.2.1,192.0.2.2 \
  --communal-storage-location /communal

Show restore points with the name db1:

$ vcluster show_restore_points --db-name test_db \
  --hosts 192.0.2.0,192.0.2.1,192.0.2.2 \
  --restore-point-archive db1

Show restore points on an Eon Mode database with the ID 34668031-c63d-4f3b-ba97-70223c4f97d6:

$ vcluster show_restore_points --db-name test_db \
  --hosts 192.0.2.0,192.0.2.1,192.0.2.2 \
  --communal-storage-location /communal \
  --restore-point-id 34668031-c63d-4f3b-ba97-70223c4f97d6

Show restore points on an Eon Mode database between 2024-03-04 08:32:33.277569 and 2024-03-04 08:32:34.176391:

$ vcluster show_restore_points --db-name test_db \
  --hosts 192.0.2.0,192.0.2.1,192.0.2.2 \
  --communal-storage-location /communal \
  --start-timestamp 2024-03-04 08:32:33.277569 \
  --end-timestamp 2024-03-04 08:32:34.176391

Admin: start_db

Mon, 01 Jan 0001 00:00:00 +0000

Starts a database and establishes cluster quorum.

The IP address provided for each node name must match the current IP address in the OpenText™ Analytics Database catalog. If the IPs do not match, you must first run re_ip to inform the database of the updated IP addresses.

If you pass the --hosts option a subset of all nodes in the cluster, only the specified nodes are started, and the specified subset must be a quorum of nodes.

Syntax

vcluster start_db options

Required options

{ -c | --config } string: The path to the configuration file. If a configuration file is present in the default location (automatically generated by create_db), you do not need to specify this option.
Default: /opt/vertica/config/vertica_cluster.yaml

Options

--ca-cert-file string: The path to the trusted CA certificate file.
Default: /opt/vertica/config/https_certs/rootca.pem

--catalog-path string: The absolute path to the catalog directory.

--cert-file string: The absolute path to the certificate file. If you specify this option, you must also specify --key-file. You should only use --cert-file and --key-file if you have configured the Node Management Agent (NMA) to use custom certificates.

--communal-storage-location string: [Eon only] The absolute path of your communal storage location.

--config-param PARAMETER=VALUE[,...]

A comma-separated list of PARAMETER=VALUE pairs. Parameters specified with this option override the ones in configuration files, if any, and take the following parameters:

AWSAuth
AWSEndpoint
AWSEnableHttps
AWSRegion

--config-param-file string: The absolute path to a file containing configuration parameters and their values.

--eon-mode: [Eon only] Indicates that the database is an Eon Mode database.

--epoch string: [Enterprise only] Specifies the epoch from which the database should start. If --epoch last is provided, the database starts from the last known good epoch.

Caution
This option may result in data loss.

{ -h | --help }: Prints help text.

--hosts strings: A comma-separated list of hosts in the database.

--ipv6: Specifies if the hosts use IPv6 addresses.
Default: IPv4

--key-file string: Path to the key file. If you specify this option, you must also specify --cert-file. You should only use --cert-file and --key-file if you have configured the Node Management Agent (NMA) to use custom certificates.

{ -l | --log-path } string: The absolute path for debug logs.
Default: /opt/vertica/log/vcluster.log

--main-cluster-only: Starts the database on a main cluster and does not start any sandboxes.

{ -p | --password } string: The database password.

--password-file string: The absolute path to a file containing the database password.
If you pass a dash(-) (that is, `--password-file -`), the password is read from STDIN.

Important
Your database password cannot include single quotes.

--read-password-from-prompt: Prompts the user to enter the password.

--sandbox string: Name of the sandbox to start.
--sync-catalog: Whether to sync the catalog after all nodes are up.

--timeout int: The time (in seconds) to wait for nodes to start up. Extend this value to allow additional time (for example, 3600 for one hour).
Default: 300

--tls-mode string: Sets the TLS validation mode. Valid options are enable, verify-ca, verify-full.
Default: enable

--use-password-for-sql-client-only: Use the password for the NMA SQL client only.

--verbose: Shows the details of VCluster run in the console.

Examples

To start a database

$ vcluster start_db --password my_password \
  --config /opt/vertica/config/vertica_cluster.yaml

To start a datbase from the last good epoch:

Return the last good epoch:

vcluster return_epoch

Start from the last good epoch:

vcluster start_db --epoch 1234

Admin: start_node

Mon, 01 Jan 0001 00:00:00 +0000

Starts nodes in a running cluster. This differs from start_db, which starts OpenText™ Analytics Database after cluster quorum is lost.

Syntax

vcluster restart_node options

Required options

{ -c | --config } string: The path to the configuration file. If a configuration file is present in the default location (automatically generated by create_db), you do not need to specify this option.
Default: /opt/vertica/config/vertica_cluster.yaml

One of --restart and --start-hosts is required.

--restart node_name=ip_address[,...]: A comma-separated list of node_name=ip_address pairs, specifying the nodes to restart. If ip_address doesn't match the database's listed IP address for that node, OpenText™ Analytics Database updates its catalog information for that node with the specified IP address and then restarts the node.
--start-hosts string[,...]: A comma-separated list of hosts to be restarted.

Options

--cert-file string: The absolute path to the certificate file. If you specify this option, you must also specify --key-file. You should only use --cert-file and --key-file if you have configured the Node Management Agent (NMA) to use custom certificates.

{ -h | --help }: Prints help text.

--ipv6: Specifies if the hosts use IPv6 addresses.
Default: IPv4

--key-file string: Path to the key file. If you specify this option, you must also specify --cert-file. You should only use --cert-file and --key-file if you have configured the Node Management Agent (NMA) to use custom certificates.

{ -l | --log-path } string: The absolute path for debug logs.
Default: /opt/vertica/log/vcluster.log

{ -p | --password } string: The database password.

--password-file string: The absolute path to a file containing the database password.
If you pass a dash(-) (that is, `--password-file -`), the password is read from STDIN.

Important
Your database password cannot include single quotes.

--read-password-from-prompt: Prompts the user to enter the password.

--timeout int: The time (in seconds) to wait for nodes to start up. Extend this value to allow additional time (for example, 3600 for one hour).
Default: 300

--verbose: Shows the details of VCluster run in the console.

Examples

To restart a node:

$ vcluster restart_node --db-name vertica_db \
    --restart v_vertica_db_node0004=192.0.2.0 --password my_password \
    --config /opt/vertica/config/vertica_cluster.yaml

To restart a single node and change its IP address in the database with config file (assuming the node IP address previously stored catalog was not 192.0.2.4):

$ vcluster restart_node --db-name vertica_db \
  --restart v_vertica_db_node0004=192.0.2.4 --password testpassword \
  --config /opt/vertica/config/vertica_cluster.yaml

To restart multiple nodes:

$   vcluster restart_node --db-name test_db \
  --restart v_test_db_node0003=192.0.2.3,v_test_db_node0004=192.0.2.4 \
  --password testpassword --config /opt/vertica/config/vertica_cluster.yaml

Admin: start_subcluster

Mon, 01 Jan 0001 00:00:00 +0000

Starts stopped nodes in a subcluster.

Syntax

vcluster start_subcluster options

Required options

{ -c | --config } string: The path to the configuration file. If a configuration file is present in the default location (automatically generated by create_db), you do not need to specify this option.
Default: /opt/vertica/config/vertica_cluster.yaml

--subcluster string: Name of subcluster to start

Options

--cert-file string: The absolute path to the certificate file. If you specify this option, you must also specify --key-file. You should only use --cert-file and --key-file if you have configured the Node Management Agent (NMA) to use custom certificates.

{ -h | --help }: Prints help text.

--ipv6: Specifies if the hosts use IPv6 addresses.
Default: IPv4

--key-file string: Path to the key file. If you specify this option, you must also specify --cert-file. You should only use --cert-file and --key-file if you have configured the Node Management Agent (NMA) to use custom certificates.

{ -l | --log-path } string: The absolute path for debug logs.
Default: /opt/vertica/log/vcluster.log

{ -p | --password } string: The database password.

--password-file string: The absolute path to a file containing the database password.
If you pass a dash(-) (that is, `--password-file -`), the password is read from STDIN.

Important
Your database password cannot include single quotes.

--read-password-from-prompt: Prompts the user to enter the password.

--timeout int: The time (in seconds) to wait for nodes to start up. Extend this value to allow additional time (for example, 3600 for one hour).
Default: 300

--verbose: Shows the details of VCluster run in the console.

Examples

To start a subcluster:

$ vcluster start_subcluster --subcluster sc1 \
  --config /opt/vertica/config/vertica_cluster.yaml

Admin: stop_db

Mon, 01 Jan 0001 00:00:00 +0000

Stops a database or sandbox.

Syntax

vcluster stop_db options

Required options

{ -c | --config } string: The path to the configuration file. If a configuration file is present in the default location (automatically generated by create_db), you do not need to specify this option.
Default: /opt/vertica/config/vertica_cluster.yaml

Options

--ca-cert-file string: The path to the trusted CA certificate file.
Default: /opt/vertica/config/https_certs/rootca.pem

--cert-file string: The absolute path to the certificate file. If you specify this option, you must also specify --key-file. You should only use --cert-file and --key-file if you have configured the Node Management Agent (NMA) to use custom certificates.

{ -d | --db-name } string: The name of the database. You should only use this option if you want to override the database name in your configuration file. This string must conform to the format used for database names.

--drain-seconds int: [Eon only] The time to wait, in seconds, for user connections to close on their own. When the time expires, user connections are automatically closed and the database is shut down. If set to 0, VCluster closes all user connections immediately. If the value is negative, VCluster waits indefinitely until all user connections close.
Default: 60

--eon-mode: [Eon only] Indicates that the database is an Eon Mode database.

--force-kill: Closes all active sessions before stopping the database.

{ -h | --help }: Prints help text.

--hosts strings: A comma-separated list of hosts in the database.

--if-no-users: Shuts down the database only if no users are currently connected. If any users are connected, the command exits with an error.

--ipv6: Specifies if the hosts use IPv6 addresses.
Default: IPv4

--key-file string: Path to the key file. If you specify this option, you must also specify --cert-file. You should only use --cert-file and --key-file if you have configured the Node Management Agent (NMA) to use custom certificates.

{ -l | --log-path } string: The absolute path for debug logs.
Default: /opt/vertica/log/vcluster.log

--main-cluster-only: Stops the database without stopping any sandboxed subclusters.

{ -p | --password } string: The database password.

--password-file string: The absolute path to a file containing the database password.
If you pass a dash(-) (that is, `--password-file -`), the password is read from STDIN.

Important
Your database password cannot include single quotes.

--read-password-from-prompt: Prompts the user to enter the password.

--sandbox string: Name of the sandbox to stop.
--sync-catalog: Specifies whether to sync the catalog before stopping the database.

--tls-mode string: Sets the TLS validation mode. Valid options are enable, verify-ca, verify-full.
Default: enable

--use-password-for-sql-client-only: Use the password for the NMA SQL client only.

--verbose: Shows the details of VCluster run in the console.

Examples

To stop a database with default drain timeout (60 seconds):

vcluster stop_db

To stop a database with config file using password authentication with user-specified drain seconds:

  vcluster stop_db --password "PASSWORD" \
    --config /opt/vertica/config/vertica_cluster.yaml --drain-seconds 10

To stop a database if no users are connected:

vcluster stop_db --if-no-users

To close all active sessions before stopping the database:

vcluster stop_db --force-kill

To stop a database with config file using password authentication and close all active sessions before stopping the database:

  vcluster stop_db --password "PASSWORD" \
    --config /opt/vertica/config/vertica_cluster.yaml
    --force-kill

Admin: stop_node

Mon, 01 Jan 0001 00:00:00 +0000

Stops one or more nodes in a database.

You must provide the host list with the --stop-hosts option followed by one or more hosts to stop as a comma-separated list.

Caution

If you only have just enough nodes up to establish database quorum and you stop a node, you will lose database quorum and the remaining up nodes will be set to read-only mode to prevent data loss.

Syntax

vcluster stop_node options

Required options

{ -c | --config } string: The path to the configuration file. If a configuration file is present in the default location (automatically generated by create_db), you do not need to specify this option.
Default: /opt/vertica/config/vertica_cluster.yaml

--stop-hosts string: Comma-separated list of host(s) to stop.

Options

--ca-cert-file string: The path to the trusted CA certificate file.
Default: /opt/vertica/config/https_certs/rootca.pem

--cert-file string: The absolute path to the certificate file. If you specify this option, you must also specify --key-file. You should only use --cert-file and --key-file if you have configured the Node Management Agent (NMA) to use custom certificates.

{ -d | --db-name } string: The name of the database. You should only use this option if you want to override the database name in your configuration file. This string must conform to the format used for database names.

--force-kill: Forces node termination using SIGKILL instead of a graceful shutdown (SIGTERM).

Caution
This option may cause data loss. Use it only if a graceful shutdown fails.

{ -h | --help }: Prints help text.

--hosts strings: A comma-separated list of hosts in the database.

--ipv6: Specifies if the hosts use IPv6 addresses.
Default: IPv4

--key-file string: Path to the key file. If you specify this option, you must also specify --cert-file. You should only use --cert-file and --key-file if you have configured the Node Management Agent (NMA) to use custom certificates.

{ -l | --log-path } string: The absolute path for debug logs.
Default: /opt/vertica/log/vcluster.log

{ -p | --password } string: The database password.

--password-file string: The absolute path to a file containing the database password.
If you pass a dash(-) (that is, `--password-file -`), the password is read from STDIN.

Important
Your database password cannot include single quotes.

--read-password-from-prompt: Prompts the user to enter the password.

--tls-mode string: Sets the TLS validation mode. Valid options are enable, verify-ca, verify-full.
Default: enable

--use-password-for-sql-client-only: Use the password for the NMA SQL client only.

--verbose: Shows the details of VCluster run in the console.

Examples

Stop the node on 192.0.2.0 and 192.0.2.1:

$ vcluster stop_node --stop-hosts 192.0.2.0,192.0.2.1 \
  --config /home/dbadmin/vertica_cluster.yaml

Admin: stop_subcluster

Mon, 01 Jan 0001 00:00:00 +0000

Stops a subcluster and all its hosts.

Syntax

vcluster stop_subcluster options

Required options

{ -c | --config } string: The path to the configuration file. If a configuration file is present in the default location (automatically generated by create_db), you do not need to specify this option.
Default: /opt/vertica/config/vertica_cluster.yaml

--subcluster string: The name of the subcluster to stop.

Options

--cert-file string: The absolute path to the certificate file. If you specify this option, you must also specify --key-file. You should only use --cert-file and --key-file if you have configured the Node Management Agent (NMA) to use custom certificates.

--drain-seconds int: [Eon only] The time to wait, in seconds, for user connections to close on their own. When the time expires, user connections are automatically closed and the database is shut down. If set to 0, VCluster closes all user connections immediately. If the value is negative, VCluster waits indefinitely until all user connections close.
Default: 60

--force: Shut down the subcluster immediately even if users are connected.

{ -h | --help }: Prints help text.

--ipv6: Specifies if the hosts use IPv6 addresses.
Default: IPv4

--key-file string: Path to the key file. If you specify this option, you must also specify --cert-file. You should only use --cert-file and --key-file if you have configured the Node Management Agent (NMA) to use custom certificates.

{ -l | --log-path } string: The absolute path for debug logs.
Default: /opt/vertica/log/vcluster.log

{ -p | --password } string: The database password.

--password-file string: The absolute path to a file containing the database password.
If you pass a dash(-) (that is, `--password-file -`), the password is read from STDIN.

Important
Your database password cannot include single quotes.

--read-password-from-prompt: Prompts the user to enter the password.

--verbose: Shows the details of VCluster run in the console.

Examples

Stops the subcluster sc1, waiting 10 seconds for user connections to close:

$ vcluster stop_subcluster --subcluster sc1 --drain-seconds 10 \
  --config /opt/vertica/config/vertica_cluster.yaml

Admin: uninstall_packages

Mon, 01 Jan 0001 00:00:00 +0000

Uninstalls packages from /opt/vertica/packages to remove unused or problematic packages, clean up before reinstalling, or reduce database size.

Syntax

vcluster uninstall_packages options

Options

--ca-cert-file string: The path to the trusted CA certificate file.
Default: /opt/vertica/config/https_certs/rootca.pem

--cert-file string: The path to the certificate file.
Default: /opt/vertica/config/https_certs/{username}.pem

{ -c | --config } string: The path to the configuration file. If a configuration file is present in the default location (automatically generated by create_db), you do not need to specify this option.
Default: /opt/vertica/config/vertica_cluster.yaml

{ -d | --db-name } string: The name of the database. You should only use this option if you want to override the database name in your configuration file. This string must conform to the format used for database names.

{ -h | --help }: Prints help text.

--hosts strings: A comma-separated list of hosts in the database.

--ipv6: Specifies if the hosts use IPv6 addresses.
Default: IPv4

--key-file string: Path to the key file. If you specify this option, you must also specify --cert-file. You should only use --cert-file and --key-file if you have configured the Node Management Agent (NMA) to use custom certificates.

{ -l | --log-path } string: The absolute path for debug logs.
Default: /opt/vertica/log/vcluster.log

{ -o | --output-file } string: Writes the output to the specified file instead of STDOUT.
Default: STDOUT

--package string: Select packages using all, default, specific package name, or comma-separated list of package names.
Default: all

{ -p | --password } string: The database password.

--password-file string: The absolute path to a file containing the database password.
If you pass a dash(-) (that is, `--password-file -`), the password is read from STDIN.

Important
Your database password cannot include single quotes.

--read-password-from-prompt: Prompts the user to enter the password.

--tls-mode string: Sets the TLS validation mode. Valid options are enable, verify-ca, verify-full.
Default: enable

--use-password-for-sql-client-only: Use the password for the NMA SQL client only.

--verbose: Shows the details of VCluster run in the console.

Examples

To uninstall all available packages (default):

vcluster uninstall_packages

To uninstall default packages:

vcluster uninstall_packages --package "default"

To uninstall all packages:

vcluster uninstall_packages --package "all"

To uninstall a specific package:

vcluster uninstall_packages --package "ComplexTypes"

To uninstall multiple packages (comma-separated):

vcluster uninstall_packages --package "ComplexTypes,kafka,logsearch"

To uninstall all packages using database and host name:

vcluster uninstall_packages --db-name test_db \
    --hosts 192.0.2.0,192.0.2.1,192.0.2.2 \
    --password <PASSWORD>

Admin: unsandbox_subcluster

Mon, 01 Jan 0001 00:00:00 +0000

Removes a subcluster from the sandbox, "unsandboxing" it. When you unsandbox a subcluster, its hosts immediately shut down and restart. When the hosts come back up, the subcluster is unsandboxed.

When a subcluster is unsandboxed, you should manually delete that subcluster's metadata in communal storage before attempting to add a subcluster to that sandbox again. For example, if you unsandbox subcluster sc1, you should delete the directory path_to_catalog_of_sc1/metadata/sandbox_name.

Syntax

$ vcluster unsandbox_subcluster options

Required options

{ -c | --config } string: The path to the configuration file. If a configuration file is present in the default location (automatically generated by create_db), you do not need to specify this option.
Default: /opt/vertica/config/vertica_cluster.yaml

--subcluster string: The name of the subcluster to be unsandboxed.

Options

--cert-file string: The absolute path to the certificate file. If you specify this option, you must also specify --key-file. You should only use --cert-file and --key-file if you have configured the Node Management Agent (NMA) to use custom certificates.

{ -h | --help }: Prints help text.

--hosts strings: A comma-separated list of hosts in the database. This must include at least one up host from the primary subcluster.

--ipv6: Specifies if the hosts use IPv6 addresses.
Default: IPv4

--key-file string: Path to the key file. If you specify this option, you must also specify --cert-file. You should only use --cert-file and --key-file if you have configured the Node Management Agent (NMA) to use custom certificates.

{ -l | --log-path } string: The absolute path for debug logs.
Default: /opt/vertica/log/vcluster.log

{ -p | --password } string: The database password.

--password-file string: The absolute path to a file containing the database password.
If you pass a dash(-) (that is, `--password-file -`), the password is read from STDIN.

Important
Your database password cannot include single quotes.

--read-password-from-prompt: Prompts the user to enter the password.

--verbose: Shows the details of VCluster run in the console.

Examples

To unsandbox subcluster sc1:

$ vcluster unsandbox_subcluster --subcluster sc1 \
  --hosts 192.0.2.0,192.0.2.1,192.0.2.2 --db-name vertica_db

Admin: upgrade_license

Mon, 01 Jan 0001 00:00:00 +0000

Upgrades the database license by applying a new license file to an existing database or replacing an expired license.

Syntax

vcluster upgrade_license options

Required options

--license-file string: Absolute path of the license file.

Options

--ca-cert-file string: The path to the trusted CA certificate file.
Default: /opt/vertica/config/https_certs/rootca.pem

--cert-file string: The path to the certificate file.
Default: /opt/vertica/config/https_certs/{username}.pem

{ -c | --config } string: The path to the configuration file. If a configuration file is present in the default location (automatically generated by create_db), you do not need to specify this option.
Default: /opt/vertica/config/vertica_cluster.yaml

{ -d | --db-name } string: The name of the database. You should only use this option if you want to override the database name in your configuration file. This string must conform to the format used for database names.

{ -h | --help }: Prints help text.

--hosts strings: A comma-separated list of hosts in the database.

--ipv6: Specifies if the hosts use IPv6 addresses.
Default: IPv4

--key-file string: Path to the key file. If you specify this option, you must also specify --cert-file. You should only use --cert-file and --key-file if you have configured the Node Management Agent (NMA) to use custom certificates.

--license-host string: The host where the license file is located.

{ -l | --log-path } string: The absolute path for debug logs.
Default: /opt/vertica/log/vcluster.log

{ -p | --password } string: The database password.

--password-file string: The absolute path to a file containing the database password.
If you pass a dash(-) (that is, `--password-file -`), the password is read from STDIN.

Important
Your database password cannot include single quotes.

--read-password-from-prompt: Prompts the user to enter the password.

--tls-mode string: Sets the TLS validation mode. Valid options are enable, verify-ca, verify-full.
Default: enable

--use-password-for-sql-client-only: Use the password for the NMA SQL client only.

--verbose: Shows the details of VCluster run in the console.

Examples

To upgrade a license:

vcluster upgrade_license --license-file LICENSE_FILE --license-host HOST_OF_LICENSE_FILE

To upgrade a license using the database password:

vcluster upgrade_license --license-file LICENSE_FILE --license-host HOST_OF_LICENSE_FILE  --password "PASSWORD"

OpenText Analytics Database 26.2.x – VCluster commands

Admin: add_node

Syntax

Required options

Options

Important

Examples

Admin: add_subcluster

Syntax

Required options

Options

Important

Examples

Admin: completion

Syntax

Subcommands options

Examples

Admin: create_db

Syntax

Required options

Eon options

Options

Important

Examples

Admin: drop_db

Syntax

Required options

Options

Examples

Admin: help

Syntax

Commands

Options

Admin: install_packages

Syntax

Required options

Options

Important

Examples

Admin: list_all_nodes

Note

Syntax

Required options

Options

Important

Examples

Admin: list_packages

Syntax

Options

Important

Examples

Admin: manage_config

Syntax

Subcommands

Admin: re_ip

Caution

Syntax

Required options

Options

Examples

Admin: remove_node

Syntax

Required options

Options

Important

Examples

Admin: remove_sucluster

Syntax

Required options

Options

Important

Examples

Admin: replace_node

Syntax

Required options

Options

Important

Examples

Admin: return_epoch

Syntax