Categorygithub.com/cockroachdb/cockroachpkgcli
package
25.1.0+incompatible
Repository: https://github.com/cockroachdb/cockroach.git
Documentation: pkg.go.dev
Versions
7
Dependencies
222
Dependents
500
Files
22.3k SLOC

# README

CLI utility design guidelines

Guidelines for operator-level utilities

  • Be concise in the common case, verbose with errors.

  • Be flexible on input, strict on output. (Accept mistakes by the user providing flags / input; but make the output format specific: it is consumed by programs.)

  • Errors on stderr, regular output on stdout.

  • CLI tools other than the debug utilities are part of the API: don't change features without release notes; use the deprecation cycle to remove features or change flags; and ensure cross-version compatibility (possibly via opt-in flags).

Guidelines for the SQL shell

  • Be mindful of the two "modes" of output:

    • output consumed by a human. (cliCtx.terminalOutput == true)

      In this mode, there can be explanations printed out to help the human understand what they are seeing. Long operations (eg workload init) should be described by an explanatory message before the operation starts, so that the user knows there is something to wait for.

    • output consumed by scripts, automation etc. (cliCtx.terminalOutput == false)

      In the output automation mode: output should be concise, parsable: it is consumed by programs.

      In the non-human case, the output is part of the public API of CockroachDB. Beware of documenting changes in release notes; use the deprecation cycle to remove key output aspects; ensure that users can preserve specific outputs from previous version when upgrading, possibly via opt-in flags.

  • Be mindful of the two "modes" of input:

    • input provided by a human: interactive use via a terminal. (cliCtx.isInteractive == true)

      In this mode, there can be explanations to suggest to the human what is a good “next step” after they do something.

    • input provided by scripts, automation etc., e.g. via cockroach sql <input.sql. (cliCtx.isInteractive == false)

      In this mode, there should not be guidance printed out to help a human.

      Also, the automated input mode is part of the public API of CockroachDB. Beware of documenting changes in release notes; use the deprecation cycle to remove key input aspects; ensure that users can preserve specific outputs from previous version when upgrading, possibly via opt-in flags.

  • Beware: the two modes above are orthogonal to each other. We know about real-world usage of all 4 combinations:

    • fully interactive: terminalOutput && isInteractive
    • fully automated: !terminalOutput && !isInteractive
    • human reads a SQL script from a file but wants explanations about what's going on, e.g. running cockroach sql <foo.sql on a terminal: terminalOutput && !isInteractive
    • human runs the SQL shell but filters the output, e.g. cockroach sql | grep XXX !terminalOutput && isInteractive.

  • Be mindful of the --embedded flag, for use in "playground" environments.

    If sqlCtx.embeddedMode is set, the (human) user has no control over the command line and the configuration. In that case, help texts about the configuration should be avoided because they are non-actionable.

# Packages

Package clicfg defines configuration settings common to all CLI commands.
Package clientflags contains common logic to define command-line flags for client commands.
Package clienturl provides glue between: - security/clientconnurl, which is able to translate configuration parameters for SQL clients and compute security parameters, - cli/clisqlcfg, which serves as input for a SQL shell.
Package clierror provides common functions to display program errors to the user.
Package clierrorplus contains facilities that would nominally belong to package `clierror` instead, but which we do not wish to place there to prevent `clierror` from depending to more complex packages.
Package cliflagcfg contains the common logic to define CLI flag sets for CockroachDB commands.
Package clisqlcfg defines configuration settings and mechanisms for instances of the SQL shell.
Package clisqlclient implements the connection code between a SQL client and server.
Package clisqlexec implements the execution of SQL queries and rendering of SQL values for the end-user.
Package clisqlshell contains the code that powers CockroachDB's interactive SQL shell.
Package democluster implements the transient, in-memory CockroachDB cluster that powers 'cockroach demo'.
Package exit encapsulates calls to os.Exit to control the production of process exit status codes.

# Functions

AddPersistentPreRunE add 'fn' as a persistent pre-run function to 'cmd'.
ClearStoresAndSetupLoggingForMTCommands will clear the cluster name, the store specs, and then sets up default logging.
CockroachCmd returns the root cockroach Command object.
ElideInsecureDeprecationNotice elides the deprecation notice for --insecure.
GetCsvNumCols returns the number of columns in the given csv string.
GetServerCfgStores provides direct public access to the StoreSpecList inside serverCfg.
GetWALFailoverConfig provides direct public access to the WALFailoverConfig inside serverCfg.
Main is the entry point for the cli, with a single line calling it intended to be the body of an action package main `main` func elsewhere.
MatchCSV matches a multi-line csv string with the provided regex (matchColRow[i][j] will be matched against the i-th line, j-th column).
NewCLITest export for cclcli.
OpenEngine opens the engine at 'dir'.
OpenFilesystemEnv opens the filesystem environment at 'dir'.
PrintQueryOutput takes a list of column names and a list of row contents writes a formatted table to 'w'.
RegisterCommandWithCustomLogging is used by cliccl to note commands which want to suppress default logging setup.
RegisterFlags exists so that other packages can register flags using the Register<Type>FlagDepth functions and end up in a call frame in the cli package rather than the cliccl package to defeat the duplicate envvar registration logic.
RemoveMatchingLines removes lines from the input string that match any of the provided regexps.
Run ...
TestingReset resets global mutable state so that Run can be called multiple times from the same test process.
UsageAndErr informs the user about the usage of the command and returns an error.

# Constants

# Variables

DebugCmd is the root of all debug commands.
DebugCommandsRequiringEncryption lists debug commands that access Pebble through the engine and need encryption flags (injected by CCL code).
DebugPebbleCmd is the root of all debug pebble commands.
DrainSignals is the list of signals that trigger the start of a shutdown sequence ("server drain").
EncryptedStorePathsHook is a callback set by CCL code.
GenCmd is the root of all gen commands.
MTCmd is the base command for functionality related to multi-tenancy.
PopulateEnvConfigHook is a callback set by CCL code.
StartCmds lists the commands that start KV nodes as a server.

# Structs

DatadogPoint is a single metric point in Datadog format.
DatadogSeries contains a JSON encoding of a single series object that can be send to Datadog.
DatadogSubmitMetrics is the top level JSON object that must be sent to Datadog.
TableQuery holds two sql query strings together that are used to dump tables when generating a debug zip.
TableRegistryConfig is the unit of configuration used in the DebugZipTableRegistry, providing the option to define custom redacted/unredacted queries if necessary.
TestCLI wraps a test server and is used by tests to make assertions about the output of CLI commands.
TestCLIParams contains parameters used by TestCLI.

# Type aliases

DebugZipTableRegistry is a registry of `crdb_internal` and `system` tables that we wish to include in `debug zip` bundles.
NonSensitiveColumns is a string list used to define table columns that do not contain sensitive data.