Sync from server repo (1f7eafd6a20)

vclusterops/adapter_pool.go

@@ -85,7 +85,7 @@ func (pool *adapterPool) sendRequest(httpRequest *clusterHTTPRequest) error {
 	if pool.logger.ForCli {
 		// use context to check whether a step has completed
 		ctx, cancelCtx := context.WithCancel(context.Background())
-		go progressCheck(ctx, httpRequest.Name)
+		go progressCheck(ctx, httpRequest.Name, pool.logger)
 		// cancel the progress check context when the result channel is closed
 		defer cancelCtx()
 	}
@@ -115,7 +115,7 @@ func (pool *adapterPool) sendRequest(httpRequest *clusterHTTPRequest) error {
 
 // progressCheck checks whether a step (operation) has been completed.
 // Elapsed time of the step in seconds will be displayed.
-func progressCheck(ctx context.Context, name string) {
+func progressCheck(ctx context.Context, name string, logger vlog.Printer) {
 	const progressCheckInterval = 5
 	startTime := time.Now()
 
@@ -131,7 +131,7 @@ func progressCheck(ctx context.Context, name string) {
 			return
 		case tickTime := <-ticker.C:
 			elapsedTime := tickTime.Sub(startTime)
-			vlog.PrintWithIndent("[%s] is still running. %.f seconds spent at this step.",
+			logger.PrintWithIndent("[%s] is still running. %.f seconds spent at this step.",
 				name, elapsedTime.Seconds())
 		}
 	}

vclusterops/add_node.go

@@ -23,25 +23,17 @@ import (
 	"github.com/vertica/vcluster/vclusterops/vlog"
 )
 
-// VAddNodeOptions are the option arguments for the VAddNode API
+// VAddNodeOptions represents the available options for VAddNode.
 type VAddNodeOptions struct {
 	DatabaseOptions
-	// Hosts to add to database
-	NewHosts []string
-	// Name of the subcluster that the new nodes will be added to
-	SCName *string
-	// A primary up host that will be used to execute
-	// add_node operations.
-	Initiator string
-	DepotSize *string // like 10G
-	// Skip rebalance shards if true
-	SkipRebalanceShards *bool
-	// Use force remove if true
-	ForceRemoval *bool
-
-	// Names of the existing nodes in the cluster.
-	// This options can be used to remove partially added nodes from catalog.
-	ExpectedNodeNames []string
+	NewHosts            []string // Hosts to add to database
+	SCName              *string  // Name of the subcluster that the new nodes will be added to
+	Initiator           string   // A primary up host that will be used to execute add_node operations.
+	DepotSize           *string  // Depot size, e.g. 10G
+	SkipRebalanceShards *bool    // Skip rebalance shards if true
+	ForceRemoval        *bool    // Use force remove if true
+	ExpectedNodeNames   []string // Names of the existing nodes in the cluster. This option can be
+	// used to remove partially added nodes from catalog.
 }
 
 func VAddNodeOptionsFactory() VAddNodeOptions {
@@ -119,7 +111,8 @@ func (o *VAddNodeOptions) validateAnalyzeOptions(logger vlog.Printer) error {
 	return o.analyzeOptions()
 }
 
-// VAddNode is the top-level API for adding node(s) to an existing database.
+// VAddNode adds one or more nodes to an existing database.
+// It returns a VCoordinationDatabase that contains catalog information and any error encountered.
 func (vcc *VClusterCommands) VAddNode(options *VAddNodeOptions) (VCoordinationDatabase, error) {
 	vdb := makeVCoordinationDatabase()
 

vclusterops/add_subcluster.go

@@ -176,7 +176,8 @@ func (options *VAddSubclusterOptions) validateAnalyzeOptions(config *ClusterConf
 	return options.analyzeOptions()
 }
 
-// VAddSubcluster can add a new subcluster to a running database
+// VAddSubcluster adds to a running database a new subcluster with provided options.
+// It returns any error encountered.
 func (vcc *VClusterCommands) VAddSubcluster(options *VAddSubclusterOptions) error {
 	/*
 	 *   - Produce Instructions

vclusterops/cluster_config.go

@@ -39,7 +39,7 @@ type Config struct {
 	Databases ClusterConfig `yaml:"databases"`
 }
 
-// ClusterConfig holds information of the databases in the cluster
+// ClusterConfig is a map that stores configuration information for each database in the cluster.
 type ClusterConfig map[string]DatabaseConfig
 
 type DatabaseConfig struct {
@@ -66,7 +66,8 @@ func MakeDatabaseConfig() DatabaseConfig {
 	return DatabaseConfig{}
 }
 
-// read config information from the YAML file
+// ReadConfig reads cluster configuration information from a YAML-formatted file in configDirectory.
+// It returns a ClusterConfig and any error encountered when reading and parsing the file.
 func ReadConfig(configDirectory string, logger vlog.Printer) (ClusterConfig, error) {
 	configFilePath := filepath.Join(configDirectory, ConfigFileName)
 	configBytes, err := os.ReadFile(configFilePath)
@@ -103,7 +104,8 @@ func ReadConfig(configDirectory string, logger vlog.Printer) (ClusterConfig, err
 	return clusterConfig, nil
 }
 
-// write config information to the YAML file
+// WriteConfig writes configuration information to configFilePath.
+// It returns any write error encountered.
 func (c *ClusterConfig) WriteConfig(configFilePath string) error {
 	var config Config
 	config.Version = CurrentConfigFileVersion

vclusterops/cluster_op.go

@@ -380,9 +380,8 @@ func (opb *opHTTPSBase) validateAndSetUsernameAndPassword(opName string, useHTTP
 	return nil
 }
 
-// VClusterCommands is struct for all top-level admin commands (e.g. create db,
-// add node, etc.). This is used to pass state around for the various APIs. We
-// also use it for mocking in our unit test.
+// VClusterCommands passes state around for all top-level administrator commands
+// (e.g. create db, add node, etc.).
 type VClusterCommands struct {
 	Log vlog.Printer
 }

vclusterops/cluster_op_engine.go

@@ -72,7 +72,7 @@ func (opEngine *VClusterOpEngine) run(logger vlog.Printer) error {
 			return fmt.Errorf("finalize failed %w", err)
 		}
 
-		vlog.PrintWithIndent("[%s] is successfully completed", op.getName())
+		logger.PrintWithIndent("[%s] is successfully completed", op.getName())
 	}
 
 	return nil

vclusterops/coordinator_database.go

@@ -26,14 +26,9 @@ import (
 	"golang.org/x/exp/maps"
 )
 
-/* VCoordinationDatabase contains a copy of some of the CAT::Database
- * information from the catalog. It also contains a list of VCoordinationNodes.
- * It is similar to the admintools VDatabase object.
- *
- * The create database command produces a VCoordinationDatabase.
- * Start database, for example, consumes a VCoordinationDatabase.
- *
- */
+// VCoordinationDatabase represents catalog and node information for a database. The
+// VCreateDatabase command returns a VCoordinationDatabase struct. Operations on
+// an existing database (e.g. VStartDatabase) consume a VCoordinationDatabase struct.
 type VCoordinationDatabase struct {
 	Name string
 	// processed path prefixes
@@ -345,11 +340,7 @@ func (vdb *VCoordinationDatabase) filterPrimaryNodes() {
 	vdb.HostList = maps.Keys(vdb.HostNodeMap)
 }
 
-/* VCoordinationNode contains a copy of the some of CAT::Node information
- * from the database catalog (visible in the vs_nodes table). It is similar
- * to the admintools VNode object.
- *
- */
+// VCoordinationNode represents node information from the database catalog.
 type VCoordinationNode struct {
 	Name    string `json:"name"`
 	Address string
@@ -427,7 +418,9 @@ func (vnode *VCoordinationNode) setFromNodeConfig(nodeConfig *NodeConfig, vdb *V
 	}
 }
 
-// WriteClusterConfig updates the yaml config file with the given vdb information
+// WriteClusterConfig updates cluster configuration with the YAML-formatted file in configDir
+// and writes to the log and stdout.
+// It returns any error encountered.
 func (vdb *VCoordinationDatabase) WriteClusterConfig(configDir *string, logger vlog.Printer) error {
 	/* build config information
 	 */

vclusterops/create_db.go

@@ -25,8 +25,8 @@ import (
 	"github.com/vertica/vcluster/vclusterops/vlog"
 )
 
-// A good rule of thumb is to use normal strings unless you need nil.
-// Normal strings are easier and safer to use in Go.
+// VCreateDatabaseOptions represents the available options when you create a database with
+// VCreateDatabase.
 type VCreateDatabaseOptions struct {
 	/* part 1: basic db info */
 	DatabaseOptions

vclusterops/drop_db.go

@@ -22,8 +22,7 @@ import (
 	"github.com/vertica/vcluster/vclusterops/util"
 )
 
-// A good rule of thumb is to use normal strings unless you need nil.
-// Normal strings are easier and safer to use in Go.
+// VDropDatabaseOptions adds to VCreateDatabaseOptions the option to force delete directories.
 type VDropDatabaseOptions struct {
 	VCreateDatabaseOptions
 	ForceDelete *bool // whether force delete directories
@@ -37,7 +36,8 @@ func VDropDatabaseOptionsFactory() VDropDatabaseOptions {
 	return opt
 }
 
-// TODO: call this func when honor-user-input is implemented
+// AnalyzeOptions verifies the host options for the VDropDatabaseOptions struct and
+// returns any error encountered.
 func (options *VDropDatabaseOptions) AnalyzeOptions() error {
 	hostAddresses, err := util.ResolveRawHostsToAddresses(options.RawHosts, options.Ipv6.ToBool())
 	if err != nil {

vclusterops/fetch_node_state.go

@@ -47,7 +47,8 @@ func (options *VFetchNodeStateOptions) validateAnalyzeOptions(vcc *VClusterComma
 	return options.analyzeOptions()
 }
 
-// VFetchNodeState fetches node states (e.g., up or down) in the cluster
+// VFetchNodeState returns the node state (e.g., up or down) for each node in the cluster and any
+// error encountered.
 func (vcc *VClusterCommands) VFetchNodeState(options *VFetchNodeStateOptions) ([]NodeInfo, error) {
 	/*
 	 *   - Produce Instructions

vclusterops/https_poll_node_state_op.go

@@ -140,7 +140,7 @@ func (op *httpsPollNodeStateOp) finalize(_ *opEngineExecContext) error {
 }
 
 func (op *httpsPollNodeStateOp) processResult(execContext *opEngineExecContext) error {
-	vlog.PrintWithIndent("[%s] expecting %d up host(s)", op.name, len(op.hosts))
+	op.logger.PrintWithIndent("[%s] expecting %d up host(s)", op.name, len(op.hosts))
 
 	err := pollState(op, execContext)
 	if err != nil {
@@ -206,11 +206,11 @@ func (op *httpsPollNodeStateOp) shouldStopPolling() (bool, error) {
 	}
 
 	if upNodeCount < len(op.hosts) {
-		vlog.PrintWithIndent("[%s] %d host(s) up", op.name, upNodeCount)
+		op.logger.PrintWithIndent("[%s] %d host(s) up", op.name, upNodeCount)
 		return false, nil
 	}
 
-	vlog.PrintWithIndent("[%s] All nodes are up", op.name)
+	op.logger.PrintWithIndent("[%s] All nodes are up", op.name)
 
 	return true, nil
 }

vclusterops/nma_download_file_op.go

@@ -55,8 +55,8 @@ type downloadFileRequestData struct {
 	Parameters          map[string]string `json:"parameters,omitempty"`
 }
 
-// ClusterLeaseNotExpiredFailure is returned when an attempt is made to use a
-// communal storage before the lease for it has expired.
+// ClusterLeaseNotExpiredError is returned when you attempt to access a
+// communal storage location when there is an active cluster lease on it.
 type ClusterLeaseNotExpiredError struct {
 	Expiration string
 }
@@ -68,8 +68,8 @@ func (e *ClusterLeaseNotExpiredError) Error() string {
 		e.Expiration)
 }
 
-// ReviveDBNodeCountMismatchError is returned when the number of nodes in new cluster
-// does not match the number of nodes in original cluster
+// ReviveDBNodeCountMismatchError is the error that is returned when the number of
+// nodes in the revived cluster does not match the number of nodes in the original cluster.
 type ReviveDBNodeCountMismatchError struct {
 	ReviveDBStep  string
 	FailureHost   string

vclusterops/node_info.go

@@ -17,11 +17,10 @@ package vclusterops
 
 import mapset "github.com/deckarep/golang-set/v2"
 
-// the following structs only hosts necessary information for this op
+// NodeInfo represents information to identify a node.
 type NodeInfo struct {
-	Address string `json:"address"`
-	// vnode name, e.g., v_dbname_node0001
-	Name        string `json:"name"`
+	Address     string `json:"address"`
+	Name        string `json:"name"` // vnode name, e.g., v_dbname_node0001
 	State       string `json:"state"`
 	CatalogPath string `json:"catalog_path"`
 }

vclusterops/re_ip.go

@@ -114,7 +114,8 @@ func (opt *VReIPOptions) validateAnalyzeOptions(logger vlog.Printer) error {
 	return nil
 }
 
-// VReIP changes nodes addresses (node address, control address, and control broadcast)
+// VReIP changes the node address, control address, and control broadcast for a node.
+// It returns any error encountered.
 func (vcc *VClusterCommands) VReIP(options *VReIPOptions) error {
 	/*
 	 *   - Produce Instructions
@@ -237,7 +238,8 @@ type reIPRow struct {
 	NewControlBroadcast string `json:"to_control_broadcast,omitempty"`
 }
 
-// ReadReIPFile reads the re-ip file and build a list of ReIPInfo
+// ReadReIPFile reads the re-IP file and builds a slice of ReIPInfo.
+// It returns any error encountered.
 func (opt *VReIPOptions) ReadReIPFile(path string) error {
 	if err := util.AbsPathCheck(path); err != nil {
 		return fmt.Errorf("must specify an absolute path for the re-ip file")

vclusterops/remove_node.go

@@ -24,16 +24,13 @@ import (
 	"github.com/vertica/vcluster/vclusterops/vlog"
 )
 
-// VRemoveNodeOptions are the option arguments for the VRemoveNode API
+// VRemoveNodeOptions represents the available options to remove one or more nodes from
+// the database.
 type VRemoveNodeOptions struct {
 	DatabaseOptions
-	// Hosts to remove from database
-	HostsToRemove []string
-	// A primary up host that will be used to execute
-	// remove_node operations.
-	Initiator string
-	// whether force delete directories
-	ForceDelete *bool
+	HostsToRemove []string // Hosts to remove from database
+	Initiator     string   // A primary up host that will be used to execute remove_node operations.
+	ForceDelete   *bool    // whether force delete directories
 }
 
 func VRemoveNodeOptionsFactory() VRemoveNodeOptions {
@@ -51,8 +48,9 @@ func (o *VRemoveNodeOptions) setDefaultValues() {
 	*o.ForceDelete = true
 }
 
-// ParseHostToRemoveList converts the string list of hosts, to remove, into a slice of strings.
-// The hosts should be separated by comma, and will be converted to lower case.
+// ParseHostToRemoveList converts a comma-separated string list of hosts into a slice of host names
+// to remove from the database. During parsing, the hosts are converted to lowercase.
+// It returns any parsing error encountered.
 func (o *VRemoveNodeOptions) ParseHostToRemoveList(hosts string) error {
 	inputHostList, err := util.SplitHosts(hosts)
 	if err != nil {

vclusterops/remove_subcluster.go

@@ -24,13 +24,12 @@ import (
 	"github.com/vertica/vcluster/vclusterops/vlog"
 )
 
-// VRemoveScOptions are the option arguments for the VRemoveSubcluster API
+// VRemoveScOptions represents the available options when you remove a subcluster from a
+// database.
 type VRemoveScOptions struct {
 	DatabaseOptions
-	// Subcluster to remove from database
-	SubclusterToRemove *string
-	// whether force delete directories
-	ForceDelete *bool
+	SubclusterToRemove *string // subcluster to remove from database
+	ForceDelete        *bool   // whether force delete directories
 }
 
 func VRemoveScOptionsFactory() VRemoveScOptions {
@@ -105,12 +104,11 @@ func (o *VRemoveScOptions) validateAnalyzeOptions(logger vlog.Printer) error {
 	return o.setUsePassword(logger)
 }
 
-/*
-VRemoveSubcluster has three major phases:
- 1. pre-check (check the subcluster name and get nodes for the subcluster)
- 2. run VRemoveNode (refer to the instructions in VRemoveNode; Optional: if there are any nodes still associated with the subcluster)
- 3. run drop subcluster (i.e., remove the subcluster name from catalog)
-*/
+// VRemoveSubcluster removes a subcluster. It returns updated database catalog information and any error encountered.
+// VRemoveSubcluster has three major phases:
+//  1. Pre-check: check the subcluster name and get nodes for the subcluster.
+//  2. Removes nodes: Optional. If there are any nodes still associated with the subcluster, runs VRemoveNode.
+//  3. Drop the subcluster: Remove the subcluster name from the database catalog.
 func (vcc *VClusterCommands) VRemoveSubcluster(removeScOpt *VRemoveScOptions) (VCoordinationDatabase, error) {
 	vdb := makeVCoordinationDatabase()
 

vclusterops/revive_db.go

@@ -105,7 +105,8 @@ func (options *VReviveDatabaseOptions) validateAnalyzeOptions() error {
 	return options.analyzeOptions()
 }
 
-// VReviveDatabase can revive a database which has been terminated but its communal storage data still exists
+// VReviveDatabase revives a database that was terminated but whose communal storage data still exists.
+// It returns the database information retrieved from communal storage and any error encountered.
 func (vcc *VClusterCommands) VReviveDatabase(options *VReviveDatabaseOptions) (dbInfo string, err error) {
 	/*
 	 *   - Validate options

vclusterops/start_db.go

@@ -22,18 +22,12 @@ import (
 	"github.com/vertica/vcluster/vclusterops/vlog"
 )
 
-// Normal strings are easier and safer to use in Go.
+// VStartDatabaseOptions represents the available options when you start a database
+// with VStartDatabase.
 type VStartDatabaseOptions struct {
-	// basic db info
-	DatabaseOptions
-
-	// timeout for polling the states of all nodes in the database in HTTPSPollNodeStateOp
-	StatePollingTimeout *int
-
-	/* hidden option */
-
-	// whether trim the input host list based on the catalog info
-	TrimHostList *bool
+	DatabaseOptions           // basic db info
+	StatePollingTimeout *int  // timeout for polling the states of all nodes in the database in HTTPSPollNodeStateOp
+	TrimHostList        *bool // whether trim the input host list based on the catalog info
 }
 
 func VStartDatabaseOptionsFactory() VStartDatabaseOptions {