psql 是一个基于终端的 PostgreSQL 前端。它允许您交互式地输入查询，将其发送给 PostgreSQL，并查看查询结果。或者，输入可以来自文件或命令行参数。此外，psql 提供了许多元命令和各种类似 shell 的功能，以方便编写脚本和自动化各种任务。
用法
psql [选项...] [数据库名 [用户名]]
选项
-a
--echo-all
在读取时将所有非空输入行打印到标准输出。（这不适用于交互式读取的行。）这相当于将变量 ECHO 设置为 all。
-A
--no-align
切换到非对齐输出模式。（默认输出模式是对齐的。）这相当于 \pset format unaligned。
-b
--echo-errors
将失败的 SQL 命令打印到标准错误输出。这相当于将变量 ECHO 设置为 errors。
-c 命令
--command=命令
指定 psql 要执行给定的命令字符串 command。此选项可以重复，并可以与 -f 选项以任意顺序组合。当指定了 -c 或 -f 时，psql 不会从标准输入读取命令；而是在依次处理完所有 -c 和 -f 选项后终止。
command 必须是一个完全可以被服务器解析的命令字符串（即，它不包含任何 psql 特定的功能），或者是一个单独的反斜杠命令。因此，您不能在 -c 选项内混合 SQL 和 psql 元命令。要实现这一点，您可以使用重复的 -c 选项或将字符串通过管道传递给 psql，例如：
psql -c '\x' -c 'SELECT * FROM foo;'
或
echo '\x \\ SELECT * FROM foo;' | psql
（\\ 是分隔符元命令。）
传递给 -c 的每个 SQL 命令字符串都作为单个请求发送到服务器。因此，即使字符串包含多个 SQL 命令，服务器也会将其作为单个事务执行，除非字符串中包含显式的 BEGIN/COMMIT 命令将其划分为多个事务。（有关服务器如何处理多查询字符串的更多详细信息，请参见第 54.2.2.1 节。）
如果不希望多个命令在一个事务中执行，请使用重复的 -c 命令或将多个命令馈送到 psql 的标准输入，可以使用如上所示的 echo，或通过 shell 的 here-document，例如：
psql <<EOF
\x
SELECT * FROM foo;
EOF
--csv
切换到 CSV（逗号分隔值）输出模式。这相当于 \pset format csv。
-d 数据库名
--dbname=数据库名
指定要连接到的数据库的名称。这相当于在命令行上将数据库名指定为第一个非选项参数。数据库名可以是一个连接字符串。如果是，连接字符串参数将覆盖任何冲突的命令行选项。
-e
--echo-queries
将所有发送到服务器的 SQL 命令也复制到标准输出。这相当于将变量 ECHO 设置为 queries。
-E
--echo-hidden
回显由 \d 和其他反斜杠命令生成的实际查询。您可以使用它来研究 psql 的内部操作。这相当于将变量 ECHO_HIDDEN 设置为 on。
-f 文件名
--file=文件名
从文件 filename 读取命令，而不是标准输入。此选项可以重复，并可以与 -c 选项以任意顺序组合。当指定了 -c 或 -f 时，psql 不会从标准输入读取命令；而是在依次处理完所有 -c 和 -f 选项后终止。除此之外，此选项在很大程度上等同于元命令 \i。
如果 filename 是 -（连字符），则读取标准输入直到 EOF 指示或 \q 元命令。这可用于将交互式输入与文件输入交错。但请注意，在这种情况下不使用 Readline（就像指定了 -n 一样）。
使用此选项与编写 psql < filename 略有不同。通常，两者都会按预期工作，但使用 -f 可以启用一些不错的功能，例如带有行号的错误消息。使用此选项也有可能减少启动开销。另一方面，使用 shell 输入重定向的变体（理论上）保证产生与您手动输入所有内容所得到的输出完全相同的输出。
-F 分隔符
--field-separator=分隔符
使用 separator 作为非对齐输出的字段分隔符。这相当于 \pset fieldsep 或 \f。
-h 主机名
--host=主机名
指定服务器运行所在机器的主机名。如果值以斜杠开头，则将其用作 Unix 域套接字的目录。
-H
--html
切换到 HTML 输出模式。这相当于 \pset format html 或 \H 命令。
-l
--list
列出所有可用的数据库，然后退出。其他非连接选项被忽略。这类似于元命令 \list。
使用此选项时，psql 将连接到 postgres 数据库，除非在命令行上指定了不同的数据库（选项 -d 或非选项参数，可能通过服务条目，但不通过环境变量）。
-L 文件名
--log-file=文件名
将所有查询输出写入文件 filename，除了正常的输出目标。
-n
--no-readline
不要使用 Readline 进行行编辑，也不要使用命令历史记录（请参阅下面名为“命令行编辑”的部分）。
-o 文件名
--output=文件名
将所有查询输出放入文件 filename。这相当于命令 \o。
-p 端口
--port=端口
指定服务器正在监听连接的 TCP 端口或本地 Unix 域套接字文件扩展名。默认为 PGPORT 环境变量的值，如果未设置，则使用编译时指定的端口，通常为 5432。
-P 赋值
--pset=赋值
以 \pset 的风格指定打印选项。请注意，这里必须用等号而不是空格分隔名称和值。例如，要将输出格式设置为 LaTeX，可以编写 -P format=latex。
-q
--quiet
指定 psql 应静默工作。默认情况下，它会打印欢迎消息和各种信息性输出。如果使用此选项，则不会发生任何这种情况。这对于 -c 选项很有用。这相当于将变量 QUIET 设置为 on。
-R 分隔符
--record-separator=分隔符
使用 separator 作为非对齐输出的记录分隔符。这相当于 \pset recordsep。
-s
--single-step
在单步模式下运行。这意味着在每个命令发送到服务器之前会提示用户，并可以选择取消执行。使用此模式来调试脚本。
-S
--single-line
在单行模式下运行，其中换行符终止 SQL 命令，就像分号一样。
注意
提供此模式是为了满足那些坚持使用它的人，但不一定鼓励您使用它。特别是，如果您在一行中混合使用 SQL 和元命令，那么执行顺序对于缺乏经验的用户可能并不总是清晰的。
-t
--tuples-only
关闭列名和结果行计数页脚等的打印。这相当于 \t 或 \pset tuples_only。
-T 表选项
--table-attr=表选项
指定要放在 HTML 表标签内的选项。有关详细信息，请参阅 \pset tableattr。
-U 用户名
--username=用户名
以用户 username 身份连接到数据库，而不是默认用户。（当然，您必须有权这样做。）
-v 赋值
--set=赋值
--variable=赋值
执行变量赋值，类似于 \set 元命令。请注意，在命令行上必须用等号分隔名称和值（如果有）。要取消设置变量，请省略等号。要将变量设置为空值，请使用等号但省略值。这些赋值在命令行处理期间完成，因此反映连接状态的变量稍后会被覆盖。
-V
--version
打印 psql 版本并退出。
-w
--no-password
从不发出密码提示。如果服务器需要密码认证，并且密码无法从其他来源（如 .pgpass 文件）获得，则连接尝试将失败。此选项在批处理作业和脚本中非常有用，因为没有用户在场输入密码。
请注意，此选项将在整个会话期间保持设置，因此它会影响元命令 \connect 的使用以及初始连接尝试。
-W
--password
强制 psql 在连接到数据库之前提示输入密码，即使不会使用该密码。
如果服务器需要密码认证，并且密码无法从其他来源（如 .pgpass 文件）获得，psql 在任何情况下都会提示输入密码。但是，psql 将浪费一次连接尝试来发现服务器需要密码。在某些情况下，键入 -W 以避免额外的连接尝试是值得的。
请注意，此选项将在整个会话期间保持设置，因此它会影响元命令 \connect 的使用以及初始连接尝试。
-x
--expanded
打开扩展表格式化模式。这相当于 \x 或 \pset expanded。
-X
--no-psqlrc
不读取启动文件（既不读取系统范围的 psqlrc 文件，也不读取用户的 ~/.psqlrc 文件）。
-z
--field-separator-zero
将非对齐输出的字段分隔符设置为零字节。这相当于 \pset fieldsep_zero。
-0
--record-separator-zero
将非对齐输出的记录分隔符设置为零字节。这对于与例如 xargs -0 交互很有用。这相当于 \pset recordsep_zero。
-1
--single-transaction
此选项只能与一个或多个 -c 和/或 -f 选项结合使用。它导致 psql 在第一个此类选项之前发出 BEGIN 命令，在最后一个选项之后发出 COMMIT 命令，从而将所有命令包装到单个事务中。如果任何命令失败并且变量 ON_ERROR_STOP 已设置，则发送 ROLLBACK 命令。这确保了要么所有命令成功完成，要么不应用任何更改。
如果命令本身包含 BEGIN、COMMIT 或 ROLLBACK，则此选项不会产生预期效果。此外，如果单个命令不能在事务块内执行，指定此选项将导致整个事务失败。
-?
--help[=主题]
显示有关 psql 的帮助并退出。可选的 topic 参数（默认为 options）选择解释 psql 的哪一部分：commands 描述 psql 的反斜杠命令；options 描述可以传递给 psql 的命令行选项；variables 显示有关 psql 配置变量的帮助。
退出状态
如果 psql 正常结束，则向 shell 返回 0；如果发生自身致命错误（例如，内存不足、文件未找到），则返回 1；如果与服务器的连接中断且会话不是交互式的，则返回 2；如果脚本中发生错误且变量 ON_ERROR_STOP 已设置，则返回 3。
连接到数据库
psql 是一个常规的 PostgreSQL 客户端应用程序。为了连接到数据库，您需要知道目标数据库的名称、服务器的主机名和端口号，以及您要连接到的数据库用户名。可以通过命令行选项告诉 psql 这些参数，分别是 -d、-h、-p 和 -U。如果发现一个不属于任何选项的参数，它将被解释为数据库名（或者，如果已经给出了数据库名，则解释为数据库用户名）。并非所有这些选项都是必需的；有一些有用的默认值。如果省略主机名，psql 将通过 Unix 域套接字连接到本地主机上的服务器，或在 Windows 上通过 TCP/IP 连接到 localhost。默认端口号在编译时确定。由于数据库服务器使用相同的默认值，因此在大多数情况下您不必指定端口。默认数据库用户名是您的操作系统用户名。一旦确定了数据库用户名，它就被用作默认数据库名。请注意，您不能仅以任何数据库用户名连接到任何数据库。您的数据库管理员应该已经告知您的访问权限。
当默认值不太合适时，您可以通过设置环境变量 PGDATABASE、PGHOST、PGPORT 和/或 PGUSER 为适当的值来节省一些输入。拥有一个 ~/.pgpass 文件以避免经常需要输入密码也很方便。
指定连接参数的另一种方法是使用 conninfo 字符串或 URI，它代替数据库名使用。这种机制使您可以非常广泛地控制连接。例如：
$ psql "service=myservice sslmode=require"
$ psql postgresql://dbmaster:5433/mydb?sslmode=require
通过这种方式，您还可以使用 LDAP 来查找连接参数
LDAP 连接参数查询会使用连接服务文件 pg_service.conf（详见第 32.17 节）。pg_service.conf 配置块中，以 ldap:// 开头的行将被识别为 LDAP 统一资源定位符（URL），并触发 LDAP 查询操作。查询结果必须是关键字 = 值的键值对列表，这些键值对将用于设置连接选项。该 URL 需符合 RFC 1959 标准，格式如下：
ldap://[主机名[:端口]]/搜索基准?属性?搜索范围?筛选条件
其中，主机名默认值为 localhost，端口默认值为 389。
若 LDAP 查询成功，pg_service.conf 的解析流程将终止；若无法连接到 LDAP 服务器，解析流程会继续执行。这种机制支持配置降级方案：后续可以配置指向其他 LDAP 服务器的 URL 行、传统的关键字 = 值键值对，或默认连接选项。如果希望在连接 LDAP 服务器失败时直接抛出错误提示，可在 LDAP URL 行后添加一行语法无效的配置。
示例
1. LDAP 条目配置（LDIF 文件）
以下是通过 LDIF 文件创建的 LDAP 条目示例：
version: 1
dn: cn=mydatabase,dc=mycompany,dc=com
changetype: add
objectclass: top
objectclass: device
cn: mydatabase
description: host=dbserver.mycompany.com
description: port=5439
description: dbname=mydb
description: user=mydb_user
description: sslmode=require
2. LDAP 查询 URL
可通过以下 LDAP URL 查询上述条目：
ldap://ldap.mycompany.com/dc=mycompany,dc=com?description?one?(cn=mydatabase)
3. pg_service.conf 配置示例
你也可以将常规的服务文件配置项与 LDAP 查询混合使用。以下是 pg_service.conf 中一个完整的配置块示例：
# 仅主机和端口信息存储在 LDAP 中，数据库名和用户名需显式指定
[customerdb]
dbname=customer
user=appuser
ldap://ldap.acme.com/cn=dbserver,cn=hosts?pgconnectinfo?base?(objectclass=*)
以下是有关所有可用连接选项的信息：
postgresql://[userspec@][hostspec][/dbname][?paramspec]
各部分的定义如下：
userspec:user[:password]hostspec:[host][:port][,...]paramspec:name=value[&...]
URI 的协议标识符可以是 postgresql:// 或 postgres://。其余部分均为可选。
合法 URI 示例：
postgresql://
postgresql://localhost
postgresql://localhost:5433
postgresql://localhost/mydb
postgresql://user@localhost
postgresql://user:secret@localhost
postgresql://other@localhost/otherdb?connect_timeout=10&application_name=myapp
postgresql://host1:123,host2:456/somedb?target_session_attrs=any&application_name=myapp
通常出现在 URI 层级部分的参数，也可以作为命名参数放在查询字符串中。例如：
postgresql:///mydb?host=localhost&port=5433
为了兼容 JDBC 连接 URI，参数中的 ssl=true 会被自动转换为 sslmode=require。
若 URI 中包含具有特殊含义的符号，需要对其进行 百分号编码。例如，等号（=）需替换为 %3D，空格需替换为 %20：
postgresql://user@localhost:5433/mydb?options=-c%20synchronous_commit%3Doff
URI 中的主机部分可以是主机名或 IP 地址。若为 IPv6 地址，需用方括号包裹：
postgresql://[2001:db8::1234]/database
如果由于任何原因（例如，权限不足、服务器未在目标主机上运行等）无法建立连接，psql 将返回错误并终止。
如果标准输入和标准输出都是终端，则 psql 将客户端编码设置为“auto”，这将从区域设置（Unix 系统上的 LC_CTYPE 环境变量）检测适当的客户端编码。如果这不能按预期工作，可以使用环境变量 PGCLIENTENCODING 覆盖客户端编码。
输入 SQL 命令
在正常操作中，psql 提供一个提示符，其中包含 psql 当前连接到的数据库的名称，后跟字符串 =>。例如：
$ psql testdb
psql (18.1)
Type "help" for help.
testdb=>
在提示符下，用户可以键入 SQL 命令。通常，当到达命令终止分号时，输入行会发送到服务器。行尾不会终止命令。因此，为了清晰起见，命令可以跨越多行。如果命令发送并执行无误，则命令的结果将显示在屏幕上。
如果不受信任的用户可以访问未采用安全模式使用模式的数据库，请通过从 search_path 中删除公共可写模式来开始会话。可以在连接字符串中添加 options=-csearch_path=，或在其他 SQL 命令之前发出 SELECT pg_catalog.set_config('search_path', '', false)。这种考虑并非特定于 psql；它适用于执行任意 SQL 命令的每个接口。
每当执行命令时，psql 还会轮询由LISTEN 和 NOTIFY 生成的异步通知事件。
