PostgreSQL 8.2.3 中文文档
后退快退快进前进

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

把所有发送给服务器的查询同时也回显到标准输出。等效于把变量 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

-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 和元命令,执行的顺序对不熟练的用户而言并不总是清晰的。

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

用法

连接一个数据库

psql 是一个普通的 PostgreSQL 客户端应用。为了与一个数据库连接,你需要知道目标数据库、服务器的主机名和端口号、以及你希望以哪个用户的身份进行连接等信息。可以通过命令行参数 -d, -h, -p, -U 告诉 psql 这些信息。如果某个参数不属于任何选项,那么它会被解释成数据库名或者是用户名(如果数据库名称已经给出了)。不是所有这些选项都是必须的,有的缺省就存在。如果你省略主机名,psql 将通过 Unix 域套接字与本地主机的服务器相联,或者在没有 unix 域套接字的机器上,通过 TCP/IP 与 localhost 连接。缺省的端口号是编译时确定的。因为数据库服务器使用同样的缺省值,所以在大多数设置下,你可能不需要声明端口号。缺省的用户名是你的 Unix 用户名,与数据库同名。要注意的是你不能用任意用户名与任何数据库相联。你的数据库管理员应该告诉你有哪些访问权限。

如果缺省不太正确,那么你可以通过设置几个环境变量 PGDATABASE, PGHOST, PGPORT and/or PGUSER 的方法节约几次敲击。其它环境变量的信息,参阅节29.12。另外,用一个 ~/.pgpass 文件来避免输入密码也是很方便的。参阅节29.13获取更多信息。

如果因为任何原因而无法与数据库相联(权限不够、服务器没有运行等),psql 将返回一个错误并退出。

输入 SQL 命令

通常状况下,psql 提供一个带有正在与之连接的接数据库名的,后缀 => 的提示符。例如,

$ psql testdb
Welcome to psql 8.2.3, 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 同样还轮询由 LISTENNOTIFY 生成的异步通知信号。

元命令

你在 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(或 \c) [ dbname [ username ] [ host ] [ port ] ]

与一个新的数据库建立一个连接,使用/不用一个用户名。前面的连接将关闭。如果 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 的标准输入或者输出读/写,可以使用 pstdinpstdout 。这个选项用于把和 SQL 脚本嵌在一起的文件填充表很有用。

【提示】 此操作不像 SQL COPY 命令这样高效,因为所有数据必须通过客户端/服务器连接。对于大数据量的操作,SQL 命令的方法更可行。

\copyright

显示 PostgreSQL 的版权和版本信息。

\d [ pattern ]
\d+ [ pattern ]

对于每个匹配 pattern 的关系(表、视图、索引、序列),显示所有列、它们的类型、表空间(如果不是缺省的)和任何特殊属性(诸如 NOT NULL 或缺省等,只要存在)。唯一约束相关的索引、规则、约束、触发器也同样显示出来。如果关系是一个视图,还显示视图的定义。"匹配模式"在下面定义。

\d+ 来的命令也是一样的,只不过显示更多信息:任何与表的列关联的注释也都会显示,还有就是表中出现的 OID 。

【注意】如果如果不带任何 pattern 调用 \d ,那么等效于 \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 命令生成对象的描述。

\dD [ pattern ]

列出所有可用域。如果声明了 pattern ,那么只显示匹配的域。

\df [ pattern ]
\df+ [ pattern ]

列出所有可用函数,以及它们的参数和返回的数据类型。如果声明了 pattern ,那么只显示匹配(正则表达式)的函数。如果使用了 \df+ 的形式,每个函数的附加信息,包括语言和描述也会显示出来。

【注意】要查找接受或者返回特定类型的函数,使用你的分页器搜索功能来滚动 \df 的输出。

为了减少混乱,\df 并不显示数据类型的输入输出函数。这样是通过忽略那些接受或者返回类型 cstring 的函数实现的。

\dg [ pattern ]

列出所有数据库角色。如果声明了 pattern ,那么只显示那些匹配模式的名字。这条命令实际上等于 \du

\distvS [ pattern ]

这不是实际的命令名称:字母 i, s, t, v, S 分别代表索引(index)、序列(sequence)、表(table)、视图(view)、系统表(system table)。。你可以以任意顺序声明任意或者所有这些字母获得这些对象的一个列表。字母 S 把列表限制于系统对象;如果没有 S ,则只显示非系统对象。如果在命令名上附加了 + ,那么还会列出和每个对象相关联的描述,如果有的话。

如果声明了 pattern ,那么只列出匹配模式的对象。

\dl

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

\dn [ pattern ]
\dn+ [ pattern ]

列出所有可用模式(名字空间)。如果声明了 pattern ,那么只列出匹配模式的模式名。不显示非本地的临时模式。如果在命令名上附加了 + ,那么每个对象都和与之相关的权限和注释一起列出(如果有的话)。

\do [ pattern ]

列出所有可用操作符,以及它们的操作数和返回的数据类型。如果声明了 pattern ,那么只显示匹配模式的操作符。

\dp [ pattern ]

生成一列可用的表和它们相关的权限。如果声明了 pattern ,那么只列出名字匹配模式的表。

GRANTREVOKE 命令用于设置访问权限。

\dT [ pattern ]
\dT+ [ pattern ]

列出所有数据类型或只显示那些匹配 pattern 的。这条命令的 \dT+ 形式显示更多信息。

\du [ pattern ]

列出所有已配置角色或者只列出那些匹配 pattern 的角色。

\edit(或 \e) [ filename ]

如果声明了 filename ,则编辑此文件并且在编辑器退出后将其内容拷贝回查询缓冲区。如果没有给出此参数,则把当前查询缓冲区内容拷贝到一个临时文件然后以相同方式编辑。

然后根据一般的 psql 规则重新分析查询缓冲区,这时整个缓冲区当作一个单行,因此你无法用这个方法制作脚本(用 \i)。这还意味着如果该查询以分号结尾(或者包含分号),它就会马上被执行。否则它只是在查询缓冲区里等待。

【提示】 psqlPSQL_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(或 \h) [ command ]

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

【注意】为简化击键,包含多个单字的命令不需要引起。因此键入 \help alter table 是正确的。

\H

打开 HTML 查询输出格式。如果 HTML 格式已经打开,则切换回缺省的对齐的文本格式。这个命令是为了兼容和方便,参阅 \pset 获取设置其它输出选项的内容。

\i filename

从文件 filename 中读取并把其内容当作从键盘输入的那样执行查询。

【注意】如果你想在屏幕上看到读入的行,就必须对所有行将变量 ECHO 设置为 all

\l(或 \list)
\l+(或 \list+)

列出服务器上所有数据库的名字和它们的所有者以及字符集编码。在命令名称后面加一个 + 还可以看到对数据库的描述。

\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

响应表明此大对象得到一个对象标识 152801 ,如果你还想访问该对象,就应该把这个对象标识记住。因此,建议总是给每个对象关联一个人类可读的注解。那样就可以用 \lo_list 命令看到这些注解。

注意这条命令与服务器端的 lo_import 有一些区别,因为这条命令是本地用户在本地文件系统上操作,而不是以服务器用户在服务器文件系统上操作。

\lo_list

显示一个目前存储在该数据库里的所有 PostgreSQL 大对象和它们的所有者的列表。

\lo_unlink loid

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

【提示】使用 \lo_list 查找大对象的 OID 。

\o [ {filename | |command} ]

把后面的查询结果保存到文件 filename 里或者把后面的查询结果重定向到一个独立执行 command 的 Unix shell 。如果没有声明参数,查询输出将被重置为标准输出。

"查询结果"包括所有表,命令响应和从数据库服务器来的提示,同样还有各种各样查询数据库的反斜杠命令的输出(如 \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(或 x)

在正常和扩展格式之间切换。当打开扩展格式时,查询结果用两列显示,字段名称在左、数据在右。这个模式在数据无法放进通常的"水平"模式的屏幕时很有用。

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

null

第二个参数是一个字符串,用以代表字段的值为 null 时的打印输出。缺省是什么都不打,这样很容易和类似一个空字符串混淆。因此,可能选择 \pset null '(null)'

fieldsep

声明在非对齐模式时的域分隔符。这样就可以创建其它程序希望的制表符或逗号分隔的输出。要设置制表符域分隔符,键入 \pset fieldsep '\t' 。缺省域分隔符是 '|' (竖条符)。

footer

切换缺省脚注(x rows)

numericlocale

切换分隔小数点左边的数值的区域相关的分组符号。它还打开区域相关的小数点。

recordsep

声明在非对齐模式时的记录分隔符。缺省是换行符。

tuples_only(或 t)

在完全显示和只显示记录之间切换。完全显示将显示像列头、标题、各种脚注等信息。在这个模式下,只显示记录模式将只显示实际的表数据。

title [ text ]

为任何随后打印的表设置标题。这个参数可以用于给你的输出一个描述性标记。如果不带参数,重置标题。

tableattr(或 T) [ text ]

允许你声明放在 HTML table 标签里的任何属性(例如 cellpaddingbgcolor)。注意,你可能不需要在这里声明 border ,因为已经在 \pset border 里用过了。

pager

控制查询和 psql 帮助输出的分页器。如果设置了环境变量 PAGER ,那么输出被定向到指定程序,否则使用系统缺省(比如 more)。

如果关闭了分页器,则不使用它,如果打开了,程序只在需要的时候使用分页器,也就是说,输出是到终端,而且那个表很可能无法与屏幕匹配。psql 在决定何时分页时不是很完美。\pset pager 开关分页器。也可以把分页器设置为 always ,导致在任何情况下都使用分页器。

可以在例子小节看到这些不同格式输出的示例。

【提示】有很多用于 \pset 的快速命令。参阅 \a, \C, \H, \t, \T, \x

【注意】无参数运行 \pset 是错误的。以后这样调用将显示当前打印选项状态。

\q

退出 psql 程序。

\qecho text [ ... ]

这条命令等效于 \echo ,区别是所有输出将写入由 \o 设置的输出通道。

\r

重置(清空)查询缓冲区

\s [ filename ]

将命令行历史打印出或是存放到 filename 。如果省略则输出到标准输出。这个选项只有在 psql 配置成使用 GNU Readline 库后才生效。

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

设置内部变量 namevalue 或者如果给出了多于一个值,设置为所有这些值的连接结果。如果没有给出第二个参数,那么只设变量不设值。要重置一个变量,使用 \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 ,则被当成一个正则表达式,只显示匹配的表、视图、序列。

GRANTREVOKE 命令用于设置访问权限。

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

\! [ command ]

返回到一个单独的 Unix shell 或者执行 Unix 命令 command 。参数不会被进一步解释,shell 将看到全部参数。

\?

获得关于反斜杠命令的帮助信息。

匹配模式

各种 \d 命令都接受一个 pattern 参数,声明要显示的对象名字。最简单的情况下 pattern 正好等于对象的名字。pattern 中的字符通常会被自动转换成小写,就像 SQL 名字一样。例如 \dt FOO 将显示名为 foo 的表。与在 SQL 名字中相同的是双引号界定的 pattern 将保持原样(不做大小写转换)。如果需要在双引号界定的 pattern 中使用双引号字符,你可以写两个并列的双引号,这与 SQL 的引号规则相同。例如,\dt "FOO""BAR" 将会显示名为 FOO"BAR 的表,但是不会显示 foo"bar 。与一般的 SQL 名字规则不同的是,你可以仅用双引号界定名字的一部分,例如 \dt FOO"FOO"BAR 将显示名为 fooFOObar 的表。

pattern 中的 * 表示"任何字符序列",包括"没有字符",而 ? 表示"任何单个字符"。这个表示法和 Unix 的 shell 文件名模式兼容。比如 \dt int* 显示所有名字以 int 开头的表。但是在双引号内部的 *? 不具有匹配的功能,它们只代表自身。

包含点(.)的 pattern 将被解释成模式名 pattern 后面跟一个对象名 pattern 。例如 \dt foo*.bar* 显示所有名字以 foo 开头的模式中的所有名字以 bar 开头的表。如果没有出现句点,那么这个模式只匹配在当前模式搜索路径中可见的对象。同样,在双引号内的点没有这个含义,它只代表其自身。

还可以使用正则表达式语法,比如字符类等等。例如用 [0-9] 匹配所有数字。除 . 之外的所有正则表达式中的特殊字符都按照节9.7.3里面描述的规则进行解析,此外,* 将被理解成 .* ,同时 ? 将被理解成 . 。这样一来,你就可以用 ? 代替 . 、用 (R+|) for R* 、用 (R|) 代替 R? 。需要注意的是模式必须匹配整个名称,而不是一般理解的匹配一部分即可。如果你只想匹配一部分,可以在 pattern 的开头和结尾使用 * 。还需要注意的是在双引号内部的所有正则表达式特殊字符都将失去其特殊含义。同样,在对操作符(也就是作为 \do 参数的时候)进行匹配时正则表达式特殊字符也将失去其特殊含义。

如果完全省略 pattern 参数,那么 \d 命令显示所有在当前模式搜索路径中可见的对象(等价于使用 * 匹配模式)。要查阅在数据库中的所有对象,使用 *.* 模式。

高级特性

变量

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 命令都在成功完成后自动提交。要推迟这种模式下的提交,你必须输入一个 BEGINSTART TRANSACTION 命令。如果是 off 或者未设置,SQL 命令不会提交,直到你明确地发出 COMMITEND 。关闭自动提交的模式是通过为你明确发出一个 BEGIN 实现的,它是放在任何尚未在一个事务块中并且自己不是 BEGIN 或其它事务控制命令也不是那些不能在事务块里执行的命令(比如 VACUUM)的前面。

【注意】在关闭自动提交的模式下,你必须明确放弃任何失败的事务,方法是执行 ABORTROLLBACK 。还要注意,如果你不提交就退出会话,所做的工作会丢失。

【注意】打开自动提交是 PostgreSQL 的传统行为,但是关闭自动提交更接近 SQL 规范。你可以在系统范围的 psqlrc~/.psqlrc 文件中关闭自动提交。

DBNAME

正在连接着的数据库名称。每次与一个数据库联结都会设置这个值(包括程序启动),但是可以删除。

ECHO

如果设为 all ,那么来自键盘或脚本的所有输入行在分析或执行前都回显到标准输出。使用 -a 选项声明在程序启动时就默认这样做。如果设置为 queries ,那么 psql 只是在查询发送给服务器之前打印出来。实现这个功能的命令行选项是 -e

ECHO_HIDDEN

当设置了这个变量并且一个反斜杠命令查询数据库时,首先显示查询。这样你可以学习 PostgreSQL 内部的东西并且在你自己的程序里提供类似功能。要在程序一起动的时候就启用这个行为,可以使用 -E 选项。如果你设置该变量的值为 noexec ,那么查询只是显示出来但是实际上不发送到服务器去执行。

ENCODING

当前的客户端字符集编码

FETCH_COUNT

如果该变量的值大于零,SELECT 查询的结果将按此值分批返回和显示,而不是缺省的一次取出和显示所有结果。这样就可以无论结果集有多大都只使用很少量的内存。一般来说,设为 100 到 1000 之间的值比较合理。需要注意的是,使用此特性后,一个查询可能在显示了一部分结果之后遭遇失败。

【提示】虽然该特性可以用于所有输出格式。但是并不适合在缺省的 aligned 格式上使用这个特性,因为每一批结果会被单独的分开格式化,这样一来每一批输出结果的列宽就可能各不相等。不过对于其他格式这个特性工作的很好。

HISTCONTROL

如果将这个变量设为 ignorespace ,那么以空格开始的行将不会进入历史列表。如果设置为 ignoredups ,那么与以前历史记录里匹配的行也不会进入历史记录。值 ignoreboth 是上面两个的结合。如果删除此变量或者其值为任何与上面的值不同的东西,所有交互模式读入的行都被保存入历史列表。

【注意】这个特性是从 Bash 偷学来的。

HISTFILE

此文件将用于存储历史列表。缺省值是 ~/.psql_history 。比如,在 ~/.psqlrc 里使用:

\set HISTFILE ~/.psql_history- :DBNAME

将使得 psql 为每个数据库维护一个独立的历史。

【注意】这个特性是从 Bash 偷学来的。

HISTSIZE

保存在命令历史里的命令的个数。缺省值是 500 。

【注意】这个特性是从 Bash 偷学来的。

HOST

当前你正连接的数据库服务器主机。这是在每次你与数据库连接时(包括程序启动)设置的,但是可以删除。

IGNOREEOF

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

【注意】这个特性是从 Bash 偷学来的。

LASTOID

最后影响的 oid 值,即为从一条 INSERTlo_insert 命令返回的值。此变量只保证在下一条 SQL 命令的结果显示之前有效。

ON_ERROR_ROLLBACK

如果是 on ,那么当一个事务块里的语句产生错误的时候,这个错误将被忽略而事务将继续。如果是 interactive ,那么这样的错误只是在交互的会话里忽略,而不是在从读取脚本文件的时候。如果是 off(缺省),事务块里一个语句生成的错误将会回滚整个事务。on_error_rollback-on 的模式是通过在一个事务块的每个命令前为你隐含地发出一个 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 代换

一个附加的 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 包含描述提示符的外观的字符串和特殊逃逸序列。PROMPT1psql 请求一个新命令时使用的正常提示符。PROMPT2 是在一个命令输入期待更多输入时(因为查询没有用一个分号结束或者引号没有关闭)显示的提示符。PROMPT3 在你运行一个 SQL COPY 命令和等待你在终端上键入记录时使用。

相应的提示符变量的值是按字面打印的,除非碰到一个百分号(%)。这时某些其它的文本被替换,替换为何物取决于下一个字符。已定义的替换是:

%M

数据库服务器全程主机名(带着域名),如果连接是通过 Unix 域套接字进行的就是 [local] ,或者如果 Unix 域套接字不是编译的缺省位置,就是 [local:/dir/name]

%m

数据库服务器的主机名删去第一个点后面的部分剩下的东西。或者如果是通过 Unix 域套接字连接,就是 [local]

%>

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

%n

数据库会话的用户名。这个值的扩展可能在一个数据库会话过程中因为 SET SESSION AUTHORIZATION 命令而改变。

%/

当前数据库名称

%~

类似 %/ ,但如果数据库是你的缺省数据库输出是波浪线 ~

%#

如果会话用户是数据库超级用户,使用 # ,否则用 > 。这个值的扩展可能在一个数据库会话过程中因为 SET SESSION AUTHORIZATION 命令而改变。

%R

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

%x

事务状态:如果不在事务块里则是一个空字符串,如果在事务块里则是 * ,如果在一个失败的事务块里则是 ! ,或者无法判断事务状态时为 ? (比如没有连接)。

%digits

指定字节值的字符将被替换到该位置。

%:name:

psql 变量 name 的值。参阅变量小节获取细节。

%`command`

command 的输出,类似于通常的"反勾号"替换。

%[ ... %]

提示可以包含终端控制字符,这些字符可以改变颜色、背景、提示文本的风格、终端窗口的标题。为了让 Readline 的行编辑特性正确运行,这些不可打印的控制字符必须设计成不可见的,方法是用 %[%] 包围它们。在提示符里可能出现这些东西的多个配对。例如

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

的结果是在 VT100 兼容的可显示彩色的终端上的一个宽体(1;)黑底黄字(33;40)。

键入 %% 可以在提示符里插入百分号。缺省提示符为 '%/%R%# ' 用于第一二个提示符,'>> ' 用于第三个提示符。

【注意】这个特性是从 tcsh 偷学来的。

命令行编辑

psql 为了编辑和检索命令行的方便支持 Readline 和历史库。命令历史在 psql 退出的时候自动保存,在 psql 启动的时候加载。还支持 Tab 补齐,尽管该补齐逻辑并不是一个 SQL 分析器必备的。如果因某些原因你不喜欢 tab 补齐,可以把下面几行放在你的家目录下的 .inputrc 文件里关闭这个特性:

$if psql
set disable-completion on
$endif

这不是 psql 而是 Readline 的特性,参考它的文档获取更多细节。

环境变量

PAGER

如果查询结果在一页里放不下,那么它们被重定向到这个命令。典型的值是 moreless 。缺省值是平台相关的。可以用 \pset 命令关闭分页器。

PGDATABASE

缺省连接的数据库

PGHOST
PGPORT
PGUSER

缺省连接参数

PSQL_EDITOR
EDITOR
VISUAL

\e 命令使用的编辑器。这些变量是按照上面的顺序检查的;设置最早的最先使用。

SHELL

\! 命令执行的命令

TMPDIR

存储临时文件的目录。缺省是 /tmp

因为 psql 在内部使用 libpq 库,所以所有 libpq 库的环境变量都可以被 psql 识别。参见节29.12获取所有变量的列表。

文件

注意

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

后退首页前进
pg_restore上一级reindexdb