psql

psql

Greenplum数据库的交互式命令行接口。

概要

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

描述

psql是一个基于终端的Greenplum数据库前端。它是用户能够交互式输入查询、将它们发到Greenplum数据库并且查看查询结果。另外,输入可以来自于一个文件。此外,它还提供了很多元命令和一些类似shell的特性来方便书写脚本以及自动化各种任务。

选项

-a | --echo-all
把所有输入行原样打印到标准输出。相对于交互模式,这对于脚本处理更加有用。
-A | --no-align
切换到非对齐输出模式(默认输出模式是对齐的)。
-c 'command' | --command 'command'
指定psql指定指定的命令字符串,然后退出。这在shell脚本中很有用。command必须是一个服务器完全可解析的命令字符串,或者是一个单一的反斜线命令。因此用户不能用这个选项混杂SQL和psql的元命令。为了实现混杂,用户可以把字符串用管道导向psql,就像这样:
echo '\x \\ SELECT * FROM foo;' | psql
\\是分隔符元命令)。
如果这个命令字符串包含多个SQL命令,它们会被在单个事务中处理,除非有明确的BEGIN/COMMIT命令被包含在该字符串中把它划分为多个事务。这和把同样的字符串交给psql的标准输入时的行为不同。
-d dbname | --dbname dbname
指定要连接的数据库。这等效于把数据库名指定为命令行上的第一个非选项参数。
如果这个参数包含一个等号,它会被当作一个conninfo字符串对待。例如,用户可以传递'dbname=postgres user=username password=mypass'作为dbname
-e | --echo-queries
把所有发送到服务器的SQL命令也拷贝到标准输出。
-E | --echo-hidden
回显\d以及其他反斜线命令生成的实际查询。用户可以使用这个选项来学习psql的内部操作。
-f filename | --file filename
使用一个文件作为命令的来源而不是交互式地读取命令。在该文件被处理后,psql就终止。如果filename-(连字符),那么会使用标准输入。使用这个选项与书写psql <filename有些许不同。通常两者都会按照预期执行,但是使用-f会启用一些不错的特性,例如带有行号的错误消息。
-F separator | --field-separator separator
只用指定的分隔符作为非对齐输出的域分隔符。
-H | --html
打开HTML表格输出。
-l | --list
列出所有可用数据库,然后退出。其他非连接选项会被忽略。
-L filename | --log-file filename
在普通输出目标之外,把所有查询输出写入到指定的日志文件。
-o filename | --output filename
把所有查询输出放到指定的文件中。
-P assignment | --pset assignment
允许用户在命令行上以\pset风格指定打印选项。注意这里用户必须用等号而不是空格分隔名称和值。因此要把输出格式设置成LaTeX,可以写成-P format=latex
-q | --quiet
指定psql应该安静地做它的工作。它默认会把欢迎信息和一些信息性的输出打印出来。如果使用这一选项,这些都不会发生。这对-c选项很有用。
-R separator | --record-separator separator
使用separator作为非对齐输出的记录分隔符。
-s | --single-step
运行在单步模式中。这意味着在每一个命令被发送到服务器之前都会提示用户,也有取消执行的选项。使用这一选项可以调试脚本。
-S | --single-line
运行在单行模式中,其中新行会终止一个SQL命令(就像分号那样)。
-t | --tuples-only
关闭列名和结果行计数页脚等的打印。这个命令等效于\pset tuples_only,提供它只是为了方便。
-T table_options | --table-attr table_options
允许用户指定要被放在HTML表标签中的选项。详见\pset
-v assignment | --set assignment | --variable assignment
执行变量赋值,就像内部命令\set。注意用户必须在命令上用一个等号分隔名称和值(如果有)。要复原一个变量,省去等号。要把一个变量设置为没有值,使用等号但是省去值。这些赋值会在启动的非常早期阶段完成,因此为内部目的保留的变量可能会在后面被覆盖。
-V | --version
打印psql版本并且退出。
-x | --expanded
打开扩展的表格式化模式。
-X | --no-psqlrc
不要读取启动文件(不管是系统范围的psqlrc文件还是用户的~/.psqlrc文件)。
-1 | --single-transaction
psql-f选项指定一个脚本时,增加这个选项会在脚本上包裹BEGIN/COMMIT以便将它放在一个单一事务中执行。这确保要么所有命令成功完成,要么什么改变也不发生。
如果脚本本身使用BEGINCOMMIT或者ROLLBACK,这个选项将不会取得想要的效果。此外,如果脚本包含任何不能在事务块内执行的命令,指定这个选项将导致命令失败(进而导致整个事务失败)。
-? | --help
显示有关psql命令行参数的帮助,然后退出。
连接选项
-h host | --host host
指定Greenplum的Master数据库服务器在其上运行的机器的主机名。如果没有指定,会从环境变量PGHOST读取或者默认为localhost。
-p port | --port port
指定Greenplum的Master数据库服务器在其上监听连接的TCP端口。如果没有指定,会从环境变量PGPORT读取或者默认为5432。
-U username | --username username
要用其进行连接的数据库角色名。如果没有指定,会从环境变量PGUSER读取或者默认为当前系统用户名。
-W | --password
强制口令提示。只要服务器要求口令认证,psql应该自动提示要求口令。不过,当前的口令请求检测并不完全可靠,因此这个选项可以强制一个提示。如果没有口令提示发出并且服务器要求口令认证,连接尝试将会失败。
-w --no-password
从不发出口令提示。如果服务器要求口令认证并且不能通过其他方式(例如.pgpass文件)提供口令,则连接尝试将会失败。这个选项对于批作业和脚本很有用,因为这些情况下不会有用户输入口令。
注意: 这个选项设置会为整个会话保留,因此它会影响元命令\connect的使用。

退出状态

如果psql正常结束,它返回0给shell;如果发生其自身的致命错误(内存不足、找不到文件)则返回1;如果到服务器的连接出现问题或者会话不是交互式的则返回2;如果在脚本中发生错误并且变量ON_ERROR_STOP被设置则返回3。

用法

连接到数据库

psql是Greenplum数据库的一个客户端应用。为了连接到数据库,用户需要知道目标数据库的名称、Greenplum的Master服务器的主机名和端口号,还有想要作为其身份进行连接的数据库用户名。可以通过命令行选项告诉psql那些参数,分别是-d-h-p以及-U。如果找到一个不属于任何选项的参数,它将被解释为数据库名(如果数据库名称已给出,则解释成用户名)。并非所有这些选项都是必需的,它们都有有用的默认值。如果用户省略主机名,psql将通过UNIX域套接字连接到本地主机上的Master服务器,或者在没有UNIX域套接字的机器上通过TCP/IP连接到localhost。默认的Master端口号是5432。如果用户为Master使用不同的端口,用户必须指定该端口。默认的数据库用户名是用户的UNIX用户名,它也是默认的数据库名。注意用户不能用任意用户名连接到任意数据库。用户的数据库管理员应该已经告知过用户的访问权利。

当默认值不正确时,用户可以通过把环境变量PGAPPNAMEPGDATABASEPGHOSTPGPORT以及PGUSER中的一个或者全部设置为合适的值来省去一些输入工作。

用一个~/.pgpass文件避免定期输入口令也很方便。这个文件应该位于用户的主目录之下并且包含下列格式的行:

hostname:port:database:username:password

The permissions on .pgpass上的权限必须不允许全域或者组的任何访问(例如:chmod 0600 ~/.pgpass)。如果权限没有这样严格,该文件将被忽略(不过,当前微软Windows上的客户端当前不检查该文件的权限)。

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

输入SQL命令

在通常的操作中,psql提供一个提示符,提示符是psql当前连接上的数据库名后面接上字符串=>(普通用户)或者=#(超级用户)。例如:

testdb=>
testdb=#

在提示符上,用户可以输入SQL命令。通常,当达到一个终止命令的分号时,输入行会被发送到服务器。行结束不会终止命令。因此命令可以被散布在多个行上以提高其清晰度。如果命令被发出并且执行时没有发生错误,该命令的结果会被显示在屏幕上。

元命令

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

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

要在一个参数中包括空白,可以将它加上单引号。要在一个参数中包括一个单引号,则需要在文本中写上两个单引号。任何包含在单引号中的东西都服从与C语言中\n(新行)、\t(制表符)、\digits(10 进制)以及\xdigits(16 进制)类似的替换规则。

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

在一个参数中,封闭在反引号(`)中的文本被当做要被送给shell 的一个命令行。该命令的输出(去掉尾部的新行)将会被用作该参数的值。上面的转义序列在反引号中也适用。

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

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

可以使用下列元命令:

\a
如果当前的表输出格式是非对齐的,则切换成对齐格式。如果不是非对齐格式,则设置成非对齐格式。保留这个命令是为了向后兼容性。更一般的方案请见\pset
\cd [directory]
改变当前工作目录。如果不带参数,则切换到当前用户的主目录。要打印用户的当前工作目录,可以使用\!pwd
\C [title]
设置被打印为查询结果的表的标题,或者重置这类标题。这个命令等效于\pset title
\c | \connect [dbname [username] [host] [port]]
建立一个新连接。如果新连接成功地被建立,之前的连接会被关闭。如果dbname、username、host或者port中的任何一个被省略,该参数的值将使用之前连接中的。如果连接尝试失败,只有在psql处于交互模式的情况下才会保留之前的连接。当执行一个非交互式脚本时出现连接尝试失败,处理将被立即停止,并且报出一个错误。这种区别一方面可以帮助用户发现打字错误,另一方面也可以作为一种安全机制防止脚本在错误的数据库上执行动作。
\conninfo
输出有关当前数据库连接的信息,包括数据库名、用户名、连接类型(UNIX域套接字、TCP/IP等)、主机以及端口。
\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命令COPY有效,因为所有的数据必须通过客户端/服务器的连接来传递。
\copyright
显示Greenplum数据库所基于的PostgreSQL的版权以及发布条款。
\d [relation_pattern]  | \d+ [relation_pattern] | \dS [relation_pattern]
对于每一个匹配关系pattern的关系(表、外部表、视图、索引或者序列),显示所有的列、它们的类型、表空间(如果非默认表空间)以及任何诸如NOT NULL或者默认值的特殊属性(如果有)。相关的索引、约束、规则以及触发器也会被显示,如果关系是视图还显示该视图的定义。
  • 命令形式\d+是一样的,不过会显示更多信息:与该表的列相关的任何注释,表中是否存在 OID。

    对于分区表,指定根分区表或者子分区表的\d或者\d+显示有关该表的信息,包括该分区表的当前层次上的分区键。命令\d+还显示该表的直接子分区以及该子分区是外部表还是常规表。

    对于追加优化表和列存表,\d+显示表的存储选项。对于追加优化表,会显示表的选项。对于列存表,为每列显示存储选项。

  • 命令形式\dS是一样的,不过会显示系统信息以及用户信息。例如,\dt显示用户表但不显示系统表;\dtS同时显示用户表和系统表。这些命令都可以接收+参数以显示额外的信息,和在\dt+\dtS+中一样。

    如果使用\d没有带有模式参数,它等效于显示所有表、视图和序列列表的\dtvs

\da [aggregate_pattern]
列出所有可用的聚集函数,以及它们所操作的数据类型。如果指定了模式,只显示名称匹配该模式的聚集。
\db [tablespace_pattern] | \db+ [tablespace_pattern]
列出所有可用的表空间和它们对应的文件空间位置。如果指定了模式,只显示名称匹配该模式的表空间。如果在命令名称后面追加+,则会为每个对象列出其相关的权限。
\dc [conversion_pattern]
列出所有可用的字符集编码之间的转换。如果指定了模式,只列出名称匹配该模式的转换。
\dC
列出所有可用的类型造型。
\dd [object_pattern]
列出所有可用的对象。如果指定了模式,只列出匹配的对象。
\dD [domain_pattern]
列出所有可用的域。如果指定模式,只列出匹配的域。
\df [function_pattern] | \df+ [function_pattern ]
列出可用的函数,以及它们的参数和返回类型。如果指定了模式,则只显示名称匹配模式的函数。如果使用了形式\df+,关于每个函数的额外信息(包括语言和描述)会被显示。为了减少混乱,\df 不显示数据类型的I/O函数。这通过忽略接受或者返回类型cstring的函数来实现。
\dg [role_pattern]
列出所有数据库角色。如果指定了模式,则仅列出名称匹配模式的那些角色。
\distPvES [index | sequence | table | parent table | view | external_table | system_object]
这不是实际的命令名称:字母istPvES分别代表索引、序列、表、父表、视图、外部表和系统表。用户可以以任意顺序指定这些字母中的任意一个或者全部,以便得到所有匹配对象的列表。字母S限制列表为系统对象;如果没有S,只有非系统对象会被显示。如果在命令名称后面加上+,列出的每个对象会带有其相关的权限(如果有)。如果指定了模式,仅列出名称匹配模式的对象。
\dl
这是\lo_list的别名,它显示大对象的列表。
\dn [schema_pattern] | \dn+ [schema_pattern]
列出所有可用的方案(名字空间)。如果指定了模式,仅列出名称匹配该模式的方案。非本地临时方案不会被列出。如果在命令名称后面加上+,列出每个对象时会带有其相关的权限和描述(如果有)。
\do [operator_pattern]
列出可用的操作符以及它们的操作数和返回类型。如果指定了模式,仅列出名称匹配该模式的操作符。
\dp [relation_pattern_to_show_privileges]
产生所有可用的表、视图和序列及其相关访问特权的列表。如果指定了模式,则仅列出名称匹配该模式的表、视图和序列。GRANTREVOKE命令被用来设置访问特权。
\dT [datatype_pattern] | \dT+ [datatype_pattern]
列出所有数据类型或者仅列出那些匹配模式的。命令形式\dT+会显示额外的信息。
\du [role_pattern]
列出所有的数据库角色或者仅列出那些匹配模式的。
\dx [extension_pattern]
列出所有已安装的扩展或者仅列出那些匹配模式的。
\e | \edit [filename]
如果指定一个文件名,该文件会被编辑。在编辑器退出后,该文件的内容被拷贝回查询缓冲区。如果没有给出参数,当前查询缓冲区会被拷贝到一个临时文件,然后以同样的方式编辑。新的查询缓冲区接着会被根据psql的正常规则解析,其中整个缓冲区被当做一个单一行(因此不能用这种方式制作脚本,制作脚本请用\i)。这还意味着如果该查询以一个分号结尾(或者包含一个分号),它会被立即执行。在其他情况中,它将在查询缓冲区中等待。
psql会在环境变量PSQL_EDITOREDITORVISUAL(按这个顺序)中搜索要使用的编辑器。如果它们都没有被设置,会使用UNIX系统的vi或者Windows系统上的notepad.exe
\echo text [ ... ]
把参数打印到标准输出,用一个空格分隔并且接上一个新行。这对于在脚本输出中点缀一些信息有用。
如果用户使用\o命令重定向查询输出,用户可能希望使用\qecho来取代这个命令。
\encoding [encoding]
设置客户端字符集编码。如果没有参数,这个命令显示当前编码。
\f [field_separator_string]
为非对齐查询输出设置域分隔符。默认是竖线(|)。设置输出选项的一般方法另见\pset.
\g [{filename | |command }]
把当前查询输入缓冲区发送到服务器,并且根据选择把查询的输出存储在一个文件中或者把输出用管道导向一个执行command的单独的UNIX shell。一个裸的\g实质上等价于一个分号。带有参数的\g\o命令的一个"一次性的"替换方案。
\h | \help [sql_command]
给出指定SQL命令的语法帮助。如果没有指定command,则psql会列出语法帮助有用的所有命令。如果command是一个星号(*),则会显示所有SQL命令的语法帮助。为了简化输入,由几个词构成的命令不需要被加上引号。
\H
开启HTML查询输出格式。如果HTML格式已经开启,这会把它切换回默认的对齐文本格式。这个命令是为了兼容性和方便,有关设置其他输出选项请见\pset
\i input_filename
从一个文件读取输入并且把它当作从键盘输入的命令来执行。如果用户想要在行被读取时在屏幕上看到它们,用户必须设置变量ECHO为all。
\l | \list | \l+ | \list+
列出服务器中所有数据库的名称、拥有者和字符集编码。如果在命令名称后面加上+,则还会显示数据库描述。
\lo_export loid filename
从数据库中读取OID为loid的大对象并且将它写入到filename。注意这和服务器函数lo_export有微妙的不同,后者会以运行数据库服务器的用户权限来执行并且运行在服务器的文件系统上。使用\lo_list可以找出大对象的OID。
\lo_import large_object_filename [comment]
把该文件存储到PostgreSQL大对象。可选地,它可以把给定的注释关联到该对象。例如:
mydb=> \lo_import '/home/gpadmin/pictures/photo.xcf' 'a 
picture of me'
lo_import 152801
该响应表示该大对象得到的对象ID是152801,如果想要再次访问该对象,需要记住这个ID。由于这个原因,推荐总是给每一个对象都关联人类可读的注释。OID 和注释都可以用\lo_list命令查看。注意这个命令和服务器端的lo_import有微妙的不同,因为它以本地文件系统上的本地用户的身份运行,而不是服务器用户和文件系统。
\lo_list
显示当前存储在数据库中的所有大对象,同时显示它们的任何注释。
\lo_unlink largeobject_oid
从数据库中删除指定OID的大对象。使用\lo_list可以找出该大对象的OID。
\o [ {query_result_filename | |command} ]
把未来的查询结果保存到一个文件中或者用管道导向到一个UNIX的shell命令command。如果没有指定参数,查询输出会被重置到标准输出。查询结果包括从数据库服务器得到的所有表、命令响应和提示,还有查询数据库的各种反斜线命令(如\d)的输出,但不包括错误消息。要在查询结果之间混入文本输出,可以使用\qecho
\p
把当前查询缓冲区打印到标准输出。
\password [username]
更改指定用户(默认情况下是当前用户)的口令。这个命令会提示要求输入新口令、对口令加密然后把加密后的口令作为一个ALTER ROLE命令发送到服务器。这确保新口令不会以明文的形式出现在命令历史、服务器日志或者其他地方。
\prompt [ text ] name
提示用户设置变量name。可以指定一个可选的提示字符串text(对于多个词组成的提示,把文本包裹在单引号中)。
默认情况下,\prompt使用终端进行输入和输出。不过,如果使用了-f命令行开关,\prompt会使用标准输入和标准输出。
\pset print_option [value]
这个命令设置影响查询结果表输出的选项。print_option表示要设置哪个选项。可调整的打印选项是:
  • format – 设置输出格式为unalignedalignedhtmllatextroff-ms或者wrapped之一。允许使用首字母缩写。unaligned格式把一行的所有列都写在一行上,之间用当前活动的域分隔符分隔。这可用于生成意图由其他程序读取的输出。aligned格式是标准的、人类可读的、格式化好的文本输出,这是默认格式。HTML和LaTeX模式输出用于包括在使用相应标记语言的文档中的表格。它们不是完整的文档(在HTML中这可能不那么严重,但在LaTeX中必须有一个完整的文档包装器)!

    wrapped选项设置输出格式类似于aligned参数,但是让宽数据值自动换行以便让输出能适合目标列宽度。目标宽度由columns选项设置。要指定列宽并且选择wrapped格式,使用两个\pset命令。例如,要设置列宽为72并且指定wrapped格式,使用命令\pset columns 72,然后使用\pset format wrapped.

    注意: 由于psql不会尝试自动换行列头标题,如果列头所需的总宽度超过目标值,wrapped格式的行为和aligned相同。
  • border – 第二个参数必须是数字。通常,数字越高表格会有越多边界和线条,但是这取决于特定格式。在HTML模式中,这将被直接翻译成border=...属性,在其他模式中只有值0(无边界)、1(内部划分线)和2(表边框)有意义。
  • columns – 为wrapped格式设置目标宽度,还有用于判断输出是否过宽导致要求分页器的宽度限制。默认是zero。零导致目标宽度受环境变量COLUMNS控制,或者在COLUMNS没有设置时检测屏幕宽度。此外,如果columns为零,则wrapped格式只影响屏幕输出。如果columns为非零则文件和管道输出也会按照该宽度换行。

    在设置目标宽度后,使用命令\pset format wrapped可以启用wrapped格式。

  • expanded | x – 在常规和扩展格式之间切换。当扩展格式被启用时,查询结果被显示为两列,列名在左数据在右。如果数据无法在普通的水平模式下适应屏幕,这种模式就能发挥作用。扩展模式被所有四种输出格式支持。
  • linestyle [unicode | ascii | old-ascii] – 将边界线绘制风格设置为unicode、ascii或者old-ascii中的一个。也允许使用这三种风格的唯一缩写,包括一个字母。默认设置为ascii。这个选项只影响alignedwrapped输出格式。

    ascii – 使用纯ASCII字符。数据中的新行用右手边边缘的+号显示。当wrapped格式把数据从一行绕回到下一行且没有用新行字符时,在第一行的右手边边缘会显示一个点号(.),并且在下一行的左手边边缘也显示一个点号。

    old-ascii – 使用纯ASCII字符的风格,使用PostgreSQL 8.4及较早版本中的格式化风格。数据中的新行使用一个冒号代替左手边列分隔符来显示。当数据被从一行绕回到下一行且没有用新行字符时,一个分号会被用于替代左手边的列分隔符。

    unicode – 使用Unicode方框绘制字符的风格。数据中的新行被显示为右手边边缘的一个回车符号。当数据被从一行绕回到下一行且没有用新行字符时,一个省略符被显示在第一行的右手边边缘中,并且在下一行的左手边边缘也显示一个省略号。

    border设置超过零时,这个选项还决定用于绘制边界线的字符。纯ASCII字符在每个地方都适用,但Unicode字符只在识别它们的显示上才比较好。

  • null 'string' – 第二个参数是为空值列打印的字符串。默认是不打印任何东西,但很容易被误认为是一个空字符串。例如,命令\psetnull '(empty)' 在空值列中显示(empty)
  • fieldsep – 指定在非对齐输出格式中使用的域分隔符。用那种方式,用户可以创建制表符或者逗号分隔的输出,这种形式其他程序可能更喜欢。要设置制表符为域分隔符,可以键入\pset fieldsep '\t'。默认的域分隔符是'|'(一个竖线)。
  • footer – 切换默认页脚的显示(x rows)。
  • numericlocale – 切换一个区域相关字符的显示,该字符被用来分隔数字组和左边的十进制标记。它也启用一种区域相关的十进制标记。
  • recordsep – 指定用在非对齐输出格式中的记录(行)分隔符。默认是一个新行字符。
  • title [text] – 设置用于任何后续被打印表的表标题。这可以用来给输出加上描述性的标签。如果没有给出参数,这个标题会被复原。
  • tableattr | T [text] – 允许用户指定要放在HTML表格标签内的属性。例如,这可能是cellpadding或者bgcolor。注意用户可能不想在这里指定边界,因为那由\pset border负责。
  • tuples_only | t [novalue | on | off] – \pset tuples_only命令本身在只显示元组和完全显示之间切换。值onoff设置元组显示,不管当前的设置如何。完全显示可以显示额外的信息,例如列头、标题和多种页脚。在只显示元组模式中,只有实际的表数据会被显示。\t命令等效于\psettuples_only,提供它只是为了方便。
  • pager – 控制对查询和psql的帮助输出使用分页器程序。当值为on时,如果环境变量PAGER被设置,输出会被用管道输送到指定的程序。否则将使用与平台相关的默认分页器程序(例如more)。当值为off时,则不会使用分页器程序。如果pager选项被设为on,则仅会在适当的时候使用分页器,即当输出到终端并且无法适合屏幕时就会使用分页器。pager选项也可以被设置为always,这会导致总是使用分页器。
\q
退出psql程序。
\qecho text [ ... ]
这个命令与\echo相同,不过输出将被写到由\o设置的查询输出通道。
\r
重置(清除)查询缓冲区。
\s [history_filename]
打印命令行历史或者保存命令行历史到filename。如果filename被省略,历史会被写到标准输出。
\set [name [value [ ... ]]]
设置内部变量namevalue,或者是给出的多个值的串接。如果没有给出第二个参数,该变量被设置为没有值。要复原一个变量,可使用\unset命令。
合法的变量名可以包含字母、数字和下划线。详见高级特性中的“变量”。变量名是大小写敏感的。
尽管可以自由地把任意变量设置为任意的值,但是有几个变量会受到psql的特殊对待。在有关变量的主题中有介绍。
这个命令和SQL命令SET完全无关。
\t [novalue | on | off]
\t命令本身切换输出列名称标题以及行计数页脚的显示。值onoff设置元组显示,而不管当前设置如何。这个命令等效于\pset tuples_only,提供它只是为了方便。
\T table_options
允许用户指定在HTML表格输出模式中,要放在表格标签内的属性。
\timing [novalue | on | off]
\timing命令本身切换是否显示每个SQL语句花费的时间,以毫秒为单位。onoff设置时间显示,而不管当前设置如何。
\w {filename | |command}
把当前查询缓冲区输出到一个文件或者用管道导向到一个UNIX命令。
\x
切换扩展的表格式化模式。
\z [relation_to_show_privileges]
列出表、视图和序列,以及它们相关的访问特权。如果指定了模式,则只会列出名称匹配该模式的表、视图和序列。这是\dp的别名。
\! [command]
转义到一个单独的UNIX shell或者执行该UNIX命令。参数不会被进一步解释,shell将看到它们的原样。
\?
显示有关psql反斜线命令的帮助信息。

模式

很多\d命令都可以用一个模式参数来指定要被显示的对象名称。在最简单的情况下,模式正好就是该对象的准确名称。在模式中的字符通常会被变成小写形式(就像在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的表。如果没有出现点号,那么模式将只匹配当前方案搜索路径中可见的对象。同样,双引号内的点号会失去其特殊含义并且变成普通的字符。

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

只要模式参数被完全省略,\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时没有第二个参数,会用一个空字符串作为value来设置该变量。要复原(即删除)一个变量,可以使用命令\unset

psql的内部变量可以由任意顺序和任意数量的字母、数字以及下划线构成。有一些变量会被psql特殊对待。它们表示特定的选项设置,运行时这类选项设置可以通过修改该变量的值来改变,它们还可以表示该应用的某种状态。尽管可以把这些变量用于其他目的,但并不推荐这样做,因为该程序的行为可能超出预期。按照惯例,所有被特殊对待的变量的名称由全部大写字母(还有可能是数字和下划线)组成。为了确保未来最大的兼容性,最好避免把这类变量名用于自己的目的。下文列出了所有被特殊对待的变量:

AUTOCOMMIT
在被设置为on(默认)时,每一个 SQL 命令在成功完成时会被自动提交。在这种模式中要推迟提交,必须输入一个SQL命令BEGIN或者START TRANSACTION。当被设置为off或者被复原时,在显式发出COMMIT或者END之前,SQL命令不会被提交。自动提交打开模式会为用户发出一个隐式的BEGIN,这会发生在任何不在一个事务块中且本身即不是BEGIN及其他事务控制命令且不是无法在事务块中执行的命令(例如VACUUM)之前。
在自动提交关闭模式中,必须通过ABORT或者ROLLBACK显式地放弃任何失败的事务。还要记住,如果退出会话时没有提交,则所有的工作都会丢失。
自动提交打开模式是PostgreSQL的传统行为,但是自动提交关闭模式更接近于SQL的规范。如果更喜欢自动提交关闭模式,可以在个人的~/.psqlrc文件中设置它。
DBNAME
当前已连接的数据库名称。每次连接到一个数据库时都会设置该变量(包括程序启动时),但是可以被复原。
ECHO
如果被设置为all,所有从键盘输入或者来自于一个脚本的行在被解析或者执行前会被写到标准输出。要在程序开始时选择这种行为,可以使用开关-a。如果被设置为queries,psql只会在发送查询给服务器时打印它们。这种行为的开关是-e
ECHO_HIDDEN
当这个变量被设置且一个反斜线命令查询数据库时,相应的查询会被先显示。这种特性可以帮助我们学习Greenplum数据库的内部并且在自己的程序中提供类似的功能(要在程序开始时选择这种行为,可以使用开关-E)。如果把这个变量设置为值noexec,则对应的查询只会被显示而并不真正被发送给服务器执行。
ENCODING
当前的客户端字符集编码。
FETCH_COUNT
如果这个变量被设置为一个> 0的整数值,SELECT查询的结果会以一组一组的方式取出并且显示(而不是像默认的那样把整个结果集拿到以后再显示),每一组就会包括这么多个行。因此,这种方式只会使用有限的内存量,而不管整个结果集的大小。在启用这个特性时,通常会使用100到1000的设置。记住在使用这种特性时,一个查询可能会在已经显示了一些行之后失败。
尽管可以把这种特性用于任何的输出格式,但是默认的aligned格式看起来会比较糟糕,因为每一组的FETCH_COUNT个行将被单独格式化,这就会导致不同的行组的列宽不同。其他的输出格式会更好。
HISTCONTROL
如果这个变量被设置为ignorespace,则以一个空格开始的行不会被放入到历史列表中。如果被设置为值ignoredups,则匹配之前的历史行的行不会被放入。值ignoreboth组合了上述两种值。如果被复原或者被设置为其他非上述值,所有在交互模式中被读入的行都会保存在历史列表中。
HISTFILE
将被用于存储历史列表的文件名。默认值是~/.psql_history。例如,把
\set HISTFILE ~/.psql_history- :DBNAME
放在~/.psqlrc中将会导致psql为每一个数据库维护一个单独的历史。
HISTSIZE
要存储在命令历史中的命令数量。默认值是500。
HOST
用户当前连接到的数据库服务器主机。每次用户连接到一个数据库(包括程序启动)时都会设置这个变量,但是不能被复原。
IGNOREEOF
如果被重置,向psql的一个交互式会话发送一个EOF字符(通常是CTRL+D)将会终止该应用。如果被设置为一个数字值,则在应用终止前会忽略那么多个EOF字符。如果该变量被设置但不是数字值,则默认为10
LASTOID
最后一个受影响的OID的值,由一个INSERT或者lo_insert命令返回。这个变量只保证在下一个SQL命令的结果被显示之前有效。
ON_ERROR_ROLLBACK
当值为on时,如果一个在事务块中的语句产生错误,该错误会被忽略并且事务继续。对于交互模式,这类错误仅在交互式会话中被忽略,而在读取脚本文件时不会忽略。当值为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
这个变量可以被设置为值defaultverbose或者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仍然是特殊的,因此我们需要双写它们。

因为冒号可以合法地出现在SQL命令中,需要应用下面的规则:字符序列":name"不会改变,除非"name"是一个当前被设置的变量名。在任何情况下用户都可以用一个反斜线转义冒号以包含它不被替换(变量的冒号语法是嵌入式查询语言例如ECPG的标准SQL。数组切片和类型造型的冒号语法是Greenplum数据库的扩展,因此有冲突)。

提示符

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

被选中的提示符变量的值会被原样打印,除非碰到一个百分号(%)。百分号的下一个字符会被特定的其他文本替换。预定义好的替换有:

%M
数据库服务器的完整主机名(带有域名),或者当该连接是建立在一个Unix域套接字上时则是[local],或者当Unix域套接字不在编译在系统内的默认位置上时则是[local:/dir/name]
%m
数据库服务器的主机名,在第一个点处截断,如果连接建立在UNIX域套接字上,则为[local]
%>
服务器在哪个端口号上监听。
%n
数据库会话的用户名(在数据库会话期间,这个值的展开可能会由于命令SET SESSION AUTHORIZATION的结果而改变)。
%/
当前数据库的名称。
%~
%/相似,但是如果数据库为用户的默认数据库则输出为~(波浪线)。
%#
如果会话用户是一个数据库超级用户,那么是一个#,否则是一个>(在数据库会话期间,这个值的展开可能会由于命令SET SESSION AUTHORIZATION的结果而改变)。
%R
在提示符 1 中通常是=,但如果在单行模式中是^,如果会话断开了与数据库的连接(如果\connect失败会这样)则是!。在提示符 2 中,根据为什么psql期待更多的输入,%R会被一个相应的字符替换:如果命令还没有被终止是-,如果在一段/* ... */注释中则是*,如果在被引用字符串则是一个单引号或者双引号,如果在美元转义的字符串中则是一个美元符号。在提示符 3 中%R不会产生任何东西。
%x
事务状态:当不在事务块中时是一个空字符串,在一个事务块中时是*,在一个失败的事务块中时是!,当事务状态是未判定时(例如因为没有连接)为?
%digits
带有指定的八进制码的字符会被替换。
%:name:
psql变量name的值。详见高级特性中的“变量”部分。
%`command`
命令的输出,类似于普通的反引号替换。
%[ ... %]
提示符可以包含终端控制字符,例如改变提示符文本的颜色、背景或者风格以及更改终端窗口标题的控制字符。为了让行编辑特性正确工作,这些不可打印的控制字符必须被包裹在%[%]之间以指定它们是不可见的。在提示符中可以出现多个这样的标识对。例如:
testdb=> \set PROMPT1 '%[%033[1;33;40m%]%n@%/%R%[%033[0m%]%#'
会导致一个在兼容 VT100 的彩色终端上的粗体(1;)的、黑底黄字(33;40)的提示符。要在用户的提示符中插入一个百分号,可以写成%%。提示符 1 和 2 的默认提示是'%/%R%# ',提示符 3 的提示是'>> '
命令行编辑

psql支持NetBSD的libedit库用于方便的行编辑和检索。当psql退出时,命令历史被自动保存;而当psql启动是命令历史被重新载入。还支持Tab键补全,不过补全逻辑并不是一个SQL解析器。如果由于某种原因不喜欢Tab补全,用户可以在自己主目录下的.inputrc文件中放入如下内容来关掉该功能:

$if psql
set disable-completion on
$endif

环境

PAGER
如果查询结果不适合屏幕,它们会被这个命令导出。典型的值是more或者less。默认值依赖于平台。通过使用\pset命令可以禁用分页器的使用。
PGDATABASE
PGHOST
PGPORT
PGUSER
默认连接参数。
PSQL_EDITOR
EDITOR
VISUAL
\e命令使用的编辑器。会以列出的顺序检查变量,使用第一个有设置的变量。
SHELL
\!命令执行的命令。
TMPDIR
用于存储临时文件的目录。默认是/tmp

文件

在启动前,psql会尝试从用户的~/.psqlrc文件中读取并且执行命令。

命令行历史被存储在文件~/.psql_history中。

注解

psql只在具有相同版本的服务器下工作流畅。这并不意味着其他的组合会立刻失败,但是细微以及不那么细微的问题可能会出现。如果服务器具有不同的版本,反斜线命令尤其容易失败。

给Windows用户的注解

psql被构建为一种控制台应用。因为Windows的控制台窗口使用和系统其余部分不同的编码,用户在psql中使用8位字符时必须要特别小心。如果psql检测到一种有问题的控制台代码页,它将会在启动时警告用户。要更改控制台代码页,有两件事是必需的:

输入下面的命令设置代码页:
cmd.exe /c chcp 1252
1252是Latin字母表的字符编码,微软Windows把它用于英语和某些其他西方语言。如果用户在使用Cygwin,可以把这个命令放在/etc/profile中。

设置控制台字体为Lucida Console,因为栅格字体无法在ANSI代码页下工作。

示例

以交互模式启动psql

psql -p 54321 -U sally mydatabase

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    |

通过传递一个含有SQL命令的文件把psql运行在非交互模式:

psql -f /home/gpadmin/test/myscript.sql