↑↓ 选择 ↵ 打开 ⌫ 改范围 完整检索页

pgsql.cc 提供对 postgresql.org 官网内容的中文翻译,由 Pigsty 团队维护。

受支持版本: 当前版本 (18) / 17 / 16 / 15 / 14
测试与开发版本: 19 / devel
不受支持的版本: 13 / 12 / 11 / 10 / 9.6 / 9.5 / 9.4 / 9.3 / 9.2 / 9.1 / 9.0 / 8.4 / 8.3 / 8.2 / 8.1 / 8.0 / 7.4 / 7.3 / 7.2 / 7.1 / 7.0 / 6.5 / 6.4
历史版本PostgreSQL 8.2 已于 2011 年 12 月结束社区维护,本页译文保留供仍在使用旧版本的读者参考。新系统请看当前版本。

psql

psql — PostgreSQL的交互式终端

大纲

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

描述

psql是PostgreSQL的一个基于终端的前端。它使你能够交互式地输入查询,将其发送给PostgreSQL,并查看查询结果。也可以从文件提供输入。此外,它还提供了若干元命令和多种类似 shell 的特性,以便于编写脚本和自动化执行各种任务。

选项

-a
--echo-all

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

-A
--no-align

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

-c command
--command command

指定psql执行一个命令字符串command,然后退出。这在 shell 脚本中很有用。

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

如果命令字符串包含多条 SQL 命令,它们会在单个事务中处理,除非字符串中包含显式的BEGIN/COMMIT命令将其分成多个事务。这与把同一字符串送入psql标准输入时的行为不同。

-d dbname
--dbname dbname

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

-e
--echo-queries

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

-E
--echo-hidden

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

-f filename
--file filename

使用文件filename作为命令来源,而不是交互式地读取命令。文件处理完毕后,psql终止。这在很多方面等价于元命令\i。

如果filename是-(连字符),则会读取标准输入。

使用这个选项与写成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选项时,配合这个选项很有用。在psql中,你还可以设置QUIET变量来达到同样的效果。

-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

强制psql在连接数据库之前提示输入用户名和密码。

这个选项已被弃用,因为它在概念上有缺陷。(提示输入非默认用户名,与因为服务器要求而提示输入密码,实际上是两件不同的事情。)建议你改用-U和-W选项。

-U username
--username username

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

-v assignment
--set assignment
--variable assignment

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

-V
--version

打印psql版本并且退出。

-W
--password

强制psql在连接数据库之前提示输入密码。

只要服务器请求密码认证,psql就应当自动提示输入密码。然而,目前的密码请求检测并不完全可靠,因此提供了这个选项来强制提示。如果没有发出密码提示而服务器又要求密码认证,连接尝试将失败。

即使你后来用元命令\connect改变了数据库连接,这个选项在整个会话期间也将保持有效。

-x
--expanded

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

-X,
--no-psqlrc

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

-1
--single-transaction

当 psql 使用 -f 选项执行一个脚本时,加上这个选项会在脚本前后包上 BEGIN/COMMIT,把它作为单个事务执行。这确保要么所有命令都成功完成,要么不应用任何更改。

如果脚本本身使用了BEGIN、COMMIT或ROLLBACK,这个选项就不会产生期望的效果。另外,如果脚本中包含不能在事务块中执行的命令,指定这个选项将导致该命令(进而整个事务)失败。

-?
--help

显示有关psql命令行参数的帮助并且退出。

退出状态

如果psql正常结束,它会向 shell 返回 0;如果它自身发生致命错误(例如内存耗尽、找不到文件),则返回 1;如果到服务器的连接发生故障且该会话不是交互式的,则返回 2;如果脚本中发生错误且变量ON_ERROR_STOP已设置,则返回 3。

用法

Connecting To A Database

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

当默认值不完全合适时,可以通过把环境变量PGDATABASE、PGHOST、PGPORT和PGUSER设置为适当的值来少敲一些键盘(额外的环境变量见第 29.12 节)。另外,准备一个~/.pgpass文件也很方便,这样就不必经常手工输入密码。详见第 29.13 节。

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

输入 SQL 命令

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

$ psql testdb
Welcome to psql 8.2.23, the PostgreSQL interactive terminal.

Type:  \copyright for distribution terms
       \h for help with SQL commands
       \? for help with psql commands
       \g or terminate with semicolon to execute query
       \q to quit

testdb=>

在提示符下,用户可以输入SQL命令。通常,当遇到表示命令结束的分号时,输入的内容就会被发送给服务器。行结束并不会终止一条命令,因此为了提高清晰度,命令可以分布在多行上。如果命令被发送并成功执行,其结果就会显示在屏幕上。

每当执行命令时,psql也会轮询由LISTEN和NOTIFY生成的异步通知事件。

元命令

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

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

要在参数中包含空白,可以用单引号将它括起来。要在这样的参数中包含一个单引号,可以写两个单引号。单引号中的内容还会接受类似 C 语言的替换:\n(换行)、\t(制表符)、\digits(八进制)和 \xdigits(十六进制)。

如果未加引号的参数以冒号(:)开头,它会被当作一个 psql 变量,该变量的值将被用作参数。

用反引号(`)包围的参数会被当作传给 shell 的命令行。该命令的输出(去掉末尾的换行符)将被用作参数值。上述转义序列在反引号中同样适用。

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

参数解析会在行尾或遇到另一个未加引号的反斜线时停止。未加引号的反斜线会被视为新元命令的开始。特殊序列\(两个反斜线)表示参数结束,并继续解析SQL命令(如果还有)。通过这种方式,SQL命令和psql命令可以自由地混合在同一行中。但无论如何,元命令的参数都不能延续到下一行。

定义了下列元命令:

\a

如果当前表格输出格式是非对齐,则切换为对齐;否则切换为非对齐。保留此命令是为了向后兼容。更通用的解决方案请参见\pset。

\cd [ directory ]

将当前工作目录更改为directory。如果没有参数,则切换到当前用户的主目录。

提示

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

\C [ title ]

设置作为查询结果打印的表的标题,或取消此类标题。该命令等价于\pset title title。(此命令的名称源自“caption”,因为它过去只用于设置HTML表的标题。)

\connect (or \c) [ dbname [ username ] [ host ] [ port ] ]

建立到PostgreSQL服务器的新连接。如果成功建立了新连接,则关闭先前的连接。如果dbname、username、host或port中的任何一个被省略或被指定为-,将使用前一个连接中该参数的值。如果没有前一个连接,则使用libpq对该参数值的默认值。

如果连接尝试失败(用户名错误、访问被拒绝等),只有在psql处于交互模式时才会保留先前的连接。在执行非交互式脚本时,处理会立即停止并报错。选择这种区别对待,一方面是为了让用户方便地应对输入错误,另一方面是作为一种安全机制,防止脚本意外地作用于错误的数据库。

\copy { table [ ( column_list ) ] | ( query ) } { from | to } { filename | stdin | stdout | pstdin | pstdout } [ with ] [ binary ] [ oids ] [ delimiter [ as ] 'character' ] [ null [ as ] 'string' ] [ csv [ header ] [ quote [ as ] 'character' ] [ escape [ as ] 'character' ] [ force quote column_list ] [ force not null column_list ] ]

执行前端(客户端)复制。该操作会运行一个SQL COPY命令,但并不是由服务器读取或写入指定文件,而是由psql读取或写入文件,并在服务器与本地文件系统之间转送数据。这意味着文件可访问性和权限取决于本地用户,而不是服务器,也不需要 SQL 超级用户权限。

该命令的语法与 SQL 的 COPY 命令类似。注意,正因为如此,\copy 命令适用特殊的解析规则。特别是,变量替换规则和反斜线转义在这里不适用。

\copy ... from stdin | to stdout 分别基于命令的输入和输出进行读取/写入。所有行都从发出该命令的同一输入源读取,直到读到仅包含 \. 的一行或流到达 EOF 为止。输出会发送到与命令输出相同的位置。若要读写psql的标准输入或输出,请使用 pstdin 或 pstdout。这个选项适合在 SQL 脚本文件中以内联方式填充表。

提示

这个操作不像SQL的COPY命令那样高效,因为所有数据都必须经过客户端/服务器连接。对于大量数据,SQL命令可能更可取。

\copyright

显示PostgreSQL的版权和分发条款。

\d [ pattern ]
\d+ [ pattern ]

对于每个匹配pattern的关系(表、视图、索引或序列),显示其所有列、列的类型、表空间(如果不是默认表空间),以及任何特殊属性,例如NOT NULL或默认值(如果有)。关联的索引、约束、规则和触发器也会显示;如果该关系是视图,还会显示视图定义。(“匹配模式”的定义见下文。)

命令形式\d+与之相同,只是显示的信息更多:会显示与表各列关联的任何注释,以及表中是否存在 OID。

注意

如果使用\d时没有pattern参数,它等同于\dtvs,将显示所有表、视图和序列的列表。这纯粹是一种便利措施。

\da [ pattern ]

列出所有可用的聚合函数及它们所操作的数据类型。如果指定了pattern,则只显示名称匹配该模式的聚合函数。

\db [ pattern ]
\db+ [ pattern ]

列出所有可用的表空间。如果指定了pattern,则只显示名称匹配该模式的表空间。如果在命令名后附加+,每个对象还会与它关联的权限一起列出。

\dc [ pattern ]

列出所有可用的字符集编码之间的转换。如果指定了pattern,则只列出名称匹配该模式的转换。

\dC

列出所有可用的类型转换。

\dd [ pattern ]

显示匹配pattern的对象的描述,如果没有给出参数则显示所有可见对象的描述。但无论哪种情况,都只列出有描述的对象。(“对象”涵盖聚合、函数、操作符、类型、关系(表、视图、索引、序列、大对象)、规则和触发器。)例如:

=> \dd version
                     Object descriptions
   Schema   |  Name   |  Object  |        Description
------------+---------+----------+---------------------------
 pg_catalog | version | function | PostgreSQL version string
(1 row)

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

\dD [ pattern ]

列出所有可用的域。如果指定了pattern,则只显示匹配该模式的域。

\df [ pattern ]
\df+ [ pattern ]

列出可用的函数及其参数和返回类型。如果指定了pattern,则只显示名称匹配该模式的函数。如果使用\df+形式,还会显示每个函数的附加信息,包括语言和描述。

注意

要查找接受特定类型的参数或返回特定类型值的函数,请使用分页器的搜索功能浏览\df输出。

为了减少杂乱,\df不显示数据类型的 I/O 函数。其实现方式是忽略接受或返回cstring类型的函数。

\dg [ pattern ]

列出所有数据库角色。如果指定了pattern,则只列出名称匹配该模式的角色。(此命令现在实际上等价于\du。)

\distvS [ pattern ]

这不是实际的命令名:字母i、s、t、v、S分别代表索引、序列、表、视图和系统表。你可以按任意顺序指定这些字母中的任意个或全部,来获得所有匹配对象的列表。字母S把列表限定为系统对象;不带S时,只显示非系统对象。如果在命令名后面追加+,每个对象还会连同它关联的描述(如果有)一起列出。

如果指定了pattern,则只列出名称匹配该模式的对象。

\dl

这是\lo_list的别名,用于显示大对象列表。

\dn [ pattern ]
\dn+ [ pattern ]

列出所有可用的模式(命名空间)。如果指定了pattern(一个正则表达式),则只列出名称匹配该模式的模式。非本地的临时模式会被隐藏。如果在命令名后面追加+,每个对象还会连同它关联的权限和描述(如果有)一起列出。

\do [ pattern ]

列出可用的操作符及其操作数和返回类型。如果指定了pattern,则只列出名称匹配该模式的操作符。

\dp [ pattern ]

列出所有可用的表、视图和序列及其关联的访问权限。如果指定了pattern,则只列出名称匹配该模式的表、视图和序列。

GRANT 和 REVOKE 命令用来设置访问权限。

\dT [ pattern ]
\dT+ [ pattern ]

列出所有数据类型,或者只列出匹配pattern的类型。命令形式\dT+显示额外的信息。

\du [ pattern ]

列出所有数据库角色,或者只列出匹配pattern的角色。

\edit (or \e) [ filename ]

如果指定了filename,则编辑该文件;编辑器退出后,其内容会被复制回查询缓冲区。如果没有给出参数,则把当前查询缓冲区复制到一个临时文件中,然后以相同的方式编辑。

然后,新的查询缓冲区会按照psql的正常规则被重新解析,整个缓冲区被当作单独一行。(因此你不能用这种方式编写脚本。请使用\i。)这也意味着,如果查询以分号结尾(或者更确切地说包含分号),它会立即被执行。在其他情况下,它只会在查询缓冲区中等待。

提示

psql按顺序搜索环境变量PSQL_EDITOR、EDITOR和VISUAL来寻找要使用的编辑器。如果它们都未设置,Unix 系统上使用vi,Windows 系统上使用notepad.exe。

\echo text [ ... ]

将参数打印到标准输出,参数之间用一个空格分隔,末尾跟随换行符。这可用于在脚本输出中插入信息。例如:

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

如果第一个参数是未加引号的-n,则不输出末尾的换行符。

提示

如果使用\o命令重定向查询输出,可能会想用\qecho代替这个命令。

\encoding [ encoding ]

设置客户端字符集编码。没有参数时,此命令显示当前编码。

\f [ string ]

设置非对齐查询输出的字段分隔符。默认值是竖线(|)。另请参见 \pset,那里介绍了设置输出选项的通用方法。

\g [ { filename | |command } ]

把当前查询输入缓冲区发送给服务器,并可选地把查询输出存储到filename中,或者把输出通过管道送给执行command的单独 Unix shell。不带参数的\g实际上等效于分号。带参数的\g是\o命令的一种“一次性”替代。

\help (or \h) [ command ]

给出指定SQL命令的语法帮助。如果未指定command, 则psql将列出所有可用语法帮助的命令。如果command是星号 (*),则显示所有SQL命令的语法帮助。

注意

为了简化输入,由多个单词组成的命令不需要加引号。因此,可以直接输入\help alter table。

\H

打开HTML查询输出格式。如果HTML格式已经打开,则切换回默认的对齐文本格式。此命令是为兼容性和便利性而保留的;设置其他输出选项的方法见\pset。

\i filename

从文件filename中读取输入,并像在键盘上输入一样执行它。

注意

如果想在屏幕上看到被读入的各行,请将变量ECHO设置为all。

\l (or \list)
\l+ (or \list+)

列出服务器中所有数据库的名称、拥有者和字符集编码。如果在命令名后附加 +,还会显示数据库的描述。

\lo_export loid filename

从数据库中读取具有OIDloid的大对象,并将其写入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。因此,建议始终为每个对象关联一条便于人阅读的注释。随后可以用\lo_list命令查看这些注释。

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

\lo_list

列出当前存储在数据库中的所有PostgreSQL大对象,以及为它们提供的注释。

\lo_unlink loid

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

提示

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

\o [ {filename | |command} ]

把以后的查询结果保存到文件filename中,或通过管道把以后的结果送给单独的 Unix shell 去执行command。如果未指定参数,查询输出将重置为标准输出。

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

提示

要在查询结果之间穿插文本输出,可使用\qecho。

\p

将当前查询缓冲区打印到标准输出。

\password [ username ]

更改指定用户(默认为当前用户)的密码。此命令提示输入新密码,对其进行加密, 并将其作为ALTER ROLE命令发送到服务器。这样可以确保新密码 不会以明文形式出现在命令历史记录、服务器日志或其他地方。

\pset parameter [ value ]

这个命令设置影响查询结果表输出的选项。parameter描述要设置哪个选项。value的含义取决于该选项。

可调整的打印选项有:

format

将输出格式设置为 unaligned、aligned、html、latex 或 troff-ms 之一。允许使用无歧义的缩写。(这意味着一个字母就足够了。)

“Unaligned” 格式把一行的所有列写在一行上,用当前生效的字段分隔符分隔。这适合创建可能要由其他程序读入的输出(例如制表符分隔、逗号分隔格式)。“Aligned” 模式是默认的标准、人类可读、格式美观的文本输出。“HTML” 和 “LaTeX” 模式生成的表格旨在包含在使用相应标记语言的文档中。它们不是完整的文档!(这在 HTML 中可能不是必需的,但在 LaTeX 中,必须有一个完整文档的外层结构。)

border

第二个参数必须是数字。一般来说,数字越大,表格的边框和分隔线就越多,但这取决于具体的格式。在 HTML 模式中,它会直接转换为 border=... 属性;在其他模式中,只有值 0(无边框)、1(内部分隔线)和 2(表格外框)有意义。

expanded (or x)

在常规格式和扩展格式之间切换。启用扩展格式时,查询结果以两列显示,左侧为列名,右侧为数据。如果数据在通常的“横向”模式下无法在屏幕上完整显示,这种模式就很有用。

所有四种输出格式都支持扩展模式。

null

设置用于代替空值打印的字符串。默认不打印任何内容,这很容易被误认为空字符串。例如,你可能更喜欢使用 \pset null '(null)'。

fieldsep

指定非对齐输出格式使用的字段分隔符。这样就可以生成例如制表符分隔或逗号分隔的输出,其他程序可能更喜欢这种格式。要把制表符设置为字段分隔符,可以键入 \pset fieldsep '\t'。默认的字段分隔符是 '|'(竖线)。

footer

切换默认页脚(x rows)的显示。

numericlocale

切换是否显示区域感知的字符来分隔小数点左侧的数字组。它还会启用区域感知的小数点标记。

recordsep

指定非对齐输出格式使用的记录(行)分隔符。默认是换行符。

tuples_only (or t)

在仅元组显示和完整显示之间切换。完整显示包含列标题、表格标题和各种页脚等附加信息。在仅元组模式下,只显示实际的表格数据。

title [ text ]

设置随后打印的任何表格的标题。这可以为输出提供描述性标签。如果没有给出参数,则取消标题的设置。

tableattr (or T) [ text ]

指定要放在 HTML table 标签内部的属性。例如可以是cellpadding或bgcolor。注意,你可能不想在这里指定border,因为这已经由\pset border处理。

pager

控制查询和 psql 帮助输出是否使用分页器程序。如果设置了环境变量 PAGER,输出会通过管道传递给指定的程序。否则,使用与平台有关的默认程序(如 more)。

当 pager 为 off 时,不使用分页器。当 pager 为 on 时,只在适当的时候使用分页器,即输出目标是终端且无法在屏幕上完整显示时。(psql 对何时使用分页器的估计并不完美。)\pset pager 打开和关闭分页器。分页器也可以设置为always,这使分页器总是被使用。

这些不同格式的外观示例可参见 示例 一节。

提示

有各种用于 \pset 的快捷命令。请参见 \a、\C、\H、\t、\T 和 \x。

注意

不带任何参数调用 \pset 是一个错误。在将来的版本中,这种情况可能会显示所有打印选项的当前状态。

\q or \quit

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

\qecho text [ ... ]

这个命令与\echo相同,只是输出会写入由\o设置的查询输出通道。

\r

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

\s [ filename ]

打印或保存命令行历史记录到filename。如果省略filename,历史记录将被写入标准输出。只有当psql被配置为使用GNU Readline库时,此选项才可用。

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

把内部变量 name 设置为 value;如果给出多个值,则设置为所有值的串接。如果没有给出第二个参数,变量只是被设置为没有值。要取消变量的设置,使用 \unset 命令。

合法的变量名可以包含字母、数字和下划线。详情见下面的变量。变量名区分大小写。

尽管你可以随意将任何变量设置为任何值,但psql将其中若干变量视为特殊变量。这些变量在下面有关变量的章节中介绍。

注意

这个命令与 SQL 命令 SET 完全无关。

\t

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

\T table_options

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

\timing

切换以毫秒为单位显示每条 SQL 语句执行耗时的开关状态。

\w {filename | |command}

把当前查询缓冲区输出到文件filename,或通过管道送给 Unix 命令command。

\x

设置或切换扩展表格格式模式。它等价于\pset expanded。

\z [ pattern ]

产生一份所有表、视图和序列及其关联访问权限的列表。 如果指定了pattern, 则只列出名称匹配该模式的表、视图和序列。

GRANT和 REVOKE 命令用于设置访问权限。

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

\! [ command ]

进入一个单独的 shell,或执行 shell 命令 command。参数不会被进一步解释;shell 会原样看到它们。

\?

显示有关反斜线命令的帮助信息。

模式

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

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

包含点号(.)的模式会被解释为模式名称的匹配模式,后接对象名称的匹配模式。例如,\dt foo*.bar*显示模式名以foo开头且表名以bar开始的所有表。如果没有点号,则该匹配模式只匹配当前模式搜索路径中可见的对象。同样,双引号内的点号会失去其特殊含义,而按字面匹配。

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

每当完全省略pattern参数时,\d命令会显示当前模式搜索路径中可见的所有对象 — 这等价于使用模式*。要查看数据库中的所有对象,可使用模式*.*。

Advanced features

变量

psql 提供了与常见 Unix 命令 shell 相似的变量替换特性。变量就是简单的名称/值对,其中值可以是任意长度的任意字符串。要设置变量,使用 psql 元命令 \set:

testdb=> \set foo bar

把变量 foo 设置为值 bar。要获取变量的内容,在名称前加上冒号,并把它用作任何斜线命令的参数:

testdb=> \echo :foo
bar

注意

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

如果调用 \set 时没有第二个参数,该变量会被设置,其值为空字符串。要取消设置(即删除)一个变量,使用命令 \unset。

psql 的内部变量名可以由字母、数字和下划线按任意顺序、任意数量组成。其中一些变量会被 psql 特殊对待。它们表示特定的选项设置(运行时可以通过更改该变量的值来改变),或者表示应用的某种状态。尽管你可以把这些变量用于其他目的,但不建议这样做,因为程序的行为可能会很快变得非常奇怪。按照惯例,所有被特殊对待的变量都由全大写字母(以及可能的数字和下划线)组成。为了确保将来最大的兼容性,请避免把这类变量名用于自己的目的。下面是所有被特殊对待的变量的列表。

AUTOCOMMIT

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

注意

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

注意

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

DBNAME

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

ECHO

如果被设置为all,所有非空输入行会在读入时打印到标准输出(不适用于交互式读取的行)。要在程序开始时选择这种行为,可以使用开关-a。如果被设置为queries,psql会在发送每个查询给服务器时将它们打印到标准输出。选择这种行为的开关是-e。如果未设置,或被设置为上述值以外的其他值,则不会显示任何查询。

ECHO_HIDDEN

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

ENCODING

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

FETCH_COUNT

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

提示

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

HISTCONTROL

如果这个变量被设置为ignorespace,则以一个空格开始的行不会被放入到历史列表中。如果被设置为值ignoredups,则与上一条历史记录相同的行不会被放入。值ignoreboth组合了上述两种值。如果未设置,或被设置为上述值以外的其他值,所有在交互模式中被读入的行都会保存在历史列表中。

注意

这个特性是可耻地从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

默认情况下,如果非交互式脚本遇到错误(例如一个格式错误的SQL命令或内部元命令),处理会继续进行。这是psql的传统行为,但有时并不理想。如果设置了该变量,脚本处理将在出错后立即终止。如果该脚本是从另一个脚本调用的,那个脚本也会以同样的方式终止。如果最外层的脚本不是从交互式psql会话中调用、而是使用-f选项调用的,psql将返回错误码 3,以区分这种情况与致命错误情况(错误码 1)。

PORT

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

PROMPT1
PROMPT2
PROMPT3

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

QUIET

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

SINGLELINE

这个变量等效于命令行选项-S。

SINGLESTEP

这个变量等效于命令行选项-s。

USER

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

VERBOSITY

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

SQL Interpolation

psql 变量的另一个有用特性是可以把它们替换(“插值”)到常规 SQL 语句中。这种操作的语法同样是在变量名前加上冒号(:):

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

将查询表my_table。变量的值会被按字面拷贝,因此它甚至可能包含不平衡的引号或反斜线命令。你必须确保把它放在那里是有意义的。不会对加了引号的SQL实体执行变量插值。

这种机制的一个流行应用是在后续语句中引用最后插入的OID来构建外键场景。这种机制的另一个可能用途是把一个文件的内容拷贝到一个表列中。首先把该文件载入到一个变量,然后按上面的做法进行:

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

这种做法的一个问题是my_file.txt可能包含单引号。这些单引号需要被转义,以免在处理第二行时导致语法错误。这可以用sed程序来完成:

testdb=> \set content '''' `sed -e "s/'/''/g" < my_file.txt` ''''

如果你使用非标准兼容的字符串,那么还需要把反斜线也加倍。这有点绕:

testdb=> \set content '''' `sed -e "s/'/''/g" -e 's/\\/\\\\/g' < my_file.txt` ''''

注意这里使用了不同的 shell 引号约定,使得单引号和反斜线对 shell 都没有特殊含义。但反斜线对sed仍然是特殊的,所以我们需要把它们加倍。(也许在某个时候你会觉得所有 Unix 命令使用相同的转义字符是一件很棒的事。)

由于冒号可以合法地出现在 SQL 命令中,适用如下规则:字符序列“:name”不会被改变,除非“name”是当前已设置的某个变量的名称。无论哪种情况,都可以用反斜线对冒号转义,以避免它被替换。(变量的冒号语法是嵌入式查询语言(例如ECPG)的标准SQL语法。数组切片和类型转换的冒号语法是PostgreSQL的扩展,因此存在冲突。)

提示符

psql 发出的提示符可以按你的喜好进行定制。PROMPT1、PROMPT2 和 PROMPT3 这三个变量包含描述提示符外观的字符串和特殊转义序列。提示符 1 是 psql 请求新命令时发出的常规提示符。提示符 2 会在录入命令期间还需要更多输入时发出,例如命令尚未以分号结束,或者引号尚未闭合时。在执行 SQL COPY FROM STDIN 命令并需要在终端中输入一行值时,会发出提示符 3。

被选中的提示符变量的值会按字面打印,除非遇到百分号(%)。根据下一个字符的不同,会替换为某些其他文本。已定义的替换有:

%M

数据库服务器的完整主机名(含域名);如果通过 Unix 域套接字连接,则为[local];如果 Unix 域套接字不在编译时指定的默认位置,则为[local:/dir/name]。

%m

数据库服务器的主机名,在第一个点号处截断;如果通过 Unix 域套接字连接,则为[local]。

%>

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

%n

数据库会话用户名。(在数据库会话期间,SET SESSION AUTHORIZATION命令可能改变该值的扩展结果。)

%/

当前数据库的名称。

%~

类似 %/,但如果该数据库是你的默认数据库,则输出 ~ (波浪号)。

%#

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

%R

在提示符 1 中通常是=,但如果处于单行模式则是^;如果会话已与数据库断开连接(例如\connect失败时可能发生),则是!。在提示符 2 中,该序列分别被替换为-、*、单引号、双引号或美元符,具体取决于psql期待更多输入是因为命令尚未结束、因为你正处于一个/* ... */注释中,还是因为你正处于一个带引号的或用美元符转义的字符串中。在提示符 3 中,该序列不产生任何内容。

%x

事务状态:如果当前不在事务块中,则为空字符串;如果处于事务块中,则为 *;如果处于失败的事务块中,则为 !;如果事务状态不确定(例如因为当前没有连接),则为 ?。

%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 启动时重新载入。也支持 Tab 补全,不过其补全逻辑并不声称自己是 SQL 解析器。如果出于某种原因你不喜欢 Tab 补全,可以将以下内容放入主目录下名为 .inputrc 的文件中,将其关闭:

$if psql
set disable-completion on
$endif

(这不是 psql 的功能,而是 Readline 的功能。更多细节请阅读其文档。)

环境

PAGER

如果查询结果无法在屏幕上完整显示,则会通过管道传递给这个命令。典型值为 more 或 less。默认值取决于平台。可以使用 \pset 命令禁用分页器的使用。

PGDATABASE

默认连接数据库。

PGHOST
PGPORT
PGUSER

默认连接参数。

PSQL_EDITOR
EDITOR
VISUAL

\e命令使用的编辑器。这些变量按列出的顺序检查;使用第一个被设置的变量。

SHELL

被\!命令执行的命令。

TMPDIR

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

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

文件

  • psql 在启动之前会尝试从系统级的 psqlrc 文件和用户的 ~/.psqlrc 文件中读取并执行命令。(在 Windows 上,用户的启动文件名为 %APPDATA%\postgresql\psqlrc.conf。)有关设置系统级文件的信息,参见 PREFIX/share/psqlrc.sample。它可用来按个人喜好设置客户端或服务器(使用 \set 和 SET 命令)。

  • 系统范围的 psqlrc 文件和用户的 ~/.psqlrc 文件都可以通过在文件名后附加连字符和 PostgreSQL 的版本号来使其与版本相关,例如 ~/.psqlrc-8.2.23。匹配的版本特定文件将优先于非版本特定的文件被读取。

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

注解

  • 在早期版本中,psql 允许一个单字母反斜线命令的第一个参数直接写在该命令后面,中间不需要空白。出于兼容性考虑,这种写法在一定程度上仍然得到支持,但我们不打算在这里解释细节,因为这种用法是不鼓励的。如果你收到了奇怪的消息,请记住这一点。例如:

    testdb=> \foo
    Field separator is "oo".
    

    这可能不是你所期望的。

  • psql 只能与相同版本的服务器顺利配合工作。这并不意味着其他组合会完全失败,但可能出现或微妙或不那么微妙的问题。如果服务器的版本不同,反斜线命令特别容易失败。

Notes for Windows users

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

提交更正

译文有误、术语不当或页面显示问题,请到译文仓库 pgsty/pgdoc 报告译文问题。 英文原文本身的问题,请在当前版本的对应页面向上游反馈;上游不再修订已结束维护的版本。