Note

psql

psql — PostgreSQL 交互式终端

Synopsis

psql [ option ...] [ dbname [ username ]]

Description

psql 是 PostgreSQL 的基于终端的前端。它使您能够以交互方式键入查询，将其发布到 PostgreSQL，并查看查询结果。或者，Importing 可以来自文件，也可以来自命令行参数。另外，psql 提供了许多元命令和各种类似于 shell 的功能，以帮助编写脚本和自动化各种任务。

Options

psql -c '\x' -c 'SELECT * FROM foo;'

or

echo '\x \\ SELECT * FROM foo;' | psql

(\\是分隔符元命令.)

传递给-c的每个 SQL 命令字符串都作为单个请求发送到服务器。因此，即使字符串包含多个 SQL 命令，服务器也将其作为单个事务执行，除非字符串中包含显式的BEGIN/COMMIT命令将其分为多个事务。 (有关服务器如何处理多重查询字符串的更多详细信息，请参见Section 53.2.2.1。)而且，psql 仅输出字符串中最后一个 SQL 命令的结果。这与从文件中读取相同的字符串或将其馈送到 psql 的标准 Importing 时的行为不同，因为 psql 会分别发送每个 SQL 命令。

由于这种行为，在单个-c字符串中放置多个 SQL 命令通常会产生意外结果。最好使用重复的-c命令或将多个命令提供给 psql 的标准 Importing，例如使用上面说明的 echo 或通过 shell here-document，例如：

psql <<EOF
\x
SELECT * FROM foo;
EOF

如果此参数包含=符号或以有效的 URI 前缀(postgresql://或postgres://)开头，则将其视为* conninfo *字符串。有关更多信息，请参见Section 34.1.1。

如果* filename *为-(连字符)，则将读取标准 Importing，直到 EOF 指示或\q元命令为止。这可用于将交互式 Importing 与文件 Importing 进行穿插。但是请注意，在这种情况下不使用 Readline(就像已指定-n一样)。

使用此选项与编写psql < filename稍有不同。通常，两者都能达到您的期望，但是使用-f可以启用一些不错的功能，例如带有行号的错误消息。使用此选项还可能会减少启动开销。另一方面，使用 shell 的 Importing 重定向的变体在理论上可以保证产生与您手工 Importing 的所有内容完全相同的输出。

使用此选项时，除非在命令行上命名其他数据库(选项-d或非选项参数，可能通过服务条目，而不是环境变量)，否则 psql 将连接到数据库postgres。

Note

坚持使用此模式的人可以使用，但不一定鼓励您使用它。特别是，如果您在一行上混合使用 SQL 和元命令，则对于经验不足的用户，执行 Sequences 可能并不总是很清楚。

请注意，此选项将在整个会话中保持设置状态，因此会影响元命令\connect的使用以及初始连接尝试。

此选项从不是必需的，因为如果服务器要求密码验证，则 psql 将自动提示 Importing 密码。但是，psql 会浪费连接尝试，以便发现服务器需要密码。在某些情况下，值得 Importing-W以避免额外的连接尝试。

请注意，此选项将在整个会话中保持设置状态，因此会影响元命令\connect的使用以及初始连接尝试。

如果命令本身包含BEGIN，COMMIT或ROLLBACK，则此选项将不会产生所需的效果。另外，如果不能在事务块内执行单个命令，则指定此选项将导致整个事务失败。

Exit Status

如果 psql 正常完成，它将返回 0 到 Shell；如果发生自身的致命错误(例如，内存不足，找不到文件)，则返回 1；如果与服务器的连接断开并且会话不是交互式的，则返回 2；脚本中发生错误，并设置了变量ON_ERROR_STOP。

Usage

连接到数据库

psql 是常规的 PostgreSQLClient 端应用程序。为了连接到数据库，您需要知道目标数据库的名称，服务器的主机名和端口号以及要用作连接的用户名。可以通过命令行选项告诉 psql 这些参数，分别是-d，-h，-p和-U。如果找到的参数不属于任何选项，它将被解释为数据库名称(或用户名，如果已经提供了数据库名称)。并非所有这些选项都是必需的。有一些有用的默认值。如果省略主机名，则 psql 将通过 Unix 域套接字连接到 localhost 上的服务器，或者通过 TCP/IP 连接到不具有 Unix 域套接字的计算机上的localhost。默认端口号在编译时确定。由于数据库服务器使用相同的缺省值，因此在大多数情况下，您不必指定端口。默认用户名是您的 os 用户名，默认数据库名也是。请注意，您不能仅以任何用户名连接到任何数据库。您的数据库 Management 员应已将您的访问权限告知您。

当默认值不太合适时，可以通过将环境变量PGDATABASE，PGHOST，PGPORT和/或PGUSER设置为适当的值来节省键入时间。 (有关其他环境变量，请参见Section 34.14。)拥有~/.pgpass文件也很方便，以避免经常需要 Importing 密码。有关更多信息，请参见Section 34.15。

指定连接参数的另一种方法是使用* conninfo *字符串或 URI，而不是数据库名称。此机制使您可以非常广泛地控制连接。例如：

$ psql "service=myservice sslmode=require"
$ psql postgresql://dbmaster:5433/mydb?sslmode=require

这样，您还可以使用 LDAP 来进行连接参数查找，如Section 34.17中所述。有关所有可用连接选项的更多信息，请参见Section 34.1.2。

如果由于任何原因(例如，特权不足，目标主机上的服务器未运行等)而无法构建连接，则 psql 将返回错误并终止。

如果标准 Importing 和标准输出均为终端，则 psql 将 Client 端编码设置为“自动”，这将从区域设置(Unix 系统上的LC_CTYPE环境变量)中检测相应的 Client 端编码。如果无法正常工作，则可以使用环境变量PGCLIENTENCODING覆盖 Client 端编码。

ImportingSQL 命令

在正常操作中，psql 会提示您 Importing 当前与 psql 连接的数据库的名称，后跟字符串=>。例如：

$ psql testdb
psql (11.8)
Type "help" for help.

testdb=>

在提示符下，用户可以键入 SQL 命令。通常，当到达命令终止分号时，会将 Importing 行发送到服务器。行尾不会终止命令。因此，为了清楚起见，命令可以分布在几行上。如果命令已正确发送和执行，则命令的结果将显示在屏幕上。

如果不受信任的用户可以访问未采用安全模式使用模式的数据库，请通过从search_path删除可公开写模式来开始会话。可以将options=-csearch_path=添加到连接字符串中，或在其他 SQL 命令之前发出SELECT pg_catalog.set_config('search_path', '', false)。此注意事项并非特定于 psql；它适用于执行任意 SQL 命令的每个接口。

每当执行命令时，psql 还将轮询LISTEN和NOTIFY生成的异步通知事件。

将 C 样式的块 Comments 传递到服务器进行处理和除去时，psql 除去 SQL 标准 Comments。

Meta-Commands

在 psql 中 Importing 的任何以引号反斜杠开头的内容都是 psql 元命令，该命令由 psql 本身处理。这些命令使 psql 对 Management 或脚本化更加有用。元命令通常称为斜杠或反斜杠命令。

psql 命令的格式为反斜杠，后跟命令动词，然后是任何参数。参数与命令动词彼此分隔，并由任意数量的空格字符分隔。

要在参数中包含空格，可以用单引号将其引起来。要在参数中包含单引号，请在单引号引起来的文本中写两个单引号。此外，单引号中包含的所有内容都可以用 C 代替\n(换行)，\t(制表符)，\b(退格键)，\r(回车符)，\f(换页)，\ * digits *(八进制)，和\x * digits *(十六进制)。单引号文本中任何其他字符前面的反斜杠都会引用该单个字符，无论它是什么。

如果参数中出现未加引号的冒号(:)后跟 psql 变量名，则将其替换为变量的值，如SQL Interpolation中所述。此处描述的:'variable_name'和:"variable_name"形式也适用。 :{?variable_name}语法允许测试是否定义了变量。用 TRUE 或 FALSE 代替。用反斜杠将冒号转义可防止其被替换。

在参数内，用反引号(```)引起来的文本将作为传递给 shell 的命令行使用。命令的输出(删除了所有尾随的换行符)将替换反引号引起的文本。在反引号内的文本内，不进行特殊的引号或其他处理，除了在:variable_name的出现(其中* variable_name *是 psql 变量名称)替换为变量的值。同样，:'variable_name'的外观将替换为适当引用以成为单个 shell 命令参数的变量的值。 (除非您非常确定变量中有什么，否则后一种形式几乎总是可取的.)由于不能在所有平台上安全地引用回车符和换行符，因此:'variable_name'表单会显示错误消息，并且不能替代变量值中出现此类字符时的值。

一些命令将 SQL 标识符(例如表名)作为参数。这些参数遵循 SQL 的语法规则：不带引号的字母被强制小写，而双引号(")保护字母不进行大小写转换，并允许将空格合并到标识符中。在双引号中，成对的双引号会在结果名称中减少为单双引号。例如，FOO"BAR"BAZ被解释为fooBARbaz，而"A weird"" name"成为A weird" name。

对参数的解析在该行的结尾处停止，或者在找到另一个未引用的反斜杠时停止。无引号的反斜杠被视为新元命令的开始。特殊序列\\(两个反斜杠)标记参数的结尾，并 continue 解析 SQL 命令(如果有)。这样，SQL 和 psql 命令可以自由地混合在一行上。但是无论如何，元命令的参数不能 continue 超出行尾。

许多元命令作用于当前查询缓冲区。这只是一个缓冲区，用于保存已键入但尚未发送到服务器以执行的任何 SQL 命令文本。这将包括先前的 Importing 行以及在同一行上的 meta 命令之前出现的所有文本。

定义了以下元命令：

如果该命令省略了数据库名称，用户，主机或端口，则新连接可以重用先前 Connecting 的值。默认情况下，除非处理* conninfo 字符串，否则将重用先前连接的值。传递第一个参数-reuse-previous=on或-reuse-previous=off会覆盖该默认值。当命令既未指定也不重用特定参数时，将使用 libpq 缺省值。将 dbname ， username ， host 或 port *指定为-等效于忽略该参数。

如果成功构建了新连接，则先前的连接将关闭。如果连接尝试失败(错误的用户名，访问被拒绝等)，则仅当 psql 处于交互模式时才保留先前的连接。执行非交互式脚本时，处理将立即停止并显示错误。选择此区别的目的是一方面为用户提供了避免 Importing 错误的便利，另一方面又选择了一种安全机制，确保脚本不会意外地作用于错误的数据库。

Examples:

=> \c mydb myuser host.dom 6432
=> \c service=foo
=> \c "host=localhost port=5432 dbname=mydb connect_timeout=10 sslmode=disable"
=> \c postgresql://tom@localhost/mydb?application_name=myapp

Tip

要打印当前的工作目录，请使用\! pwd。

当指定program时，* command *由 psql 执行，并且从command 传递到 command的数据在服务器和 Client 端之间路由。同样，执行特权是本地用户的特权，而不是服务器的特权，并且不需要 SQL 超级用户特权。

对于\copy ... from stdin，从发出该命令的同一源读取数据行，一直持续到读取\.或流到达 EOF 为止。此选项对于在 SQL 脚本文件中内联填充表很有用。对于\copy ... to stdout，输出将发送到与 psql 命令输出相同的位置，并且不会打印COPY count命令状态(因为它可能与数据行混淆)。要读取/写入 psql 的标准 Importing 或输出而不管当前命令源或\o选项如何，请写入from pstdin或to pstdout。

该命令的语法与 SQL COPY命令的语法相似。数据源/目标以外的所有其他选项均已为COPY指定。因此，特殊的解析规则适用于\copy元命令。与大多数其他元命令不同，该行的其余部分始终被视为\copy的参数，并且在参数中既不执行变量插值也不执行反引号扩展。

Tip

获得与\copy ... to相同的结果的另一种方法是使用 SQL COPY ... TO STDOUT命令并以\g filename或\g |program终止它。与\copy不同，此方法允许命令跨越多行。同样，可以使用变量插值和反引号扩展。

Tip

这些操作的效率不如带有文件或程序数据源或目标的 SQL COPY命令，因为所有数据都必须通过 Client 端/服务器连接传递。对于大量数据，SQL 命令可能更可取。

每个列规范可以是列号(从 1 开始)或列名。通常的 SQL 情况下的折叠和引用规则适用于列名。如果省略，* colV 作为第 1 列， colH 作为第 2 列. colH 必须与 colV 不同。如果未指定 colD ，那么查询结果中必须恰好有三列，并且既不是 colV 也不是 colH 的列将被视为 colD *。

垂直标题显示在最左边的列中，包含在* colV *列中找到的值，其 Sequences 与查询结果中的 Sequences 相同，但删除了重复项。

显示为第一行的水平标题包含在* colH 列中找到的值，并删除了重复项。默认情况下，它们的显示 Sequences 与查询结果中的 Sequences 相同。但是，如果给出了可选的 sortcolH 参数，它将标识一列其值必须为整数的列，并且 colH 中的值将出现在水平标题中，并根据相应的 sortcolH *值进行排序。

在交叉表网格内部，对于* colH 的每个不同值x和 colV 的每个不同值y，位于交点(x,y)的单元格包含查询结果行中colD列的值， colH的值是x， colV *的值是y。如果没有这样的行，则该单元格为空。如果有多个这样的行，则会报告错误。

对于某些类型的关系，\d显示每列的其他信息：序列的列值，索引的索引表达式以及外部表的外部数据包装器选项。

命令形式\d+相同，只是显示了更多信息：显示了与表的列关联的所有 Comments，以及表中是否存在 OID，如果关系是视图，则为视图定义，这是非默认值replica identity设置。

默认情况下，仅显示用户创建的对象。提供一个模式或S修饰符以包含系统对象。

Note

如果使用\d而不带* pattern *参数，则它等效于\dtvmsE，它将显示所有可见表，视图，实例化视图，序列和外部表的列表。这纯粹是一种方便的措施。

\dd显示与* pattern *匹配的对象的描述，或者如果没有给出参数，则显示适当类型的可见对象的描述。但无论哪种情况，仅列出具有描述的对象。默认情况下，仅显示用户创建的对象。提供一个模式或S修饰符以包含系统对象。

可以使用COMMENT SQL 命令创建对象的描述。

更改默认特权命令用于设置默认访问权限。特权显示的含义在GRANT下解释。

Caution

\deu+可能还会显示远程用户的用户名和密码，因此请注意不要泄露它们。

Tip

要查找带有参数或返回特定数据类型值的函数，请使用寻呼机的搜索功能滚动\df输出。

GRANT和REVOKE命令用于设置访问权限。 GRANT下解释特权显示的含义。

ALTER ROLE和ALTER DATABASE命令用于定义每个角色和每个数据库的配置设置。

然后根据 psql 的常规规则重新解析查询缓冲区的新内容，将整个缓冲区视为一行。任何完整的查询都会立即执行；也就是说，如果查询缓冲区包含分号或以分号结尾，则执行该操作。剩下的将在查询缓冲区中 await；Importing 分号或\g发送，或\r通过清除查询缓冲区将其取消。将缓冲区视为单行主要影响元命令：元命令之后缓冲区中的内容将被视为元命令的参数，即使它跨越多行也是如此。 (因此，您不能以这种方式制作使用元命令的脚本.为此请使用\i.)

如果指定了行号，则 psql 将光标定位在文件或查询缓冲区的指定行上。请注意，如果给出单个全数字参数，则 psql 假定它是行号，而不是文件名。

Tip

有关如何配置和自定义编辑器的信息，请参见Environment。

=> \echo `date`
Tue Oct 26 21:40:57 CEST 1999

如果第一个参数是未加引号的-n，则不写结尾的换行符。

Tip

如果使用\o命令重定向查询输出，则可能希望使用\qecho代替此命令。

目标函数可以仅通过名称指定，也可以通过名称和参数指定，例如foo(integer, text)。如果有多个同名函数，则必须给出参数类型。

如果未指定功能，则会显示空白的CREATE FUNCTION模板进行编辑。

如果指定了行号，则 psql 将光标定位在函数主体的指定行上。 (请注意，函数主体通常不在文件的第一行开始.)

与大多数其他元命令不同，该行的其余部分始终被视为\ef的参数，并且在参数中既不执行变量插值也不执行反引号扩展。

Tip

有关如何配置和自定义编辑器的信息，请参见Environment。

如果未指定视图，则会显示空白的CREATE VIEW模板进行编辑。

如果指定了行号，则 psql 将光标定位在视图定义的指定行上。

与大多数其他元命令不同，该行的其余部分始终被视为\ev的参数，并且在参数中既不执行变量插值也不执行反引号扩展。

如果当前查询缓冲区为空，则重新执行最近发送的查询。除了该行为外，不带参数的\g本质上等效于分号。带参数的\g是\o命令的“一次性”替代。

如果参数以|开头，则该行的其余全部为* command *要执行，并且变量插值和反引号扩展均未执行。该行的其余部分仅按字面意义传递给 Shell。

如果当前查询缓冲区为空，则描述最近发送的查询。

=> SELECT format('create index on my_table(%I)', attname)
-> FROM pg_attribute
-> WHERE attrelid = 'my_table'::regclass AND attnum > 0
-> ORDER BY attnum
-> \gexec
CREATE INDEX
CREATE INDEX
CREATE INDEX
CREATE INDEX

生成的查询将按返回行的 Sequences 执行，如果有多个列，则在每一行中从左到右执行。空字段将被忽略。生成的查询从字面上发送到服务器进行处理，因此它们既不能是 psql 元命令，也不能包含 psql 变量引用。如果任何单个查询失败，除非设置ON_ERROR_STOP，否则其余查询将 continue 执行。每个查询的执行都经过ECHO处理。 (使用\gexec时，通常建议将ECHO设置为all或queries.)查询日志记录，单步模式，计时和其他查询执行功能也适用于每个生成的查询。

如果当前查询缓冲区为空，则重新执行最近发送的查询。

=> SELECT 'hello' AS var1, 10 AS var2
-> \gset
=> \echo :var1 :var2
hello 10

如果指定* prefix *，则该字符串将放在查询的列名之前，以创建要使用的变量名：

=> SELECT 'hello' AS var1, 10 AS var2
-> \gset result_
=> \echo :result_var1 :result_var2
hello 10

如果列结果为 NULL，则未设置而不是设置相应的变量。

如果查询失败或不返回一行，则不会更改任何变量。

如果当前查询缓冲区为空，则重新执行最近发送的查询。

与大多数其他元命令不同，该行的其余部分始终被视为\help的参数，并且在参数中既不执行变量插值也不执行反引号扩展。

Note

为了简化键入，不必引用由几个单词组成的命令。因此，可以 Importing \help alter table 。

如果* filename *为-(连字符)，则将读取标准 Importing，直到 EOF 指示或\q元命令为止。这可用于将交互式 Importing 与文件 Importing 进行穿插。请注意，只有在最外层处于活动状态时，才会使用 Readline 行为。

Note

如果要在阅读时看到屏幕上的线条，必须将变量ECHO设置为all。

\if和\elif命令读取其参数，并将其评估为布尔表达式。如果表达式的结果为true，则处理将 continue 正常进行；否则，处理将 continue 进行。否则，将跳过行，直到达到匹配的\elif，\else或\endif。一旦\if或\elif测试成功，就不会求值同一块中后来的\elif命令的自变量，而是将其视为 false。仅当没有成功匹配\if或\elif时，才处理\else之后的行。

就像其他反斜杠命令参数一样，\if或\elif命令的* expression *参数也要进行变量插值和反引号扩展。之后，将像打开/关闭选项变量的值一样对它进行评估。因此，有效值是true，false，1，0，on，off，yes，no之一的任何明确的不区分大小写的匹配。例如，t，T和tR都将被视为true。

不能正确评估为 true 或 false 的表达式将生成警告，并被视为 false。

正常情况下，将解析被跳过的行以标识查询和反斜杠命令，但是查询不会发送到服务器，并且将忽略条件语句(\if，\elif，\else，\endif)以外的反斜杠命令。仅检查条件命令的有效嵌套。跳过行中的变量引用不会扩展，也不执行反引号扩展。

给定条件块的所有反斜杠命令必须出现在同一源文件中。如果在关闭所有本地\if -block 之前在主 Importing 文件或\include -ed 文件上达到 EOF，则 psql 将引发错误。

这是一个例子：

-- check for the existence of two separate records in the database and store
-- the results in separate psql variables
SELECT
    EXISTS(SELECT 1 FROM customer WHERE customer_id = 123) as is_customer,
    EXISTS(SELECT 1 FROM employee WHERE employee_id = 456) as is_employee
\gset
\if :is_customer
    SELECT * FROM customer WHERE customer_id = 123;
\elif :is_employee
    \echo 'is not a customer but is an employee'
    SELECT * FROM employee WHERE employee_id = 456;
\else
    \if yes
        \echo 'not a customer or employee'
    \else
        \echo 'this will never print'
    \endif
\endif

Tip

使用\lo_list查找大对象的 OID。

foo=> \lo_import '/home/peter/pictures/photo.xcf' 'a picture of me'
lo_import 152801

该响应指示大对象接收到对象 ID 152801，该对象 ID 将来可用于访问新创建的大对象。为了便于阅读，建议始终将人类可读的 Comments 与每个对象相关联。可以使用\lo_list命令查看 OID 和 Comments。

请注意，此命令与服务器端lo_import略有不同，因为它充当本地文件系统上的本地用户，而不是服务器的用户和文件系统。

Tip

使用\lo_list查找大对象的 OID。

如果参数以|开头，则该行的其余全部为* command *要执行，并且变量插值和反引号扩展均未执行。该行的其余部分仅按字面意义传递给 Shell。

“查询结果”包括从数据库服务器获得的所有表，命令响应和通知，以及查询数据库的各种反斜杠命令的输出(例如\d)；但不是错误消息。

Tip

要在查询结果之间插入文本输出，请使用\qecho。

默认情况下，\prompt使用终端进行 Importing 和输出。但是，如果使用了-f命令行开关，则\prompt使用标准 Importing 和标准输出。

\pset不带任何参数将显示所有打印选项的当前状态。

可调打印选项包括：

unaligned格式将一行的所有列写在一行上，并由当前活动的字段分隔符分隔。这对于创建可能打算由其他程序读取的输出(例如，制表符分隔或逗号分隔的格式)很有用。

aligned格式是标准的，人类可读的，格式良好的文本输出；这是默认值。

wrapped格式与aligned类似，但是跨行包装宽数据值以使输出适合目标列宽。如columns选项所述确定目标宽度。请注意，psql 不会尝试包装列标题标题。因此，如果列标题所需的总宽度超过目标，则wrapped格式的行为与aligned相同。

html，asciidoc，latex，latex-longtable和troff-ms格式使用相应的标记语言列出了旨在包含在文档中的表格。它们不是完整的文件！在 HTML 中这可能不是必需的，但是在 LaTeX 中，您必须具有完整的文档包装器。 latex-longtable还需要 LaTeX longtable和booktabs软件包。

ascii样式使用纯 ASCII 字符。数据中的换行符在右边距中使用+符号显示。当wrapped格式将数据从一行换行到下一行而没有换行符时，在第一行的右边距中显示一个点(.)，在下一行的左边距中再次显示一个点。

old-ascii样式使用普通 ASCII 字符，并使用 PostgreSQL 8.4 及更早版本中使用的格式样式。使用:符号代替左列分隔符来显示数据中的换行符。当数据从一行换到另一行而没有换行符时，使用;符号代替左侧的列分隔符。

unicode样式使用 Unicode 框画字符。数据中的换行符在右边距中使用回车符显示。当数据从一行换行到下一行而没有换行符时，在第一行的右边距中显示省略号，并在下一行的左边距中显示省略号。

当border设置大于零时，linestyle选项还确定绘制边框线的字符。纯 ASCII 字符在任何地方都可以使用，但是 Unicode 字符在可以识别它们的显示器上看起来更好。

当pager选项为off时，不使用寻呼程序。当pager选项为on时，将在适当的时候使用寻呼机，即当输出到终端并且不适合屏幕时。 pager选项也可以设置为always，这将使寻呼机用于所有终端输出，无论它是否适合屏幕显示。 \pset pager不带* value *可以打开和关闭寻呼机的使用。

在latex-longtable格式中，这控制着包含左对齐数据类型的每一列的比例宽度。它被指定为以空格分隔的值列表，例如'0.2 0.2 0.6'。未指定的输出列使用最后指定的值。

Examples部分中提供了这些不同格式的外观说明。

Tip

\pset有多种快捷方式命令。参见\a，\C，\f，\H，\t，\T和\x。

\set不带任何参数将显示所有当前设置的 psql 变量的名称和值。

有效的变量名称可以包含字母，数字和下划线。有关详情，请参见下面的Variables部分。变量名称区分大小写。

某些变量是特殊的，因为它们控制 psql 的行为或自动设置以反映连接状态。这些变量记录在下面的Variables中。

Note

该命令与 SQL 命令SET无关。

testdb=> \setenv PAGER less
testdb=> \setenv LESS -imx4F

目标函数可以仅通过名称指定，也可以通过名称和参数指定，例如foo(integer, text)。如果有多个同名函数，则必须给出参数类型。

如果在命令名后附加了+，则对输出行进行编号，而函数主体的第一行为行 1.

与大多数其他元命令不同，该行的其余部分始终被视为\sf的参数，并且在参数中既不执行变量插值也不执行反引号扩展。

如果在命令名称后附加了+，则输出行从 1 开始编号。

与大多数其他元命令不同，该行的其余部分始终被视为\sv的参数，并且在参数中既不执行变量插值也不执行反引号扩展。

大多数控制 psql 行为的变量不能被取消设置。而是将\unset命令解释为将其设置为默认值。请参阅下面的Variables。

如果参数以|开头，则该行的其余全部为* command *要执行，并且变量插值和反引号扩展均未执行。该行的其余部分仅按字面意义传递给 Shell。

如果当前查询缓冲区为空，则重新执行最近发送的查询。

这是\dp(“显示权限”)的别名。

与大多数其他元命令不同，该行的其余部分始终被视为\!的参数，并且在参数中既不执行变量插值也不执行反引号扩展。该行的其余部分仅按字面意义传递给 Shell。

通常，即使当前行上仍有更多 Importing，psql 也会在到达命令结束分号后立即将 SQL 命令分派给服务器。因此例如进入

select 1; select 2; select 3;

将导致将三个 SQL 命令分别发送到服务器，并在 continue 下一个命令之前显示每个命令的结果。但是，Importing 为\;的分号将不会触发命令处理，因此前一个命令和后一个命令将被有效组合并在一个请求中发送给服务器。所以举个例子

select 1\; select 2\; select 3;

导致在达到非反斜杠分号时，在单个请求中将三个 SQL 命令发送到服务器。服务器将这样的请求作为单个事务执行，除非字符串中包含明确的BEGIN/COMMIT命令将其分为多个事务。 (有关服务器如何处理多查询字符串的更多详细信息，请参见Section 53.2.2.1。)psql 仅打印每个请求收到的最后一个查询结果。在此示例中，虽然确实执行了所有三个SELECT，但是 psql 仅打印3。

Patterns

各种\d命令接受* pattern *参数以指定要显示的对象名称。在最简单的情况下，模式只是对象的确切名称。模式中的字符通常折叠成小写，就像 SQL 名称一样。例如，\dt FOO将显示名为foo的表。与在 SQL 名称中一样，在模式周围放置双引号会停止折叠为小写。如果需要在模式中包含实际的双引号字符，请将其写为双引号序列中的一对双引号。再次符合 SQL 带引号的标识符的规则。例如，\dt "FOO""BAR"将显示名为FOO"BAR的表(而不是foo"bar)。与一般的 SQL 名称规则不同，您可以在模式的一部分周围加上双引号，例如\dt FOO"FOO"BAR将显示名为fooFOObar的表。

只要* pattern 参数被完全省略，\d命令就会显示在当前模式搜索路径中可见的所有对象-这等效于使用*作为模式。 (如果对象包含的架构位于搜索路径中，并且在搜索路径中较早出现的对象没有相同种类和名称，则称该对象为可见*.显式架构限定.)要查看数据库中的所有对象而不论可见性如何，请使用*.*作为模式。

在模式中，*匹配任何字符序列(包括没有字符)，而?匹配任何单个字符。 (此表示法可与 Unix Shell 文件名模式相提并论.)例如，\dt int*显示名称以int开头的表。但是在双引号中，*和?失去了这些特殊含义，只是在字面上匹配。

包含点(.)的模式被解释为架构名称模式，后跟对象名称模式。例如，\dt foo*.*bar*显示表名包含bar的所有表，这些表的模式名以foo开头。如果没有点出现，则该模式仅匹配在当前模式搜索路径中可见的对象。同样，双引号中的点失去其特殊含义，并且在字面上匹配。

高级用户可以使用正则表达式表示法，例如字符类，例如[0-9]来匹配任何数字。所有正则表达式特殊字符均按Section 9.7.3的规定工作，除了.如上所述(用作分隔符)，*转换为正则表达式.*，?转换为.以及$从字面上匹配。您可以根据需要通过将?表示.，(R+|)表示R*或(R|)表示R?来模拟这些模式字符。不需要$作为正则表达式字符，因为该模式必须与整个名称匹配，这与通常对正则表达式的解释不同(换句话说，$自动添加到您的模式)。如果您不希望锚定图案，请在开头和/或结尾处写*。请注意，在双引号中，所有正则表达式特殊字符都会失去其特殊含义，并且会在字面上进行匹配。同样，正则表达式特殊字符在运算符名称模式(即\do的参数)中按字面值进行匹配。

Advanced Features

Variables

psql 提供了类似于普通 Unix 命令 shell 的变量替换功能。变量只是名称/值对，其中值可以是任何长度的任何字符串。名称必须由字母(包括非拉丁字母)，数字和下划线组成。

要设置变量，请使用 psql 元命令\set。例如，

testdb=> \set foo bar

将变量foo设置为值bar。要检索变量的内容，请在名称前加上冒号，例如：

testdb=> \echo :foo
bar

这在常规 SQL 命令和元命令中均有效；在下面的SQL Interpolation中有更多详细信息。

如果您在没有第二个参数的情况下调用\set，则该变量将设置为空字符串值。要取消设置(即删除)变量，请使用命令\unset。要显示所有变量的值，请不带任何参数调用\set。

Note

\set的参数应遵循与其他命令相同的替换规则。因此，您可以构造有趣的引用，例如\set :foo 'something'并分别获得 Perl 或 PHP 的“软链接”或“变量变量”。不幸的是(或者幸运的是？)，无法对这些构造做任何有用的事情。另一方面，\set bar :foo是复制变量的完美有效方法。

psql 特别处理了许多这些变量。它们表示某些选项设置，可以在运行时通过更改变量的值来更改这些设置，或者在某些情况下表示 psql 的可更改状态。按照惯例，所有经过特殊处理的变量名称均由所有大写 ASCII 字母(以及可能的数字和下划线)组成。为了确保将来具有最大的兼容性，请避免出于自己的目的使用此类变量名。

控制 psql 行为的变量通常不能取消设置或设置为无效值。允许使用\unset命令，但将其解释为将变量设置为其默认值。对于接受第二个参数的控制变量，不带第二个参数的\set命令被解释为将变量设置为on。同样，接受值on和off的控制变量也将接受布尔值的其他常见拼写，例如true和false。

特殊处理的变量是：

Note

在自动提交模式下，您必须通过 ImportingABORT或ROLLBACK明确放弃任何失败的事务。另外请记住，如果您退出会话而不提交，则您的工作将会丢失。

Note

自动提交模式是 PostgreSQL 的传统行为，但是自动提交模式更接近 SQL 规范。如果您希望自动提交，则可能希望在系统范围的psqlrc文件或~/.psqlrc文件中进行设置。

Tip

尽管您可以使用此功能使用任何输出格式，但是默认的aligned格式看起来很糟糕，因为每组FETCH_COUNT行将分别设置格式，从而导致行组中的列宽变化。其他输出格式效果更好。

Note

Bash 毫不掩饰地 feature 窃了此功能。

\set HISTFILE ~/.psql_history- :DBNAME

~/.psqlrc中的 in 将导致 psql 为每个数据库维护单独的历史记录。

Note

Bash 毫不掩饰地 feature 窃了此功能。

Note

Bash 毫不掩饰地 feature 窃了此功能。

Note

Bash 毫不掩饰地 feature 窃了此功能。

SQL Interpolation

psql 变量的一个关键功能是您可以将它们替换(“内插”)到常规 SQL 语句以及元命令的参数中。此外，psql 提供了一些设施，以确保正确引用用作 SQLLiterals 和标识符的变量值。不带引号插值的语法是在变量名前加冒号(:)。例如，

testdb=> \set foo 'my_table'
testdb=> SELECT * FROM :foo;

将查询表my_table。请注意，这可能是不安全的：变量的值是按字面值复制的，因此它可以包含不平衡的引号，甚至包含反斜杠命令。您必须确保将它放在哪里有意义。

当将值用作 SQLLiterals 或标识符时，最安全的方法是对其进行引用。要将变量的值引用为 SQLLiterals，请在单引号中写一个冒号，后跟变量名称。要将值用作 SQL 标识符，请在冒号后加上双引号，然后在变量名前加上双引号。这些构造可以正确处理包含在变量值中的引号和其他特殊字符。前面的示例将通过这种方式更安全地编写：

testdb=> \set foo 'my_table'
testdb=> SELECT * FROM :"foo";

在带引号的 SQLLiterals 和标识符中不会执行变量插值。因此，诸如':foo'之类的构造不适用于从变量的值中产生带引号的 Literals(并且如果起作用，将是不安全的，因为它将无法正确处理值中嵌入的引号)。

此机制的一个示例用法是将文件的内容复制到表列中。首先将文件加载到变量中，然后将变量的值作为带引号的字符串插入：

testdb=> \set content `cat my_file.txt`
testdb=> INSERT INTO my_table VALUES (:'content');

(请注意，如果my_file.txt包含 NUL 字节，这仍然行不通.psql 不支持在变量值中嵌入 NUL 字节.)

由于冒号可以合法地出现在 SQL 命令中，因此除非当前设置了命名变量，否则不会替换明显的插值尝试(即:name，:'name'或:"name")。无论如何，您都可以使用反斜杠转义冒号，以防止其被替换。

:{?name}特殊语法根据变量是否存在返回 TRUE 或 FALSE，因此始终替换该变量，除非冒号用反斜杠转义。

变量的冒号语法是嵌入式查询语言(例如 ECPG)的标准 SQL。数组切片和类型转换的冒号语法是 PostgreSQL 扩展，有时可能与标准用法冲突。将变量值转义为 SQLLiterals 或标识符的冒号引用语法是 psql 扩展。

Prompting

可以根据您的喜好自定义提示 psql 问题。三个变量PROMPT1，PROMPT2和PROMPT3包含字符串和特殊的转义序列，用于描述提示的外观。提示 1 是 psql 请求新命令时发出的普通提示。当在命令 Importing 期间需要更多 Importing 时，例如因为命令未以分号终止或未关闭引号，则发出提示 2.当您运行 SQL COPY FROM STDIN命令并且需要在终端上 Importing 行值时，将发出提示 3.

所选提示变量的值按字面意义打印，除非遇到百分号(%)。根据下一个字符，某些其他文本将被替换。定义的替换是：

testdb=> \set PROMPT1 '%[%033[1;33;40m%]%n@%/%R%[%033[0m%]%# '

会在兼容 VT100 且具有颜色的终端上显示黑底黑字(33;40)的粗体(1;)提示。

要将百分号插入提示中，请 Importing%%。默认提示是'%/%R%# '表示提示 1 和 2，'>> '表示提示 3.

Note

从 tcsh sh 窃此功能。

Command-Line Editing

psql 支持 Readline 库，以方便进行行编辑和检索。当 psql 退出时，命令历史记录将自动保存，并在 psql 启动时重新加载。尽管补全逻辑不声称是 SQL 解析器，但也支持制表符补全。制表符补全生成的查询也可能会干扰其他 SQL 命令，例如SET TRANSACTION ISOLATION LEVEL。如果由于某种原因您不喜欢制表符补全，可以通过将其放在主目录中名为.inputrc的文件中将其关闭：

$if psql
set disable-completion on
$endif

(这不是 psql，而是 Readline 功能.有关更多详细信息，请阅读其文档.)

Environment

PSQL_EDITOR_LINENUMBER_ARG='+'
PSQL_EDITOR_LINENUMBER_ARG='--line '

在 Unix 系统上，默认值为+(与默认编辑器vi对应，对许多其他常用编辑器很有用)；但 Windows 系统上没有默认设置。

与大多数其他 PostgreSQLUtil 一样，该 Util 也使用 libpq 支持的环境变量(请参见Section 34.14)。

Files

系统范围的启动文件名为psqlrc，可以在安装的“系统配置”目录中找到，该目录可以通过运行pg_config --sysconfdir来最可靠地标识。默认情况下，该目录相对于包含 PostgreSQL 可执行文件的目录为../etc/。可以通过PGSYSCONFDIR环境变量显式设置此目录的名称。

用户的个人启动文件名为.psqlrc，并在调用用户的主目录中查找。在缺少这种概念的 Windows 上，个人启动文件名为%APPDATA%\postgresql\psqlrc.conf。可以通过PSQLRC环境变量显式设置用户启动文件的位置。

通过在文件名后加上破折号和 PostgreSQL 主要或次要发行版号，例如~/.psqlrc-9.2或~/.psqlrc-9.2.5，可以使系统范围内的启动文件和用户的个人启动文件都成为 psql-version-specific。与非版本特定的文件相比，将优先读取最特定的版本匹配文件。

可以通过HISTFILE psql 变量或PSQL_HISTORY环境变量显式设置历史记录文件的位置。

Notes

如果要使用 psql 连接到多个具有不同主要版本的服务器，则建议使用最新版本的 psql。另外，您可以保留每个主要版本的 psql 副本，并确保使用与相应服务器匹配的版本。但是在实践中，这种额外的复杂性是不必要的。

Windows 用户注意事项

psql 被构建为“控制台应用程序”。由于 Windows 控制台窗口使用与系统其余部分不同的编码，因此在 psql 中使用 8 位字符时必须格外小心。如果 psql 检测到有问题的控制台代码页，它将在启动时警告您。要更改控制台代码页，需要做两件事：

Examples

第一个示例显示了如何将命令分布在多行 Importing 上。注意更改提示：

testdb=> CREATE TABLE my_table (
testdb(>  first integer not null default 0,
testdb(>  second text)
testdb-> ;
CREATE TABLE

现在再次查看表定义：

testdb=> \d my_table
              Table "public.my_table"
 Column |  Type   | Collation | Nullable | Default
--------+---------+-----------+----------+---------
 first  | integer |           | not null | 0
 second | text    |           |          |

现在，我们将提示更改为更有趣的内容：

testdb=> \set PROMPT1 '%n@%m %~%R%# '
peter@localhost testdb=>

假设您已经用数据填充了表并想看一下它：

peter@localhost testdb=> SELECT * FROM my_table;
 first | second
-------+--------
     1 | one
     2 | two
     3 | three
     4 | four
(4 rows)

您可以使用\pset命令以不同方式显示表：

peter@localhost testdb=> \pset border 2
Border style is 2.
peter@localhost testdb=> SELECT * FROM my_table;
+-------+--------+
| first | second |
+-------+--------+
|     1 | one    |
|     2 | two    |
|     3 | three  |
|     4 | four   |
+-------+--------+
(4 rows)

peter@localhost testdb=> \pset border 0
Border style is 0.
peter@localhost testdb=> SELECT * FROM my_table;
first second
----- ------
    1 one
    2 two
    3 three
    4 four
(4 rows)

peter@localhost testdb=> \pset border 1
Border style is 1.
peter@localhost testdb=> \pset format unaligned
Output format is unaligned.
peter@localhost testdb=> \pset fieldsep ","
Field separator is ",".
peter@localhost testdb=> \pset tuples_only
Showing only tuples.
peter@localhost testdb=> SELECT second, first FROM my_table;
one,1
two,2
three,3
four,4

或者，使用简短命令：

peter@localhost testdb=> \a \t \x
Output format is aligned.
Tuples only is off.
Expanded display is on.
peter@localhost testdb=> SELECT * FROM my_table;
-[ RECORD 1 ]-
first  | 1
second | one
-[ RECORD 2 ]-
first  | 2
second | two
-[ RECORD 3 ]-
first  | 3
second | three
-[ RECORD 4 ]-
first  | 4
second | four

如果合适，查询结果可以使用\crosstabview命令以交叉表的形式显示：

testdb=> SELECT first, second, first > 2 AS gt2 FROM my_table;
 first | second | gt2 
-------+--------+-----
     1 | one    | f
     2 | two    | f
     3 | three  | t
     4 | four   | t
(4 rows)

testdb=> \crosstabview first second
 first | one | two | three | four 
-------+-----+-----+-------+------
     1 | f   |     |       | 
     2 |     | f   |       | 
     3 |     |     | t     | 
     4 |     |     |       | t
(4 rows)

第二个示例显示了一个乘法表，其中行以相反的数字 Sequences 排序，而列则具有独立的，升序数字 Sequences。

testdb=> SELECT t1.first as "A", t2.first+100 AS "B", t1.first*(t2.first+100) as "AxB",
testdb(> row_number() over(order by t2.first) AS ord
testdb(> FROM my_table t1 CROSS JOIN my_table t2 ORDER BY 1 DESC
testdb(> \crosstabview "A" "B" "AxB" ord
 A | 101 | 102 | 103 | 104 
---+-----+-----+-----+-----
 4 | 404 | 408 | 412 | 416
 3 | 303 | 306 | 309 | 312
 2 | 202 | 204 | 206 | 208
 1 | 101 | 102 | 103 | 104
(4 rows)
上一章 首页 下一章