问题报告 纠错本页面

psql

名称

psql --  PostgreSQL的交互式终端

大纲

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

描述

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

选项

-a
--echo-all

读取所有非空输入行时,将其打印到标准输出。(不适用于交互式行读取)。 这等效于把变量ECHO设置为all

-A
--no-align

切换到非对齐输出模式(默认输出模式是对齐的)。

-b
--echo-errors

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

-c command
--command=command

指定psql执行一个命令字符串( command)然后退出。 这在 shell 脚本中有用。使用这个选项会忽略开始文件( psqlrc~/.psqlrc)。

command 必须是一个服务器完全可解析的命令字符串(即不包含 psql相关的特性)或者单个反斜线命令。 因此不能用这个选项混合SQLpsql元命令。要那样做,可以把字符串用管道输送到 psql中,例如, echo '\x \\ SELECT * FROM foo;' | psql\\是分隔符元命令)。

如果该命令字符串包含多个 SQL 命令,它们会在一个单一事务中被处理 (除非字符串中包括了显式的BEGIN/COMMIT 命令把它分隔成多个事务)。这和把同样的字符串输送给 psql的标准输入的行为不同。还有, 只有最后一个 SQL 命令的结果会被返回。

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

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

-d dbname
--dbname=dbname

指定要连接的数据库的名称。这等效于指定dbname为命令行上的第一个非选项参数。

如果这个参数包含一个=符号或者以一个合法的 URI前缀( postgresql://或者 postgres://)开始,它会被当作一个 conninfo字符串。详见第 31.1.1 节

-e
--echo-queries

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

-E
--echo-hidden

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

-f filename
--file=filename

使用文件filename 作为命令的来源,而不是交互式地读取命令。在文件被处理后, psql会终止。在很多方面, 这等效于元命令\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类似。

-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命令。

-T table_options
--table-attr=table_options

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

-U username
--username=username

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

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

执行一次变量赋值,和\set元命令相似。 注意你必须在命令行上用等号分隔名字和值(如果有)。要重置一个 变量,去掉等号就行。要把一个变量置为空值,使用等号但是去掉值。 这些赋值都是在启动的很早期阶段完成的,因此为内部目的保留的变 量可能会在后面被覆盖。

-V
--version

打印psql版本并且退出。

-w
--no-password

从不发出一个口令提示。如果服务器要求口令认证并且没有其他方式提供口令 (例如一个.pgpass文件),那么连接尝试将失败。 这个选项对于批处理任务和脚本有用,因为在其中没有一个用户输入口令。

注意这个选项将对整个会话保持设置,并且因此它会影响元命令 \connect,以及初始的连接尝试的使用。

-W
--password

强制psql在连接到一个数据库之前提示要求一个口令。

这个选项不是必不可少的,因为如果服务器要求口令认证, psql将自动提示要求一个口令。但是, psql将浪费一次连接尝试来发现服务器想要一个口令。 在某些情况下值得用-W来避免额外的连接尝试。

注意这个选项将对整个会话保持设置,并且因此它会影响元命令 \connect,以及初始连接尝试的使用。

-x
--expanded

打开扩展表格式模式。这等效于\x命令。

-X,
--no-psqlrc

不读取启动文件(系统范围的psqlrc文件, 或者用户的~/.psqlrc文件都不读取)。

-z
--field-separator-zero

设置非对齐输出的域分隔符为零字节。

-0
--record-separator-zero

设置非对齐输出的记录分隔符为零字节。例如,这对与 xargs -0配合有关。

-1
--single-transaction

psql执行脚本时,增加这个选项会在脚本上包裹 BEGIN/COMMIT来让该脚本在一个事务中执行。 这确保了所有命令要么成功完成,要么任何更改都不被应用。

如果脚本本身使用了BEGINCOMMIT 或者ROLLBACK,这个选项将不会得到想要的效果。 还有,如果该脚本包含任何不能在一个事务块中执行的命令, 指定这个选项将导致该命令失败(进而导致整个事务失败)。

-?
--help[=topic]

显示有关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 域套接字连接到本地主机上的服务器, 或者通过 TCP/IP 连接到没有 Unix 域套接字的主机上的localhost。 默认端口号则在编译时决定。由于数据库服务器使用相同的默认值, 大多数情况下你将不必指定端口。默认的用户名是你的操作系统用户名, 它也会是默认的数据库名。注意你不一定能连接到任意用户名下的任何数据库。 你的数据库管理员应该已经告知过你有关你的访问权限。

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

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

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

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

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

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

输入 SQL 命令

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

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

testdb=>

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

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

当 C 风格的注释块被传给服务器进行处理和移除时, SQL 标准的注释通过psql移除。

元命令

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

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

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

在一个参数中,封闭在反引号(`) 中的文本被当做要被送给 shell 的一个命令行。该命令的输出(去掉尾部的新行) 将会替换这段反引号文本。

如果一个参数中出现一个未加引号的冒号(:)后面跟着一个 psql变量名,如SQL 插值中所述, 它会被该变量的值所替换。

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

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

下面是已定义的元命令:

\a

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

\c\connect [ dbname [ username ] [ host ] [ port ] ] | conninfo

与一台PostgreSQL服务器建立一个新连接。 可以使用位置语法指定要使用的连接参数,或者使用 第 31.1.1 节中详细介绍的conninfo连接串。

当使用位置参数时,如果dbnameusernamehostport中的任意一个被省略或者指定为 -,那么使用前一个连接中的该参数的值;如果没有前一个连接, 则使用该参数值的libpq默认值。当使用conninfo 字符串时,没有来自先前连接的值用于新连接。

如果新连接成功地被建立,之前的连接会被关闭。如果连接尝试失败 (错误的用户名、访问被拒绝等),只有在psql 处于交互模式的情况下才会保留之前的连接。 当执行一个非交互式脚本时处理将被立即停止, 并且报出一个错误。这种区别一方面可以帮助用户发现打字错误, 另一方面也可以作为一种安全机制防止脚本在错误的数据库上执行动作。

例子:

=> \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
\C [ title ]

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

\cd [ directory ]

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

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

\conninfo

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

\copy { table [ ( column_list ) ] | ( query ) } { from | to } { 'filename' | program 'command' | stdin | stdout | pstdin | 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命令应用特殊的解析规则。特别地,psql 的变量替换规则和反斜线转义不适合于此。

提示: 这个操作不如SQL COPY命令有效, 因为所有的数据必须通过客户端/服务器的连接来传递。 对于大量的数据来说SQL命令可能会更好。

\copyright

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

\d[S+] [ pattern ]

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

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

命令形式\d+是一样的,不过会显示更多信息: 与该表的列相关的任何注释,表中是否存在 OID,如果关系是视图则显示视图定义, 非默认的复制身份设置。

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

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

\da[S] [ pattern ]

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

\db[+] [ pattern ]

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

\dc[S+] [ pattern ]

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

\dC[+] [ pattern ]

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

\dd[S] [ pattern ]

显示constraintoperator classoperator familyrule以及trigger类型对象的描述。 所有其他注释可以通过那些对象类型相应的反斜线命令查看。

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

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

\ddp [ pattern ]

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

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

\dD[S+] [ pattern ]

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

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

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

\des[+] [ pattern ]

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

\det[+] [ pattern ]

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

\deu[+] [ pattern ]

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

小心

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

\dew[+] [ pattern ]

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

\df[antwS+] [ pattern ]

列出被分为"agg"(聚集)、"normal""trigger" 以及"window"的函数及其参数、返回类型和函数类型。要想只显示指定类型的函数, 可以在该命令上增加相应的字母ant 或者w。如果指定了pattern,只显示名称匹配该模式的函数。 默认情况下只会显示用户创建的对象,提供一个模式或者S 修饰符可以把系统对象包括在内。如果使用了\df+形式, 则有关每个函数的额外信息也会被显示,包括安全分类、波动性、所有者、 语言、源代码和描述。

提示: 如果要查找接收指定数据类型参数或者返回指定类型值的函数, 可以使用分页器的搜索能力来滚动显示\df输出。

\dF[+] [ pattern ]

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

\dFd[+] [ pattern ]

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

\dFp[+] [ pattern ]

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

\dFt[+] [ pattern ]

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

\dg[+] [ pattern ]

列出数据库角色(因为"用户""组"的概念已经被统一成 "角色",这个命令现在等价于\du)。 如果指定了pattern, 只列出名称匹配该模式的那些角色。如果使用了\dg+形式, 有关每个角色的额外信息也将被显示,当前这种形式会为角色增加注释。

\dl

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

\dL[S+] [ pattern ]

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

\dn[S+] [ pattern ]

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

\do[S+] [ pattern ]

列出操作符及其操作数和结果类型。如果指定了 pattern, 只列出名称匹配该模式的操作符。默认情况下只会显示用户创建的对象, 提供一个模式或者S修饰符可以把系统对象包括在内。 如果向命令名称追加+,有关每个操作符的额外信息也将被显示, 当前只显示底层函数的名称。

\dO[S+] [ pattern ]

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

\dp [ pattern ]

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

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

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

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

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

\dT[S+] [ pattern ]

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

\du[+] [ pattern ]

列出数据库角色(因为"用户""组"的概念已经被统一成 "角色",这个命令现在等价于\dg)。 如果指定了pattern, 只列出名称匹配该模式的那些角色。如果使用了\du+形式, 有关每一种角色的额外信息也会被显示,目前这为每个角色增加了注释。

\dx[+] [ pattern ]

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

\dy[+] [ pattern ]

列出事件触发器。如果指定了pattern, 只列出名称匹配该模式的事件触发器。如果在命令名称后面加上+, 则每个对象都和与其相关的描述一起列出。

\e\edit [ filename ] [ line_number ]

如果指定了filename, 则会编辑该文件,并且在编辑器退出后,它的内容会被复制到查询缓冲区中。 如果没有给出filename, 将会把当前的查询缓冲区复制到一个临时文件并且以同样的方式编辑该临时文件。

新的查询缓冲区接下来将被重新根据psql的规则进行解析, 这里整个缓冲区会被当做一个单一行处理(因此无法用这种方式制作脚本, 如果需要做脚本请用\i)。这意味着如果查询以一个分号结束 (或者包含一个分号),它会立即被执行。否则它将在查询缓冲区中等待, 键入分号或者\g会把它发出,用\r则可以取消之。

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

提示: 关于如何配置以及自定义编辑器,请见下面的环境

\echo text [ ... ]

把参数打印到标准输出,参数之间用一个空格分隔,最后加上一个新行。 这可以用来在脚本的输出中间混入信息,例如:

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

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

提示: 如果使用\o命令来重定向查询的输出, 你可能希望使用\qecho来取代这个命令。

\ef [ function_description [ line_number ] ]

这个命令会以一个CREATE OR REPLACE FUNCTION 的形式取出并且编辑指定函数的定义。编辑的方式与\edit完全相同。 在编辑器退出后,更新过的命令将在查询缓冲区中等待,可以键入分号或者 \g把它发出,也可以用\r取消之。

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

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

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

提示: 有关如何配置和自定义编辑器可见环境

\encoding [ encoding ]

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

\f [ string ]

设置用于非对齐查询输出的域分隔符。默认值是竖线(|)。 还可以参见用于设置输出选项的一般方法\pset

\g [ filename ]
\g [ |command ]

把当前查询输入缓冲区发送到服务器,并且根据选择把查询的输出存储在 filename 或者把输出用管道导向 shell 命令command。 只有该查询成功地返回零个或者更多元组时才会向文件或者命令写入, 而查询失败或者不是返回数据的 SQL 命令时则不会写入。

单独一个\g实质上等价于一个分号。带有参数的 \g\o命令的一个 "一次性的"替换方案。

\gset [ prefix ]

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

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

如果查询失败或者不返回行,任何变量都不会被改变。

\h\help [ command ]

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

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

\H\html

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

\i\include filename

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

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

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

\ir\include_relative filename

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

\l[+]\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

从数据库中删除OID loid对应的大对象。

提示: 使用\lo_list可以找到大对象的 OID

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

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

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

提示: 要在查询结果之间散布文本输出,可以使用 \qecho

\p\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为非零则文件和管道输出也会被包裹成该宽度。

expanded (或 x)

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

fieldsep

指定在非对齐输出格式中使用的域分隔符。这样就可以创建其它程序希望的输出, 例如制表符或逗号分隔的输出。 要设置 tab 为域分隔符,可以键入\pset fieldsep '\t'。默认的域分隔符是'|'(一个竖线)。

fieldsep_zero

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

footer

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

format

设置输出格式为unalignedalignedwrappedhtmlasciidoclatex(使用 tabular)、latex-longtable或者 troff-ms之一。允许使用唯一缩写 (这意味着一个字母就够了)。

unaligned格式把一个数据行的所有列都写在一行上, 之间用当前活动的域分隔符分隔。这可用于生成意图由其他程序读取的输出 (例如,tab 分隔或者逗号分隔格式)。

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

wrapped格式和aligned相似, 但是包装跨行的宽数据值,使其适应目标字段的宽度输出。 目标宽度的确定如columns选项中的描述。注意psql 将不会尝试对列头部标题进行包装,因此如果列头部需要的总宽度超过目标宽度, wrapped格式的行为就变得和aligned一样了。

htmlasciidoclatexlatex-longtabletroff-ms 格式分别用相应的标记语言把要输出的表格放在文档中, 不过它们的输出并不是完整的文档。在HTML 中这可能并不重要,但是在LaTeX 中必须有完整的文档。latex-longtable 还要求有LaTeXlongtable 以及booktabs包。

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的帮助输出使用分页器程序。 如果环境变量PAGER被设置,输出会被用管道输送到指定的程序。 否则将使用与平台相关的默认分页器程序(例如more)。

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

pager_min_lines

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

recordsep

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

recordsep_zero

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

tableattr (或 T)

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

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

title

为任何随后打印的表设置标题。这可以用来给输出加上描述性的标签。 如果没有给出value,则标题是未设置的。

tuples_only (或 t)

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

unicode_border_linestyle

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

unicode_column_linestyle

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

unicode_header_linestyle

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

这些不同格式的外观可以在例子小节中看到。

提示: \pset有多种快捷命令。请参见 \a\C\H\t\T\x.

\q\quit

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

\qecho text [ ... ]

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

\r\reset

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

\s [ filename ]

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

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

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

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

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

尽管可以自由地把任意变量设置为任意的值,但是有几个变量会受到 psql的特殊对待。在有关变量的小节中有介绍。

注意: 这个命令和SQL命令SET无关。

\setenv name [ value ]

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

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

\sf[+] function_description

这个命令取出并且显示指定函数的定义,以一个CREATE OR REPLACE FUNCTION 命令的格式。定义会被打印到当前的查询输出通道, 就像\o所设定的那样。

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

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

\t

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

\T table_options

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

\timing [ on | off ]

如果不带参数,则打开/关闭显示每个 SQL 语句花费的时间(以毫秒为单位)。 如果有参数,参数是on则打开显示,否则关闭显示。

\unset name

重置(删除)psql变量name

\w\write filename
\w\write |command

把当前查询缓冲区输出到文件filename或者用管道导出到 shell 命令 command

\watch [ seconds ]

反复执行当前的查询缓冲区(就像\g那样)直到被中止或者查询失败。 两次执行之间等待指定的秒数(默认是 2 秒)。

\x [ on | off | auto ]

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

\z [ pattern ]

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

这是\dp"display privileges")的一个别名。

\! [ command ]

跳到一个单独的 shell 或者执行 shell 命令 command。 参数不会被进一步解释,shell 将会原封不动地看到参数。特别要说明的是, 变量替换规则和反斜线转义在这里不适用。

\? [ topic ]

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

Patterns

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

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

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

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

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

高级特性

变量

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

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

testdb=> \set foo bar

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

testdb=> \echo :foo
bar

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

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

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

有一些变量会被psql特殊对待。它们表示特定的选项设置, 运行时这类选项设置可以通过修改该变量的值来改变, 或者在某些情况下它们表示psql的可更改的状态。 尽管可以把这些变量用于其他目的,但并不推荐这样做, 因为该程序的行为可能发展得很快很奇怪。按照惯例, 所有被特殊对待的变量的名称由全部大写形式的 ASCII 字母 (还有可能是数字和下划线)组成。为了确保未来最大的兼容性, 最好避免把这类变量名用于自己的目的。下文列出了所有被特殊对待的变量。

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,则对应的查询只会被显示而并不真正被发送给服务器执行。

ENCODING

当前的客户端字符集编码。

FETCH_COUNT

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

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

HISTCONTROL

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

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

HISTFILE

将被用于存储历史列表的文件名。默认值是~/.psql_history。 例如,把

\set HISTFILE ~/.psql_history- :DBNAME

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

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

HISTSIZE

存储在命令历史中的命令数。默认值是 500。

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

HOST

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

IGNOREEOF

如果没有设置,向psql的一个交互式会话发送一个 EOF字符(通常是Control+D) 将会终止该应用。如果被设置为一个数字值, 则在应用终止前会忽略那么多个EOF字符。 如果该变量被设置但不是数字值,则默认为 10。

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

LASTOID

最后被影响的 OID 的值,由INSERT 或者\lo_import命令返回。 这个变量只保证在下一个SQL命令的结果被显示之前有效。

ON_ERROR_ROLLBACK

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

ON_ERROR_STOP

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

PORT

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

PROMPT1
PROMPT2
PROMPT3

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

QUIET

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

SINGLELINE

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

SINGLESTEP

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

USER

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

VERBOSITY

这个变量可以被设置为值defaultverbose 或者terse来控制错误报告的详细程度。

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")不会被替换,除非所提及的变量就是当前被设置的。 在任何情况下,可以用一个反斜线对冒号进行转义以避免它被替换。

变量的冒号语法对嵌入式查询语言(例如ECPG) 来说是标准的SQL。用于数组切片和类型转换的冒号语法是 PostgreSQL扩展,它有时可能会与标准用法冲突。 把一个变量值转义成SQL 文本或者标识符的冒号引用语法是一种 psql扩展。

提示符

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

被选中的提示符变量会被原样打印,除非碰到一个百分号(%)。 这时某些其它的文本被替换,替换为何物取决于下一个字符。预定义好的替换有:

%M

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

%m

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

%>

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

%n

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

%/

当前数据库的名称。

%~

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

%#

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

%R

对于PROMPT1通常是=,但是如果是单行模式则是^, 而如果会话与数据库断开(如果\connect失败可能发生)则是 !。对于PROMPT2该序列被-*、 一个单引号/双引号/美元符(取决于psql是否等待更多的输入: 命令没有终止、正在一个/* ... */注释内、 正在引号或者美元符转义字符串内)代替。对于PROMPT3该序列不解释成任何东西。

%x

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

%l

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

%digits

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

%:name:

psql变量 name的值。 详见变量

%`command`

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

%[ ... %]

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

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

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

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

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

命令行编辑

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

$if psql
set disable-completion on
$endif

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

环境

COLUMNS

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

PAGER

如果屏幕无法容纳查询结果,则查询结果会通过这个命令导出。 典型的值是more或者less。 它的默认值与平台相关。分页器的使用可以通过使用\pset命令禁止。

PGDATABASE
PGHOST
PGPORT
PGUSER

默认连接参数(见第 31.14 节).

PSQL_EDITOR
EDITOR
VISUAL

\e\ef命令使用的编辑器。 将以上述列出的顺序检查这些变量,第一个被设置的变量将被使用。

在 Unix 系统上内建的默认编辑器是vi, Windows 系统上则是notepad.exe

PSQL_EDITOR_LINENUMBER_ARG

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

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

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

PSQL_HISTORY

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

PSQLRC

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

SHELL

\!命令执行的命令。

TMPDIR

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

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

文件

psqlrc~/.psqlrc

如果没有-X-c选项, 在连接到数据库后但在接收正常的命令之前,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中。

历史文件的位置可以通过PSQL_HISTORY环境变量显式地设置。

注意

Windows用户注意事项

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

例子

第一个例子展示如何把一个命令分布在多个输入行上。注意提示符的变化:

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

现在再看看表定义:

testdb=> \d my_table
             Table "my_table"
 Attribute |  Type   |      Modifier
-----------+---------+--------------------
 first     | integer | not null default 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