OpenText Analytics Database 26.2.x – Database management with VCluster CLI

Admin: Common administrative tasks

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

Stop, restart, and revive

This procedure can be useful in cases where you want to change AWS instances to save money. For example, you can use us-east instances during the day and switch to us-west instances at night.

This example uses the database created by the following command using the region us-east-1:

$ vcluster create_db --db-name test_db --hosts 192.2.0.1,192.2.0.2,192.2.0.3 --catalog-path /scratch_b/qa --data-path /scratch_b/qa --shard-count 4 --communal-storage-location s3://testbucket/test_db --depot-path /path/to/depot --depot-size 20G --config /opt/vertica/config/vertica_cluster.yaml --config-param awsauth=key:secret,awsenablehttps=0,awsregion=us-east-1,awsendpoint=myhost:9000 --password "" --skip-package-install
✔ Check NMA service health
...
✔ Synchronize catalog with communal storage
[INFO] Successfully created a database with name [test_db]

Note

When the OpenText™ Analytics Database host is stopped and restarted, you must restart the NMA to ensure proper functionality.

Stop the database:

$ Stop DB
/opt/vertica/bin/vcluster stop_db --db-name test_db --config /opt/vertica/config/vertica_cluster.yaml --password ""
✔ Collect node information
✔ Collect cluster information
✔ Update node state from running database
✔ Collect information for all up nodes
✔ Synchronize catalog with communal storage
✔ Stop database
✔ Verify database is not running
[INFO] Successfully stopped a database with name test_db

Revive the database. For this example, the database is revived into a different region:

$ vcluster revive_db --db-name test_db --hosts 192.2.0.1,192.2.0.2,192.2.0.3 --communal-storage-location s3://testbucket/test_db --config /opt/vertica/config/vertica_cluster.yaml --config-param awsauth=key:secret,awsenablehttps=0,awsregion=us-west-1,awsendpoint=myhost:9000
✔ Check NMA service health
✔ Verify database is running
✔ Download cluster_config.json
✔ Create necessary directories on database hosts
✔ Get network profile of cluster
✔ Load remote catalog
[INFO] Successfully revived database test_db

Start the database:

$ /opt/vertica/bin/vcluster start_db --db-name test_db --hosts 192.2.0.1,192.2.0.2,192.2.0.3 --catalog-path /path/to/catalog --config /opt/vertica/config/vertica_cluster.yaml --config-param awsauth=miniokey:miniosecret,awsenablehttps=0,awsregion=us-east-1,awsendpoint=qastress-39:9000 --password ""
✔ Check NMA service health
✔ Collect nodes information
✔ Download cluster_config.json
✔ Check NMA service health
✔ Verify database is running
✔ Read catalog
✔ Check Vertica version
✔ Get contents of vertica.conf
✔ Get contents of spread.conf
✔ Start 3 node(s)
✔ Wait for 3 node(s) to come up: all nodes are up
✔ Synchronize catalog with communal storage
✔ Collect node information
✔ Collect cluster information
✔ Update node state from running database
[INFO] Started database test_db

Test on sandboxed subclusters

You can create sandboxed subclusters and perform tests on them without affecting your production database. For details, see Subcluster sandboxing:

Add the subcluster sc1 which contains nodes 192.2.0.4 and 192.2.0.5:

$ vcluster add_subcluster  --subcluster sc1 --db-name test_db --password "" --hosts 192.2.0.1,192.2.0.2,192.2.0.3 --control-set-size 1 --new-hosts 192.2.0.4,192.2.0.5
✔ Collect cluster information
✔ Check NMA service health
...
✔ Initiate rebalance of subcluster shards
[INFO] Successfully added subcluster sc1 with nodes [192.2.0.3,192.2.0.4] to database **test_db**

Sandbox the subcluster sc1 with a the new sandbox sand:

$ vcluster sandbox_subcluster --subcluster sc1 --sandbox sand -p "" --config /opt/vertica/config/vertica_cluster.yaml
✔ Collect information for all up nodes
✔ Find all subclusters and record their sandboxing information
✔ Convert subcluster into sandbox in catalog system
✔ Wait for subcluster nodes to come up
[INFO] Successfully sandboxed subcluster sc1 as sand

Verify that your nodes were sandboxed with list_all_nodes. The following command is run from outside the sandbox sand, so the state of nodes in sand are listed as UNKNOWN:

$ vcluster list_all_nodes --config /opt/vertica/config/vertica_cluster.yaml -p ""
✔ Collect node information
✔ Collect cluster information
✔ Update node state from running database
✔ Check NMA service health
✔ Read Vertica version
✔ Check node state from running database
[
{
"address": "192.0.2.1",
"name": "v_test_db_node0001",
"state": "UP",
"catalog_path": "/scratch_b/qa/test_db/v_test_db_node0001_catalog/Catalog",
"subcluster": "default_subcluster",
"sandbox": "",
"is_primary": true,
"version": "v24.3.0-20240613"
},
{
"address": "192.0.2.2",
"name": "v_test_db_node0002",
"state": "UP",
"catalog_path": "/scratch_b/qa/test_db/v_test_db_node0002_catalog/Catalog",
"subcluster": "default_subcluster",
"sandbox": "",
"is_primary": true,
"version": "v24.3.0-20240613"
},
{
"address": "192.0.2.3",
"name": "v_test_db_node0003",
"state": "UP",
"catalog_path": "/scratch_b/qa/test_db/v_test_db_node0003_catalog/Catalog",
"subcluster": "default_subcluster",
"sandbox": "",
"is_primary": true,
"version": "v24.3.0-20240613"
},
{
"address": "192.0.2.4",
"name": "v_test_db_node0004",
"state": "UNKNOWN",
"catalog_path": "/scratch_b/qa/test_db/v_test_db_node0004_catalog/Catalog",
"subcluster": "sc1",
"sandbox": "sand",
"is_primary": false,
"version": "v24.3.0-20240613"
},
{
"address": "192.0.2.5",
"name": "v_test_db_node0005",
"state": "UNKNOWN",
"catalog_path": "/scratch_b/qa/test_db/v_test_db_node0005_catalog/Catalog",
"subcluster": "sc1",
"sandbox": "sand",
"is_primary": false,
"version": "v24.3.0-20240613"
}
]
[INFO] Successfully listed all nodes

After you finish testing your sandboxed subcluster, unsandbox it:

$ vcluster unsandbox_subcluster --subcluster sc1 -p "" --config /opt/vertica/config/vertica_cluster.yaml
✔ Collect node information
✔ Collect cluster information
✔ Update node state from running database
✔ Check NMA service health
✔ Collect information for all up nodes
✔ Stop node
✔ Wait for subcluster nodes to come down
✔ Convert sandboxed subcluster into regular subcluster in catalog
✔ Delete database directories
✔ Check Vertica version
✔ Get startup command for unsandboxed nodes
✔ Start 0 node(s)
✔ Wait for subcluster nodes to come up
[INFO] Successfully unsandboxed subcluster sc1

Admin: NUMA multi-node clusters

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

VCluster CLI supports managing NUMA (Non-Uniform Memory Access) multi-node clusters, where multiple database nodes run on the same physical host, each on a different client port. This works both on real multi-node NUMA hardware and in standard environments where multiple nodes share a single host.

Note

Only add_node, remove_node, and list_all_nodes are supported in NUMA multi-node environments. Support for sandbox and compute node operations is planned for a future release.

Prerequisites

TLS must be configured so that commands can run without supplying a password.
The configuration file must be at the default location (/opt/vertica/config/vertica_cluster.yaml), or you must supply its path with --config.

Create a database

You cannot create a database using the NUMA workflow. Create your database using the standard create_db workflow. After creation, use the commands in the following sections to add and remove nodes.

Note

VCluster CLI automatically detects whether the environment is NUMA by checking the command input (such as --new-hosts-ports or --existing-hosts-ports) or the configuration file.

Control node

Each host running NUMA nodes has one control node. The control node is always the first node added to that host and is responsible for distributing information to the other nodes on the host. Because of the control node, all nodes on the host must be part of the same subcluster.

Add nodes

To add a node at a custom client port using the configuration file:

$ vcluster add_node --new-hosts-ports 10.20.30.40=6433

To add a node when no configuration file is available, specify the existing cluster hosts and their ports alongside the new host:

$ vcluster add_node --existing-hosts-ports 10.20.30.40=5433,10.20.30.41=5433 \
  --new-hosts-ports 10.20.30.42=5678

To add a node into an existing subcluster:

$ vcluster add_node --new-hosts-ports 10.20.30.40=6433 --subcluster sc1

Note

You cannot create a new subcluster using the NUMA architecture at this moment in time. To add NUMA nodes to a new subcluster, first use add_subcluster to create it, then add nodes to it.

To use a NUMA node configuration file, pass it with --numa-node-file. You can target a specific subcluster or add to the default subcluster:

# Add into subcluster sc1
$ vcluster add_node --numa-node-file ./numanodeconfig.json --subcluster sc1

# Add into the default subcluster
$ vcluster add_node --numa-node-file ./numanodeconfig.json

The --numa-node-file option accepts a JSON file with the following format:

{
  "nodes": [
    {
      "host": "192.168.1.101",
      "clientPort": 5678,
      "numaMode": "auto"
    },
    {
      "host": "192.168.1.102",
      "clientPort": 5678,
      "numaMode": 1
    }
  ]
}

Each node entry supports the following properties:

Property	Required	Default	Description
`host`	Yes	—	The IP address or hostname of the node.
`clientPort`	No	`5433`	The client port for the node.
`numaMode`	No	`null`	Controls NUMA node assignment. Accepted values: a non-negative integer (specific NUMA node index), `"auto"` (selects the least-busy NUMA node), or omitted (no NUMA pinning; standard `add_node` workflow).

Remove nodes

Each node has a unique name identifier (for example, v_dbname_node0001). When nodes run on custom ports, remove them by node name rather than by IP address:

$ vcluster remove_node --remove-node-names v_test_db_node0004

To remove a node by name when no configuration file is available:

$ vcluster remove_node \
  --existing-hosts-ports 10.20.30.40=5433,10.20.30.41=5433,10.20.30.42=5678 \
  --remove-node-names v_test_db_node0003

Note

You cannot remove an entire subcluster using the NUMA workflow at this moment in time. To remove a subcluster, first remove all of its nodes with remove_node, then drop the now-empty subcluster from vsql:

DROP SUBCLUSTER sc1;

List nodes

To list all nodes using the configuration file:

$ vcluster list_all_nodes

To list nodes when no configuration file is available:

$ vcluster list_all_nodes --existing-hosts-ports 10.20.30.40=5433,10.20.30.41=5433,10.20.30.42=5678

Example

The following example walks through a complete NUMA workflow: creating a database, adding nodes on custom ports (including a second node on an existing host), confirming the cluster state, and removing a node.

1. Create the database.

$ vcluster create_db --db-name test_db \
    --hosts 10.20.30.40,10.20.30.41 \
    --catalog-path /data --data-path /data \
    --password-file /password.txt

2. Add two nodes at custom ports on separate hosts.

$ vcluster add_node --new-hosts-ports 10.20.30.40=6433,10.20.30.41=7433

3. Add another node on the same host as the first node, on a different port.

$ vcluster add_node --new-hosts-ports 10.20.30.40=6533

4. Confirm that all nodes are present.

$ vcluster list_all_nodes

5. Remove the node added in step 3.

$ vcluster remove_node --remove-node-names v_test_db_node0003

Admin: VCluster commands

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

This section contains reference material and simple examples for various vcluster commands. These examples assume that you have fulfilled the prerequisites for using vcluster. For more detailed examples, see Common administrative tasks.

You can also use the --help flag on any command or vcluster itself to view the manual.

For the vcluster manual:

$ vcluster --help

For help with any given command, use vcluster command --help or vcluster help command. For example:

$ vcluster create_db --help
$ vcluster help create_db