COCKROACH-SQL(1)

NAME

cockroach-sql - open a sql shell

SYNOPSIS

cockroach sql [options] [flags]

DESCRIPTION

Open a sql shell running against a cockroach database.

OPTIONS

--cert-principal-map=[]

A comma separated list of : mappings. This
 allows mapping the principal in a cert to a DB principal such as "node" or
 "root" or any SQL user. This is intended for use in situations where the
 certificate management system places restrictions on the Subject.CommonName or
 SubjectAlternateName fields in the certificate (e.g. disallowing a CommonName
 such as "node" or "root"). If multiple mappings are provided for the same
 , the last one specified in the list takes precedence. A
 principal not specified in the map is passed through as-is via the identity
 function. A cert is allowed to authenticate a DB principal if the DB principal
 name is contained in the mapped CommonName or DNS-type SubjectAlternateName
 fields. It is permissible for the string to contain colons.

--certs-dir="/home/builder/.cockroach-certs"

Path to the directory containing SSL certificates and keys.
 Environment variable: COCKROACH_CERTS_DIR

-d, --database=""

The name of the database and (optionally) virtual cluster to connect to:
    -d [database]
    -d cluster:[virtual-cluster]/[database]

For example:
    -d mydb
    -d cluster:mycluster/mydb

If empty or unspecified, the virtual cluster defaults to the
 "server.controller.default_target_cluster" cluster setting.
 Environment variable: COCKROACH_DATABASE

--debug-sql-cli[=false]

Simplify the SQL CLI to ease troubleshooting of CockroachDB issues. This
 echoes sent SQL, removes the database name and txn status from the prompt, and
 forces behavior to become independent on current transaction state. Equivalent
 to --echo-sql, \unset check_syntax and \set prompt1 %n@%M>.

--echo-sql[=false]

Reveal the SQL statements sent implicitly by the command-line utility.

--embedded[=false]

Simplify and reduce the SQL CLI output to make it appropriate for embedding in
 a 'playground'-type environment. This causes the shell to omit informational
 message about aspects that can only be changed with command-line flags or
 environment variables: in an embedded environment, the user has no control
 over these and the messages would thus be confusing. It also causes the shell
 to omit informational messages about networking details (e.g. server address),
 as it is assumed that the embedding environment will report those instead.

-e, --execute=

Execute the SQL statement(s) on the command line, then exit. This flag may
 be specified multiple times and each value may contain multiple semicolon
 separated statements. If an error occurs in any statement, the command exits
 with a non-zero status code and further statements are not executed. The
 results of each SQL statement are printed on the standard output. This flag
 is incompatible with --file / -f.

-f, --file=""

Read and execute the SQL statement(s) from the specified file. The file is
 processed as if it has been redirected on the standard input of the shell.
 This flag is incompatible with --execute / -e.

--format="table"

Selects how to display table rows in results. Possible values: tsv, csv,
 table, records, ndjson, json, sql, html, raw. If left unspecified, defaults to
 tsv for non-interactive sessions and table for interactive sessions.

-h, --help[=false]
    help for sql

--insecure[=false]

Connect to a cluster without using TLS nor authentication. This makes the
 client-server connection vulnerable to MITM attacks. Use with care.
 Environment variable: COCKROACH_INSECURE

--no-line-editor[=false]

Force disable the interactive line editor. Can help during testing.

--read-only[=false]

Set the session variable default_transaction_read_only to on.

--safe-updates[=]

Disable SQL statements that may have undesired side effects. For example a
 DELETE or UPDATE without a WHERE clause. By default, this setting is enabled
 (true) and such statements are rejected to prevent accidents. This can also be
 overridden in a session with SET sql_safe_updates = FALSE.

--set=

Set a client-side configuration parameter before running the SQL shell. This
 flag may be specified multiple times.

--url=

Connection URL, of the form:
    postgresql://[user[:passwd]@]host[:port]/[db][?parameters...]
    postgresql://[user[:passwd]@]host[:port]/cluster:[virtual-cluster]/[db][?parameters...]

For example:
    postgresql://myuser@localhost:26257/mydb
    postgresql://myuser@localhost:26257/cluster:mycluster/mydb

If left empty, the discrete connection flags are used: host, port, user,
 database, insecure, certs-dir.
 Environment variable: COCKROACH_URL

-u, --user="root"

Database user name.
 Environment variable: COCKROACH_USER

--watch=0s

Repeat the SQL statement(s) specified with --execute with the specified
 period. The client will stop watching if an execution of the SQL statement(s)
 fail.

OPTIONS INHERITED FROM PARENT COMMANDS

--enterprise-require-fips-ready[=false]
    abort if FIPS readiness checks fail

--log=

Logging configuration, expressed using YAML syntax. For example, you can
 change the default logging directory with: --log='file-defaults: {dir: ...}'.
 See the documentation for more options and details. To preview how the log
 configuration is applied, or preview the default configuration, you can use
 the 'cockroach debug check-log-config' sub-command.

--log-config-file=

File name to read the logging configuration from. This has the same effect as
 passing the content of the file via the --log flag.

--log-config-vars=[]

Environment variables that will be expanded if present in the body of the
 logging configuration.

--log-dir=

--log-dir=XXX is an alias for --log='file-defaults: {dir: XXX}'.

--logtostderr[=UNKNOWN]

--logtostderr=XXX is an alias for --log='sinks: {stderr: {filter: XXX}}'. If
 no value is specified, the default value for the command is inferred: INFO for
 server commands, WARNING for client commands.

--redactable-logs=false

--redactable-logs=XXX is an alias for --log='file-defaults: {redactable:
 XXX}}'.

--vmodule=
    comma-separated list of pattern=N settings for file-filtered logging (significantly hurts performance)

SEE ALSO

cockroach(1)

HISTORY

13-May-2026 Auto generated by spf13/cobra