Merge #150624

150624: cli: update --database and --url flag help text for virtual clusters r=petermattis a=petermattis

Release note (cli change): Update the help text for the --database and --url
CLI flags to document support for virtual cluster syntax. The --database flag
now shows examples of both simple database names and the
cluster:virtual-cluster/database format. The --url flag examples now include
the virtual cluster syntax in PostgreSQL connection URLs.


Co-authored-by: Peter Mattis <[email protected]>

Author: craig[bot]

pkg/cli/cliflags/flags.go

@@ -284,10 +284,25 @@ example [::1]:26257 or [fe80::f6f2:::]:26257.`,
 	}
 
 	Database = FlagInfo{
-		Name:        "database",
-		Shorthand:   "d",
-		EnvVar:      "COCKROACH_DATABASE",
-		Description: `The name of the database to connect to.`,
+		Name:      "database",
+		Shorthand: "d",
+		EnvVar:    "COCKROACH_DATABASE",
+		Description: `
+The name of the database and (optionally) virtual cluster to connect to:
+<PRE>
+   -d [database]
+   -d cluster:[virtual-cluster]/[database]
+
+</PRE>
+For example:
+<PRE>
+   -d mydb
+   -d cluster:mycluster/mydb
+
+</PRE>
+If empty or unspecified, the virtual cluster defaults to the
+"server.controller.default_target_cluster" cluster setting.
+`,
 	}
 
 	DumpMode = FlagInfo{
@@ -1229,9 +1244,13 @@ The value "disabled" will disable all local file I/O.
 Connection URL, of the form:
 <PRE>
    postgresql://[user[:passwd]@]host[:port]/[db][?parameters...]
+   postgresql://[user[:passwd]@]host[:port]/cluster:[virtual-cluster]/[db][?parameters...]
+
 </PRE>
-For example, postgresql://myuser@localhost:26257/mydb.
+For example:
 <PRE>
+   postgresql://myuser@localhost:26257/mydb
+   postgresql://myuser@localhost:26257/cluster:mycluster/mydb
 
 </PRE>
 If left empty, the discrete connection flags are used: host, port,