Provided by: manpages-zh_1.5.2-1.1_all 
NAME
psql - PostgreSQL 交互终端
SYNOPSIS
psql [option...] [dbname [username]]
DESCRIPTION 描述
psql 是一个以终端为基础的 PostgreSQL 前端。它允许你交互地键入查询，把它们发出给
PostgreSQL， 然后看看查询的结果。另外，输入可以来自一个文件。还有， 它提供了一些元命令和多
种类 shell 地特性来实现书写脚本以及对大量任务的自动化。
OPTIONS 选项
-a
--echo-all
在读取行时向屏幕打印所有内容。 这个选项在脚本处理时比交互模式时更有用。这个选项等
效于设置变量 ECHO 为 all。
-A
--no-align
切换为非对齐输出模式。（缺省输出模式是对齐的。）
-ccommand
--commandcommand
声明 psql 将执行一条查询字串， command，然后退出。这一点在 shell 脚本里很有用。
command 必须是一条完全可以被服务器分析的查询字串（也就是说，它不包含 psql特有的特
性）， 或者是一个反斜杠命令。这样你就不会混合 SQL 和 psql 元命令。要想混合使用，你
可以把字串定向到psql 里，象这样： echo "\x\ select * from foo;" | psql。
如果命令字串包含多个 SQL 命令，那么他们在一个事务里处理， 除非在字串里包含了明确的
BEGIN/COMMIT 命令把他们分成多个事务。 这个和从 psql 的标准输入里给它填充相同字串不
同。
-ddbname
--dbnamedbname
声明想要联接的数据库名称。等效于在命令行行上把 dbname 声明为第一个非选项参数。
-e
--echo-queries
显示所由发送给服务器的查询。 等效于把变量 ECHO 设置为 queries。
-E
--echo-hidden
回显由\d 和其他反斜杠命令生成的实际查询。 如果你希望在你自己的程序里包含类似的功
能， 你就可以使用这个选项。这等效于在psql里设置变量ECHO_HIDDEN。
-ffilename
--filefilename
使用 filename作为命令的语句源而不是交互式读入查询。 在处理完文件后，psql 结束。这
个选项在很多方面等效于内部命令\i。
如果filename 是- （连字符），则从标准输入读取。
使用这个选项与用 psql < filename 有微小的区别。通常，两者都回按照你预期那样运
行，但是使用 -f打开了一些很好的特性， 比如带行号的错误信息。而且，使用这个选项还有
可能有减小启动负荷的机会。 另一方面，如果你把所有内容手工输入， 使用 shell 输入定向
的方式（理论上）能保证生成和你已经得到的完全一样的输出（译注：重复运行命令）。
-Fseparator
--field-separatorseparator
使用 separator 作为域分隔符。等效于 \pset fieldsep 或\f。
-hhostname
--hosthostname
声明正在运行服务器的主机名。 如果主机名以斜扛开头，则它被用做到 Unix 域套接字的路
径。
-H
--html
打开HTML格式输出。等效于\pset format html 或\H 命令。
-l
--list
列出所有可用的数据库，然后退出。其他非联接选项将被忽略。类似于内部命令 \list。
-ofilename
--outputfilename
将所有查询输出定向到文件 filename。这个选项等效于命令\o。
-pport
--portport
声明被服务器侦听的 TCP 端口或使用的缺省本地 Unix 主控套接字文件句柄。 缺省的是环境
变量PGPORT的值，如果没有设置的话是编译是声明的端口，通常是 5432。
-Passignment
--psetassignment
允许你在命令行上以\pset 的风格设置打印选项。 要注意的是你在这里用等号分割名称和
值，而不能用空格。 因此要把输出格式设置为 LaTeX，你可以敲入 -P format=latex。
-q
--quiet
声明 psql 将安静地执行处理任务。 缺省时psql将打印欢迎和许多其他输出信息。 如果使用
了此选项，这些都不出现。这在和 -c 选项一起使用时很有效。在 psql 里，你可以通过设置
QUIET 变量实现同样效果。
-Rseparator
--record-separatorseparator
使用 separator 做为记录分隔符。 等效于\pset recordsep 命令。
-s
--single-step
进入单步模式运行。意味着每个查询在发往服务器之前都要提示用户， 用这个选项也可以取
消执行。此选项主要用于调试脚本。
-S
--single-line
进入单行运行模式，这时每个命令都将由换行符结束，象分号那样。
Note: 注意: 注意这个模式是给那些坚持要这个特性的人的，我们不鼓励你这么用。 实际
上，如果你在一行里混合使用 SQL 和元命令，执行的顺序对不熟练的用户而言不总是清晰的。
-t
--tuples-only
关闭打印列名称和结果行计数脚注等信息。完全等效于元命令\t。
-Ttable_options
--table-attrtable_options
允许你声明放在 HTML table 标记里的选项。 参阅\pset 获取细节。
-u
让 psql 在和数据库联接之提示输入用户的用户名和口令。
这个选项已经废弃了，因为它在概念上有漏洞。 （提示输入非缺省用户名和提示输入服务器
要求的口令是完全两码事。）我们鼓励你用 -U 和 -W 选项取代。
-Uusername
--usernameusername
以用户 username 代替缺省用户与数据库联接。（当然，你必须有这么做的权限。）
-vassignment
--setassignment
--variableassignment
进行一次变量分配，象内部命令\set 那样。 注意，如果有变量名和值的话，你必须在命令行
上用等号分隔它们。要重置一个变量， 去掉等号。这个分配是在启动的很早的阶段进行的，所
以为内部使用保留的变量可能被再次覆盖。
-V
--version
显示psql版本。
-W
--password
要求 psql 在与一个数据库联接前提示输入口令。 这个选项将在整个会话过程中有效，即使
你用元命令 \connect 改变了所联接的数据库。
在当前版本里，如果服务器要求口令认证，psql 自动提出一个口令提示符。因为目 前这个特
性是以一个“hack”为基础， 自动识别有可能奇怪地失效，因此用这个选项 强制一个提示符。
如果没有声明口令提示符而服务器要求口令认证，那么联接企图 将失败。
-x
--expanded
打开扩展表格式模式。等效于\x。
-X,
--no-psqlrc
不读取启动文件 ~/.psqlrc。
-?
--help
显示关于psql命令行参数的帮助。
EXIT STATUS 退出状态
如果正常结束，那么psql 向 shell 返回 0，如果自身发生致命错误，则返回 1（内存用尽，未找到
文件等）， 如果和数据库的连接失效而且会话不再活跃则返回 2，如果脚本中发生错误并且设置了
ON_ERROR_STOP 则返回 3。
USAGE 用法
CONNECTING TO A DATABASE 与一个数据库联接
psql 是一个普通的 PostgreSQL 客户端应用。为了与一个数据库联接，你需要知道你的目标数据库，
服务器的主机名和端口号以及你希望以哪个用户的身份进行联接等信息。 我们可以通过命令行参数告
诉 psql 这些信息，分别是 -d， -h，-p，和 -U。 如果有个参数不属于任何选项开关，那么它会被解
释成数据库名（或者是用户名－如果数据库名称也给出了。）。 不是所有这些选项都是必须的，缺省
的也可以。如果你省略主机名， psql 将通过 Unix 域套接字与本地主机的服务器相联。 缺省的端口
号是编译时确定的。因为数据库服务器使用同样的缺省值， 所以在大多数设置下，你可能不需要声明
端口号。缺省的用户名是你的 Unix 用户名，与数据库同名。 要注意的是你不能用任意用户名与任何
数据库相联。你的数据库管理员应该告诉你你的访问权限。 你可以通过设置几个环境变量
PGDATABASE， PGHOST，PGPORT 和 PGUSER 为对应的值的方法节约几次敲击。
如果因为任何原因而无法与数据库相联（例如，权限不够，服务器没有运行等）， psql 将返回一个
错误并退出。
ENTERING SQL COMMANDS 输入 SQL 命令
通常状况下，psql 提供一个带有 psql 正在与之联接的接数据库名的，后缀 =>的提示符。例如，
$psql testdb
Welcome to psql 7.4beta5, the PostgreSQL interactive terminal.
Type: \copyright for distribution terms
\h for help with SQL commands
\? for help on internal slash commands
\g or terminate with semicolon to execute query
\q to quit
testdb=>
用户可以在这个提示符下键入SQL 查询。 通常，输入的行将在命令终止分号出现时送到服务器。 一
行的终止并不结束命令！因此命令可以因清晰起见跨越好几行。如果命令发送出去而且没有错误， 命
令结果会显示在屏幕上。
当命令正在进行时，psql 同样还轮询由 LISTEN [listen(7)] 和 NOTIFY [notify(7)] 生成的异步通
知信号。
META-COMMANDS 元命令
你在 psql 里输入的任何以不带引号的反斜杠（'\'）开头的东西都是 psql 元命令，这些命令是由
psql 自己处理的。这些命令也是令 psql 可用于管理或书写脚本的原因。 元命令更常见的叫法是斜杠
或反斜杠命令。
一个 psql 命令的格式是反斜杠后面紧跟一个命令动词，然后是任意参数。 参数与命令动词和其他参
数以任意个空白字符间隔。
要在参数里面包含空白，你必须用单引号把它包围起来。 要在这样的参数里包含单引号，前面加一个
反斜杠。 任何包含在单引号里的东西会被进一步进行类 C 的替换，把 \n (new line),\t (tab),
\digits, \0digits, 和 \0xdigits （给出的十进制，八进制，或十六进制码的字符）替换掉。
如果一个不带引号的参数以冒号（:）开头， 它会被当作一个psql 变量，并且该变量的值会最终成为
真正的参数值。 （译注：类似 ecpg 和 pl/pgsql 的变量用法。）
用反引号 （"backticks" `） 包围的内容被当作一个命令行传入 shell。 该命令的输出（删除了结
尾的新行）被当作参数值。上面描述的逃逸（字符）序列在反引号里也生效。
有些命令以一个 SQL 标识的名称（如，一个表名）为参数。 这些参数遵循 SQL 语法关于双引号的规
则： 不带双引号的标识强制成小写， 而双引号保护字母不受大小写转换，并且允许在标识符中使用空
白。 在双引号中，成对的双引号在结果名字中分析成一个双引号。比如， FOO"BAR"BAZ 解析成
fooBARbaz，而 "A weird"" name" 变成 A weird" name。 name.
对参数的分析在碰到另一个不带引号的反斜杠时停止。 这里会认为是一个新的元命令的开始。特殊序
列 \\ （双反斜杠）标识参数的结尾并将继续分析后面的 SQL 命令（如果存在的话）。这样 SQL 和
psql命令可以自由的在一行里面混合。 但是在任何情况下，一条元命令的参数不能延续超过行尾。
下列元命令是已定义的：
\a
如果目前的表输出格式是不对齐的，切换成对齐的。 如果是对齐的，切换成不对齐。这条命
令是为了向后兼容。参阅\pset 获取一个通用的解决方法。
\cd [directory]
把当前工作目录改变到 directory。 没有参数是则改变到当前用户的家目录。
Tip: 提示: 要打印出你的当前工作目录，使用\!pwd.
\C [title ]
把正在打印的表的标题设置为一个查询的结果或者取消这样的设置。 这条命令等效于 \pset
titletitle. （这条命令的名称源于 "caption"，因为以前只是用于在一个 HTML 表里面设置
标题。）
\connect (or\c) [dbname [username ] ]
与一个新的数据库建立一个联接，使用/不用一个用户名。 前面的联接将关闭。如果 dbname
是 -，那么就假设是当前数据库名称。
如果省略 username，则假设是当前用户名。
作为一条特殊规则，不带任何参数运行\connect 将以缺省用户身份与缺省数据库连接（正如
你不带任何参数运行 psql 一样。）
如果联接失败（用户名错，访问拒绝等），那么将保留前面的联接--当且仅当在 psql 处于交
互模式下如此。 如果运行的是非交互的脚本，处理会马上停止，并返回一个错误。 选择这样
的区别是一方面为用户使用方便考虑，另一方面为保证脚本不会碰巧操作了错误的数据库的安
全机制考虑的。
\copytable
执行前端（客户端）拷贝。这是一个运行 SQL COPY 命令的操作， 不同的是 SQL COPY 是服
务器在读写指明的文件，而 psql 读写文件并作为本地的文件系统和服务器之间的路由取出或
写入数据。 这意味着文件访问性和权限都是本地用户的，而不是服务器的，因此不需要 SQL
超级用户权限。
这条命令的语法是模拟 SQL COPY 命令的。（参考它的描述获取细节。） 要注意的是由此而
来，有一些特殊的分析规则应用于\copy 命令。 尤其是变量替换规则和反斜杠代换规则不起作
用。
Tip: 提示: 此操作不象 SQL COPY 命令这样高效， 因为所有数据必须通过客户端/服务器联
接。对于大数据量的操作，另一种方法更可行。
Note: 注意: 注意在客户端和服务器拷贝时对 stdin 和 stdout 的解释的区别：在前端拷贝
时，这些总是指 psql的输入和输出流。在服务器拷贝时 stdin 来自 COPY 本身的标准输入（
比如，一个带有 -f 选项的脚本）， 而 stdout 指的是查询输出流（参阅下面的\o 元命
令）。
\copyright
显示 PostgreSQL 的版权和版本信息。
\d [pattern ]
对于每个匹配pattern的关系（表，视图，索引或者序列）， 显示所有列，它们的类型，和任
何特殊属性，象NOT NULL或缺省等－－只要存在。 如果实际上这个关系是一个表，任何已定义
的索引，主键，唯一约束相关的索引，规则，约束，和触发器也同样显示出来， 如果关系是一
个视图，还显示视图的定义。 （"匹配模式"在下面定义。）
从\d+ 来的命令也是一样的，只不过还显示与表的列关联的注解。
Note: 注意: 如果如果不带任何pattern调用\d ， 等效于\dtvs，将显示一个所有表，视图和
序列的列表。 这完全是出于方便的考虑。
\da [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 ]
列出所有可用函数，以及它们的参数和返回的数据类型。如果声明了 pattern，那么只显示匹
配（正则表达式）的函数。如果使用了\df+ 的形式，每个函数的附加信息，包括语言和描述也
会显示出来。
Note: 注意: 为了减少混乱，\df 并不显示数据类型的 I/O 函数。 这样是通过忽略那些接受
或者返回类型 cstring 的函数实现的。
\distvS [pattern ]
这不是一个实际上的命令名称：字母 i，s，t，v，S 分别代表索引（index）， 序列
（sequence），表（table），视图（view）和系统表（system table）。 你可以以任意顺序
声明任意或者所有这些字母获得这些对象的一个列表。 字幕 S 把列表限制于系统对象；如果
没有 S，则只显示非系统对象。 如果在命令名上附加了 +，那么还会列出和每个对象相关联的
描述，如果有的话。
如果声明了 pattern，那么只列出匹配模式的对象。
\dl 这是\lo_list 的别名，显示一个大对象的列表。
\dn [pattern ]
列出所有可用模式（名字空间）。如果声明了 pattern （一个正则表达式），那么只列出匹
配模式的模式名。
\do [pattern ]
列出所有可用操作符，以及它们的操作数和返回的数据类型。 如果声明了 pattern，那么只
显示匹配模式的操作符。
\dp [pattern ]
生成一列可用的表和它们相关的权限。 如果声明了 pattern， 那么只列出名字可以匹配模式
的表。
命令grant(7) 和revoke(7) 用于设置访问权限。参阅grant(7) 获取更多信息。
\dT [pattern ]
列出所有数据类型或只显示那些匹配 pattern的。这条命令的\dT+ 形式显示更多信息。
\du [pattern ]
列出所有已配置用户或者只列出那些匹配 pattern 的用户。
\edit (or\e) [filename ]
如果声明了 filename， 则编辑此文件并且在编辑器退出后将其内容拷贝回查询缓 冲区。 如
果没有给出参数，则把当前查询缓冲区内容拷贝到一个临时文件然后以相 同方式编辑。
然后根据一般的psql规则重新分析查询缓冲区， 这时整个缓冲区当作一个单行。 （因此你无
法用这个方法制作“脚本”，用\i 做脚本。） 这还意味着 如果该查询以分号结尾（或者包含分
号），它就会马上被执行。否则它只是在查询 缓冲区里等待。
Tip: 提示: psql 搜索环境变量 PSQL_EDITOR，EDITOR 和 VISUAL（以此顺序）查找要用到
哪个编辑器。如果上面的都没有设置，使用/bin/vi。
\echotext [ ... ]
向标准输出打印参数，用一个空格分隔并且最后跟着一个新行。 这个特性在显示脚本的输出
时会有用。例如：
=>\echo `date`
Tue Oct 26 21:40:57 CEST 1999
果第一个参数是一个无引号的 -n，那么不会写出结尾的新行。
Tip: 提示: 如果你使用\o 命令重定向你的查询的输出，你可能会用\qecho 取代这条命令。
\encoding [encoding ]
设置客户端字符编码方式。不带参数时，这条命令显示当前的编码方式。
\f [string ]
为不对齐的查询输出设置域分隔符。缺省时是竖条（|）。 参阅\pset 获取设置输出选项的通
用方法。
\g [ {filename | |command } ]
把当前的查询输入缓冲区的内容发送给服务器并且把输出输出到可选的 filename 或者把输
出定向到一个独立的 Unix shell 执行 command。 单独一个\g 实际上等效于一个分号。一个
带有参数的\g 是"一次性"的\o 命令的代用品。
\help (or\h) [command ]
给出指定 SQL 命令的语法帮助。如果没有给出 command ，那么 psql 将列出可获得语法帮助
的所有命令。如果 command 是一个星号（"*"），则显示所有 SQL 命令的语法帮助。
Note: 注意: 为简化敲击，包含多个单字的命令不需要引用。因此键入\help alter table 是
正确的。
\H
打开 HTML 查询输出格式。如果 HTML 格式已经打开，则切换回缺省的对齐的文本格式。 这
个命令是为了兼容和方便，参阅\pset 获取设置其他输出选项的内容。
\ifilename
从文件filename中读取并把其内容当作从键盘输入的那样执行查询。
Note: 注意: 如果你想在屏幕上看到读入的行，你必须对所有行设置变量 ECHO 为 all。
\l (or\list)
列出服务器上所有数据库的名字和它们的所有者以及字符集编码。在命令名称后面加一个 "+"
还可以看到对数据库的描述。
\lo_exportloidfilename
从数据库里读取 OID 为 loid 的大对象并把她写到 filename里。 注意这个功能与服务器函
数 lo_export 有些微小的区别， lo_export 运行时带着运行数据库服务器的用户权限， 而且
是在服务器的文件系统上。
Tip: 提示: 使用\lo_list 查看大对象的 OID。 OID.
\lo_importfilename [comment ]
把文件存储为一个 PostgreSQL 大对象。可以带着一个该对象的注解选项。例如：
foo=>\lo_import '/home/peter/pictures/photo.xcf' 'a picture of me'
lo_import 152801
响应表明此大对象得到一个对象标识 152801，如果你还想访问该对象，就应该把这个对象标
识记住。 因此，我们建议总是给每个对象关联一个人类可读的注解。那样就可以用\lo_list
命令看到这些注解。
注意这条命令与服务器端的 lo_import 有一些区别，因为这条命令是本地用户在本地文件系
统上操作， 而不是以服务器用户在服务器文件系统上操作。
\lo_list
显示一个目前存储在该数据库里的所有 PostgreSQL 大对象和它们的所有者的列表。
\lo_unlinkloid
从数据库里删除OID为loid 的大对象。
Tip: 提示: 使用\lo_list 查找大对象的 OID。 OID.
\o [ {filename | |command} ]
把后面的查询结果保存到文件 filename 里或者把后面的查询结果定向到一个独立的 Unix
shell 执行 command。 如果没有声明参数，查询输出重置为标准输出。
"查询结果"包括所有表，命令响应和从数据库服务器来的提示， 同样还有各种各样查询数据库
的反斜杠命令的输出（如\d），但是没有错误信息。
Tip: 提示: 要用文本分散查询结果之间的输出，用\qecho。
\p
打印当前查询缓冲区到标准输出。
\psetparameter [value ]
这条命令设置影响查询结果表输出的选项。parameter 描述要设置的选项是哪一个。value
的语意也取决于它。
可调节的打印选项有：
format
设置输出格式为 unaligned，aligned，html， 或 latex之一。允许使用唯一的缩
写。（这也意味着一个字母就够了。）
"Unaligned" （不对齐）把一条记录的所有字段都输出到一行， 用当前有效的域分隔
符分隔。这主要用于生成那些要被其他程序读取的输出（tab分隔，逗号分隔）。
"Aligned" （对齐）模式是标准的，人类可读的，格式化好了的文本输出，也是缺省。
"HTML" 和 "LaTeX" 模式把表输出为可用于文档里的对应标记语言。它们还不是完整
的文档！ （可能对于 HTML 变化还不是太大，但是在 LaTeX 里，你必须有一个完整的
文档包装器。）
border
第二个参数必须是一个数字。通常，数字越大，表就有越宽的边界和越多的线， 但是
这个参数取决于实际的格式。在HTML模式里， 这个参数会直接翻译成border=...属
性，在其他的模式里， 只有值 0 （无边界），1 （内部分隔线）和 2 （表框架）有
意义。
expanded (or x)
在正常和扩展格式之间切换。当打开扩展格式时，所有的输出都是两列， 字段名称在
左，数据在右。 这个模式在数据无法放进通常的"水平"模式的屏幕时很有用。
所有四种输出模式都支持扩展格式。
null
第二个参数是一个字串，用以代表字段的值为 null 时的打印输出。 缺省是什么都不
打，这样很容易和类似一个空字串混淆。 因此，我们可能选择\pset null '(null)'。
fieldsep
声明在非对齐模式时的域分隔符。 这样我们就可以创建其他程序希望的tab或逗号分
隔的输出。要设置 tab 域分隔符， 键入\pset fieldsep ''。缺省域分隔符是 '|' （
一个竖条符号）。
footer
切换默认足标的显示 (x rows)。
recordsep
声明在非对齐模式时的记录分隔符。缺省是换行符。
tuples_only (或 t)
在完全显示和只显示记录之间切换。 完全显示将显示象列头，标题和各种脚注等信
息。 只显示记录模式将只显示实际的表数据。
title [text ]
为任何随后打印的表设置标题。 这个参数可以用于给你的输出一个描述性标记。 如
果不带参数，重置标题。
tableattr (or T) [text ]
允许你声明放在 HTML table 标记里的任何属性。例如，可以是 cellpadding 或
bgcolor。注意你可能不需要在这里声明 border ，因为已经在\pset border 里用过
了。
pager
控制查询和psql帮助输出的分页器。如果设置了环境变量 PAGER， 输出被定向到指定
程序，否则使用系统缺省（比如 more）。
如果关闭了分页器，则不使用它，如果打开了，程序只在需要的时候使用分页器，也
就是说， 输出是到终端，而且那个表很可能无法与屏幕匹配。 （psql 在决定何时分
页时不是很完美。）\pset pager 开关分页器。我们也可以把分页器设置为
always，导致我们在任何情况下都使用分页器。
可以在 "Examples 例子" 节看到这些不同格式输出的示例。
Tip: 提示: 有很多用于\pset 的快速命令。参阅 \a,\C,\H, \t,\T, 和\x。
Note: 注意: 无参数运行\pset 是错误的。 以后这样调用将显示当前打印选项状态。
\q
退出 psql 程序。
\qechotext [ ... ]
这条命令等效于\echo ，区别是所有输出将写入由\o 设置的输出通道。
\r
重置（清空）查询缓冲区。
\s [filename ]
将命令行历史打印出或是存放到 filename。 如果省略 filename， 历史将输出到标准输
出。这个选项只有在 psql 配置成使用 GNU 历史库后才生效。
Note: 注意: 在当前版本里，这个（ GNU 历史库）不再是必须的了， 实际上，在程序结束时
自动保存命令行历史。每次 psql 启动都会装载命令行历史。
\set [name [value [ ... ]]]
设置内部变量 name 为 value 或着如果给出了多于一个值， 设置为所有这些值的联接结
果。如果没有给出第二个参数，只设变量不设值。要重置一个变量，使用\unset 命令。
有效的变量名可以包含字符，数字和下划线。 参阅下面的 "Variables 变量" 获取细节。
尽管你可以设置任何变量为任意值， psql对一些变量特殊对待。它们在关于变量的节里面有
文档。
Note: 注意: 这条命令是完全和 SQL 命令 SET [set(7)] 不一样的。
\t
切换输出的列/字段名的信息头和行记数脚注。 这条命令等效于\pset tuples_only，提供主
要为了方便。
\Ttable_options
允许你在使用HTML输出模式时声明放在 table 标记里的属性。 这条命令等效于\pset
tableattr table_options。
\timing
切换每个 SQL 语句使用的时间，单位是毫秒。
\w {filename ||command}
将当前查询缓冲区输出到文件 filename 或者定向到 Unix 命令 command。
\x
切换扩展行格式。等效于\pset expanded。
\z [pattern ]
生成一个带有访问权限列表的数据库中所有表的列表。 如果给出任何pattern，则被当成一个
规则表达式， 只显示匹配的表。
命令grant(7) 和revoke(7) 用于设置访问权限。 参阅grant(7) 获取更多信息。
这是\dp（"显示权限"）的别名。
\! [command ]
返回到一个独立的 Unix shell 或者执行 Unix 命令 command。 参数不会被进一步解
释，shell 将看到全部参数。
\?
获得关于反斜杠命令的帮助信息。
各种\d 命令都接受一个 pattern 参数，声明要显示的对象名字。* 表示"任何字符序列"， 而 ? 表
示"任何单个字符"。（这个表示法和 Unix 的 shell 文件名模式兼容。） 高级用户也可以使用正则表
达式表示法，比如字符表，[0-9] 这样的东西来匹配"任意数字"。 要让任何这些模式匹配字符可以安
字面方式解析，那就应该用双引号包围它们。
一个包含（无引号的）句点的模式会被解析承一个模式名的模式后面跟着一个对象名的模式。 比
如，\dt foo*.bar* 显示所有以foo 开头的模式里的以 bar 开头的表名字。 如果没有出现句点，那么
这个模式只匹配在当前模式搜索路径中可见的对象。
如果完全省略 pattern 参数， 那么\d 命令显示所有在当前模式搜索路径中可见的对象。 要查阅在
数据库中的所有对象，使用模式 *.*。
ADVANCED FEATURES 高级特性
VARIABLES 变量
psql 提供类似通常 Unix 命令 shell 那样的变量替换特性。 变量只是简单的名称/数值对， 这里的
值可以是任何长度的任何值。要设置一个变量，使用 psql 元命令 \set：
testdb=>\set foo bar
把变量"foo" 设置为值 "bar"。 要检索变量的内容，在变量名前面放上冒号然后把它用在任意斜杠命
令里：
testdb=>\echo :foo
bar
Note: 注意: \set 的参数服从和其他命令一样的替换规则。 因此你可以构造有趣的引
用，象\set :foo 'something' 这样， 获得分别象Perl或 PHP那样有名的"软连接（soft
links）"或"变量 变量"。 不幸的是（或者 万幸的？），用这些构造不能做任何有用的事
情。另一方面，\set bar :foo 是一个非常有效的拷贝变量的方法。
如果你不带第二个参数调用\set， 那么只是设置这个变量而没有值。 要重置（或删除）一个变
量，使用命令\unset。
psql 的内部变量可以包括任意顺序， 任意数量的字母，数字和下划线。 有一些常用变量被 psql 另
眼相待。它们是一些选项设置， 这些选项在运行时可以通过改变变量的值或者改变一些应用的表现状
态而改变。 尽管你可以把这些变量用于其他用途，但是我们不鼓励这么做，因为程序的特性可能会很
快变得非常奇怪。 通常，所有特殊对待的变量都是由大写字母组成（可能还有数字和下划线）。 为了
保证和未来的最大限度的兼容性，请避免使用这样的变量。 下面是一个所有特殊对待的变量列表。
AUTOCOMMIT
如果是 on（缺省），那么每个 SQL 命令都在成功完成后自动提交。 要推迟这种模式下的提
交，你必须输入一个 BEGIN 或者 START TRANSACTION SQL 命令。 如果是 off 或者未设
置，SQL 命令不会提交，知道你明确地发出 COMMIT 或者 END。 关闭自动提交的模式是通过为
你明确发出一个 BEGIN 实现的， 它是放在任何尚未在一个事务块中并且自己不是 BEGIN 或者
其它事务控制命令的前面。
Note: 注意: 在关闭自动提交的模式下，你必须明确放弃任何失败的事务，方法是执行 ABORT
或者 ROLLBACK。 还要注意如果你不提交就退出会话，你的工作会丢失。
Note: 注意: 自动提交打开方式是 PostgreSQL 传统的行为， 但是关闭自动提交更接近 SQL
规范。如果你喜欢关闭自动提交，你应该在你的.psqlrc 文件里设置它。
DBNAME
你正在联接着的数据库名称。 每次你与一个数据库联结都会设置这个值（包括程序启
动），但是可以删除。
ECHO
如果置为 all， 输入的或者来自一个脚本的所有行在分析或执行前都写到标准输出。 要在程
序启动时声明这些，使用 -a如果设置为 queries， psql 只是在查询发送给服务器之前打印出
来。 实现这个功能的命令行选项是 -e。
ECHO_HIDDEN
当设置了这个变量并且一个反斜杠命令查询数据库时，首先显示查询。 这样你可以学习
PostgreSQL 内部的东西并且在你自己的程序里提供类似功能。如果你设置该变量的值为
"noexec"，查询只是显示出来但是实际上不发送到服务器和执行。
ENCODING
当前的客户端字符集编码。
HISTCONTROL
如果这个变量设置为 ignorespace， 以空格开始的行将不会进入历史列表。 如果设置为变量
ignoredups， 与以前历史记录里匹配的行也不会进入历史记录。值 ignoreboth是上面两个的
结合。 如果删除此变量或者其值为任何与上面的值不同的东西， 所有交互模式读入的行都被
保存入历史列表。
Note: 注意: 这个特性是无耻地从bash 里剽窃来的。
HISTSIZE
存在命令历史里的命令的个数。缺省值是 500。
Note: 注意: 这个特性是无耻地从bash 里剽窃来的。
HOST
当前你正联接的数据库服务器主机。 这是在每次你与数据库联接时（包括程序启动）设置
的，但是可以删除。
IGNOREEOF
如果删除此变量，向一个交互的 psql会话发送一个 EOF （通常是Control+D）将终止应
用。如果设置为一个数字值，那么在应用终止前该数值的 EOF 字符将被忽略。 如果设置了此
变量但是没有数字值，缺省是 10。
Note: 注意: 这个特性是无耻地从bash 里剽窃来的。
LASTOID
最后影响的oid值，即为从一条 INSERT 或 lo_insert 命令返回的值。 此变量只保证在下一
条 SQL 命令的结果显示之前有效。
ON_ERROR_STOP
缺省时，如果非交互的脚本碰到一个错误，象一条错误的 SQL 命令或者内部元命令，处理会
继续进行。 这是 psql 的传统特性， 但是有时候我们不太希望这样。如果设置了这个变
量，脚本处理将马上停止。 如果该脚本是从另外一个脚本调用的，那个脚本也会按同样的方式
停止。 如果最外层的脚本不是从一次交互的 psql 会话中调用的而是用 -f 选项调用
的，psql 将返回错误代码 3，以示这个情况与致命错误条件的区别（错误代码 1）。
PORT
当前你正在联接的数据库服务器的端口。 这是在每次你与数据库联接时（包括程序启动）设
置的，但是可以删除。
PROMPT1
PROMPT2
PROMPT3
这些指明psql 显示的提示符看上去象什么。 参阅下面的 "Prompting 提示符"。
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` '\''
观察正确数量的反斜杠（6）！你可以这样解释它：在 psql 分析完这行后，它把 sed -e
"s/'/\\\'/g" < my_file.txt 传递给shell。 shell 将对双引号里的东西做其处理然后用参数 -e 和
s/'/\\'/g 执行 sed。当 sed分析这些时， 它将把双反斜杠替换为单个反斜杠然后进行替换。 可能
有时候你认为所有 Unix 命令使用同一个逃逸字符是个好事。 但具有讽刺意味的事实是你可能不得不
逃逸所有反斜杠，因为 SQL 文本常量同样也惨遭这种解释。 这种情况下你可能最好在外部准备文件。
因为冒号也可以合法的出现在 SQL 命令里，便有下面规则的应用： 如果没有设置变量，字符序列
"冒号+名称" 不会被改变。 在任何情况下你都可以用反斜杠逃逸冒号以保护它免于被解释。 （变量的
冒号语法是 SQL 用于嵌入查询语言的标准，如 ECPG。用于数组片段和类型转换的冒号语法是
PostgreSQL 扩展，因此有冲突。）
PROMPTING 提示符
psql 使用的提示符可以根据你的喜好客户化。三个变量 PROMPT1，PROMPT2，和 PROMPT3 包含描述提
示符的外观的字串和特殊逃逸序列。Prompt 1 是 psql 请求一个新命令时的使用的正常提示符。
Prompt 2 是在一个命令输入期待更多输入时（因为查询没有用一个分号结束或者引号没有关闭）显示
的提示符。 Prompt 3 在你运行一个 SQL COPY 命令和等待你在终端上键入记录时使用。
相应的提示符变量的值是按字面打印的，除非碰到一个百分号（%）。这时某些其他的文本被替换，
替换为何物取决于下一个字符。已定义的替换是：
%M
数据库服务器主机名全名（带着域名），如果联接是通过 Unix 域套接字进行的就是
[local]， 或者如果 Unix 域套接字不是编译的缺省位置，就是 [local:/dir/name]。
%m
数据库服务器的主机名删去第一个点后面的部分剩下的东西。 或者如果联接是通过 Unix 域
套接字，就是 [local]。
%>
数据库服务器正在侦听的端口号。
%n
数据库会话的用户名。 （这个值的扩展可能在一个数据库会话过程中因为SET SESSION
AUTHORIZATION 命令而改变。）
%/ 当前数据库名称。
%~ 类似 %/， 但如果数据库是你的缺省数据库输出是"~" （波浪线（tilde））。
%#
如果会话用户是数据库超级用户，使用 "#"，否则用">"。 （这个值的扩展可能在一个数据库
会话过程中因为SET SESSION AUTHORIZATION 命令而改变。）
%R
对于 prompt 1 通常是 =，但是如果是单行模式则是 ^，而如果会话与数据库断开（如果
%x
事务状态：如果不在事务块里，是一个空字串，如果在事务块里，是 *， 如果在一个失败的
事务块里是 !，或者无法判断事务状态时为 ? （比如，因为没有连接）。
%digits
如果 digits 以 0x 开头， 那么其余字符被解释成一个十六进制数字并且替换为对应（十六
进制码）的字符。 如果第一个数字是 0，该字符被解释成一个八进制数字并且替换为对应的（
八进制码）的字符。 否则认为是一个十进制数字。
%:name:
psql变量name的值。参阅 "Variables 变量" 节获取细节。
%`command`
command的输出， 类似于通常的反引号（back-tick）替换。
要在提示符里插入百分号，键入%%。缺省提示符等效于 '%/%R%# ' 用于 prompts 1 和 2，以及'>> '
用于 prompt 3。
Note: 注意: 这个特性是无耻地从tcsh 里剽窃来的。
COMMAND-LINE EDITING 命令行编辑
psql 为了编辑和检索命令行的方便支持 readline 和历史库。 命令历史存放在你的家目录的一个叫
.psql_history 的文件里， 并且当 psql 启动的时候会装载进来。 还支持 Tab 补齐，尽管该补齐逻
辑并不是一个 SQL 分析器必备的。 如果因某些原因你不喜欢 tab 补齐，你可以把下面几行放在你的
家目录的一个叫.inputrc 的文件里关闭这个特性：
$if psql
set disable-completion on
$endif
（这不是 psql 的特性， 是Readline 的。参考它的文档获取更多细节。）
ENVIRONMENT 环境
HOME
初始化文件（.psqlrc）和命令历史文件（.psql_history）的目录。
PAGER
如果查询结果在一页里放不下，那么它们被定向到这个命令。 典型的值是 more 或者 less。
缺省的是平台相关的。我们可以用\pset 命令关闭分页器。
PGDATABASE
缺省连接的数据库
PGHOST
PGPORT
PGUSER
缺省连接参数
PSQL_EDITOR
EDITOR
VISUAL \e 命令使用的编辑器。这些变量是按照上面的顺序检查的；设置最早的最先使用。
SHELL \! 命令执行的命令。
TMPDIR
存储临时文件的目录。缺省是/tmp。
FILES
•
在启动之前，psql 视图读取并 执行来自文件$HOME/.psqlrc 的命令。 它将用于设置客户端或者服
务器的风格（使用\set 和SET 命令）。
•
命令行历史存储在$HOME/.psql_history。
NOTES 注意
•
一些 psql的早期版本允许一个单字母的反斜杠命令（元命令）的第一个参数直接跟在命令后面，
而不用空白间隔。出于兼容性原因，这个特性仍然在某些程度上被支持，但是我不准备在这里详细解
释，因为我不鼓励这样使用。 不过如果你收到莫名其妙的信息，想想这个用法。例如
testdb=>\foo
Field separator is "oo".
可能不是你想要的东西。
• psql 只能与同版本的服务器平稳地工作。 这不意味着其他组合会完全失败，但是可能有微小的或者
不那么微小的问题。 如果服务器的版本不同，反斜杠命令是特别容易失效的。
EXAMPLES 例子
第一个例子演示了如何把一个查询分成多个行进行输入。注意提示符的变化：
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
译者
Postgresql 中文网站 何伟平 <laser@pgsqldb.org>