9.3 9.4 9.5 9.6 10 11 12 13
阿里云PostgreSQL 问题报告 纠错本页面

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 脚本里很有用。这个选项忽略启动文件 (psqlrc~/.psqlrc)。

command必须是一条完全可以被服务器分析的字符串 (也就是不包含psql特有的特性),或者是一个反斜杠命令。 这样你就不会混合SQLpsql元命令。 要想混合使用,你可以把字符串重定向到psql里, 像这样:echo '\x \\ SELECT * FROM foo;' | psql (\\用于隔开元命令)。

如果命令字符串包含多个 SQL 命令,那么他们将在一个事务里处理, 除非在字符串里包含了明确的BEGIN/COMMIT命令把他们分成多个事务。 这个和从psql的标准输入里给它填充相同字符串不同。 另外,只返回最后一条SQL命令的结果。

-d dbname
--dbname=dbname

声明想要连接的数据库名称。等效于在命令行行上把 dbname声明为第一个非选项参数。

如果这个参数包含一个=号,或者以一个有效的URI 前缀(postgresql://postgres://)开头, 那么将它看做一个conninfo字符串。 参阅第 31.1.1 节获取更多信息。

-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

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

-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 来把整个脚本当作一个事务执行。这将保证该脚本要么完全执行成功,要么不产生任何影响。

如果在脚本中已经使用了BEGINCOMMITROLLBACK, 那么该选项将不会得到期望的效果。同样,如果脚本中包含任何不能在事务块内部使用的命令, 使用这个选项将导致这样的命令执行失败,当然整个事务亦将失败。

-?
--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和/或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 设置客户端编码为"自动",这将从本地设置中检测合适的客户端编码 (在Unix系统上是LC_CTYPE环境变量)。如果不像预期的那样工作, 客户端编码可以使用环境变量PGCLIENTENCODING重写。

输入 SQL 命令

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

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

testdb=>

用户可以在这个提示符下键入SQL命令。通常, 输入的行将在命令终止分号出现时送到服务器。一行的终止并不表示命令的结束。 因此命令可以为了清晰起见跨越好几行。如果命令发送出去而且执行没有错误, 命令结果会显示在屏幕上。

当命令正在进行时,psql同样还轮询由 LISTENNOTIFY生成的异步通知信号。

元命令

你在psql里输入的任何以不带引号的反斜杠开头的东西都是 psql元命令,这些命令是将由psql 自己处理的。这些命令使得psql 更便于管理或书写脚本。元命令通常被称为斜杠或反斜杠命令。

一个psql命令的格式是反斜杠后面紧跟一个命令动词, 然后是任意参数。参数与命令动词和其它参数以任意个空白字符间隔。

要在参数里面包含空白,你必须用单引号把它包围起来。要在参数里包含单引号, 在单引号包围的文本里写两个单引号。任何包含在单引号里的东西都会被进一步进行类 C的替换:\n(新行)、\t(制表符)、 \b(退格)、\r(回车)、 \f(换页)、\digits (八进制表示的字符)、\xdigits (十六进制表示的字符)。在单引号包围的文本中,反斜杠前导任何其他字符, 都表示是该单个字符,不管它是什么。

在一个参数中,加上反勾号(`)的文本被看做是一个命令行, 传递给shell。该命令的输出(删除结尾的新行)替换了加上反勾号的文本。

如果一个未加引号的冒号(:)后面跟着一个psql 变量名,出现在一个参数中,那么它会被变量的值取代,就像 SQL 代换 中描述的那样。

有些命令以一个SQL标识的名称(比如一个表名)为参数。 这些参数遵循SQL语法关于双引号的规则: 不带双引号的标识强制成小写,而双引号(")保护字母不进行大小写转换, 并且允许在标识符中使用空白。在双引号中, 成对的双引号在结果名字中分析成一个双引号。比如, FOO"BAR"BAZ解析成fooBARbaz; 而"A weird"" name"解析成A weird" name

对参数的分析在行的末尾停止,或者在找到另一个不带引号的反斜杠时停止。 一个不带引号的反斜杠会认为是一个新的元命令的开始。特殊的双反斜杠序列 \\标识参数的结尾并将继续分析后面的SQL 命令(如果存在的话)。这样SQLpsql 命令可以自由的在一行里面混合。但是在任何情况下,一条元命令的参数不能延续超过行尾。

下面是已定义的元命令:

\a

如果目前的表输出格式是不对齐的,则切换成对齐的。如果是对齐的,则切换成不对齐。 这条命令是为了向后兼容。参阅\pset获取一个更通用的解决方法。

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

与一个PostgreSQL服务器建立一个新的连接。如果成功建立了新的连接, 则前面的连接将关闭。如果dbname, username, host, port被省略或是指定为 -,那么就使用上次连接里面的值。 如果之前没有链接则使用libpq的缺省值。

如果连接失败(用户名错、访问被拒绝等),那么仅当psql 处于交互模式时将保留前面的连接。如果运行的是非交互的脚本, 处理会马上停止并返回一个错误。设置这样的区别一方面是为用户使用方便考虑, 另一方面也为了保证脚本不会碰巧操作了错误的数据库的安全机制考虑。

\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时,command 是通过psql执行的,并且来自或到达 command 的数据在服务器和客户端之间传送。这意味着文件访问性和权限都是本地用户的, 而不是服务器的,因此不需要 SQL 超级用户权限。

\copy ... from stdin | to stdout分别基于命令输入和输出进行读/写。 所有行都从发出命令的同一个源读取,直到读到了\. 或者流达到EOF。输出发送到和命令输出相同的位置。 要从psql的标准输入或者输出读/写, 可以使用pstdinpstdout。 这个选项用于填充SQL 脚本文件中嵌入的表很有用。

这条命令的语法是类似于SQL COPY命令, 并且option必须指出 SQL COPY命令的一个选项。 要注意的是因此带来一些应用于\copy命令的特殊分析规则。 尤其是变量替换规则和反斜杠逃逸规则将不起作用。

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

\copyright

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

\d[S+] [ pattern ]

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

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

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

缺省的,只显示用户创建的对象;应用一个模式或S 修饰符包含系统对象。

注意: 如果不带任何pattern参数调用 \d,那么等效于\dtvsE, 将显示一个所有可见表,视图,序列和外部表的列表。这完全是出于方便的考虑。

\da[S] [ pattern ]

列出聚合函数,以及它们的返回类型和操作的数据类型。如果声明了 pattern, 那么只显示匹配模式的聚合函数。缺省的,只显示用户创建的对象; 应用一个模式或S修饰符包含系统对象。

\db[+] [ pattern ]

列出表空间。如果声明了pattern, 那么只显示那些匹配模式的表空间。如果在命令名上附加了+, 那么每个对象都和与之相关的权限一起列出。

\dc[S+] [ pattern ]

列出字符集编码之间的转换。如果声明了pattern, 则只列出那些匹配模式的转换。缺省的,只显示用户创建的对象; 应用一个模式或S修饰符包含系统对象。如果在命令名上附加了 +,那么每个对象都和与之相关的描述一起列出。

\dC[+] [ pattern ]

列出类型转换。如果声明了pattern, 则只列出源或目标类型匹配该模式的转换。如果在命令名上附加了 +,那么每个对象都和与之相关的描述一起列出。

\dd[S] [ pattern ]

显示类型为constraintoperator classoperator familyruletrigger的对象的描述。 所有其他的注释可以通过各自对象类型的反斜杠命令看到。

\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" (aggregate)、"normal""trigger""window"的函数和它们的参数、返回类型和函数类型。 要想只显示指定类型的函数,在命令中添加对应的字母antw。如果声明了 pattern, 那么只显示名字匹配该模式的函数。如果使用了\df+格式, 则也显示关于每个函数的额外信息,包括安全、波动性、语言、源代码和描述。 缺省的,只显示用户创建的对象;提供一个模式或S 修饰符包含系统对象。

提示: 要查找接受或者返回特定类型的函数,使用你的分页器搜索功能来滚动\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 ]

列出数据库角色。(因为"用户""组"的概念已经统一成"角色", 所以这个命令现在等于\du。)如果声明了 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 | |command } ]

把当前的查询输入缓冲区的内容发送给服务器并且把查询的输出存储到可选的 filename 或者把输出重定向到一个独立的执行command 的 Unix shell 。文件或命令只在查询成功返回零个或更多元组时写入, 查询失败或者是一个非数据返回的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格式已经打开, 则切换回缺省的对齐的文本格式。这个命令是为了兼容和方便, 参阅\pset获取设置其它输出选项的内容。

\i filename

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

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

\ir filename

\ir命令类似于\i,但是对相关文件名的解析不同。 当在交互模式执行时,两个命令的表现相同。不过,当在脚本中调用时, \ir解释文件名关系为脚本所在的目录,而不是当前工作目录。

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

列出服务器上的数据库并显示它们的名字、所有者、字符集编码和访问权限。 如果声明了pattern, 则只列出名字匹配该模式的数据库。如果在命令名称后面加一个+, 则也显示数据库尺寸、缺省表空间和描述。(尺寸信息只在当前用户可以联接的数据库上可用。)

\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

响应表明此大对象得到一个对象标识 152801 ,可以用来在后面访问新创建的大对象。 出于可读性的目的,建议总是给每个对象关联一个人类可读的注解。 可以用\lo_list命令看到OID和注解。

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

\lo_list

显示一个目前存储在该数据库里的所有PostgreSQL 大对象和为它们提供的任意注解的列表。

\lo_unlink loid

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

提示: 使用\lo_list查找大对象的OID

\o [ {filename | |command} ]

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

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

提示: 要分散查询结果之间的文本输出,用\qecho

\p

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

\password [ username ]

更改指定用户的口令,缺省为当前用户。该命令将提示口令输入, 然后将加密过的口令使用ALTER ROLE之类的命令发送给服务器。 这可以保证新口令不会以明文形式出现在命令历史、服务器日志、或其他什么地方。

\prompt [ text ] name

提示用户提供文本,分配给变量name。 可以声明可选的提示字符串text。 (对于多个字的提示,用单引号包围文本。)

缺省的,\prompt使用终端输入和输出。不过,如果使用了-f 命令行开关,\prompt使用标准的输入和输出。

\pset option [ value ]

这条命令设置影响查询结果表输出的选项。option 描述要设置的选项是哪一个。value 的语意也取决于选取的选项。对于一些选项,省略value导致选项切换或复位, 就像特定的选项中描述的那样。如果没有提及这样的行为,那么省略 value只会导致显示当前的设置。

可调节的打印选项有:

border

value必须是一个数字。通常, 数字越大,表就有越宽的边界和越多的线,但是这个参数取决于实际的格式。 在HTML格式中,这个参数会直接翻译成border=... 属性,在其它的模式里,只有值 0(无边界)、1(内部分隔线)、2(表框架)有意义。 latexlatex-longtable 也支持border值为3,在每行之间添加一个分隔线。

columns

wrapped格式设置目标宽度,并且宽度限制决定输出是否太宽需要分页, 或在自动扩展模式下切换到垂直显示。0(缺省)代表目标宽度受到环境变量 COLUMNS的控制,或者如果没有设置COLUMNS, 则是受到检测到的屏幕宽度的限制。另外,如果columns为0, 那么wrapped格式只影响屏幕输出。如果columns非0, 那么字段和管道输出也包装为那个宽度。

expanded (或 x)

如果声明了value,则必须是 on或者off(这将启用或禁用扩展模式) 或者auto。如果省略了value, 那么命令在正常和扩展格式之间切换。当打开扩展格式时,查询结果用两列显示, 字段名称在左、数据在右。这个模式在数据无法放进通常的"水平" 模式的屏幕时很有用。在自动设置模式下,扩展模式在查询输出比屏幕宽时使用, 否则使用正常模式。自动设置只在对齐和封装格式下有效。在其他格式下, 它总是表现的好像扩展模式为关闭一样。

fieldsep

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

fieldsep_zero

设置非对齐输出格式中使用的域分隔符为0字节。

footer

如果声明了value, 它必须是on或者off, 这将启用或禁用表的脚注的显示((n rows)计数)。 如果省略了value, 那么命令切换脚注显示为on或off。

format

设置输出格式为unalignedalignedwrappedhtmllatex (使用tabular)、latex-longtabletroff-ms之一。允许使用唯一缩写,这也意味着一个字母就够了。

unaligned(不对齐)格式把一条记录的所有字段都输出到一行, 用当前有效的域分隔符分隔。这主要用于生成那些要被其它程序读取的输出 (比如,制表符分隔或逗号分隔格式)。

aligned(对齐)模式是标准的,人类可读的, 格式化好了的文本输出,也是缺省。

wrapped格式类似于aligned,但是包装跨行的宽数据值, 使其适应目标字段的宽度输出。目标宽度的确定如columns选项中的描述。 请注意,psql将不会尝试包装字段标题:因此, 如果字段标题所需的总宽度超过目标宽度,则wrapped格式的行为和 aligned相同。

htmllatexlatex-longtabletroff-ms模式把表输出为可用于文档里的对应标记语言。 它们还不是完整的文档!可能对于HTML变化还不是太大, 但是在LaTeX里,你必须有一个完整的文档包装器。 latex-longtable也需要LaTeX longtablebooktabs包装器。

linestyle

设置边界线绘画风格为asciiold-asciiunicode之一。允许独特的缩写。(这意味着一个字母就足够了。) 缺省设置是ascii。这个选项只影响alignedwrapped输出格式。

ascii风格使用纯ASCII字母。 数据中的换行使用一个+符号在右手边显示。 当wrapped格式从一行到下一行包装数据而不带有换行符时, 一个点(.)显示在第一行的右手边,在下一行的左手边。

old-ascii风格使用纯ASCII字符, 使用在PostgreSQL 8.4及更早版本中使用的格式风格。 数据中的换行使用一个:符号显示,代替左侧的域分隔符。 当数据从一行包装到下一行而不带有换行符时,使用一个;符号, 代替左侧的域分隔符。

unicode风格使用Unicode box-drawing字符。 数据中的换行在右侧使用一个回车符显示。当数据从一行包装到下一行而不带有换行符时, 一个省略号显示在第一行的右手边,在下一行的左手边。

border设置大于0时,这个选项也决定画边界线的字符。 纯ASCII字符无处不在, 但是Unicode字符看起来显示的更好,更容易辨认。

null

设置打印出来替换空值的字符串。缺省是什么都不输出, 这样很容易和一个空字符串混淆。例如,可能更喜欢 \pset null '(null)'

numericlocale

如果声明了value,那么它必须是 onoff,这将启用或禁用区域特定的字符的显示, 分隔小数点左边的数值组。如果省略了value, 那么该命令在普通和区域特定的数值输出之间切换。

pager

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

如果pager选项为off,则不使用分页器程序。如果pager 选项是on,则在适当的时候使用分页器,也就是说,输出是到终端, 而且很可能无法与屏幕匹配。也可以把pager选项设置为always, 导致在所有终端输出中都使用分页器,而不管它是否适合屏幕。不带有 value\pset pager 切换分页器的使用与否。

recordsep

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

recordsep_zero

设置在非对齐输出格式中使用的记录分隔符为0字节。

tableattr (或 T)

HTML格式下,这指定了要放置在table 标签中的属性。例如cellpaddingbgcolor。 请注意,你可能不需要在这里声明border, 因为已经在\pset border里用过了。如果没有给出 value,那么表的属性是未设置的。

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

title

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

tuples_only (或 t)

如果声明了value,那么必须是 onoff,这将启用或禁用仅元组模式。 如果省略了value, 那么该命令在普通和仅元组输出间切换。普通输出包括额外的信息, 比如列头、标题、各种脚注等。在仅元组模式下,只显示实际的表数据。

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

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

注意: 无参数运行\pset是错误的。以后这种情况将显示当前打印选项状态。

\q\quit

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

\qecho text [ ... ]

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

\r

重置(清空)查询缓冲区

\s [ filename ]

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

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

设置psql变量namevalue,或者如果给出了多于一个值, 设置为所有这些值的连接结果。如果只给出了一个参数,那么只设带有空值的变量。 要重置一个变量,使用\unset命令。

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

有效的变量名可以包含字母,数字和下划线。参阅下面的变量获取细节。变量名是大小写敏感的。

尽管你可以设置任何变量为任意值,psql 对一些变量特殊对待。它们在关于变量的小节里面有文档。

注意: 这条命令和SQL命令SET是没有关系的。

\setenv [ name [ value ] ]

设置环境变量namevalue, 或者如果没有提供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 语句的耗时。有参数,设置相同。

\unset name

取消(删除)psql变量name

\w filename
\w |command

将当前查询缓冲区输出到文件filename 或者重定向到 Unix 命令command

\watch [ seconds ]

重复执行当前查询缓冲区(像\g),直到中断或查询失败。 在执行之间等待指定的秒数(缺省是2)。

\x [ on | off | auto ]

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

\z [ pattern ]

列出带有相关访问权限的表、视图和序列。如果声明了 pattern, 则只显示名字匹配该模式的表、视图和序列。

这是\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参数, 那么\d命令显示所有在当前模式搜索路径中可见的对象, 等价于使用*作为匹配模式。(如果一个对象的包含模式在搜索路径中, 并且没有相同类型、名字的对象出现在搜索路径中的更早位置,那么就说该对象是 可见的。这就等于可以通过名字引用而不明确模式限定的语句。) 要查阅在数据库中的所有对象,使用*.*模式。

pattern 中的*匹配任何字符序列,包括没有字符,而? 匹配任何单个字符。这个表示法和 Unix 的 shell 文件名模式兼容。 比如\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'这样, 获得分别像PerlPHP 那样有名的"软连接""变量变量"。不幸(或者万幸?)的是, 用这些构造不能做任何有用的事情。另一方面,\set bar :foo 是一个非常有效的拷贝变量的方法。

有一些常用变量被psql特殊相待。它们代表特定的选项设置, 这些选项在运行时可以通过改变变量的值而改变,或者在某些情况下代表 psql的可变状态。尽管你可以把这些变量用于其它用途, 但是不鼓励这么做,因为程序的行为可能会变得非常奇怪。通常, 所有特殊对待的变量名都是由大写ASCII字母组成(可能还有数字和下划线)。 为了保证和未来的最大限度的兼容性,请避免使用这样的变量。 下面是一个所有特殊对待的变量列表。

AUTOCOMMIT

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

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

注意: 打开自动提交是PostgreSQL的传统行为,但是关闭自动提交更接近SQL规范。 如果你更喜欢关闭自动提交,你可以在系统范围的psqlrc~/.psqlrc文件中设置它。

COMP_KEYWORD_CASE

在完成SQL关键字时决定哪个字母使用大小写。如果设置为lowerupper,则完成的单词将分别为小写或大写。如果设置为 preserve-lowerpreserve-upper(缺省), 那么完成的单词将是输入时的情况,但是单词在没有任何输入的情况下完成, 将分别是小写或大写的情况。

DBNAME

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

ECHO

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

ECHO_HIDDEN

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

ENCODING

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

FETCH_COUNT

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

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

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值,即为从一条INSERT\lo_import 命令返回的值。此变量只保证在下一条SQL命令的结果显示之前有效。

ON_ERROR_ROLLBACK

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

ON_ERROR_STOP

缺省时,遇到错误后命令处理继续进行。如果设置了这个变量,遇到错误后会立即停止。 在交互模式下,psql将返回到命令提示符; 否则,psql将退出,并返回错误代码 3 , 以示这个情况与致命错误条件的区别,致命错误条件的错误代码为 1。 不管在哪种情况下,任何当前运行的脚本(顶级脚本,如果有,和任何它调用的其他脚本) 都将立即终止。如果顶级命令字符串包含多个SQL命令,处理将在当前命令停止。

PORT

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

PROMPT1
PROMPT2
PROMPT3

这些指明psql显示的提示符看上去像什么。 参阅下面的提示符

QUIET

这个变量等效于命令行选项-q。可能在交互模式下没有什么用。

SINGLELINE

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

SINGLESTEP

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

USER

当前你正用于连接的数据库用户。这是在每次你与数据库连接时(包括程序启动)设置的, 但是可以被删除。

VERBOSITY

这个选项可以设置为值defaultverboseterse 之一以控制错误报告的冗余。

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 包含描述提示符的外观的字符串和特殊逃逸序列。PROMPT1 是psql 请求一个新命令时使用的正常提示符。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补齐产生的查询也可以与其他SQL命令交互,比如SET TRANSACTION ISOLATION LEVEL。 如果因某些原因你不喜欢 tab 补齐,可以把下面几行放在你的家目录下的 .inputrc文件里关闭这个特性:

$if psql
set disable-completion on
$endif

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

环境变量

COLUMNS

如果\pset columns为0,控制wrapped 格式的宽度和宽度确定(如果宽的输出需要分页或在自动扩展模式应该切换为垂直模式)。

PAGER

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

PGDATABASE
PGHOST
PGPORT
PGUSER

缺省连接的参数(参阅第 31.14 节)。

PSQL_EDITOR
EDITOR
VISUAL

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

在Unix系统上内建的缺省编辑器是vi, 在Windows系统上是notepad.exe

PSQL_EDITOR_LINENUMBER_ARG

\e\ef带有行号参数使用时, 这个变量声明传递给用户编辑器的启动行号的命令行参数。 对于Emacsvi这样的编辑器,这是一个加号。 如果在选项名和行号之间需要空格,则包括变量值中尾随的空白。例子:

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

在Unix系统上的缺省是+(对应于默认的编辑器 vi,并且可用于许多其他常见的编辑器); 在Windows系统上没有缺省。

PSQL_HISTORY

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

PSQLRC

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

SHELL

\!命令执行的命令。

TMPDIR

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

这个工具,像大多数其他PostgreSQL工具一样, 也使用libpq提供的环境变量(参阅第 31.14 节)。

文件

注意

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

<
/BODY >