dbcmd

Documentation

Index

• Constants
• func ConvertCommandError(cmd *exec.Cmd, err error, peakStderr string) error
• type CLICommandBuilder
  • func NewCmdBuilder(tc *client.TeleportClient, profile *client.ProfileStatus, ...) *CLICommandBuilder
  • func (c *CLICommandBuilder) GetConnectCommand() (*exec.Cmd, error)
  • func (c *CLICommandBuilder) GetConnectCommandAlternatives() ([]CommandAlternative, error)
  • func (c *CLICommandBuilder) GetConnectCommandNoAbsPath() (*exec.Cmd, error)
• type CommandAlternative
• type ConnectCommandFunc
  • func WithExecer(exe Execer) ConnectCommandFunc
  • func WithLocalProxy(host string, port int, caPath string) ConnectCommandFunc
  • func WithLogger(log *logrus.Entry) ConnectCommandFunc
  • func WithNoTLS() ConnectCommandFunc
  • func WithPassword(pass string) ConnectCommandFunc
  • func WithPrintFormat() ConnectCommandFunc
  • func WithTolerateMissingCLIClient() ConnectCommandFunc
• type Execer
• type SystemExecer
  • func (s SystemExecer) Command(name string, arg ...string) *exec.Cmd
  • func (s SystemExecer) LookPath(file string) (string, error)
  • func (s SystemExecer) RunCommand(name string, arg ...string) ([]byte, error)

Constants

const (
	// PeakStderrSize is the recommended size for capturing stderr that is used
	// for ConvertCommandError.
	PeakStderrSize = 100
)

Functions

func ConvertCommandError

func ConvertCommandError(cmd *exec.Cmd, err error, peakStderr string) error

ConvertCommandError translates some common errors to more user friendly messages.

This helps in situations where the user does not have the full context to decipher errors when the database command is executed internally (e.g. command executed through "tsh db connect").

Types

type CLICommandBuilder

type CLICommandBuilder struct {
	// contains filtered or unexported fields
}

CLICommandBuilder holds data needed to build a CLI command from args passed to NewCmdBuilder. Any calls to the exec package within CLICommandBuilder methods that need to be mocked should use the exe field rather than calling the package directly.

func NewCmdBuilder

func NewCmdBuilder(tc *client.TeleportClient, profile *client.ProfileStatus,
	db *tlsca.RouteToDatabase, rootClusterName string, opts ...ConnectCommandFunc,
) *CLICommandBuilder

func (*CLICommandBuilder) GetConnectCommand

func (c *CLICommandBuilder) GetConnectCommand() (*exec.Cmd, error)

GetConnectCommand returns a command that can connect the user directly to the given database using an appropriate CLI database client. It takes into account cluster configuration, binaries available on the system and in some cases it even connects to the database to check which exact version of the database the user is running.

Underneath it uses exec.Command, so the resulting command will always be expanded to its absolute path if exec.LookPath was able to find the given binary on user's system.

If CLICommandBuilder's options.tolerateMissingCLIClient is set to true, GetConnectCommand shouldn't return an error if it cannot locate a client binary. Check WithTolerateMissingCLIClient docs for more details.

func (*CLICommandBuilder) GetConnectCommandAlternatives

func (c *CLICommandBuilder) GetConnectCommandAlternatives() ([]CommandAlternative, error)

GetConnectCommandAlternatives returns optional connection commands for protocols that offer multiple options. Otherwise, it falls back to GetConnectCommand. The keys in the returned map are command descriptions suitable for display to the end user.

func (*CLICommandBuilder) GetConnectCommandNoAbsPath

func (c *CLICommandBuilder) GetConnectCommandNoAbsPath() (*exec.Cmd, error)

GetConnectCommandNoAbsPath works just like GetConnectCommand, with the only difference being that it guarantees that the command will always be in its base form, never in an absolute path resolved to the binary location. This is useful for situations where the resulting command is meant to be copied and then pasted into an interactive shell, rather than being run directly by a tool like tsh.

type CommandAlternative

type CommandAlternative struct {
	Description string
	Command     *exec.Cmd
}

CommandAlternative represents alternative command along with description.

type ConnectCommandFunc

type ConnectCommandFunc func(*connectionCommandOpts)

ConnectCommandFunc is a type for functions returned by the "With*" functions in this package. A function of type ConnectCommandFunc changes connectionCommandOpts of CLICommandBuilder based on the arguments passed to a "With*" function.

func WithExecer

func WithExecer(exe Execer) ConnectCommandFunc

WithExecer allows to provide a different Execer than the default SystemExecer. Useful in contexts where there's a place that wants to use dbcmd with the ability to mock out SystemExecer in tests.

func WithLocalProxy

func WithLocalProxy(host string, port int, caPath string) ConnectCommandFunc

WithLocalProxy makes CLICommandBuilder pass appropriate args to the CLI database clients that will let them connect to a database through a local proxy. In most cases it means using the passed host and port as the address, but some database clients require additional flags in those scenarios.

func WithLogger

func WithLogger(log *logrus.Entry) ConnectCommandFunc

WithLogger is the connect command option that allows the caller to pass a logger that will be used by CLICommandBuilder.

func WithNoTLS

func WithNoTLS() ConnectCommandFunc

WithNoTLS is the connect command option that makes the command connect without TLS.

It is used when connecting through the local proxy that was started in mutual TLS mode (i.e. with a client certificate).

func WithPassword

func WithPassword(pass string) ConnectCommandFunc

WithPassword is the command option that allows to set the database password that will be used for database CLI.

func WithPrintFormat

func WithPrintFormat() ConnectCommandFunc

WithPrintFormat is the connect command option that hints the command will be printed instead of being executed.

For example, when enabled, a quote will be used for Postgres and MongoDB connection strings to avoid "&" getting interpreted by the shell.

WithPrintFormat is known to be used for the following situations: - tsh db config --format cmd <database> - tsh proxy db --tunnel <database> - Teleport Connect where the command is put into a terminal.

WithPrintFormat should NOT be used when the exec.Cmd gets executed by the client application.

func WithTolerateMissingCLIClient

func WithTolerateMissingCLIClient() ConnectCommandFunc

WithTolerateMissingCLIClient is the connect command option that makes CLICommandBuilder not return an error in case a specific binary couldn't be found in the system. Instead, it should return the command with just a base version of the binary name, without an absolute path.

In general CLICommandBuilder doesn't return an error in that scenario as it uses exec.Command underneath. However, there are some specific situations where we need to execute some binaries before returning the final command.

The flag is mostly for scenarios where the caller doesn't care that the final command might not work.

type Execer

type Execer interface {
	// RunCommand runs a system command.
	RunCommand(name string, arg ...string) ([]byte, error)
	// LookPath returns a full path to a binary if this one is found in system PATH,
	// error otherwise.
	LookPath(file string) (string, error)
	// Command returns the Cmd struct to execute the named program with the given arguments.
	Command(name string, arg ...string) *exec.Cmd
}

Execer is an abstraction of Go's exec module, as this one doesn't specify any interfaces. This interface exists only to enable mocking.

type SystemExecer

type SystemExecer struct{}

SystemExecer implements execer interface by using Go exec module.

func (SystemExecer) Command

func (s SystemExecer) Command(name string, arg ...string) *exec.Cmd

Command is a wrapper for exec.Command(...)

func (SystemExecer) LookPath

func (s SystemExecer) LookPath(file string) (string, error)

LookPath is a wrapper for exec.LookPath(...)

func (SystemExecer) RunCommand

func (s SystemExecer) RunCommand(name string, arg ...string) ([]byte, error)

RunCommand is a wrapper for exec.Command(...).Output()