客户端连接参数

客户端程序,包括客户端cockroach命令,通过与cockroachDB集群建立稳定的连接来正常工作。连接参数决定了连接哪个cockroachDB集群,以及如何建立连接。

支持的连接参数

客户端连接cockroachDB主要有两种方式:

下表总结了哪些客户端支持哪些连接参数:

Client 支持通过URL连接 支持独立的连接参数
使用PostgreSQL驱动的客户端程序 依赖于应用程序
cockroach init
cockroach quit
cockroach sql
cockroach user
cockroach zone
cockroach node
cockroach dump
cockroach debug zip

使用URL进行连接

SQL客户端,包括一些cockroach命令,可以通过URL进行连接。 一个连接URL格式如下:

postgres://<username>:<password>@<host>:<port>/<database>?<parameters>
选项 描述 必填
<username> SQL用户,连接后将拥有客户端会话
<password> 用户密码。不建议直接将密码写在URL中。

查看更多关于cockroachDB处理密码的细节
<host> 主机名,或者CockroachDB节点或负载均衡的地址 大部分客户端需要
<port> CockroachDB节点或者负载均衡的SQL接口的端口号 大部分客户端需要
<database> 当前使用的数据库名
<parameters> 附加连接参数,包括SSL/TLS证书配置

你可以使用--url参数为cockroach命令指定接受连接的URL。如果--url没有指定但定义了环境变量COCKROACH_URL,则会使用该环境变量。否则,cockroach命令将使用独立的连接参数,如下文所述。

注意:不应该为cockroach sql以外的任何cockroach命令指定<database>选项。

附加连接参数

以下附加参数可以通过在URL中的?之后传递:

参数 描述 默认值
application_name session变量application_name的初始值 Empty string.
sslmode 使用哪种类型的安全连接:disable, allow, prefer, require, verify-caverify-full。查看更多信息:使用URLs进行安全连接 disable
sslrootcert 使用 sslmode时,CA certificate的路径 Empty string.
sslcert 使用sslmode时,客户端证书的路径 Empty string.
sslkey 使用sslmode时,客户端私钥的路径 Empty string.

使用URLs进行安全连接

sslmode 支持以下值,然而只推荐使用第一个和最后一个值。

参数 描述 推荐使用
sslmode=disable 完全不使用加密和安全连接 开发环境使用
sslmode=allow 仅当server要求时才使用安全连接
并非所有客户端都支持
sslmode=prefer 尝试建立安全连接,但是当server不支持安全连接时,接受非安全连接

并非所有客户端都支持
sslmode=require 强制使用安全连接。当无法建立安全连接时报错
sslmode=verify-ca 强制使用安全连接,并且检验server服务器证书是否由known CA签名
sslmode=verify-full 强制使用安全连接,检验server服务器证书是否由known CA签名,并且检查服务器地址是否和证书中指定的相符合 用于安全部署

警告:一些客户端驱动和cockroach命令不支持sslmode=allowsslmode=prefer。检查你的SQL驱动的文档以确认是否支持这些参数。

非安全连接的URL例子

以下的URL适合使用非安全连接连接到cockroachDB节点:

postgres://root@servername:26257/mydb?sslmode=disable

它指定了连接使用root用户,servername主机的26257端口(CockroachDB SQL默认端口),mydb作为当前数据库。sslmode=disable 指定非安全连接。

安全连接的例子

以下URL适用于使用安全连接到cockroachDB节点:

postgres://root@servername:26257/mydb?sslmode=verify-full&sslrootcert=path/to/ca.crt&sslcert=path/to/client.crt&sslkey=path/to/client.key

它使用了以下选项:

更多关于如何创建和管理SSL/TLS证书,查看Create Security CertificatesRotate Certificates.

使用独立参数连接

除了--url之外,大多数cockroach命令都接受连接参数作为单独的命令行标志,并将所有参数指定(或替代)为URL。

对于每个指定了连接参数的命令行标识,CockroachDB还能识别环境变量。当命令行参数没有指定时将会使用环境变量。

参数 描述
--host 连接的服务器。它可以是集群中的任意节点位置。

环境变量:COCKROACH_HOST
默认:localhost
--port -p 连接的服务端口

环境变量:COCKROACH_PORT
默认:26257
--user -u SQL用户,连接后将拥有client session

环境变量:COCKROACH_USER
默认:root
--insecure 使用非安全连接

环境变量:COCKROACH_INSECURE
默认:false
--certs-dir 包含CA和客户端证书、客户端key的证书目录路径

环境变量:COCKROACH_CERTS_DIR
默认:${HOME}/.cockroach-certs/
--url 连接使用的url

环境变量:COCKROACH_URL
默认:no URL

只有cockroach命令支持使用命令行参数--url。更多细节请查看:Supported Connection Parameters

非安全连接的命令行参数示例

通过以下命令行参数建立一个非安全连接:

--user root \
 --host servername \
 --port 26257 \
 --insecure

该连接指定了使用root用户、servername服务器、26257端口(默认cockroachDB端口)。--insecure指定建立非安全连接。

安全连接的命令行参数示例

通过以下命令行参数建立一个安全连接:

--user root \
 --host servername \
 --port 26257 \
 --certs-dir path/to/certs

它指定了以下选项:

当使用独立的连接参数时,CA、客户端证书、客户端key的文件名将通过--certs-dir 自动生成,无法指定。若要使用自定义文件名,请使用URL连接。

同时使用URL和客户端参数

Changed in v2.0

一些cockroach命令支持使用--url(或者COCKROACH_URL)来同时使用连接URL和独立的连接参数。

它们可以按如下组合:URL有最高优先级,其次是离散参数。这种组合非常有用,独立的命令行参数可以覆盖在URL中没有指定的配置。

另一方面:

涵盖当前数据库的例子

例如,cockroach start命令打印出以下连接的url:

postgres://root@servername:26257/?sslmode=disable

你可能会通过cockroach sql连接到这个服务,并且指定mydb作为当前数据库,使用以下命令:

cockroach sql \
 --url "postgres://root@servername:26257/?sslmode=disable" \
 --database mydb

这等同于:

cockroach sql --url "postgres://root@servername:26257/mydb?sslmode=disable"

查看更多