psql

psqlPostgreSQL的交互式终端

大纲

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

描述

psql是一个PostgreSQL的基于终端的前端。它让你能交互式地键入查询,把它们发送给PostgreSQL,并且查看查询结果。或者,输入可以来自于一个文件或者命令行参数。此外,psql还提供一些元命令和多种类似 shell 的特性来为编写脚本和自动化多种任务提供便利。

选项

-a
--echo-all

把所有非空输入行按照它们被读入的形式打印到标准输出(不适用于交互式行读取)。这等效于把变量ECHO设置为 all

-A
--no-align

切换到非对齐输出模式(默认输出模式是对齐的)。这等效于\pset format unaligned

-b
--echo-errors

把失败的 SQL 命令打印到标准错误输出。这等效于把变量ECHO设置为errors

-c command
--command=command

指定psql执行一个给定的命令字符串command。这个选项可以重复多次并且以任何顺序与-f选项组合在一起。当-c或者-f被指定时,psql不会从标准输入读取命令,直到它处理完序列中所有的-c-f选项之后终止。

command必须是一个服务器完全可解析的命令字符串(即不包含psql相关的特性)或者单个反斜线命令。因此不能在一个-c选项中混合SQLpsql元命令。要那样做,可以使用多个-c选项或者把字符串用管道输送到psql中,例如:

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

或者

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

\\是分隔符元命令)。

每一个被传递给-cSQL命令字符串会被当做一个单独的请求发送给服务器。因此,即便该字符串包括多个SQL命令,服务器也会把它当做一个事务来执行,除非在该字符串中有显式的BEGIN/COMMIT命令把它划分成多个事务(服务器如何处理多查询字符串的更多细节请参考第 53.2.2.1 节)。此外,psql只会打印出该字符串中最后一个SQL命令的结果。这和从文件中读取同一字符串或者把同一字符串传给psql的标准输出时的行为不同,因为那两种情况下psql会独立地发送每一个SQL命令。

由于这种行为,把多于一个SQL命令放在-c字符串中通常会得到意料之外的结果。最好使用多个-c命令或者把多个命令输送给psql的标准输入,按照上文所说的使用echo或者通过一个 shell,例如:

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

切换到CSV(逗号分隔值)输出模式。 这相当于\pset format csv

-d dbname
--dbname=dbname

指定要连接的数据库的名称。这等效于指定dbname为命令行上的第一个非选项参数。dbname 可以是 连接字符串。 如果是这样,连接字符串参数将覆盖任何冲突的命令行选项。

-e
--echo-queries

也把发送到服务器的所有 SQL 命令复制到标准输出。这等效于把变量ECHO设置为queries

-E
--echo-hidden

回显\d以及其他反斜线命令生成的实际查询。可以用它来学习psql的内部操作。这等效于把变量ECHO_HIDDEN设置为on

-f filename
--file=filename

从文件filename而不是标准输入中读取命令。这个选项可以被重复多次,也可以以任意顺序与-c选项组合。当-c或者-f被指定时,psql不会从标准输入读取命令,直到它处理完序列中所有的-c-f选项之后终止。除此以外,这个选项很大程度上等价于元命令\i

如果filename-(连字符),那么会读取标准输入直到遇见一个 EOF 指示或者\q元命令。这种方式可以用把自多个文件的输入组合成一种交互式输入。不过注意在这种情况下不会使用 Readline(很像指定了-n的情况)。

使用这个选项与psql < filename有细微的不同。通常,两种形式都可以做到我们所期望的,但是使用-f启用了一些好的特性,例如带有行号的错误消息。使用这个选项还有一丝机会可以降低启动开销。在另一方面,使用 shell输入重定向的变体(理论上)保证会得到与手工输入时相同的输出。

-F separator
--field-separator=separator

使用separator作为非对齐输出的域分隔符。这等效于\pset fieldsep或者\f

-h hostname
--host=hostname

指定运行服务器的机器的主机名。如果这个值由一个斜线开始,它会被用作 Unix 域套接字的目录。

-H
--html

切换到HTML输出模式。这等效于\pset format html或者\H命令。

-l
--list

列出所有可用的数据库,然后退出。其他非连接选项会被忽略。这与元命令\list类似。

在使用这个选项时,psql将连接到数据库postgres,除非在命令行上提及一个不同的数据(选项-d或非选项参数,可能是通过一个服务项,但不能通过一个环境变量)。

-L filename
--log-file=filename

除了把所有查询输出写到普通输出目标之外,还写到文件filename中。

-n
--no-readline

不使用Readline做行编辑并且不使用命令历史。在剪切和粘贴时,关掉 Tab 展开会有所帮助。

-o filename
--output=filename

把所有查询输出放到文件filename中。这等效于命令\o

-p port
--port=port

指定服务器用于监听连接的 TCP 端口或者本地 Unix 域套接字文件扩展。默认是PGPORT环境变量的值,如果没有设置,则默认为编译时指定的端口号(通常是5432)。

-P assignment
--pset=assignment

\pset的形式指定打印选项。注意,这里你必须用一个等号而不是空格来分隔名称和值。例如,要设置输出格式为LaTeX,应该写成-P format=latex

-q
--quiet

指定psql应该安静地工作。默认情况下,它会打印出欢迎消息以及多种输出。如果使用了这个选项,以上那些就都不会输出。在使用-c选项时,配合这个选项很有用。这等效于设置变量QUIETon

-R separator
--record-separator=separator

separator用作非对齐输出的记录分隔符。这等效于\pset recordsep命令。

-s
--single-step

运行在单步模式中。这意味着在每个命令被发送给服务器之前都会提示用户一个可以取消执行的选项。使用这个选项可以调试脚本。

-S
--single-line

运行在单行模式中,其中新行会终止一个 SQL 命令,就像分号的作用一样。

注意

这种模式被提供给那些坚持使用它的用户,但是并不一定要使用它。特别地,如果在一行中混合了SQL和元命令,那对于没有经的用户来说,它们的执行顺序可能不总是那么清晰。

-t
--tuples-only

关闭打印列名和结果行计数页脚等。这等效于\t或者\pset tuples_only命令。

-T table_options
--table-attr=table_options

指定要替换HTML table标签的选项。详见\pset tableattr

-U username
--username=username

作为用户username而不是默认用户连接到数据库(当然,你必须具有这样做的权限)。

-v assignment
--set=assignment
--variable=assignment

执行一次变量赋值,和\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命令,这样就把所有的命令都包裹在一个事务中。这个选项可以保证要么所有的命令都成功地完成,要么不应用任何更改。

如果命令本身包含BEGINCOMMIT或者ROLLBACK,这个选项将不会得到想要的效果。还有,如果当个命令不能在一个事务块中执行,指定这个选项将导致整个事务失败。

-?
--help[=topic]

显示有关psql的帮助并且退出。可选的topic参数(默认为options)选择要解释哪一部分的psqlcommands描述psql的反斜线命令;options描述可以被传递给psql的命令行选项;而variables则显示有关psql配置变量的帮助。

退出状态

如果psql正常完成,它会向 shell 返回 0。如果它自身发生一个致命错误(例如内存用完、找不到文件),它会返回 1。如果到服务器的连接出问题并且事务不是交互式的,它会返回 2。如果在脚本中发生错误,它会返回 3 并且变量ON_ERROR_STOP会被设置。

用法

连接到数据库

psql是一个常规PostgreSQL客户端应用。为了连接到数据库,你需要知道你的目标数据库的名称、主机名和该服务器的端口号,还有要作为哪个用户名连接。可以通过命令行选项告知psql这些参数,分别是-d-h-p以及-U。如果发现一个参数不属于任何选项,它将被解释为数据库名称(如果已经给出数据库名称,就解释为用户名)。并非所有这些选项都是必需的,它们都有可用的默认值。如果省略主机名,psql将通过一个 Unix 域套接字连接到本地主机上的服务器,或者通过 TCP/IP 连接到没有 Unix 域套接字的主机上的localhost。默认端口号则在编译时决定。由于数据库服务器使用相同的默认值,大多数情况下你将不必指定端口。默认的用户名是你的操作系统用户名,它也会是默认的数据库名。注意你不一定能连接到任意用户名下的任何数据库。你的数据库管理员应该已经告知过你有关你的访问权限。

当默认值不是很符合实际时,可以把环境变量PGDATABASEPGHOSTPGPORT以及PGUSER设置为适当的值,这样也能节省一些敲打键盘的工作(额外的环境变量可见第 34.15 节)。用一个~/.pgpass文件来避免定期输入密码也很方便。详见第 34.16 节

另一种指定连接参数的方法是用一个conninfo字符串或者一个URI,它可以被用来替代数据库名。这种机制可以让我们对连接具有很广的控制权。例如:

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

用这种方式,你也可以把LDAP用于第 34.18 节中描述的连接参数查找。可用连接选项的更多信息请见第 34.1.2 节

如果由于任何原因(例如权限不足、服务器没有在目标主机上运行等)导致连接无法建立,psql将返回一个错误并且终止。

如果标准输入和标准输出都是一个终端,那么psql会把客户端编码设置成auto,这会使psql从区域设置(Unix 系统上的LC_CTYPE环境变量)中检测合适的客户端编码。如果这样不起作用,可以使用环境变量PGCLIENTENCODING覆盖客户端编码。

输入 SQL 命令

在正常操作时,psql会提供一个提示符,该提示符是psql当前连接到的数据库名称后面跟上字符串=>。例如:

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

testdb=>

在提示符下,用户可以键入SQL命令。正常情况下,当碰到一个表示命令终结的分号时,输入的行会被发送给服务器。一行的结束并不表示命令的完结。因此,为了清晰,可以把命令散布在多个行上。如果命令被发送并且执行而不产生错误,该命令的结果将会显示在屏幕上。

如果不可信用户对还没有采用安全方案使用模式的一个而数据库拥有访问,通过从search_path移除公共可写的方案来开始你的会话。人们可以在连接字符串中加入options=-csearch_path=或者在其他SQL命令之前发出SELECT pg_catalog.set_config('search_path', '', false)。这种考虑并非专门针对psql,它适用于每一种执行任意SQL命令的接口。

只要执行命令,psql还会测试LISTENNOTIFY产生的异步通知。

虽然 C 风格的注释块会被传给服务器处理并且移除,psql会自己移除掉 SQL 标准的注释。

元命令

你输入到psql中的任何以未加引用的反斜线开始的东西都是一个psql元命令,它们由psql自行处理。这些命令让psql对管理和编写脚本更有用。元命令常常被称作斜线或者反斜线命令。

psql命令的格式是用反斜线后面直接跟上一个命令动词,然后是一些参数。参数与命令动词和其他参数之间用任意多个空白字符分隔开。

要在一个参数中包括空白,可以将它加上单引号。要在一个参数中包括一个单引号,则需要在文本中写上两个单引号。任何包含在单引号中的东西都服从与 C 语言中\n(新行)、\t(制表符)、\b(退格)、\r(回车)、\f(换页)、\digits(10 进制)以及\xdigits(16 进制)类似的替换规则。单引号内文本中的其他任何字符(不管它是什么)前面的反斜线都没有实际意义(会被忽略)。

如果在一个参数中出现一个未加引号的冒号(:)后面跟着一个psql变量名,它会被该变量的值替换, 如下面的SQL Interpolation所述。在其中描述的形式:'variable_name':"variable_name"也有同样的效果。:{?variable_name}语法允许测试一个变量是否被定义。它会被TRUE或FALSE替换。用一个反斜线转义该冒号可以防止它被替换。

在一个参数中,封闭在反引号(`)中的文本会被当做一个传递给shell的命令行。该命令的输出(移除任何拖尾的新行)会替换反引号文本。在封闭在反引号的文本中,不会有特别的引号或者其他处理发生,:variable_name的出现除外,其中variable_name是一个会被其值替换的psql变量名。此外,Also, appearances of :'variable_name'的出现会被替换为该变量的值,而值会被适当地加以引用以变成一个单一shell命令参数(后一种形式几乎总是优先,除非你非常确定变量中有什么)。因为回车和换行字符在所有的平台上都不能被安全地引用,:'variable_name'形式会打印一个错误消息并且在这类字符出现在值中时不替换该变量值。

有些命令把SQL标识符(例如一个表名)当作参数。这些参数遵循SQL的语法规则:无引号的字母被强制变为小写,而双引号(")可以保护字母避免大小写转换并且允许在标识符中包含空白。 在双引号内,成对的双引号会被缩减为结果名称中的单个双引号。例如,FOO"BAR"BAZ会被解释成fooBARbaz,而"A weird"" name"会变成A weird" name

对参数的解析会在行尾或者碰到另一个未加引号的反斜线时停止。一个未加引号的反斜线被当做新元命令的开始。特殊的序列\\(两个反斜线)表示参数结束并且应继续解析SQL命令(如果还有)。使用这种方法,SQL命令和psql命令可以被自由地混合在一行中。但是无论在何种情况中,元命令的参数都无法跨越一行。

很多元命令作用在当前查询缓冲区上。这就是一个缓冲区而已,它保存任何已经被键入但是还没有发送到服务器执行的SQL命令文本。这将包括之前输入的行以及在该元命令同一行上出现在前面的任何文本。

可以使用下列元命令:

\a

如果当前的表输出格式是非对齐的,则切换成对齐格式。如果不是非对齐格式,则设置成非对齐格式。保留这个命令是为了向后兼容性。更一般的方案请见\pset

\c or \connect [ -reuse-previous=on|off ] [ dbname [ username ] [ host ] [ port ] | conninfo ]

与一台PostgreSQL服务器建立一个新连接。可以使用位置语法(数据库名称、用户、主机和端口中的一个或多个)指定要使用的连接参数,或者使用第 34.1.1 节中详细介绍的conninfo连接串。如果没有给出参数,则使用与以前相同的参数建立新连接。

dbnameusernamehost或者port中的任何一个指定为-等价于省略该参数。

新连接可以重用之前连接的连接参数;不仅是数据库名称、用户、主机和端口,还有其他设置,例如 sslmode。 默认情况下,参数会在位置语法中重复使用,但在给出 conninfo 字符串时不会。 传递 -reuse-previous=on-reuse-previous=off的第一个参数会覆盖该默认值。 如果重复使用参数,则任何未明确指定为位置参数或在 conninfo 字符串中的参数都将从现有连接的参数中获取。 一个例外是,如果 host 设置使用位置语法从其先前的值更改,则现有连接参数中存在的任何 hostaddr 设置都将被删除。 并且,用作已存在的连接的任何密码,只有在用户、主机、和端口设置没有变化的时候,将被重新使用。 当命令既不指定也不重用特定参数时,将使用 libpq 默认值。

如果新连接成功地被建立,之前的连接会被关闭。 如果连接尝试失败(错误的用户名、访问被拒绝等),在psql处于交互模式的情况下会保留之前的连接。 但是当执行一个非交互式脚本时出现连接尝试失败,老的连接将关闭,并且报出一个错误。 这可能会也可能不会终止脚本;如果没有,所有的数据库访问命令将失败,直到另一个\connect命令被成功执行。 这种区别一方面可以帮助用户发现打字错误,另一方面也可以作为一种安全机制防止脚本在错误的数据库上执行动作。 注意每当\connect命令尝试重用参数,重用的是最后一次成功连接的值,而不是后续任何失败尝试的。 可是,在非交互的\connect失败的情况下,后续没有参数被允许重新使用,因为脚本会可能期望从失败的\connect中的值被重新使用。

例子:

=> \c mydb myuser host.dom 6432
=> \c service=foo
=> \c "host=localhost port=5432 dbname=mydb connect_timeout=10 sslmode=disable"
=> \c -reuse-previous=on sslmode=require    -- changes only sslmode
=> \c postgresql://tom@localhost/mydb?application_name=myapp
\C [ title ]

设置查询结果的任何表的标题,或者重置这类标题。这个命令等效于\pset title title(这个命令的名称来自于caption,因为它之前只被用来在HTML表格中设置标题)。

\cd [ directory ]

把当前工作目录改为directory。如果不带参数,则切换到当前用户的主目录。

提示

要打印当前的工作目录,可以使用\! pwd

\conninfo

输出有关当前数据库连接的信息。

\copy { table [ ( column_list ) ] } from { 'filename' | program 'command' | stdin | pstdin } [ [ with ] ( option [, ...] ) ] [ where condition ]
\copy { table [ ( column_list ) ] | ( query ) } to { 'filename' | program 'command' | stdout | pstdout } [ [ with ] ( option [, ...] ) ]

执行一次前端拷贝。 这个操作会运行一个SQL COPY命令,不过不是服务器读取或者写入指定的文件,而是由psql读写文件并且把数据从本地文件系统导向服务器。 这意味着文件的可访问性和权限是本地用户的而非服务器上的,并且不需要 SQL 超级用户特权。

program被指定时,commandpsql执行并且传给command的数据或者从command传出的数据会在服务器和客户端之间流动。同样地,执行特权是本地用户的而非服务器上的,并且不需要 SQL 超级用户特权。

对于\copy ... from stdin,数据行从发出该命令的同一来源读取,一直到读到\.或者数据流到达EOF。这个选项可以用来填充内嵌在一个 SQL 脚本文件中的表。对于\copy ... to stdout,输出被发送到与psql命令输出相同的位置,并且COPY count命令的状态不会被打印(因为它会被一个数据行搞乱)。要读/写psql的标准输入或者输出而不管当前命令的来源或者\o选项,可以写from pstdin或者to pstdout

这个命令的语法和SQL COPY命令类似。 所有除开数据来源/目的地的选项都和COPY指定的一样。 因此,\copy元命令由特殊的解析规则。 与大部分其他元命令不同,该行的所有剩余部分总是会被当做\copy的参数,并且在参数中不会执行变量篡改以及反引号展开。

提示

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

提示

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

\copyright

显示PostgreSQL的版权以及发布条款。

\crosstabview [ colV [ colH [ colD [ sortcolH ] ] ] ]

执行当前的查询缓冲区(像\g那样)并且在一个交叉表格子中显示结果。该查询必须返回至少三列。由colV标识的输出列会成为垂直页眉并且colH所标识的输出列会成为水平页眉。colD标识显示在格子中的输出列。sortcolH标识用于水平页眉的可选的排序列。

每一个列说明可以是一个列编号(从 1 开始)或者一个列名。常用的 SQL 大小写折叠和引用规则适用于列名。如果省略,colV被当做列 1 并且colH被当做列 2。colH必须和colV不同。如果没有指定colD,那么在查询结果中必须正好有三列,并且colVcolH之外的那一列会被当做colD

垂直页眉显示为最左边的列,它包含列colV中找到的值,值的顺序和查询结果中的顺序相同,但是重复值会被移除。

水平页眉显示为第一行,它包含列colH中找到的值,其中的重复值被移除。默认情况下,这些值会以查询结果中相同的顺序出现。但是如果给出了可选的sortcolH参数,它标识一个值必须为整数编号的列,并且来自colH的值将会根据相应的sortcolH值排序后出现在水平页眉中。

在交叉表格子中,对于colH的每一个可区分的值x以及colV的每一个可区分的值y,位于交叉点(x,y)的单元包含colH值为xcolV值为y的查询结果行中colD列的值。如果没有这样的行,则该单元为空。如果有多个这样的行,则会报告一个错误。

\d[S+] [ pattern ]

对于每一个匹配pattern的关系(表、视图、物化视图、索引、序列或者外部表)或者组合类型,显示所有的列、它们的类型、表空间(如果非默认表空间)以及任何诸如NOT NULL或者默认值的特殊属性。相关的索引、约束、规则以及触发器也会被显示。对于外部表,还会显示相关的外部服务器(下文的Patterns中定义了匹配模式)。

对于某些类型的关系,\d会为每一列显示额外的信息:对于序列会显示列值,对于索引显示被索引的表达式,对于外部表显示外部数据包装器选项。

命令形式\d+是一样的,不过会显示更多信息:与该表的列相关的任何注释,表中是否存在 OID,如果关系是视图则显示视图定义,非默认的replica identity设置以及access method 名称,如果该关系有访问方法。

默认情况下只会显示用户创建的对象,提供一个模式或者S修饰符可以把系统对象包括在内。

注意

如果使用\d但不带有pattern参数,它等价于\dtvmsE,后者将显示所有可见的表、视图、物化视图、序列和外部表的列表。这纯粹是一种便利措施。

\da[S] [ pattern ]

列出聚集函数,以及它们的返回类型和它们所操作的数据类型。如果指定了pattern,只显示名称匹配该模式的聚集。默认情况下只会显示用户创建的对象,提供一个模式或者S修饰符可以把系统对象包括在内。

\dA[+] [ pattern ]

列出访问方法。如果指定了pattern,只显示名称匹配该模式的访问方法。如果在命令名称后面追加+,则与访问方法相关的处理器函数和描述也会和访问方法本身一起被列出。

\dAc[+] [access-method-pattern [input-type-pattern]]

列出运算符类(请参阅 第 38.16.1 节)。 如果指定了 access-method-pattern,则仅列出与名称与该模式匹配的访问方法关联的运算符类。 如果指定了 input-type-pattern,则仅列出与名称与该模式匹配的输入类型关联的运算符类。 如果将 + 附加到命令名称,则会列出每个运算符类别及其关联的运算符系列和所有者。

\dAf[+] [access-method-pattern [input-type-pattern]]

列出运算符系列(请参阅 第 38.16.5 节)。 如果指定了 access-method-pattern,则仅列出与名称与该模式匹配的访问方法关联的运算符系列。 如果指定了 input-type-pattern,则仅列出与名称与该模式匹配的输入类型关联的运算符系列。 如果将 + 附加到命令名称,则会列出每个运算符系列及其所有者。

\dAo[+] [access-method-pattern [operator-family-pattern]]

列出与运算符系列关联的运算符(请参阅 第 38.16.2 节)。 如果指定了 access-method-pattern,则仅列出与名称与该模式匹配的访问方法关联的运算符系列的成员。 如果指定了 operator-family-pattern,则仅列出名称与该模式匹配的运算符系列的成员。 如果将 + 附加到命令名称,则会列出每个运算符及其排序运算符系列(如果它是排序运算符)。

\dAp[+] [access-method-pattern [operator-family-pattern]]

列出与运算符系列相关的支持函数(请参阅 第 38.16.3 节)。 如果指定了 access-method-pattern,则仅列出与名称与该模式匹配的访问方法关联的运算符系列的函数。 如果指定了 operator-family-pattern,则仅列出名称与该模式匹配的运算符系列的函数。 如果将 + 附加到命令名称,则会详细显示函数及其实际参数列表。

\db[+] [ pattern ]

列出表空间。如果指定了pattern,只显示名称匹配该模式的表空间。如果在命令名称后面追加+,则与表空间相关的选项、磁盘上的尺寸、权限以及描述也会和表空间本身一起被列出。

\dc[S+] [ pattern ]

列出字符集编码之间的转换。如果指定了pattern,只列出名称匹配该模式的转换。默认情况下只会显示用户创建的对象,提供一个模式或者S修饰符可以把系统对象包括在内。如果在命令名称后面追加+,则每一个对象相关的描述也会被列出。

\dC[+] [ pattern ]

列出类型转换。如果指定了pattern,只列出源类型和目标类型匹配该模式的转换。如果在命令名称后面追加+,则每一个对象相关的描述也会被列出。

\dd[S] [ pattern ]

显示约束操作符类操作符族规则以及触发器类型对象的描述。所有其他注释可以通过那些对象类型相应的反斜线命令查看。

\dd显示匹配pattern的对象的描述,如果没有给出参数则显示合适类型的可见对象的描述。但是在任一种情况下都只列出具有描述的对象。默认情况下只会显示用户创建的对象,提供一个模式或者S修饰符可以把系统对象包括在内。

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

\dD[S+] [ pattern ]

列出域。如果指定了pattern,只有名称匹配该模式的域会被显示。默认情况下,只有用户创建的对象会被显示,可以提供一个模式或者S修饰符以包括系统对象。如果+被追加到命令名称上,每一个被列出的对象会带有其相关的权限和描述。

\ddp [ pattern ]

列出默认的访问特权设置。对那些默认特权设置已经被改变得与内建默认值不同的角色(以及模式,如果适用),为每一个角色(以及模式)显示一项。如果指定了pattern,只列出角色名称或者模式名称匹配该模式的项。

ALTER DEFAULT PRIVILEGES命令被用来设置默认访问特权。 在第 5.7 节中解释了显示的特权的含义。

\dE[S+] [ pattern ]
\di[S+] [ pattern ]
\dm[S+] [ pattern ]
\ds[S+] [ pattern ]
\dt[S+] [ pattern ]
\dv[S+] [ pattern ]

在这一组命令中,字母Eimstv分别对应着外部表、索引、物化视图、序列、表和视图。你可以以任何顺序指定这些字母中的任意一个或者多个,这样可以得到这些类型的对象的列表。例如,\dti会列出表和索引。如果在命令名称后面追加+,则会列出每个对象及其持久性状态(永久、临时或未记录)、磁盘上的物理大小以及相关的描述(如果有)。如果指定了pattern,只列出名称匹配该模式的对象。默认情况下只会显示用户创建的对象,提供一个模式或者S修饰符可以把系统对象包括在内。

\des[+] [ pattern ]

列出外部服务器(助记:外部服务器)。如果指定了pattern,只列出名称匹配该模式的那些服务器。如果使用了\des+形式,将显示每个服务器的完整描述,包括该服务器的 访问特权、类型、版本、选项和描述。

\det[+] [ pattern ]

列出外部表(助记:外部表)。如果指定了pattern,只列出表名称或者模式名称匹配该模式的项。如果使用了\det+选项,一般选项和外部表描述也会被显示。

\deu[+] [ pattern ]

列出用户映射(助记:外部用户)。如果指定了pattern,只列出用户名匹配该模式的那些映射。如果使用了\deu+形式,有关每个映射的额外信息也会被显示。

小心

\deu+可能也会显示远程用户的用户名和口令,所以要小心不要把它们泄露出去。

\dew[+] [ pattern ]

列出外部数据包装器(助记:外部包装器)。如果指定了pattern,只列出名称匹配该模式的那些外部数据包装器。如果使用了\dew+形式,外部数据包装器的访问特权、选项和描述也会被显示。

\df[anptwS+] [ pattern [ arg_pattern ... ] ]

列出函数,以及它们的结果数据类型、参数数据类型和函数类型,函数类型被分为agg(聚集)、normalproceduretrigger以及window。 如果要只显示指定类型的函数,可以在该命令上增加相应的字母anpt或者w。如果指定了pattern,只显示名称匹配该模式的函数。 任何附加参数都是类型名称模式,它们与函数的第一个、第二个、以及等等参数的类型名相匹配。 (匹配函数可以有比指定的更多的参数。为了防止这种情况,写入破折号-作为最后一个arg_pattern。) 默认情况下只会显示用户创建的对象,提供一个模式或者S修饰符可以把系统对象包括在内。 如果使用了\df+形式,则有关每个函数的额外信息也会被显示,包括易失性、并行安全性、拥有者、安全性分类、访问特权、语言、源代码和描述。

\dF[+] [ pattern ]

列出文本搜索配置。如果指定了pattern,只显示名称匹配该模式的配置。如果使用了\dF+形式,每种配置的完整描述也会被显示,包括底层的文本搜索解析器和用于每一种解析器记号类型的字典列表。

\dFd[+] [ pattern ]

列出文本搜索字典。如果指定了pattern,只显示名称匹配该模式的字典。如果使用了\dFd+形式,有关每一种选中的字典的额外信息也会被显示,包括底层的文本搜索模板和选项值。

\dFp[+] [ pattern ]

列出文本搜索解析器。如果指定了pattern,只显示名称匹配该模式的解析器。如果使用了\dFp+形式,每一种解析器的完整描述也会被显示,包括底层的函数和可识别的记号类型列表。

\dFt[+] [ pattern ]

列出文本搜索模板。如果指定了pattern,只显示名称匹配该模式的模板。如果使用了\dFt+形式,每一种模板有关的额外信息也会被显示,包括底层的函数名称。

\dg[S+] [ pattern ]

列出数据库角色(因为用户的概念已经被统一成角色,这个命令现在等价于\du)。默认情况下只会显示用户创建的角色,提供一个模式或者S修饰符可以把系统角色包括在内。如果指定了pattern,只列出名称匹配该模式的那些角色。如果使用了\dg+形式,有关每种角色的额外信息也将被显示,当前这种形式会为角色增加显示注释。

\dl

这是\lo_list的一个别名,它显示大对象的列表。

\dL[S+] [ pattern ]

列出过程语言。如果指定了pattern,只列出名称匹配该模式的语言。默认情况下只会显示用户创建的语言,提供一个模式或者S修饰符可以把系统对象包括在内。如果向命令名称追加+,则每一种语言会和它的调用处理器、验证器、访问特权以及它是否为系统对象一起列出。

\dn[S+] [ pattern ]

列出模式(名字空间)。如果指定了pattern,只列出名称匹配该模式的模式。默认情况下只会显示用户创建的对象,提供一个模式或者S修饰符可以把系统对象包括在内。如果向命令名称追加+,每个对象会与它相关的权限及描述(如果有)一起被列出。

\do[S+] [ pattern [ arg_pattern [ arg_pattern ] ] ]

列出操作符及其操作数和结果类型。 如果指定了pattern,只列出名称匹配该模式的操作符。 如果指定了一个arg_pattern,则只列出右侧参数的类型名称与所列出的模式相匹配的前缀操作符。 如果指定了两个arg_pattern,则只列出参数类型名称与所列出的模式相匹配的二进制操作符。 (或者,为一元运算符的未使用参数写入-。) 默认情况下只会显示用户创建的对象,提供一个模式或者S修饰符可以把系统对象包括在内。 如果向命令名称追加+,有关每个操作符的额外信息也将被显示,当前只包括底层函数的名称。

\dO[S+] [ pattern ]

列出排序规则。如果指定了pattern,只列出名称匹配该模式的排序规则。默认情况下只会显示用户创建的对象,提供一个模式或者S修饰符可以把系统对象包括在内。如果向命令名称追加+,每个排序规则将和它相关的描述(如果有)一起被列出。注意只有可用于当前数据库编码的排序规则会被显示,因此在同一个安装下的不同数据库中执行此命令可能会得到不同的结果。

\dp [ pattern ]

列出表、视图和序列,包括与它们相关的访问特权。如果指定了pattern,只列出名称匹配该模式的表、视图以及序列。

GRANTREVOKE命令被用来设置访问特权。 所显示的特权的含义在第 5.7 节中有介绍。

\dP[itn+] [ pattern ]

列出分区关系。如果指定了pattern,则仅列出名称与模式匹配的条目。 修改符t(表)和i(索引)可以追加到命令中,筛选要列出的关系类型。默认会列出分区表和索引。

如果用了修饰符nnested)或指定了模式,则包括非根分区关系,并显示每个分区关系的父级的列。

如果+被附加到命令名中,那么还会显示每个关系分区的大小总和,以及关系的描述。 如果n_相结合,将显示两种大小:一种包含直接连接的叶分区的总大小,另一种显示所有分区的总大小,包括间接附加的子分区。

\drds [ role-pattern [ database-pattern ] ]

列出已定义的配置设置。这些设置可以是针对角色的、针对数据库的或者同时针对两者的。role-patterndatabase-pattern分别被用来选择要列出的角色和数据库。如果省略它们或者指定了*,则会列出所有设置,分别会包括针对角色和针对数据库的设置。

ALTER ROLE以及ALTER DATABASE命令可以用来定义一个角色以及一个数据库的配置设置。

\dRp[+] [ pattern ]

列出复制的publication。如果指定有pattern,只有那些名称匹配该模式的publication会被列出。如果+被追加到命令的名称上,与每个publication相关的表也会被显示。

\dRs[+] [ pattern ]

列出复制的订阅。如果指定有pattern,只有那些名字匹配该模式的订阅才会被列出。如果+被追加到命令的名称上,订阅的额外属性会被显示。

\dT[S+] [ pattern ]

列出数据类型。如果指定了pattern,只列出名称匹配该模式的类型。如果向命令名称追加+,每一种类型、其内部名称和尺寸、允许的值(如果是一种enum类型)以及相关权限会被一同列出。默认情况下只会显示用户创建的对象,提供一个模式或者S修饰符可以把系统对象包括在内。

\du[S+] [ pattern ]

列出数据库角色(因为用户的概念已经被统一成角色,这个命令现在等价于\dg)。默认情况下只会显示用户创建的角色,提供一个模式或者S修饰符可以把系统角色包括在内。如果指定了pattern,只列出名称匹配该模式的那些角色。如果使用了\du+形式,有关每一种角色的额外信息也会被显示,当前只会多显示角色的注释。

\dx[+] [ pattern ]

列出已安装的扩展。如果指定了pattern,只列出名称匹配该模式的那些扩展。如果使用了\dx+形式,所有属于每个匹配扩展的对象会被列出。

\dX [ pattern ]

列出扩展统计信息。 如果指定了pattern,只有那些名称与模式匹配的扩展统计信息会被列出。

每种扩展统计信息的状态,是显示在它的统计信息类型(例如,Ndistinct)后面的命名的列中。 defined表示它在创建统计时被请求,NULL表示它没有被请求。 如果你想知道ANALYZE 是否运行,并且统计信息对规划器是可用的,可以使用pg_stats_ext

\dy[+] [ pattern ]

列出事件触发器。如果指定了pattern,只列出名称匹配该模式的事件触发器。如果在命令名称后面加上+,还会为每个列出的对象显示其相关的描述。

\e\edit [ filename ] [ line_number ]

如果指定了filename,则它是被编辑的文件,在编辑器退出后,该文件的内容会被拷贝到当前查询缓冲区中。 如果没有给定filename,当前查询缓冲区会被拷贝到一个临时文件中,并且接着以相同的方式编辑。 或者,如果当前查询缓冲区为空,则最近被执行的查询会被拷贝到一个临时文件并且以同样的方式编辑。

如果你编辑了一个文件或者以前的查询,并且你退出编辑时没有变更文件,查询缓冲将被清除。 否则,会根据psql的一般规则重新解析查询缓冲区的新内容,把整个缓冲区当作一个单一行来处理。 任何完整的查询都会立即执行; 也就是说,如果查询缓冲区包含分号或以分号结尾,则执行该点之前的所有内容并将其从查询缓冲区中删除。 查询缓冲区中剩余的内容将重新显示。 输入分号或者\g会把它发送出去,输入\r会通过清除查询缓冲区来取消它。

把缓冲区当作单一行主要会影响元命令:缓冲区中在一个元命令之后的任何东西都将被当作该元命令的参数,即便元命令之后的内容跨越多行也是如此。(因此不能以这种方式来制作使用元命令的脚本。应该使用\i。)

如果指定了一个行号,psql将会把游标(注意不是服务器端的游标)定位到文件或者查询缓冲区的指定行上。注意如果给出了一个全是数字的参数,psql就会假定它是行号而不是文件名。

提示

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

\echo text [ ... ]

将经过计算的参数打印到标准输出,以空格分隔,后跟换行符。这可以用来在脚本的输出中间混入信息,例如:

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

如果第一个参数是一个没有加引号的-n,则不会加上最后的新行(第一个参数也不会)。

提示

如果使用\o命令来重定向查询的输出,你可能希望使用\qecho来取代这个命令。另请参见\warn

\ef [ function_description [ line_number ] ]

这个命令会以一个CREATE OR REPLACE FUNCTIONCREATE OR REPLACE PROCEDURE命令的形式取出并且编辑指定函数或过程的定义。 编辑的方式与\edit完全相同。 如果你退出编辑器而没有保存,语句会被丢弃。 如果你保存并退出编辑器,如果你给它增加了分号,更新的命令会被立即执行 否则重新显示;可以键入分号或者\g把它发出,也可以用\r取消之。

目标函数可以单独用名称或者用名称和参数(例如foo(integer, text))来指定。如果有多于一个函数具有同样的名称,则必须给出参数的类型。

如果没有指定函数,将会给出一个空白的CREATE FUNCTION模板来编辑。

如果指定了一个行号,psql将把游标定位在该函数体的指定行上(注意函数体通常不是开始于文件的第一行)。

和大部分其他元命令不同,该行的整个剩余部分总是会被当作\ef的参数,并且在参数中不会执行变量篡改以及反引号展开。

提示

有关如何配置和自定义编辑器可见下面的Environment

\encoding [ encoding ]

设置客户端字符集编码。如果没有参数,这个命令会显示当前的编码。

\errverbose

以最详细的程度重复最近的服务器错误消息,就好像VERBOSITY被设置为verboseSHOW_CONTEXT被设置为always

\ev [ view_name [ line_number ] ]

这个命令会以一个CREATE OR REPLACE VIEW的形式取出并且编辑指定函数的定义。编辑的方式与\edit完全相同。 如果你退出编辑器而没有保存,语句会被丢弃。 如果你保存并退出编辑器,如果你给它增加了分号,更新的命令会被立即执行 否则重新显示;可以键入分号或者\g把它发出,也可以用\r取消之。

如果没有指定函数,将会给出一个空白的CREATE VIEW模板来编辑。

如果指定了一个行号,psql将把游标定位在该视图定义的指定行上。

和大部分其他元命令不同,该行的整个剩余部分总是会被当作\ev的参数,并且在参数中不会执行变量篡改以及反引号展开。

\f [ string ]

设置用于非对齐查询输出的域分隔符。默认值是竖线(|)。它等效于\pset fieldsep

\g [ (option=value [...]) ] [ filename ]
\g [ (option=value [...]) ] [ |command ]

把当前查询缓冲区发送给服务器执行。

如果括号出现在 \g 之后,它们将包围以空格分隔的 option=value 格式选项子句列表,其解释方式与 \psetoptionvalue 命令相同,但仅在此查询期间生效。 在此列表中,= 符号周围不允许有空格,但选项子句之间需要空格。 如果省略 =value,命名的 option 的更改方式与 \pset option 相同,没有明确的 value

如果给定了 filename|command 参数,则查询的输出将写入命名文件或通过管道传输到给定的 shell 命令,而不是像往常一样显示它。 仅当查询成功返回零个或多个元组时才会写入文件或命令,而不是在查询失败或者是不返回数据的 SQL 命令时写入。

如果当前查询缓冲区为空,则重新执行最近一次被发送的查询。除了这种行为之外,没有参数的\g实际上等效于一个分号。对于参数,\g提供了一个替代\o命令的一次性,另外还允许对通常由\pset设置的输出格式选项进行一次性调整。

当最后一个参数以|开始时,则该行的所有剩余部分总是会被当做要执行的command,并且在参数中不会执行变量篡改以及反引号展开。该行的剩余部分会被简单地按字面传给shell。

\gdesc

显示当前查询缓冲区的结果的描述(即列名和数据类型)。查询不会被实际执行,不过,如果它含有某种类型的语法错误,该错误将被以通常的方式报出。

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

\gexec

把当前查询缓冲区发送到服务器,然后该查询输出(如果有)中的每一行的每一列都当作一个要被执行的 SQL 语句。例如,要在my_table的每一列上都创建一个索引:

=> 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

产生的查询会按照其所在行被返回的顺序执行,如果有多个列,则同一行中按照从左至右的顺序执行。NULL 域会被忽略。产生的查询会被原样发送给服务器处理,因此它们即不能是psql元命令,也不能包含psql变量引用。如果其中任何一个查询失败,剩余查询的执行将会继续,除非设置了ON_ERROR_STOP。每个查询的执行都遵照ECHO的处理(在使用\gexec时,通常建议设置ECHOall或者queries)。查询日志、单步模式、计时以及其他查询执行特性也适用于每一个生成的查询。

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

\gset [ prefix ]

把当前查询输入缓冲区发送给服务器并且将查询的输出存储在psql变量中(参见下面的Variables)。被执行的查询必须只返回一行。该行的每一列会被存储到一个单独的变量中,变量和该列的名字一样。例如:

=> 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,那么对应的变量会被重置而不是被设置。

如果查询失败或者没有返回一行,则不会有任何变量被更改。

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

\gx [ (option=value [...]) ] [ filename ]
\gx [ (option=value [...]) ] [ |command ]

\gx等效于\g\gx 等价于 \g,除了它强制此查询的扩展输出模式,就好像 expanded=on 被包含在列表中 \pset 选项。请参考\x

\h or \help [ command ]

给出指定SQL命令的语法帮助。如果没有指定command,则psql会列出可以显示语法帮助的所有命令。如果command是一个星号(*),则会显示所有SQL命令的语法帮助。

与大部分其他元命令不同,该行的所有剩余部分总是会被当做\help的参数,并且在参数中不会执行变量篡改以及反引号展开。

注意

为了简化输入,由几个词构成的命令不需要被加上引号。因此,键入\help alter table是可以的。

\H or \html

开启HTML查询输出格式。如果HTML格式已经开启,这会把它切换回默认的对齐文本格式。这个命令是为了兼容性和方便,有关设置其他输出选项请见\pset

\i or \include filename

从文件filename读取输入并且把它当作从键盘输入的命令来执行。

如果filename-(连字符),那么会一直读取标准输入直到碰到一个 EOF 指示符或者\q元命令。这可以用来把交互式输入与文件输入混杂。注意只有在最外层激活了 readline 行为的情况下才将会使用 readline 行为。

注意

如果想在屏幕上看到被读入的行,必须把变量ECHO设置成all

\if expression
\elif expression
\else
\endif

这一组命令实现可嵌套的条件块。条件块必须以一个\if开始并且以一个\endif结束。两者之间可能有任意数量的\elif子句,后面也可能有选择地跟着一个单一的\else子句。一般查询以及其他类型的反斜线命令可以出现在这些命令之间构成条件块。

\if\elif命令读取它们的参数并且将它们作为布尔表达式进行计算。如果表达式得到则处理正常继续下去,否则会跳过下面的行直到到达一个匹配的\elif\else或者\endif。一旦一个\if或者\elif测试成功,同一个块中后面的\elif命令的参数将不会被计算但会被当作为假。跟在一个\else后面的行只有在先前的匹配的\if\elif成功时才被处理。

就像任何其他反斜线命令参数一样,\if或者\elif命令的expression参数服从变量篡改以及反引号展开。然后会像一个on/off选项变量的值一样来计算它。因此,对下列项无歧义、大小写无关的匹配都是有效的值:truefalse10onoffyesno。例如,tT以及tR都将被认为是

无法被正确计算为真或假的表达式将产生一个警告并且被当做假。

正在被跳过的行还是会被正常地解析以标识查询和反斜线命令,但是查询不会被发送到服务器,并且非条件(\if\elif\else\endif)反斜线命令会被忽略。条件命令会被检查以判断嵌套是否有效。被跳过的行中的变量引用不会被展开,并且也不会执行反引号展开。

一个给定条件块中的所有反斜线命令必须出现在相同的源文件中。如果在所有的本地\if块被关闭之前,主输入文件或者一个\include进来的文件上就达到了EOF,则psql将产生一个错误。

这里是一个例子:

-- 检查数据库中两个单独记录的存在性并且把结果存在单独的psql变量中
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
\ir or \include_relative filename

\ir命令类似于\i,但是以不同的方式处理相对路径文件名。在交互模式中执行时,这两个命令的行为相同。不过,当被从脚本中调用时,\ir相对于脚本所在的目录而不是根据当前工作目录来解释文件名。

\l[+] or \list[+] [ pattern ]

列出服务器中的数据库并且显示它们的名称、拥有者、字符集编码以及访问特权。如果指定了pattern,则只列出名称匹配该模式的数据库。如果向命令名称追加+,则还会显示数据库的尺寸、默认表空间以及描述(尺寸信息只对当前用户能连接的数据库可用)。

\lo_export loid filename

从数据库中读取具有OID loid的大对象并且将它写入到filename。注意这和服务器函数lo_export有微妙的不同,后者会以运行数据库服务器的用户权限来执行并且运行在服务器的文件系统上。

提示

使用\lo_list可以找出大对象的OID

\lo_import filename [ comment ]

把该文件存储到PostgreSQL大对象。可选地,它可以把给定的注释关联到该对象。例如:

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

该响应表示该大对象得到的对象 ID 是 152801,未来可以用这个 ID 来访问这个新创建的大对象。为了便于阅读,推荐总是给每一个对象都关联人类可读的注释。OID 和注释都可以用\lo_list命令查看。

注意这个命令和服务器端的lo_import有微妙的不同,因为它以本地文件系统上的本地用户的身份运行,而不是服务器用户和文件系统。

\lo_list

显示当前存储在数据库中的所有PostgreSQL大对象,同时显示它们的任何注释。

\lo_unlink loid

从数据库中删除OIDloid的大对象。

提示

使用\lo_list可以找出该大对象的OID

\o or \out [ filename ]
\o or \out [ |command ]

安排把未来的查询结果保存到文件filename中或者用管道导向到 shell 命令command。如果没有指定参数,查询输出会被重置到标准输出。

如果该参数以|开始,则该行的所有剩余部分总是会被当做要执行的command,并且在参数中不会执行变量篡改以及反引号展开。该行的剩余部分会被简单地按字面传给shell。

查询结果包括从数据库服务器得到的所有表、命令响应和提示,还有查询数据库的各种反斜线命令(如\d)的输出,但不包括错误消息。

提示

要在查询结果之间混入文本输出,可以使用\qecho

\p or \print

把当前查询缓冲区打印到标准输出。如果当前查询缓冲区为空,会打印最近被执行的查询。

\password [ username ]

更改指定用户(默认情况下是当前用户)的口令。这个命令会提示要求输入新口令、对口令加密然后把加密后的口令作为一个ALTER ROLE命令发送到服务器。这确保新口令不会以明文的形式出现在命令历史、服务器日志或者其他地方。

\prompt [ text ] name

提示用户提供一个文本用于分配给变量name。可以指定一个可选的提示字符串text(对于多个词组成的提示,把文本包裹在单引号中)。

默认情况下,\prompt使用终端进行输入和输出。不过,如果使用了-f命令行开关,\prompt会使用标准输入和标准输出。

\pset [ option [ value ] ]

这个命令设置影响查询结果表输出的选项。option表示要设置哪个选项。value的语义取决于选中的选项。对于某些选项,如果省略value会导致该选项值被切换或者被重置,具体是哪些选项可见特定选项的描述。如果没有上面提到的那种行为,那么省略value只会导致当前设置被显示。

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

可调整的打印选项有:

border

value必须是一个数字。通常,数字越大,表格就会有更多的边框和线条,但具体要看是哪一种格式。在HTML格式中,这会直接被转换成border=...属性。在大部分其他格式中,只有值 0(没有边框)、1(内部分隔线)和 2(表格边框)有意义,并且 2 以上的值会被视为与border = 2相同。latexlatex-longtable格式会额外地允许一个值 3 表示在数据行之间增加分隔线。

columns

wrapped格式设置目标宽度,还有扩展自动模式中决定输出是否足够多到需要分页器或者切换到垂直显示的宽度限制。零(默认)导致目标宽度由环境变量COLUMNS所控制,如果没有设置COLUMNS则使用检测到的屏幕宽度。此外,如果columns为零则wrapped格式只影响屏幕输出。如果columns为非零则文件和管道输出也会被包裹成该宽度。

csv_fieldsep

规定要用于CSV输出格式的字段分隔符。如果分隔符出现在字段的值中,则该字段遵循标准CSV规则在双引号中输出。默认值为逗号。

expanded (or x)

如果value被指定,它必须是on或者off,它们分别会启用或者禁用扩展模式,也可以是auto。如果value被省略,则该命令会在开启和关闭设置之间切换。当扩展模式被启用时,查询结果被显示在两列中,第一列是列名而第二列是列值。如果在通常的水平模式中数据不适合屏幕,则可以用这种模式。在自动设置中,只要查询输出有多于一列并且比屏幕宽,就会使用扩展模式。否则,将使用常规模式。只有在对齐格式和 wrapped 格式中自动设置才有效。在其他格式中,它的行为总是像扩展模式被关闭一样。

fieldsep

指定在非对齐输出格式中使用的域分隔符。用那种方式,用户可以创建 tab 分隔的输出,这种形式其他程序可能更喜欢。要设置 tab 为域分隔符,可以键入\pset fieldsep '\t'。默认的域分隔符是'|'(一个竖线)。

fieldsep_zero

把用在非对齐输出格式中的域分隔符设置为一个零字节。

footer

如果value被指定,它必须是on或者off,它们分别会启用或者禁用表格页脚((n rows)计数)的显示。如果value被省略,则该命令会切换页脚显示为打开或者关闭。

format

设置输出格式为下列的一种: aligned, asciidoc, csv, html, latex, latex-longtable, troff-ms, unaligned, 或 wrapped。允许唯一的缩写。

aligned 格式是标准,人类可阅读的、良好格式化的文本输出;这是默认值。

unaligned格式把一个数据行的所有列都写在一行上,之间用当前活动的域分隔符分隔。这可用于生成意图由其他程序读取的输出,例如,tab 分隔或者逗号分隔格式。 但是,如果字段分隔符出现在列的值中,则不专门处理该字符;因此CSV格式可能更适合此类目的。

csv 格式 写入以逗号分隔的列值,应用引号规则描述在RFC 4180。 此输出与服务器COPY命令的 CSV 格式兼容。 除非tuples_only参数为on,否则将生成具有列名称的标头行。不打印标题和页脚。 每行都由系统相关的行尾字符结束,该字符通常是类似 Unix 的系统的单一换行符(\n)或应用于微软Windows的回车和换行顺序(\r\n)。 除了逗号之外的\pset csv_fieldsep字段分隔符,还可以使用\pset csv_fieldsep选择。

wrapped格式和aligned相似,但是前者会把过宽的数据值分成多个行以便输出能够适合目标行的宽度。目标行的宽度由columns选项决定。注意psql将不会尝试对列头部标题进行换行,因此如果列头部需要的总宽度超过目标宽度,wrapped格式的行为就变得和aligned一样了。

The asciidoc, html,latex, latex-longtable, 和troff-ms 格式分别用相应的标记语言把要输出的表格放在文档中。不过它们的输出并不是完整的文档。 这在HTML中也许不重要,但是在LaTeX中必须有完整的文档包装器。 latex 格式使用 LaTeXtabular环境。 latex-longtable 格式需要 LaTeXlongtablebooktabs 包。

linestyle

设置边框线的绘制样式为asciiold-ascii或者unicode之一。允许不产生歧义的缩写(这意味着一个字母就足够了)。默认的设置是ascii。这个选项只影响aligned以及wrapped输出格式。

ascii样式使用纯ASCII字符。数据中的新行使用一个+符号在右手边的空白处显示。当在wrapped格式中包裹两行中间没有新行字符的数据时,会在第一行右手边空白处显示一个点号(.),并且在下一行的左手边空白处也显示一个点号(.)。

old-ascii样式使用纯ASCII字符,使用PostgreSQL 8.4 及更早版本中用过的格式化样式。数据中的新行使用:符号来代替左手边的列分隔符显示。在包裹两行中间没有新行字符的数据时,会用一个;符号取代左手边的列分隔符。

unicode样式使用 Unicode 的方框绘制字符。数据中的新行会使用一个回车符号显示在右手边的空白处。在包裹两行中间没有新行字符的数据时,会在第一行的右手边空白处显示一个省略号,并且在下一行的左手边空白处也显示一个省略号。

border设置大于零时,linestyle选项也决定边框线用什么字符绘制。纯ASCII字符到处都可以使用,但是在识别 Unicode 字符的显示上使用 Unicode 字符会更好看。

null

设置要用来替代空值被打印的字符串。默认是什么也不打印,对于一个空字符串这很容易弄错。例如,有人可能更想用\pset null '(null)'

numericlocale

如果value被指定,它必须是on或者off,它们将分别启用或者禁用一个与区域相关的字符来分隔数字和左边的十进制标记。如果value被省略,该命令会在常规输出和区域相关的数字输出之间切换。

pager

控制对查询和psql的帮助输出使用分页器程序。如果环境变量PSQL_PAGERPAGER被设置,输出会被用管道输送到指定的程序。否则将使用与平台相关的默认分页器程序(例如more)。

如果pager选项被设为off,则不会使用分页器程序。如果pager选项被设为on,则会在适当的时候使用分页器,即当输出到终端并且无法适合屏幕时就会使用分页器。pager选项也可以被设置为always,这会导致对所有的终端输出都是用分页器而不管输出是否适合屏幕。不带value\pset pager会切换分页器开、关状态。

pager_min_lines

如果pager_min_lines被设置为一个大于页面高度的数字,在至少这么多输出行被显示之前都不会调用分页器程序。默认设置为 0。

recordsep

指定用在非对齐输出格式中的记录(行)分隔符。

recordsep_zero

把用在非对齐输出格式中的记录分隔符设置为一个零字节。

tableattr (or T)

HTML格式中,这会指定要放在table标记内的属性。例如,这可能是cellpadding或者bgcolor。注意你可能不想在这里指定border,因为那由\pset border负责。如果没有给出value,则表属性会被重置。

latex-longtable格式中,这个选项控制每个包含左对齐数据类型的列的宽度比例。这个选项的值是一个由空格分隔的值列表,例如'0.2 0.2 0.6'。没有指定的输出列会使用最后一个指定的值。

title (or C)

设置用于任何后续被打印表的表标题。这可以用来给输出加上描述性的标签。如果没有给出value,这个标题会被复原。

tuples_only (or t)

如果value被指定,它必须是on或者off,这个选项将启用或者禁用只显示元组的模式。如果value被省略,则该命令会在常规输出和只显示元组输出之间切换。常规输出包括列头、标题以及多种页脚之类的额外信息。在只显示元组的模式中,只会显示实际的表数据。

unicode_border_linestyle

设置unicode线型的边框绘制风格为single或者double之一。

unicode_column_linestyle

设置unicode线型的列绘制风格为single或者double之一。

unicode_header_linestyle

设置unicode线型的页眉绘制风格为single或者double之一。

这些不同格式的外观可以在Examples小节的图示中看到。

提示

\pset有多种快捷命令。请参见\a\C\f\H\t\T以及\x

\q or \quit

退出psql程序。在一个脚本文件中,只有该脚本的执行会被终止。

\qecho text [ ... ]

这个命令和\echo一样,不过输出将被写到\o所设置的查询输出通道。

\r or \reset

重置(清除)查询缓冲区。

\s [ filename ]

打印psql的命令行历史到filename。如果省略filename,该历史会被写入到标准输出(如果适用则使用分页器)。如果编译psql时没有加上Readline支持,则这个命令不可用。

\set [ name [ value [ ... ] ] ]

设置psql变量namevalue,如果给出了多于一个值,则把该变量的值设置为所有给出的值的串接。如果只给了一个参数,该变量会被设置为空字符串值。要重置一个变量,可以使用\unset 命令。

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

合法的变量名可以包含字母、数字和下划线。详见下文的Variables。变量名是大小写敏感的。

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

注意

这个命令和SQL命令SET无关。

\setenv name [ value ]

把环境变量name设置为value,如果没有提供value,则会重置该环境变量。例如:

testdb=> \setenv PAGER less
testdb=> \setenv LESS -imx4F
\sf[+] function_description

这个命令以一个CREATE OR REPLACE FUNCTION命令或者CREATE OR REPLACE PROCEDURE命令取出并且显示指定函数或者过程的定义。定义会被打印到当前的查询输出渠道,就像\o所作的那样。

目标函数可以单独用名称指定,也可以用名称和参数指定,例如foo(integer, text)。如果有多于一个函数具有相同的名字,则必须给出参数的类型。

如果向命令名称追加+,那么输出行会被编号,函数体的第一行会被编为 1。

与大部分其他元命令不同,该行的所有剩余部分总是会被当做\sf的参数,并且在参数中不会执行变量篡改以及反引号展开。

\sv[+] view_name

这个命令以一个CREATE OR REPLACE VIEW命令取出并且显示指定视图的定义。定义会被打印到当前的查询输出渠道,就像\o所作的那样。

如果在命令名称上追加+,那么输出行会从 1 开始编号。

与大部分其他元命令不同,该行的所有剩余部分总是会被当做\sv的参数,并且在参数中不会执行变量篡改以及反引号展开。

\t

切换输出列名标题和行计数页脚的显示。这个命令等效于\pset tuples_only,提供它只是为了使用方便而已。

\T table_options

指定在HTML输出格式中,要放在table标签内的属性。这个命令等效于\pset tableattr table_options

\timing [ on | off ]

如果给出一个参数,这个参数用来打开或者关闭对每个SQL语句执行时长的显示。如果没有参数,则在打开和关闭之间切换。显示的数据以毫秒为单位,超过1秒的区间还会被显示为“分钟:秒”的格式,如果必要还会加上小时和日的字段。

\unset name

重置(删除)psql变量name

大部分控制psql行为的变量不能被重置,相反,\unset命令会被解释为把它们设置为其默认值。请参考下文的Variables

\w or \write filename
\w or \write |command

把当前查询缓冲区写到文件filename或者用管道导出到 shell 命令command。如果当前查询缓冲区为空,则写最近被执行的查询。

如果参数以|开始,则该行的整个剩余部分会被当做要执行的command,并且在参数中不会执行变量篡改以及反引号展开。该行的剩余部分会被简单地按字面传递给shell。

\warn text [ ... ]

此命令与 \echo 相同,只是输出将写入 psql 的标准错误通道,而不是标准输出。

\watch [ seconds ]

反复执行当前的查询缓冲区(就像\g那样)直到被中止或者查询失败。两次执行之间等待指定的秒数(默认是 2 秒)。显示每个查询结果时带上一个由\pset title字符串(如果有)、从查询开始起的时间以及延时间隔组成的页眉。

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

\x [ on | off | auto ]

设置或者切换扩展表格格式化模式。究其本身而言,这个命令等效于\pset expanded

\z [ pattern ]

列出表、视图和序列,以及它们相关的访问特权。如果指定了pattern,则只会列出名称匹配该模式的表、视图和序列。

这是\dpdisplay privileges)的一个别名。

\! [ command ]

如果没有参数,就跳出到一个子shell,当子shell退出时psql会继续。如果有一个参数,则执行shell命令command

与大部分其他元命令不同,该行的所有剩余部分总是会被当做\!的参数,并且在参数中不会执行变量篡改以及反引号展开。该行的剩余部分会被简单地按字面传递给shell。

\? [ topic ]

显示帮助信息。可选的topic参数(默认是commands)选择解释psql的哪一部分:commands表示psql的反斜线命令;options表示可以传递给psql的命令行选项;而variables显示有关psql配置变量的帮助。

\;

反斜线分号并非和前述命令相同的元命令,它只是会把一个分号加入到查询缓冲区且不会进一步执行。

通常,只要psql达到了命令结束的分号,它就将分发一个SQL命令给服务器,即使在当前行上还留有更多输入。因此,例如输入

select 1; select 2; select 3;

将导致三个SQL命令被逐个发送给服务器,在继续到下一个命令前会显示每一个命令的结果。不过,被输入为\;的分号将不会触发命令处理,这样在它之前的命令以及其后的命令实际上会被组合在一个请求中发送给服务器。例如

select 1\; select 2\; select 3;

会导致在到达非反斜线分号时用一个单一的请求把三个SQL命令发送给服务器。服务器会把这样一个请求当作单一的事务执行,除非该字符串中有显式的BEGIN/COMMIT命令把它划分成多个事务(服务器如何处理多查询字符串的更多细节请参考第 53.2.2.1 节)。psql对每个请求仅打印出它接收到的最后一个查询结果。在这个例子中,尽管所有三个SELECT确实都被执行了,但psql只会打印出3

模式

很多\d命令都可以用一个pattern参数来指定要被显示的对象名称。在最简单的情况下,模式正好就是该对象的准确名称。在模式中的字符通常会被变成小写形式(就像在 SQL 名称中那样),例如\dt FOO将会显示名为foo的表。就像在 SQL 名称中那样,把模式放在双引号中可以阻止它被转换成小写形式。如果需要在一个模式中包括一个真正的双引号字符,则需要把它写成两个相邻的双引号,这同样是符合 SQL 引用标识符的规则。例如,\dt "FOO""BAR"将显示名为FOO"BAR(不是foo"bar)的表。和普通的 SQL 名称规则不同,你不能只在模式的一部分周围放上双引号,例如\dt FOO"FOO"BAR将会显示名为fooFOObar的表。

只要pattern参数被完全省略,\d命令会显示在当前 schema 搜索路径中可见的全部对象 — 这等价于用*作为模式(如果一个对象所在的 schema 位于搜索路径中并且没有同类且同名的对象出现在搜索路径中该 schema 之前的 schema 中,则说该对象是可见的。这表示可以直接用名称引用该对象,而不需要用 schema 来进行限定)。要查看数据库中所有的对象而不管它们的可见性,可以把*.*用作模式。

如果放在一个模式中,*将匹配任意字符序列(包括空序列),而?会匹配任意的单个字符(这种记号方法就像 Unix shell 的文件名模式一样)。例如,\dt int*会显示名称以int开始的表。但是如果被放在双引号内,*?就会失去这些特殊含义而变成普通的字符。

包含一个点号(.)的模式被解释为一个 schema 名称模式后面跟上一个对象名称模式。例如,\dt foo*.*bar*会显示名称以foo开始的 schema 中所有名称包括bar的表。如果没有出现点号,那么模式将只匹配当前 schema 搜索路径中可见的对象。同样,双引号内的点号会失去其特殊含义并且变成普通的字符。

高级用户可以使用字符类等正则表达式记法,如[0-9]可以匹配任意数字。所有的正则表达式特殊字符都按照第 9.7.3 节所说的工作,以下字符除外:.会按照上面所说的作为一种分隔符,*会被翻译成正则表达式记号.*?会被翻译成.,而$则按字面意思匹配。根据需要,可以通过书写?(R+|)(R|)R?来分别模拟模式字符.R*R?$不需要作为一个正则表达式字符,因为模式必须匹配整个名称,而不是像正则表达式的常规用法那样解释(换句话说,$会被自动地追加到模式上)。如果不希望该模式的匹配位置被固定,可以在开头或者结尾写上*。注意在双引号内,所有的正则表达式特殊字符会失去其特殊含义并且按照其字面意思进行匹配。还有,在操作符名称模式中(即作为\do的参数),正则表达式特殊字符也按照字面意思进行匹配。

高级特性

变量

psql提供了和普通 Unix 命令 shell 相似的变量替换特性。变量简单来说就是一对名称/值,其中值可以是任意长度的任意字符串。名称必须由字母(包括非拉丁字母)、数字和下划线构成。

要设置一个变量,可以使用psql的元命令\set。例如,

testdb=> \set foo bar

会设置foo为值bar。要检索该变量的内容,可以在名称前放一个分号,例如:

testdb=> \echo :foo
bar

这在常规 SQL 命令和元命令中均有效,下文的SQL Interpolation中有更多细节。

如果调用\set时没有第二个参数,该变量会被设置为一个空字符串值。要重置(即删除)一个变量,可以使用命令\unset。要显示所有变量的值,在调用\set时不带任何参数即可。

注意

\set的参数服从与其他命令相同的替换规则。因此可以构造有趣的引用,例如\set :foo 'something'以及分别得到Perl或者PHP软链接或者可变变量。不幸的是(或者幸运的是?),这些构造出来的东西并没有什么用处。在另一方面,\set bar :foo是一种很好的拷贝变量的方法。

有一些变量会被psql特殊对待。它们表示特定的选项设置,运行时这类选项设置可以通过修改该变量的值来改变,或者在某些情况下它们表示psql的可更改的状态。按照惯例,所有被特殊对待的变量的名称由全部大写形式的 ASCII 字母(还有可能是数字和下划线)组成。为了确保未来最大的兼容性,最好避免把这类变量名用于自己的目的。

控制psql行为的变量通常不能被重置或者设置为无效值。允许\unset命令,但它会被解释为将变量设置为它的默认值。没有第二参数的\set命令会被解释为将变量设置为on(对于接受该值的控制变量),对不接受该值的变量则会拒绝这个命令。此外,接受值onoff的控制变量也能接受其他常见的布尔值拼写方式,例如truefalse

被特殊对待的变量是:

AUTOCOMMIT

在被设置为on(默认)时,每一个 SQL 命令在成功完成时会被自动提交。在这种模式中要推迟提交,必须输入一个BEGIN或者START TRANSACTION SQL 命令。当被设置为off或者被重置时,在显式发出COMMIT或者END之前,SQL 命令不会被提交。自动提交打开模式会为你发出一个隐式的BEGIN,这会发生在任何不在一个事务块中且本身即不是BEGIN及其他事务控制命令且不是无法在事务块中执行的命令(例如VACUUM)之前。

注意

在自动提交关闭模式中,必须通过ABORT或者ROLLBACK显式地放弃任何失败的事务。还要记住,如果退出会话时没有提交,则所有的工作都会丢失。

注意

自动提交打开模式是PostgreSQL的传统行为,但是自动提交关闭模式更接近于 SQL 的规范。如果更喜欢自动提交关闭模式,可以在系统级的psqlrc文件或者个人的~/.psqlrc文件中设置它。

COMP_KEYWORD_CASE

确定在补全一个 SQL 关键词时要使用的大小写形式。如果被设置为lower或者upper,补全后的词将分别是小写或者大写形式。如果被设置为preserve-lower或者preserve-upper(默认),补全后的词将会保持该词已输入部分的大小写形式,但是如果被补全的词还没有被输入,则它会被分别补全成小写或者大写形式。

DBNAME

当前已连接的数据库名称。每次连接到一个数据库时都会设置该变量(包括程序启动时),但是可以被更改或者重置。

ECHO

如果被设置为all,所有非空输入行会被按照读入它们的样子打印到标准输出(不适用于交互式读取的行)。要在程序开始时选择这种行为,可以使用开关-a。如果被设置为queriespsql会在发送每个查询给服务器时将它们打印到标准输出。选择这种行为的开关是-e。如果被设置为errors,那么只有失败的查询会被显示在标准错误输出上。这种行为的开关是-b。如果被重置或者设置为none(默认值)则不会显示任何查询。

ECHO_HIDDEN

当这个变量被设置为on且一个反斜线命令查询数据库时,相应的查询会被先显示。这种特性可以帮助我们学习PostgreSQL的内部并且在自己的程序中提供类似的功能(要在程序开始时选择这种行为,可以使用开关-E)。如果把这个变量设置为值noexec,则对应的查询只会被显示而并不真正被发送给服务器执行。默认值是off

ENCODING

当前的客户端字符集编码。每一次你连接到一个数据库(包括程序启动)时以及当你用\encoding更改编码时,这个变量都会被设置,但它可以被更改或者重置。

ERROR

如果上一个SQL查询失败则为true,如果成功则是false。另见SQLSTATE

FETCH_COUNT

如果这个变量被设置为一个大于零的整数值,SELECT查询的结果会以一组一组的方式取出并且显示(而不是像默认的那样把整个结果集拿到以后再显示),每一组就会包括这么多个行。因此,这种方式只会使用有限的内存量,而不管整个结果集的大小。在启用这个特性时,通常会使用 100 到 1000 的设置。记住在使用这种特性时,一个查询可能会在已经显示了一些行之后失败。

提示

尽管可以把这种特性用于任何的输出格式,但是默认的aligned格式看起来会比较糟糕,因为每一组的FETCH_COUNT个行将被单独格式化,这就会导致不同的行组的列宽不同。其他的输出格式会更好。

HIDE_TABLEAM

如果此变量设置为true,则不显示表的访问方法的详细信息。这主要用于回归测试。

HIDE_TOAST_COMPRESSION

如果这个变量被设置为true,不显示列压缩方法的细节。 这主要用于回归测试。

HISTCONTROL

如果这个变量被设置为ignorespace,则以一个空格开始的行不会被放入到历史列表中。如果被设置为值ignoredups,则匹配之前的历史行的行不会被放入。值ignoreboth组合了上述两种值。如果被重置或者被设置为none(默认值),所有在交互模式中被读入的行都会保存在历史列表中。

注意

这个特性是可耻地从Bash抄袭过来的。

HISTFILE

该文件名将被用于存储历史列表。如果被重设,文件名将从PSQL_HISTORY环境变量中取得。如果该环境变量也没有被设置,则默认值是~/.psql_history,在Windows上是%APPDATA%\postgresql\psql_history。例如,

\set HISTFILE ~/.psql_history-:DBNAME

放在~/.psqlrc中将会导致psql为每一个数据库维护一个单独的历史。

注意

这个特性是可耻地从Bash抄袭过来的。

HISTSIZE

存储在命令历史中的最大命令数(默认值是500)。如果被设置为一个负值,则不会应用限制。

注意

这个特性是可耻地从Bash抄袭过来的。

HOST

当前连接到的数据库服务器端口。每次连接到一个数据库时都会设置该变量(包括程序启动时),但是可以被更改或者重置。

IGNOREEOF

如果被设置为1或者更小,向一个psql的交互式会话发送一个EOF字符(通常是Control+D)将会终止应用。如果设置为一个较大的数字值,则必须键入多个连续的EOF字符才能让交互式会话终止。如果该变量被设置为一个非数字值,则它会被解释为10。默认值为0。

注意

这个特性是可耻地从Bash抄袭过来的。

LASTOID

最后被影响的 OID 的值,这可能会由INSERT或者\lo_import命令返回。这个变量只保证在下一个SQL命令被显示完之前有效。 PostgreSQL 服务器从12版开始不再支持 OID 系统列,因此,在面向此类服务器时,跟随在INSERT后面的 LASTOID 将始终为0。

LAST_ERROR_MESSAGE
LAST_ERROR_SQLSTATE

当前psql会话中最近一个失败查询的主错误消息和相关的SQLSTATE代码,如果在当前会话中没有发生错误,则是一个空字符串和00000

ON_ERROR_ROLLBACK

当被设置为on时,如果事务块中的一个语句产生一个错误,该错误会被忽略并且该事务会继续。当被设置为interactive时,只在交互式会话中忽略这类错误,而读取脚本文件时则不会忽略错误。当被重置或者设置为off(默认值)时,事务块中产生错误的一个语句会中止整个事务。错误回滚模式的工作原理是在事务块的每个命令之前都为你发出一个隐式的SAVEPOINT,然后在该命令失败时回滚到该保存点。

ON_ERROR_STOP

默认情况下,出现一个错误后命令处理会继续下去。当这个变量被设置为on后,出现错误后命令处理会立即停止。在交互模式下,psql将会返回到命令提示符;否则,psql将会退出并且返回错误代码 3 来把这种情况与致命错误区分开来,致命错误会被报告为错误代码 1。在两种情况下,任何当前正在运行的脚本(顶层脚本以及任何它已经调用的其他脚本)将被立即中止。如果顶层命名字符串包含多个 SQL 命令,将在当前命令处停止处理。

PORT

当前连接到的数据库服务器端口。每次连接到一个数据库时都会设置该变量(包括程序启动时),但是可以被更改或者重置。

PROMPT1
PROMPT2
PROMPT3

这些变量指定psql发出的提示符的模样。见下文的Prompting

QUIET

把这个变量设置为on等效于命令行选项-q。在交互模式下可能用处不大。

ROW_COUNT

上一个SQL查询返回的行数或者受影响的行数,如果该查询失败或者没有报告行计数则为0。

SERVER_VERSION_NAME
SERVER_VERSION_NUM

字符串形式的服务器版本号,例如9.6.210.1或者11beta1,以及数字形式的服务器版本号,例如90602或者100001。每次你连接到一个数据库(包括程序启动)时,这些都会被设置,但可以被改变或者重设。

SHOW_CONTEXT

这个变量可以被设置为值nevererrors或者always来控制是否在来自服务器的消息中显示CONTEXT域。默认是errors(表示在错误消息中显示上下文,但在通知和警告消息中不显示)。 当VERBOSITY被设置为tersesqlstate时,这个设置无效(另见\errverbose,它可以用来得到刚遇到的错误的详细信息)。

SINGLELINE

设置这个变量为on等效于命令行选项-S

SINGLESTEP

设置这个变量为on等效于命令选项-s

SQLSTATE

与上一个SQL查询的失败相关的错误代码(见附录 A),如果上一个查询成功则为00000

USER

当前连接的数据库用户。每次连接到一个数据库时都会设置该变量(包括程序启动时),但是可以被更改或者重置。

VERBOSITY

这个变量可以被设置为值defaultverboseterse或者sqlstate来控制错误报告的详细程度(另见\errverbose,在想得到之前的错误的详细版本时使用)。

VERSION
VERSION_NAME
VERSION_NUM

这些变量在程序启动时被设置以反映psql的版本,分别是一个详细的字符串、一个短字符串(例如9.6.210.1或者11beta1)以及一个数字(例如90602或者100001)。它们可以被更改或重设。

SQL 中插入变量

psql变量的一个关键特性是可以把它们替换(插入)到常规SQL语句中,也可以把它们作为元命令的参数。此外,psql还提供了功能来确保被用作 SQL 文字和标识符的变量值会被正确地引用。插入一个值而不需要加引用的语法是在变量名前面加上一个冒号(:)。例如,

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

将查询表my_table。注意这可能会不安全:该变量的值会被按字面拷贝,因此它可能包含不平衡的引号甚至反斜线命令。必须确保把它放在那里是有意义的。

当一个值被用作 SQL 文本或者标识符时,最安全的是把它加上引用。要引用一个变量的值作为 SQL 文本,可以把变量名称放在单引号中并且在引号前面写一个冒号。要引用作为 SQL 标识符,则可以把变量名称放在双引号中并且在引号前面写一个冒号。这种结构可以正确地处理变量值中嵌入的引号和其他特殊字符。之前的例子用这种方法写会更安全:

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

在被引用的SQL文本和标识符中将不会执行变量插入。因此,一个诸如':foo'的结构不会从一个变量的值产生一个被引用的文本(即便能够也会不安全,因为无法正确地处理嵌入在值中的引号)。

使用这种机制的一个例子是把一个文件的内容拷贝到一个表列中。首先把该文件载入到一个变量,然后把该变量的值作为一个被引用的字符串插入:

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扩展,它有时可能会与标准用法冲突。把一个变量值转义成 SQL 文本或者标识符的冒号引用语法是一种psql扩展。

提示符

psql发出的提示符可以根据用户的喜好自定义。PROMPT1PROMPT2PROMPT3这三个变量包含了描述提示符外观的字符串和特殊转义序列。Prompt 1 是当psql等待新命令时发出的常规提示符。Prompt 2 是在命令输入时需要更多输入时发出的提示符,例如因为当命令没有被分号终止或者引用没有被关闭时就会发出这个提示符。在运行一个SQL COPY FROM STDIN命令并且需要在终端上输入一个行值时,会发出 Prompt 3。

被选中的提示符变量会被原样打印,除非碰到一个百分号(%)。百分号的下一个字符会被特定的其他文本替换。预定义好的替换有:

%M

数据库服务器的完整主机名(带有域名),或者当该连接是建立在一个 Unix 域套接字上时则是[local],或者当 Unix 域套接字不在编译在系统内的默认位置上时则是[local:/dir/name]

%m

数据库服务器的主机名称(在第一个点处截断),或者当连接建立在一个 Unix 域套接字上时是[local]

%>

数据库服务器正在监听的端口号。

%n

数据库会话的用户名(在数据库会话期间,这个值可能会因为命令SET SESSION AUTHORIZATION的结果而改变)。

%/

当前数据库的名称。

%~

%/类似,但是如果数据库是默认数据库时输出是~(波浪线)。

%#

如果会话用户时一个数据库超级用户,则是#,否则是一个>(在数据库会话期间,这个值可能会因为命令SET SESSION AUTHORIZATION的结果而改变)。

%p

当前连接到的后端的进程 ID。

%R

在提示符1下通常是=,但如果会话位于一个条件块的一个非活动分支中则是@,如果会话处于单行模式中则是^,如果会话从数据库断开连接(\connect失败时会发生这种情况)则是!。在提示符 2 中,根据为什么psql期待更多的输入,%R会被一个相应的字符替换:如果命令还没有被终止是-,如果有一个未完的/* ... */注释则是*,如果有一个未完的被引用字符串则是一个单引号,如果有一个未完的被引用标识符则是一个双引号,如果有一个未完的美元引用字符串则是一个美元符号,如果有一个还没有被配对的左圆括号则是(。在提示符 3 中%R不会产生任何东西。

%x

事务状态:当不在事务块中时是一个空字符串,在一个事务块中时是*,在一个失败的事务块中时是!,当事务状态是未判定时(例如因为没有连接)为?

%l

当前语句中的行号,从1开始。

%digits

带有指定的八进制码的字符会被替换。

%:name:

psql变量name的值。有关详细信息,请参阅上面的 Variables

%`command`

command的输出,类似于平常的反引号替换。

%[ ... %]

提示符可以包含终端控制字符,例如改变提示符文本的颜色、背景或者风格以及更改终端窗口标题的控制字符。为了让Readline的行编辑特性正确工作,这些不可打印的控制字符必须被包裹在%[%]之间以指定它们是不可见的。在提示附中可以出现多个这样的标识对。例如:

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

会导致一个在兼容 VT100 的彩色终端上的粗体(1;)的、黑底黄字(33;40)的提示符。

%w

PROMPT1 的最近输出相同宽度的空白。 这可以用作 PROMPT2 设置,以便多行语句与第一行对齐,但没有可见的辅助提示。

要在你的提示符中插入一个百分号,可以写成%%。提示符 1 和 2 的默认提示是'%/%R%x%# ',提示符 3 的提示是'>> '

注意

这个特性是可耻地从tcsh抄袭过来的。

命令行编辑

为了方便的行编辑和检索,psql支持Readline库。psql退出时命令历史会被自动保存,而当psql启动时命令历史会被重新载入。psql也支持 tab 补全,不过补全逻辑绝不是一个SQL解析器。tab 补全产生的查询也可能会受其他 SQL 命令干扰,例如SET TRANSACTION ISOLATION LEVEL。如果出于某种原因不想用 tab 键补全,可以把下面的代码放在主目录下的名为.inputrc文件中关闭该特性:

$if psql
set disable-completion on
$endif

(这不是psql特性而是Readline的特性。进一步的细节请阅读它的文档。)

环境

COLUMNS

如果\pset columns为零,这个环境变量控制用于wrapped格式的宽度以及用来确定是否输出需要用到分页器或者切换到扩展自动模式中的垂直格式的宽度。

PGDATABASE
PGHOST
PGPORT
PGUSER

默认连接参数(见第 34.15 节)。

PG_COLOR

规定在诊断消息中是否使用颜色。可能的值为alwaysautonever

PSQL_EDITOR
EDITOR
VISUAL

\e\ef以及\ev命令所使用的编辑器。会按照列出的顺序检查这些变量,第一个被设置的将被使用。如果都没有被设置,默认是使用Unix系统上的vi或者Windows系统上的notepad.exe

PSQL_EDITOR_LINENUMBER_ARG

\e\ef或者\ev带有一个行号参数时,这个变量指定用于传递起始行号给用户编辑器的命令行参数。对于Emacs或者vi之类的编辑器,这个变量是一个加号。如果需要在选项名称和行号之间有空格,可以在该变量的值中包括一个结尾的空格。例如:

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

在 Unix 系统上默认是+(对应于默认编辑器vi,且对很多其他常见编辑器可用)。在 Windows 系统上没有默认值。

PSQL_HISTORY

命令历史文件的替代位置。波浪线(~)扩展会被执行。

PSQL_PAGER
PAGER

如果一个查询的结果在屏幕上放不下,它们会通过这个命令分页显示。典型的值是moreless。通过把PSQL_PAGERPAGER设置为空字符串可以禁用分页器的使用,调整\pset命令与分页器相关的选项也能达到同样的效果。会按照列出的顺序检查这些变量,第一个被设置的将被使用。如果都没有被设置,则大部分平台上默认使用more,但在Cygwin上使用less

PSQLRC

用户的.psqlrc文件的替代位置。波浪线(~)扩展会被执行。

SHELL

\!命令执行的命令。

TMPDIR

存储临时文件的目录。默认是/tmp

和大部分其他PostgreSQL工具一样,这个工具也使用libpq所支持的环境变量(见第 34.15 节)。

文件

psqlrc and ~/.psqlrc

如果没有-X选项,在连接到数据库后但在接收正常的命令之前,psql会尝试依次从系统级的启动文件(psqlrc)和用户的个人启动文件(~/.psqlrc)中读取并且执行命令。这些文件可以被用来设置客户端或者服务器,通常是一些\setSET命令。

系统级的启动文件是psqlrc,它应该在安装好的PostgreSQL系统配置目录中,最可靠的定位方法是运行pg_config --sysconfdir。默认情况下,这个目录将是../etc/(相对于包含PostgreSQL可执行文件的目录)。可以通过PGSYSCONFDIR环境变量显式地设置这个目录的名称。

用户个人的启动文件是.psqlrc,它应该在调用用户的主目录中。在 Windows 上,由于没有用户主目录的概念,个人的启动文件是%APPDATA%\postgresql\psqlrc.conf。用户启动文件的位置可以通过PSQLRC环境变量设置。

系统级和用户个人的启动文件都可以弄成是针对特定psql版本的,方法是在文件名后面加上一个横线以及PostgreSQL的主、次版本号,例如~/.psqlrc-9.2或者~/.psqlrc-9.2.5。版本最为匹配的文件会优先于不那么匹配的文件读入。

.psql_history

命令行历史被存储在文件~/.psql_history中,或者是 Windows 的文件%APPDATA%\postgresql\psql_history中。

历史文件的位置可以通过HISTFILE psql变量或者PSQL_HISTORY环境变量明确的设置。

注解

  • psql和具有相同主版本或者更老的主版本服务器最为匹配。如果服务器的版本比psql本身要高,则反斜线命令尤其容易失败。不过,\d家族的反斜线命令应该可以和版本 7.4 之后的服务器一起使用,但服务器的版本不必比psql本身新。运行 SQL 命令并且显示查询结果的一般功能应该也能和具有更新主版本的服务器一起使用,但是并非在所有的情况下都能保证如此。

    如果你想用psql连接到多个具有不同主版本的服务器,推荐使用最新版本的psql。或者,你可以为每一个主版本保留一份psql拷贝,并且针对相应的服务器使用匹配的版本。但实际上,这种额外的麻烦是不必要的。

  • PostgreSQL 9.6 之前,-c选项表示-X--no-psqlrc),但现在不是这样了。

  • PostgreSQL 8.4 之前,psql允许一个单字母反斜线命令的第一个参数直接写在该命令后面,中间不需要空格。现在则要求一些空格。

给 Windows 用户的注解

psql是一个控制台应用。由于 Windows 的控制台窗口使用的是一种和系统中其他应用不同的编码,在psql中使用 8 位字符时要特别注意。如果psql检测到一个有问题的控制台代码页,它将会在启动时警告你。要更改控制台代码页,有两件事是必要的:

  • 输入cmd.exe /c chcp 1252可以设置代码页(1252 是适用于德语的一个代码页,请在这里替换成你的值)。如果正在使用 Cygwin,可以把这个命令放在/etc/profile中。

  • 把控制台字体设置为Lucida Console,因为栅格字体无法与 ANSI 代码页一起使用。

示例

第一个例子展示了如何如何跨越多行输入一个命令。注意提示符的改变:

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 csv
Output format is csv.
peter@localhost testdb=> \pset tuples_only
Tuples only is on.
peter@localhost testdb=> SELECT second, first FROM my_table;
one,1
two,2
three,3
four,4
peter@localhost testdb=> \pset format unaligned
Output format is unaligned.
peter@localhost testdb=> \pset fieldsep '\t'
Field separator is "    ".
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

此外,可以使用\g为一个查询设置这些输出格式选项:

peter@localhost testdb=> SELECT * FROM my_table
peter@localhost testdb-> \g (format=aligned tuples_only=off expanded=on)
-[ RECORD 1 ]-
first  | 1
second | one
-[ RECORD 2 ]-
first  | 2
second | two
-[ RECORD 3 ]-
first  | 3
second | three
-[ RECORD 4 ]-
first  | 4
second | four

这是一个示例,用\df命令以发现名称匹配int*pl并且第二参数是bigint类型的函数:

testdb=> \df int*pl * bigint
                          List of functions
   Schema   |  Name   | Result data type | Argument data types | Type
------------+---------+------------------+---------------------+------
 pg_catalog | int28pl | bigint           | smallint, bigint    | func
 pg_catalog | int48pl | bigint           | integer, bigint     | func
 pg_catalog | int8pl  | bigint           | bigint, bigint      | func
(3 rows)

如果需要,可以用\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)

这第二个例子展示了表的“乘法”(连接),行按照序号降序排序且列按照独立的、升序的方式排序。

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)