psql
Greenplum数据库的交互式命令行接口
概要
psql [option ...] [dbname [username]]
描述
psql
是Greenplum数据库的基于终端的前端。
它使您能够以交互方式键入查询,将其发布到Greenplum数据库,并查看查询结果。
或者,输入可以来自文件。
此外,它提供了许多元命令和各种类似于shell的功能,以帮助编写脚本和自动化各种任务。
选项
-a | --echo-all
读取时将所有非空输入行打印到标准输出。
(这不适用于以交互方式读取的行。)
这等效于将变量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
的标准输入时的行为不同。
此外,仅返回最后一个SQL命令的结果。
-d dbname | --dbname=dbname
指定要连接的数据库的名称。这等效于在命令行上将dbname指定为第一个非选项参数。
如果此参数包含=
符号或以有效的URI前缀(postgresql://
或postgres://
)开头,则将其视为conninfo
字符串。
有关更多信息,请参见PostgreSQL文档中的连接字符串。
-e | --echo-queries
将所有发送到服务器的SQL命令复制到标准输出。
-E | --echo-hidden
回显由\d
和其他反斜杠命令生成的实际查询。
您可以使用它来研究psql
的内部操作。
这等效于将变量ECHO_HIDDEN设置为on
。
-f filename | --file=filename
使用filename作为命令源,而不是交互读取命令。
处理完文件后,psql
终止。
在许多方面,这等效于元命令\i
。
如果文件名是-
(连字符),则将读取标准输入,直到EOF指示或\q
元命令为止。
但是请注意,在这种情况下不使用Readline(就像已指定-n
一样)。
使用此选项与编写psql < filename
稍有不同。
通常,两者都可以达到您的期望,但是使用-f
可以启用一些不错的功能,例如带有行号的错误消息。
使用此选项还可能会减少启动开销。
另一方面,使用shell的输入重定向的变体在理论上可以保证产生与您手工输入的所有内容完全相同的输出。
-F separator | --field-separator=separator
使用指定的分隔符作为未对齐输出的字段分隔符。 -H | --html 打开HTML表格输出。 -l | --list 列出所有可用的数据库,然后退出。其他非连接选项将被忽略。
-L filename | --log-file=filename
除正常输出目标外,还将所有查询输出写入指定的日志文件。
-n | --no-readline 不要将Readline用于行编辑,也不要使用命令历史记录。 剪切和粘贴时,这对于关闭选项卡扩展很有用。
-o filename | --output=filename
将所有查询输出放入指定的文件。 -P assignment | --pset=assignment
允许您在命令行上以\pset
样式指定打印选项。
请注意,这里必须用等号(而不是空格)分隔名称和值。
因此,要将输出格式设置为LaTeX
,可以编写-P format=latex
。
-q | --quiet
指定psql
应该安静地工作。
默认情况下,它打印欢迎消息和各种信息输出。
如果使用此选项,则不会发生任何情况。
这对于-c
选项很有用。
这等效于将变量QUIET设置为on
。
-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
meta命令。
请注意,必须在命令行上用等号分隔名称和值(如果有)。
要取消设置变量,请取消等号。
要将变量设置为空值,请使用等号,但不要使用该值。
这些分配是在启动的非常早期阶段完成的,因此保留给内部使用的变量可能会在以后被覆盖。
-V | --version
打印psql
版本并退出。
-x | --expanded
打开扩展表格式模式。
-X | --no-psqlrc
不要读取启动文件(系统范围内的psqlrc
文件或用户的~/.psqlrc
文件都不能读取)。
-z | --field-separator-zero
将未对齐输出的字段分隔符设置为零字节。
-0 | --record-separator-zero
将未对齐输出的记录分隔符设置为零字节。
这对于例如与xargs -0
配合非常有用。
-1 | --single-transaction
当psql
执行脚本时,
添加此选项会将BEGIN
/COMMIT
包装在脚本周围,以将其作为单个事务执行。
这样可以确保所有命令都成功完成,或者不应用任何更改。
如果脚本本身使用BEGIN
,COMMIT
或ROLLBACK
,则此选项将不会达到预期的效果。
另外,如果脚本包含无法在事务块内执行的任何命令,则指定此选项将导致该命令(并因此导致整个事务)失败。
-? | --help
显示有关psql
命令行参数的帮助,然后退出。
连接选项
-h host | --host=host
运行Greenplum数据库master数据库服务器的计算机的主机名。
如果未指定,则从环境变量PGHOST
读取或默认为localhost。
在master主机上启动psql
时,如果host值以斜杠开头,则它将用作UNIX域套接字的目录。
-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主服务器的主机名和端口号以及要用作连接的数据库用户名。
可以通过命令行选项(分别为-d
,-h
,-p
和-U
)告知psql
这些参数。
如果找到的参数不属于任何选项,它将被解释为数据库名称(或用户名,如果已经给出数据库名称)。
并非所有这些选项都是必需的;有一些可用的默认值。
如果省略主机名,则psql
将通过UNIX域套接字连接到本地主机上的master服务器,或者通过TCP/IP连接到没有UNIX域套接字的计算机上的localhost
。
默认的master端口号是5432。
如果为master使用其他端口,则必须指定端口。
默认数据库用户名是您的操作系统用户名,默认数据库名也是如此。
请注意,您不能仅以任何用户名连接到任何数据库。
您的数据库管理员应已将您的访问权限告知您。
当默认值不合适时,可以通过将任何或所有环境变量PGAPPNAME
,
PGDATABASE
,PGHOST
,PGPORT
和PGUSER
设置为适当的值来节省键入时间。
拥有~/.pgpass
文件也很方便,可以避免定期输入密码。
该文件应位于您的主目录中,并包含以下格式的行:
hostname:port:database:username:password
.pgpass
的权限必须禁止任何其他用户或组的访问(例如:chmod 0600 ~/.pgpass
)。
如果权限不严格于此权限,则文件将被忽略。
(但是,当前未在Microsoft Windows客户端上检查文件权限。)
指定连接参数的另一种方法是在conninfo
字符串或URI中,而不是使用数据库名称。
这种机制使您可以非常广泛地控制连接。
例如:
$ psql "service=myservice sslmode=require"
$ psql postgresql://gpmaster:5433/mydb?sslmode=require
这样,您还可以按照PostgreSQL文档中的LDAP查找连接参数中所述使用LDAP进行连接参数查找。 有关所有可用连接选项的更多信息,请参见PostgreSQL文档中的参数关键字。
如果由于某种原因(权限不足,服务器未运行等)而无法建立连接,则psql
将返回错误并终止。
如果标准输入或标准输出中至少有一个是终端,则psql
会将客户端编码设置为auto
,
它将从语言环境设置(Unix系统上的LC_CTYPE
环境变量)中检测适当的客户端编码。
如果无法按预期进行,则可以使用环境变量PGCLIENTENCODING
覆盖客户端编码。
输入SQL命令
在正常操作中,psql
会提示您输入当前已连接psql
的数据库的名称,
后跟字符串=>(对于常规用户)或=#(对于超级用户)。
例如:
testdb=>
testdb=#
在提示符下,用户可以键入SQL命令。 通常,当到达命令终止分号时,会将输入行发送到服务器。 行尾不会终止命令。 因此,为了清楚起见,命令可以分布在几行上。 如果命令已正确发送和执行,则命令的结果将显示在屏幕上。
如果不受信任的用户可以访问未采用安全模式使用模式的数据库,
请通过从search_path中删除可公开写入的模式来开始会话。
您可以在连接字符串中添加options=-csearch_path=
或在其他SQL命令之前发出SELECT pg_catalog.set_config('search_path', '', false)
。
此注意事项并非特定于psql
;它适用于执行任意SQL命令的每个接口。
元命令
在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命令(如果存在的话)。
这样SQL和psql
命令可以自由的在一行里面混合。
但是在任何情况下,一条元命令的参数不能延续超过行尾。
下面是已定义的元命令:
\a
如果目前的表输出格式是不对齐的,则切换成对齐的。
如果是对齐的,则切换成不对齐。
这条命令是为了向后兼容。
参阅\pset
获取一个更通用的解决方法。
\c | \connect [dbname [username] [host] [port]] | conninfo
与一个PostgreSQL服务器建立一个新的连接。
要使用的连接参数通过位置语法或者使用conninfo
连接字符串(在libpq连接字符串描述)指定。
如果该命令省略了数据库名称,用户,主机或端口,则新连接可以重用先前连接中的值。
默认情况下,除了处理conninfo
字符串时,都将重用先前连接的值。
传递-reuse-previous=on
或-reuse-previous=off
的第一个参数将覆盖该默认值。
当命令既未指定也不重用特定参数时,将使用libpq
缺省值。
将dbname,username,host或port中的任何一个指定为-
等同于省略该参数。
如果成功制作了新连接,那么关闭以前的连接。
如果连接失败,那么仅当psql
处于交互模式时将保留前面的连接。
如果运行的是非交互的脚本,处理会马上停止并返回一个错误。
设置这样的区别一方面是为用户使用方便考虑,另一方面也为了保证脚本不会碰巧操作了错误的数据库的安全机制考虑。
示例:
=> \c mydb myuser host.dom 6432
=> \c service=foo
=> \c "host=localhost port=5432 dbname=mydb connect_timeout=10 sslmode=disable"
=> \c postgresql://tom@localhost/mydb?application_name=myapp
\C [title]
把正在打印的表的标题设置为一个查询的结果或者取消这样的设置。
这条命令等效于\pset title
。
\cd [directory]
把当前工作目录改变到directory。
没有参数则是改变到当前用户的家目录。
使用\!pwd
打印出当前工作目录。
\conninfo
显示有关当前连接的信息,包括数据库名称,用户名,连接类型(UNIX域套接字,TCP/IP
等),主机和端口。
\copy { table [(column_list)] |
(query)} { from | to} { 'filename' | program
'command' | stdin | stdout | pstdin | pstdout} [with]
(option [, ...]) ]
执行前端(客户端)拷贝。
这是一个运行SQL [COPY](../../ref_guide/sql_commands/COPY.html#topic1)
命令的操作,
不同的是服务器在读写指明的文件,而psql
读写文件并作为本地的文件系统和服务器之间的跳板取出或写入数据。
这意味着文件访问性和权限都是本地用户的,而不是服务器的,因此不需要SQL超级用户权限。
当指定了program
时,command是通过psql
执行的,
并且来自或到达command的数据在服务器和客户端之间传送。
再次,文件访问性和权限都是本地用户的,而不是服务器的,因此不需要SQL超级用户权限。
\copy ... from stdin | to stdout
分别基于命令输入和输出进行读/写。
从发出命令的同一源读取所有行,直到\.
为止或流到达EOF
。
输出被发送到与命令输出相同的位置。
要从psql
的标准输入或输出读取/写入,请使用pstdin
或pstdout
。
此选项对于在SQL脚本文件中内联填充表很有用。
该命令的语法与SQL [COPY](../../ref_guide/sql_commands/COPY.html#topic1)
命令的语法相似,并且option必须指示SQL COPY
命令的选项之一。
请注意,因此,特殊的解析规则适用于\copy
命令。
特别是,变量替换规则和反斜杠转义不适用。
此操作不如SQL COPY
命令有效,因为所有数据都必须通过客户端/服务器连接传递。
\copyright 显示Greenplum数据库所基于的PostgreSQL的版权和发行条款。
\d [relation_pattern] | \d+ [relation_pattern]
| \dS [relation_pattern]
对于每个匹配pattern的关系 (表、视图、索引、序列或外部表)或复合类型,
显示所有列、它们的类型、表空间(如果不是缺省的)和任何特殊属性(诸如NOT NULL
或缺省等)。
相关的索引、约束、规则、触发器也同样显示出来。
对于外部表,也显示相关的外部服务器。
- 对于一些关系类型,
\d
为每个字段显示了额外的信息: 序列的字段值,索引的索引表达式和外部表的外部数据封装器选项。- 命令形式
\d+
相同,除了显示更多信息:显示与表的列关联的所有注释,以及表中是否存在OID,如果关系是视图,则为视图定义。 对于分区表,用根分区表或子分区表指定的命令\d
或\d+
显示有关该表的信息,包括分区表当前级别上的分区键。 命令\d+
还显示表的直接子分区以及该子分区是外部表还是常规表。
- 命令形式
对于追加优化的表和面向列的表,\d+
显示表的存储选项。
对于追加优化的表,将显示该表的选项。
对于面向列的表,将为每列显示存储选项。
- 缺省的,只显示用户创建的对象;应用一个模式或
S
修饰符包含系统对象。
Note: 如果不带任何pattern参数调用\d
,那么等效于\dtvsE
,
将显示一个所有可见表,视图,序列和外部表的列表。
\da[S] [aggregate_pattern]
列出聚合函数,以及它们的返回类型和操作的数据类型。
如果声明了pattern,那么只显示匹配模式的聚合函数。
缺省的,只显示用户创建的对象;应用一个模式或S
修饰符包含系统对象。
\db[+] [tablespace_pattern] 列出所有可用的表空间及其对应的路径。 如果指定了模式,则仅显示名称与模式匹配的表空间。 如果在命令名称后附加+,则会列出每个对象及其关联的权限。
\dc[S+] [conversion_pattern]
列出字符集编码之间的转换。
如果指定了模式,则仅列出名称与该模式匹配的转换。
默认情况下,仅显示用户创建的对象。
提供一个模式或S
修饰符以包含系统对象。
如果在命令名称后附加+
,则会列出每个对象及其相关描述。
\dC[+] [pattern]
列出类型转换。
如果指定了模式,则仅列出其源或目标类型与该模式匹配的转换。
如果在命令名称后附加+
,则会列出每个对象及其相关描述。
\dd[S] [pattern]
显示类型constraint
,operator class
,operator family
,rule
和trigger
的对象的描述。
所有其他注释都可以通过相应的反斜杠命令查看那些对象类型。
\dd
显示与模式匹配的对象的描述,或者如果没有给出参数,则显示适当类型的可见对象的描述。
但无论哪种情况,仅列出具有描述的对象。
默认情况下,仅显示用户创建的对象。
提供一个模式或S
修饰符以包含系统对象。
可以使用COMMENT
SQL命令创建对象的描述。
\ddp [pattern] 列出默认的访问权限设置。 将为每个角色(和模式,如果适用)显示一个条目,其默认权限设置已从内置默认值更改。 如果指定了pattern,则仅列出角色名称或模式名称与模式匹配的条目。
ALTER DEFAULT PRIVILEGES命令用于设置默认访问权限。 特权显示的含义在GRANT下进行了说明。
\dD[S+] [domain_pattern]
列出域。如果指定了模式,则仅显示名称与该模式匹配的域。
默认情况下,仅显示用户创建的对象。
提供一个模式或S
修饰符以包含系统对象。
如果在命令名称后附加+
,则会列出每个对象及其关联的权限和描述。
\dEistPv[S+] [external_table | index | sequence | table | parent table |
view]
这不是实际的命令名称:字母E
,i
,s
,t
,P
和v
分别代表外部表,
索引,序列,表,父表和视图。
您可以按任何顺序指定任何或所有这些字母,以获得这些类型的对象的列表。
例如,\dit
列出索引和表。
如果在命令名称后附加+
,则会列出每个对象及其在磁盘上的物理大小及其相关的描述(如果有)。
如果指定了模式,则仅列出名称与该模式匹配的对象。
默认情况下,仅显示用户创建的对象。
提供一个模式或S
修饰符以包含系统对象。
\des[+] [foreign_server_pattern]
列出外部服务器。
如果指定了模式,则仅列出名称与该模式匹配的服务器。
如果使用\des+
形式,则会显示每个服务器的完整描述,包括服务器的ACL,类型,版本,选项和描述。
\det[+] [foreign_table_pattern]
列出所有外部表。
如果指定了模式,则仅列出其表名或模式名称与该模式匹配的条目。
如果使用\det+
形式,则还将显示通用选项和外部表描述。
\deu[+] [user_mapping_pattern]
列出用户映射。
如果指定了模式,则仅列出其用户名与模式匹配的那些映射。
如果使用\deu+
形式,则会显示有关每个映射的其他信息。
Warning: \deu+
可能也显示远程用户的用户名和密码,所以要小心不要透漏它们。
\dew[+] [foreign_data_wrapper_pattern]
列出外部数据包装器。
如果指定了模式,则仅列出名称与该模式匹配的数据包装器。
如果使用\dew+
形式,则还将显示ACL,选项和外部数据包装程序的描述。
\df[antwS+] [function_pattern]
列出函数以及它们的参数,返回类型和函数类型,这些函数分为“agg”(聚合),“normal”,“trigger”或“window”。
要仅显示特定类型的函数,请在命令中添加相应的字母a
,n
,t
或w
。
如果指定了模式,则仅显示名称与该模式匹配的函数。
如果使用\df+
形式,则会显示有关每个函数的其他信息,包括安全性,易变性,语言,源代码和描述。
默认情况下,仅显示用户创建的对象。
提供一个模式或S
修饰符以包含系统对象。
\dF[+] [pattern]
列出文本搜索配置。
如果指定了模式,则仅显示名称与该模式匹配的配置。
如果使用\dF+
形式,则会显示每个配置的完整描述,包括基础文本搜索解析器和每种解析器令牌类型的字典列表。
\dFd[+] [pattern]
列出文本搜索词典。
如果指定了模式,则仅显示名称与该模式匹配的词典。
如果使用\dFd+
形式,则会显示有关每个所选词典的其他信息,包括基础的文本搜索模板和选项值。
\dFp[+] [pattern]
列出文本搜索解析器。
如果指定了模式,则仅显示名称与模式匹配的解析器。
如果使用\dFp+
形式,则会显示每个解析器的完整说明,包括基础函数和已识别令牌类型的列表。
\dFt[+] [pattern]
列出文本搜索模板。
如果指定了模式,则仅显示名称与该模式匹配的模板。
如果使用\dFt+
形式,则会显示有关每个模板的其他信息,包括基础函数名称。
\dg[+] [role_pattern]
列出数据库角色。
(由于将“用户”和“组”的概念统一为“角色”,因此该命令现在等效于\du
。)
如果指定了模式,则仅列出名称与模式匹配的角色。
如果使用\dg+
形式,则将显示有关每个角色的其他信息;否则,将显示其他信息。
目前,这会为每个角色添加注释。
\dl
这是\lo_list
的别名,其中显示了大对象列表。
Note: Greenplum数据库不支持PostgreSQL 大对象工具来流存储在大对象结构中的用户数据。
\dL[S+] [pattern]
列出过程语言。
如果指定了模式,则仅列出名称与该模式匹配的语言。
默认情况下,仅显示用户创建的语言。
提供S
修饰符以包括系统对象。
如果在命令名称后附加+
,则将列出每种语言及其调用处理程序,验证程序,访问特权以及是否为系统对象。
\dn[S+] [schema_pattern]
列出所有可用的模式(名称空间)。
如果指定了模式,则仅列出名称与模式匹配的模式。
默认情况下,仅显示用户创建的对象。
提供一个模式或S
修饰符以包含系统对象。
如果在命令名后附加+
,则列出每个对象及其相关的权限和描述(如果有)。
\do[S] [operator_pattern]
列出可用的运算符及其操作数和返回类型。
如果指定了模式,则仅列出名称与模式匹配的运算符。
默认情况下,仅显示用户创建的对象。
提供一个模式或S
修饰符以包含系统对象。
\dO[S+] [pattern]
列出排序规则。
如果指定了模式,则仅列出名称与模式匹配的排序规则。
默认情况下,仅显示用户创建的对象。
提供一个模式或S
修饰符以包含系统对象。
如果在命令名称后附加+
,则将列出每个排序规则及其关联的描述(如果有)。
请注意,仅显示可与当前数据库的编码一起使用的排序规则,因此在同一安装的不同数据库中,结果可能会有所不同。
\dp [relation_pattern_to_show_privileges]
列出具有相关访问权限的表,视图和序列。
如果指定了模式,则仅列出名称与该模式匹配的表,视图和序列。
[GRANT](../../ref_guide/sql_commands/GRANT.html#topic1)
和[REVOKE](../../ref_guide/sql_commands/REVOKE.html#topic1)
命令用于设置访问权限。
特权显示的含义在[GRANT](../../ref_guide/sql_commands/GRANT.html#topic1)
下进行了说明。
\drds [role-pattern [database-pattern]]
列出定义的配置设置。
这些设置可以是角色特定的,数据库特定的或两者。
role-pattern和database-pattern分别用于选择特定角色和要列出的数据库。
如果省略,或者指定*
,则列出所有设置,包括分别不是角色特定的或数据库特定的设置。
ALTER ROLE和ALTER DATABASE命令用于定义每个角色和每个数据库的角色配置设置。
\dT[S+] [datatype_pattern]
列出数据类型。
如果指定了模式,则仅列出名称与模式匹配的类型。
如果在命令名称后附加+
,则将列出每种类型及其内部名称和大小,如果是枚举类型则允许的值及其关联的权限。
默认情况下,仅显示用户创建的对象。
提供一个模式或S
修饰符以包含系统对象。
\du[+] [role_pattern]
列出数据库角色。
(由于将“用户”和“组”的概念统一为“角色”,因此此命令现在等效于\dg
。)
如果指定了模式,则仅列出名称与模式匹配的角色。
如果使用\du+
形式,则会显示有关每个角色的其他信息;
目前,这会为每个角色添加注释。
\dx[+] [extension_pattern]
列出已安装的扩展。
如果指定了模式,则仅列出名称与该模式匹配的扩展名。
如果使用\dx+
形式,则列出属于每个匹配扩展的所有对象。
\dy[+] [pattern]
列出事件触发器。
如果指定了模式,则仅列出其名称与该模式匹配的触发器。
如果在命令名称后附加+
,则会列出每个对象及其相关描述。
Note: Greenplum数据库不支持用户定义的触发器。
\e | \edit [filename] [line_number] 如果指定filename,则文件被编辑;编辑器退出后,其内容将复制回查询缓冲区。 如果未提供filename,则将当前查询缓冲区复制到一个临时文件,然后以相同的方式对其进行编辑。
然后根据psql
的常规规则重新解析新的查询缓冲区,其中整个缓冲区被视为一行。
(因此,您不能以这种方式制作脚本。为此请使用\i
。)
这也意味着,如果查询以分号结尾(或包含分号),则会立即执行该查询。
在其他情况下,它将仅在查询缓冲区中等待;输入分号或\g
发送,或\r
取消。
如果指定了行号,则psql
将光标定位在文件或查询缓冲区的指定行上。
请注意,如果给出单个全数字参数,则psql
假定它是行号,而不是文件名。
有关配置和自定义编辑器的信息,请参见环境变量。
\echo text [ ... ]
将参数输出到标准输出,中间用一个空格分隔,后跟换行符。
这对于在脚本输出中散布信息很有用。
如果第一个参数是未加引号的-n
,则不写结尾的换行符。
Note: 如果使用\o
命令重定向查询输出,则可能希望使用\qecho
代替此命令。
\ef [function_description [line_number]]
该命令以CREATE OR REPLACE FUNCTION
命令的形式获取并编辑命名函数的定义。
编辑的方式与\edit
相同。
编辑器退出后,更新的命令在查询缓冲区中等待;输入分号或\g
发送,或\r
取消。
目标函数可以仅通过名称指定,也可以通过名称和参数指定,例如foo(integer, text)
。
如果有多个具有相同名称的函数,则必须给出参数类型。
如果未指定任何函数,则会显示空白的CREATE FUNCTION
模板以供编辑。
如果指定了行号,则psql
将光标定位在函数主体的指定行上。
(请注意,函数主体通常不在文件的第一行开始。)
有关配置和自定义编辑器的信息,请参见环境变量。
\encoding [encoding] 设置客户端字符集编码。如果不带参数,此命令将显示当前编码。
\f [field_separator_string]
为未对齐的查询输出设置字段分隔符。
默认值为竖线(|
)。
另请参阅\pset
以获取设置输出选项的通用方法。
\g [filename]
\g [ |
command ]
将当前查询输入缓冲区发送到服务器,并有选择地将查询的输出存储到filename中,或将输出通过管道传递给shell命令command。
仅当查询成功返回零个或多个元组时,才写入文件或命令,如果查询失败或是不返回数据的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 [sql_command]
提供有关指定SQL命令的语法帮助。
如果未指定命令,则psql
将列出所有可使用语法帮助的命令。
如果command是星号(*
),则会显示所有SQL命令的语法帮助。
为了简化键入,不必引用由几个单词组成的命令。
\H | \html
打开HTML查询输出格式。
如果HTML格式已打开,则将其切换回默认的对齐文本格式。
此命令是为了兼容性和方便起见,但有关设置其他输出选项的信息,请参见\pset
。
\i | \include filename
从文件filename中读取输入,并像在键盘上键入文件一样执行它。
如果filename是-
(连字符),则将读取标准输入,直到EOF指示或\q
元命令为止。
这可用于将交互式输入与文件输入进行穿插。
请注意,只有在最外层处于活动状态时,才会使用Readline行为。
如果要在阅读时看到屏幕上的行,必须将变量ECHO
设置为all
。
\ir | \include_relative filename
\ir
命令类似于\i
,但是以不同的方式解析相对文件名。
在交互模式下执行时,两个命令的行为相同。
但是,从脚本调用时,\ir
会相对于脚本所在目录而不是当前工作目录来解释文件名。
\l[+] | \list[+] [pattern]
列出服务器中的数据库,并显示其名称,所有者,字符集编码和访问特权。
如果指定了模式,则仅列出名称与该模式匹配的数据库。
如果在命令名称后附加+
,则还会显示数据库大小,默认表空间和描述。
(大小信息仅适用于当前用户可以连接到的数据库。)
\lo_export loid filename
从数据库读取OID loid的大对象,并将其写入filename。
请注意,这与服务器函数lo_export
稍有不同,后者以数据库服务器运行的用户权限和服务器文件系统上的用户权限运行。
使用\lo_list
找出大对象的OID。
Note: Greenplum数据库不支持PostgreSQL大对象工具来流存储在大对象结构中的用户数据。
\lo_import large_object_filename [comment] 将文件存储到大对象中。 (可选)它将给定的注释与对象相关联。例:
mydb=> \lo_import '/home/gpadmin/pictures/photo.xcf' 'a
picture of me'
lo_import 152801
该响应表明大对象接收到对象ID 152801,如果要再次访问该对象,应该记住该对象。
因此,建议始终将可读的注释与每个对象相关联。
然后可以使用\lo_list
命令查看这些内容。
请注意,此命令与服务器端lo_import
略有不同,因为它充当本地文件系统上的本地用户,而不是服务器的用户和文件系统。
Note: Greenplum数据库不支持PostgreSQL大对象工具来流存储在大对象结构中的用户数据。
\lo_list 显示当前存储在数据库中的所有大型对象的列表,以及为其提供的任何注释。
Note: Greenplum数据库不支持PostgreSQL大对象工具来流存储在大对象结构中的用户数据。
\lo_unlink largeobject_oid
从数据库中删除指定OID的大对象。使用\lo_list
找出大对象的OID。
Note: Greenplum数据库不支持PostgreSQL大对象工具来流存储在大对象结构中的用户数据。
\o | \out [ filename ]
\o | \out [ |
command ]
将将来的查询结果保存到filename,或将将来的结果通过管道传递给shell命令command。
如果未指定任何参数,则查询输出将重置为标准输出。
查询结果包括从数据库服务器获得的所有表,命令响应和通知,
以及查询数据库的各种反斜杠命令的输出(例如\d
),但不包括错误消息。
要在查询结果之间插入文本输出,请使用\qecho
。
\p
将当前查询缓冲区打印到标准输出。
\password [username]
更改指定用户(默认情况下为当前用户)的密码。
该命令提示输入新密码,对其进行加密,然后将其作为ALTER ROLE
命令发送到服务器。
这样可以确保新密码不会在命令历史记录,服务器日志或其他地方以明文形式出现。
\prompt [ text ] name
提示用户提供文本,该文本已分配给变量name。 可以指定一个可选的提示字符串,text。 (对于多字提示,请用单引号将文本引起来。)
默认情况下,\prompt
使用终端进行输入和输出。
但是,如果使用-f
命令行开关,\prompt
将使用标准输入和标准输出。
\pset [print_option [value]] 此命令设置影响查询结果表输出的选项。 print_option描述了要设置的选项。 value的语义取决于所选选项。 对于某些选项,省略value会导致该选项被切换或取消设置,如特定选项所述。 如果未提及此类行为,则省略value只会导致显示当前设置。
没有任何参数的\pset
将显示所有打印选项的当前状态。
可调打印选项包括: *border
–
value必须是一个数字。
通常,数字越大,表就有越宽的边界和越多的线,但是这个参数取决于实际的格式。
在HTML格式中,这个参数会直接翻译成border=...
属性,
在其它的格式中,只有值0
(无边界)、1
(内部分隔线)、2
(表框架)有意义。
latex
和latex-longtable
也支持border
值为3,在每行之间添加一个分隔线。
columns
– 设置wrapped
格式的目标宽度,以及用于确定输出是否足够宽以要求分页或在扩展自动模式下切换到垂直显示的宽度限制。 默认值为零。 零导致目标宽度由环境变量COLUMNS
控制,如果未设置COLUMNS
,则检测到的屏幕宽度。 另外,如果columns
为零,则wrapped
格式仅影响屏幕输出。 如果columns
不为零,则文件和管道输出也将被包装为该宽度。 设置目标宽度后,请使用\pset format wrapped
命令启用包装格式。expanded
|x
– 如果指定了value,则必须是on
或off
,这将启用或禁用扩展模式或auto
。 如果省略value,该命令将在on
和off
设置之间切换。 启用扩展模式后,查询结果将显示在两列中,列名在左侧,数据在右侧。 如果在正常的“水平”模式下数据无法显示在屏幕上,则此模式很有用。 在auto
设置中,只要查询输出比屏幕宽,就使用扩展模式,否则使用常规模式。auto
设置仅在对齐和包装的格式中有效。 在其他格式下,它始终表现为关闭扩展模式。fieldsep
– 指定在未对齐输出模式下使用的字段分隔符。 这样,就可以创建制表符或逗号分隔的输出,而其他程序可能更喜欢这种输出。 要将选项卡设置为字段分隔符,请键入\pset fieldsep '\t'
。 默认字段分隔符为'|'
(竖线)。fieldsep_zero
- 设置非对齐输出格式中使用的域分隔符为0字节。footer
– 如果指定了value,则必须将其打开或关闭,这将启用或禁用表脚的显示((n行)计数)。 如果省略value,则该命令将打开或关闭页脚显示。format
– 将输出格式设置为unaligned
,aligned
,html
,latex
(使用tabular
),latex-longtable
,troff-ms
或wrapped
之一。 允许使用唯一的缩写,包括一个字母。unaligned
格式将一行的所有列写在一行上,由当前活动的字段分隔符分隔。 这对于创建可能打算由其他程序读取的输出(例如,制表符分隔或逗号分隔的格式)很有用。
aligned
格式是标准的,人类可读的,格式良好的文本输出;这是默认值。
html
,latex
,latex-longtable
和troff-ms
模式把表输出为可用于文档里的对应标记语言。
它们还不是完整的文档!
(可能对于HTML变化还不是太大,但是在LaTeX中,您必须具有完整的文档包装器。
latex-longtable
也需要LaTeX longtable
和booktabs
软件包。)
wrapped
格式类似于aligned
,但是在行之间包装宽数据值以使输出适合目标列宽。
目标宽度是根据columns
选项下所述确定的。
请注意,psql
不会尝试包装列标题。
如果列标题所需的总宽度超过目标,则wrapped
格式与aligned
的行为相同。
linestyle
[unicode
|ascii
|old-ascii
] – 将边界线绘制样式设置为unicode,ascii或old-ascii中的一种。 三种样式允许使用唯一的缩写,包括一个字母。 默认设置为ascii
。 此选项仅影响aligned
和wrapped
的输出格式。ascii
– 使用纯ASCII字符。 数据中的换行符在右边距中使用+
符号显示。 当换行格式将数据从一行换行到下一行而没有换行符时,在第一行的右边距中显示一个点(.
),在下一行的左边距中再次显示一个点(.
)。
old-ascii
– 样式使用纯ASCII字符,并使用PostgreSQL 8.4及更早版本中使用的格式样式。
数据中的换行符用:
符号代替左侧的列分隔符。
当数据从一行到另一行的换行而没有换行符时,;
符号用于代替左侧的列分隔符。
unicode
– 样式使用Unicode框画字符。
数据中的换行符在右边缘使用回车符显示。
当数据从一行换行到下一行而没有换行符时,在第一行的右边距中显示省略号,并在下一行的左边距中显示省略号。
当border
设置大于零时,此选项还确定绘制边框线所使用的字符。
纯ASCII字符在任何地方都可以使用,但是Unicode字符在可以识别它们的显示器上看起来更好。
null 'string'
– 第二个参数是一列为空时要打印的字符串。 默认设置为不打印任何内容,这很容易被误认为是空字符串。 例如,可能更喜欢\pset null '(null)'
。numericlocale
– 如果指定了value,则必须将其打开或关闭, 这将启用或禁用显示特定于语言的字符以将小数点标记左侧的数字组分开。 如果省略value,则该命令在常规和特定于区域的数字输出之间切换。pager
– 控制用于查询和psql
帮助输出的分页器程序的使用。 如果设置了环境变量PAGER
,则将输出通过管道传递到指定的程序。 否则,将使用依赖于平台的默认值(例如more
)。 禁用时,不使用分页器程序。 启用时,仅在适当的时候使用分页器,即当输出到终端且不匹配屏幕时。 也可以将分页器设置为always
,这将使该分页器用于所有终端输出,而不管其是否适合屏幕显示。\pset pager
(不带value)可打开和关闭分页器的使用。recordsep
– 声明在非对齐模式时的记录分隔符。缺省是换行符。recordsep_zero
- 设置在非对齐输出格式中使用的记录分隔符为0字节。tableattr
|T
[text] – 在HTML格式下,这指定了要放置在table
标签中的属性。 例如cellpadding
或bgcolor
。 请注意,你可能不需要在这里声明border
,因为已经在\pset border
里用过了。 如果没有给出value,那么表的属性是未设置的。 在latex-longtable
格式中,这控制每个包含左对齐数据类型的字段的比例宽度。 它声明为空白分隔的值列表,比如'0.2 0.2 0.6'
。 未指定的输出列使用最后指定的值。title
[text] – 为任何随后打印的表设置标题。 这个参数可以用于给你的输出一个描述性标记。 如果没有给出value,则标题未设置。tuples_only
|t
[novalue | on | off] – 如果指定了value,那么必须是on
或off
,这将启用或禁用仅元组模式。 如果省略了value,那么该命令在普通和仅元组输出间切换。 普通输出包括额外的信息,比如列头、标题、各种脚注等。 在仅元组模式下,只显示实际的表数据。\t
命令等效于\pset``tuples_only
,并且为方便起见而提供。
Tip:
有很多用于\pset
的快速命令。
参阅\a
, \C
, \f
,
\H
, \t
, \T
和\x
。
\q | \quit
退出psql
程序。在脚本文件中,仅终止该脚本的执行。
\qecho text [ ... ]
此命令与\echo
相同,除了输出将被写入\o
设置的查询输出通道外。
\r | \reset
重置(清除)查询缓冲区。
\s [filename]
将psql
的命令行历史记录打印到filename
。
如果省略filename
,则将历史记录写入标准输出(如果合适,使用分页器)。
如果psql
是在没有Readline
支持的情况下构建的,则此命令不可用。
\set [name [value [ ... ]]]
将psql
变量name设置为value,或者如果给定多个值,则将其全部串联。
如果仅给出一个参数,则该变量将设置为空值。
要取消设置变量,请使用\unset
命令。
没有任何参数的\set
将显示所有当前设置的psql
变量的名称和值。
有效的变量名称可以包含字符,数字和下划线。 请参阅高级特性中的“变量”。 变量名称区分大小写。
尽管你可以设置任何变量为任意值,psql
对一些变量特殊对待。
它们在关于变量的小节里面有文档。
该命令与SQL命令[SET](../../ref_guide/sql_commands/SET.html#topic1)
无关。
\setenv name [ value ] 将环境变量name设置为value, 或者如果未提供该value,则取消设置环境变量。例:
testdb=> \setenv PAGER less
testdb=> \setenv LESS -imx4F
\sf[+] function_description
该命令以CREATE OR REPLACE FUNCTION
命令的形式获取并显示命名函数的定义。
定义将打印到\o
设置的当前查询输出通道。
目标函数可以仅通过名称指定,也可以通过名称和参数指定,例如foo(integer, text)
。
如果有多个相同名称的函数,则必须提供参数类型。
如果在命令名称后附加+
,则对输出行进行编号,函数主体的第一行为行1。
\t [novalue | on | off]
\t
命令本身可切换输出列名称标题和行计数页脚的显示。
无论当前设置如何,打开和关闭的值都会设置元组显示。
此命令等效于\pset tuples_only
,并且为方便起见而提供。
\T table_options
声明HTML输出格式中放在table
标记里的属性。
此命令等效于\pset tableattr
table_options
\timing [novalue | on | off] 如果没有参数,则以毫秒为单位切换显示每个SQL语句花费的时间。 无论当前设置如何,打开和关闭的值都会设置时间显示。
\unset name
取消设置(删除)psql
变量name。
\w | \write filename
\w | \write |
command
将当前查询缓冲区输出到filename或将其通过管道传递给shell命令command。
\watch [seconds]
重复执行当前查询缓冲区(如\g
),直到被中断或查询失败。
在两次执行之间等待指定的秒数(默认为2)。
\x [ on | off | auto ]
设置或切换扩展表格式设置模式。
因此,它等效于\pset expanded
。
\z [pattern]
列出具有相关访问权限的表,视图和序列。
如果指定了模式,则仅列出名称与该模式匹配的表,视图和序列。
这是\dp
的别名。
\! [command] 转义到单独的shell或执行shell命令command。 参数不会被进一步解释,shell 将看到全部参数。 特别是,变量替换规则和反斜杠转义不适用。
\?
显示有关psql
反斜杠命令的帮助信息。
模式
各种\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
的表。
在模式中,*
匹配任何字符序列(包括无字符)和?
匹配任何单个字符。
(此表示法可与UNIX Shell文件名模式相提并论。)
例如,\dt int*
显示名称以int
开头的所有表。
但是在双引号内,*
和?
失去了这些特殊含义,只是字面上的匹配。
包含点(.
)的模式被解释为模式名称模式,后跟对象名称模式。
例如,\dt foo*.bar*
将显示其表名以bar
开头的所有表,这些表的模式名以foo
开头。
如果没有点出现,则该模式仅匹配在当前模式搜索路径中可见的对象。
同样,双引号中的点失去其特殊含义,并且在字面上匹配。
高级用户可以使用正则表达式。
除了.
如上所述被当做分隔符,*
将被理解成.*
,?
将被理解成.
,
所有正则表达式特殊字符均按PostgreSQL正则表达式文档的规定工作。
这样一来,你就可以用?
代替.
、 用(R+|)
代替R*
、 用(R|)
代替R?
。
请记住,模式必须匹配全名,这与对正则表达式的通常解释不同;如果您不希望锚定模式,请在开头和/或结尾处输入*
。
请注意,在双引号中,所有正则表达式特殊字符都会失去其特殊含义,并且会在字面上进行匹配。
同样,正则表达式特殊字符在运算符名称模式(例如\do
的参数)中按字面值进行匹配。
每当完全省略pattern参数时,\d
命令都会显示在当前模式搜索路径中可见的所有对象 – 这等效于使用模式*
。
要查看数据库中的所有对象,请使用模式*.*
。
高级特性
变量
psql
提供类似通常Unix命令shell那样的变量替换特性。
变量只是简单的名称/值对,这里的值可以是任何长度的任何值。
名字必须由字母(包括非拉丁字母)、数字和下划线组成。
要设置一个变量,使用psql元命令\set
。例如:
testdb=> \set foo bar
把变量foo
的值设置为bar
。
要检索变量的内容,在变量名前面放上冒号,例如:
testdb=> \echo :foo
bar
这在SQL命令和元命令中都能运行;更详细信息在下面的SQL代换中给出。
如果你不带第二个参数调用\set
,那么设置这个变量,带有一个空字符串作为value。
要重置(也就是删除)一个变量,使用\unset
命令。
要显示所有变量的值,不带有任何参数调用\set
。
Note: \set
的参数服从和其它命令一样的替换规则。
因此你可以构造有趣的引用,像\set :foo 'something'
这样,获得分别像Perl或PHP那样有名的"软连接"或"变量变量"。
不幸的是,用这些构造不能做任何有用的事情。
另一方面,\set bar :foo
是一个非常有效的拷贝变量的方法。
有一些常用变量被psql
特殊相待。
它们代表特定的选项设置,这些选项在运行时可以通过改变变量的值而改变,或者在某些情况下代表psql
的可变状态。
尽管你可以把这些变量用于其它用途,但是不鼓励这么做,因为程序的行为可能会变得非常奇怪。
通常,所有特殊对待的变量名都是由大写ASCII字母组成(可能还有数字和下划线)。
为了保证和未来的最大限度的兼容性,请避免使用这样的变量。
下面是一个所有特殊对待的变量列表。
AUTOCOMMIT
启用时(默认),成功完成后将自动提交每个SQL命令。
要以这种方式推迟提交,必须输入BEGIN
或START TRANSACTION
SQL命令。
禁用或未设置时,除非明确发出COMMIT
或END
,否则不会提交SQL命令。
自动提交模式的工作方式是:在任何尚未在事务块中且本身不是BEGIN
或其他事务控制命令的命令或无法在事务块内部执行的命令之前(例如VACUUM
),
为您发出隐式BEGIN
。
在自动提交模式下,必须通过输入ABORT
或ROLLBACK
明确放弃任何失败的事务。
另外请记住,如果您退出会话而不提交,则您的工作将会丢失。
自动提交模式是PostgreSQL的传统行为,但是自动提交模式更接近SQL规范。
如果您喜欢关闭自动提交,在~/.psqlrc
文件中进行设置。
COMP_KEYWORD_CASE
在完成SQL关键字时决定哪个字母使用大小写。
如果设置为lower
或upper
,则完成的单词将分别为小写或大写。
如果设置为preserve-lower
或preserve-upper
(缺省),那么完成的单词将是输入时的情况,
但是单词在没有任何输入的情况下完成,将分别是小写或大写的情况。
DBNAME 正在连接着的数据库名称。 每次与一个数据库联结都会设置这个值(包括程序启动),但是可以删除。
ECHO
如果设为all
,那么所有非空输入行在读取时都回显到标准输出。
(这不适用于交互式读取的行。)
使用-a
选项声明在程序启动时就默认这样做。
如果设置为queries,那么psql
只是在查询发送给服务器时打印到标准输出。
这个开关是-e
。
ECHO_HIDDEN
当此变量设置为on
并且反斜杠命令查询数据库时,将首先显示该查询。
此特性可帮助您研究Greenplum数据库的内部结构,并在您自己的程序中提供类似的功能。
(要在程序启动时选择此行为,请使用开关-E
。)
如果将变量设置为值noexec
,则仅显示查询,但实际上并未将其发送到服务器并执行查询。
ENCODING
当前的客户端字符集编码。
FETCH_COUNT
如果将此变量设置为大于0的整数值,则将提取SELECT
查询的结果并将其显示在这么多行的组中,而不是在显示之前收集整个结果集的默认行为。
因此,无论结果集的大小如何,仅使用有限的内存量。
启用此功能时,通常使用100到1000的设置。
请记住,使用此功能时,在显示了一些行后查询可能会失败。
尽管可以使用此特性使用任何输出格式,但是默认的对齐格式看起来很糟糕,
因为每组FETCH_COUNT
行将分别设置格式,从而导致各行组的列宽变化。
不过对于其他格式这个特性工作的很好。
HISTCONTROL
如果将这个变量设为ignorespace
,那么以空格开始的行将不会进入历史列表。
如果设置为ignoredups
,那么与以前历史记录里匹配的行也不会进入历史记录。
值ignoreboth
是上面两个的结合。
如果删除此变量或者其值为任何与上面的值不同的东西,所有交互模式读入的行都被保存入历史列表。
HISTFILE
此文件将用于存储历史列表。
默认值是~/.psql_history
。
例如,在~/.psqlrc
里使用:
\set HISTFILE ~/.psql_history- :DBNAME
将使得psql
为每个数据库维护一个独立的历史。
HISTSIZE 保存在命令历史里的命令的个数。缺省值是500 。
HOST 当前你正连接的数据库服务器主机。 这是在每次你与数据库连接时(包括程序启动)设置的,但是可以删除。
IGNOREEOF
如果删除此变量,向一个交互的psql
会话发送一个EOF
(通常是CTRL+D
)将终止应用。
如果设置为一个数字值,那么在应用终止前该数值的EOF
字符将被忽略。
如果设置了此变量但是没有数字值,缺省是10
。
LASTOID
最后影响的OID值,即为从一条INSERT
或lo_import
命令返回的值。
此变量只保证在下一条SQL命令的结果显示之前有效。
ON_ERROR_ROLLBACK
当设置为on
时,如果一个事务块里的语句产生错误,这个错误将被忽略而事务将继续。
当设置为interactive
时,这样的错误只是在交互的会话里忽略,而不是在从读取脚本文件的时候。
如果未设置或者设置为off
,事务块里一个语句生成的错误将会中止整个事务。
错误回滚的模式是通过在一个事务块的每个命令前为你隐含地发出一个SAVEPOINT
的方式工作的,在命令错误的时候回滚到该保存点。
ON_ERROR_STOP
缺省时,遇到错误后命令处理继续进行。
当这个变量设置为on
,处理会立即停止。
在交互模式下,psql
将返回到命令提示符;否则,psql
将退出,并返回错误代码3,以示这个情况与致命错误条件的区别,致命错误条件的错误代码为1。
不管在哪种情况下,任何当前运行的脚本(顶级脚本,如果有,和任何它调用的其他脚本)都将立即终止。
如果顶级命令字符串包含多个SQL命令,处理将在当前命令停止。
PORT 当前你正在连接的数据库服务器的端口。这是在每次你与数据库连接时 (包括程序启动)设置的,但是可以取消设置。
PROMPT1
PROMPT2
PROMPT3
这些指明psql
显示的提示符如何显示。参阅下面的提示符。
QUIET
设置这个变量为on
,等效于命令行选项-q
。可能在交互模式下没有什么用。
SINGLELINE
此变量等效于命令行选项-S
。
SINGLESTEP
将此变量设置为on
等效于命令行选项-s
。
USER
当前连接的数据库用户。每次您连接到数据库(包括程序启动)时都会进行设置,但是可以取消设置。
VERBOSITY
可以将此变量设置为default
,verbose
或terse
值,以控制错误报告的详细程度。
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标准。
数组切片和类型转换的冒号语法是Greenplum数据库扩展,有时可能与标准用法冲突。
将变量值转义为SQL文字或标识符的冒号引用语法是psql
扩展。
提示符
可以根据您的喜好自定义psql
提示符。
三个变量PROMPT1
,PROMPT2
和PROMPT3
包含字符串和特殊的转义序列,用于描述提示符的外观。
PROMPT1
是psql
请求新命令时显示的普通提示。
当在命令输入期间需要更多输入时(例如,因为命令未使用分号终止或未关闭引号),将显示PROMPT2
。
当您运行SQL COPY FROM STDIN
命令并且您需要在终端上输入行值时,将显示PROMPT3
。
所选提示变量的值按字面意义打印,除非遇到百分号(%
)。
根据下一个字符,某些其他文本将被替换。
定义的替换是:
%M
数据库服务器的完整主机名(带有域名),如果连接是通过UNIX域套接字的,则为[local]
;
如果UNIX域套接字的默认设置为未编译的默认位置,则为[local:/dir/name]
。
%m
数据库服务器的主机名,在第一个点处被截断,如果连接是通过UNIX域套接字的,则为[local]
。
%>
数据库服务器正在侦听的端口号。
%n
数据库会话用户名。
(此值的扩展可能在数据库会话期间由于命令SET SESSION AUTHORIZATION
的结果而改变。)
%/
当前数据库的名称。
%~
与%/
类似,但是如果数据库是您的默认数据库,则输出为~
(波浪号)。
%#
如果会话用户是数据库超级用户,则为#,否则为>。
(此值的扩展可能在数据库会话期间由于命令SET SESSION AUTHORIZATION
的结果而改变。)
%R
在PROMPT1
中通常为=
,但在单行模式下为^
或!
如果会话与数据库断开连接(如果\connect
失败,则可能发生)。
在PROMPT2
中,%R
被一个字符替换,该字符取决于psql
期望更多输入的原因:
-
如果命令尚未终止;
*
如果有未完成的/* ... */
注释;
'
,如果有一个未完成的带引号的字符串;
"
,如果有一个未完成的带引号的标识符;
$
,如果有一个未完成的带美元引号的字符串;
或者(
,如果有一个不匹配的左括号。
在PROMPT3
中,%R
不产生任何东西。
%x 事务状态:不在事务块中时为空字符串; 在事务块中时为*;或!当事务失败时;或?当事务状态不确定时(例如,因为没有连接)。
%digits 指示的八进制代码的字符被替换。 %:name:
psql
变量name
的值。
参阅高级特性中变量小节获取更多信息。
%`command`
command的输出,类似于通常的反引号替换。
%[ ... %]
提示可能包含终端控制字符,例如,这些字符会更改提示文本的颜色,背景或样式,或更改终端窗口的标题。
为了使行编辑正常工作,必须将这些非打印控制字符用%[
和%]
括起来以指定为不可见。
提示中可能会出现多个这种配对。例如,
testdb=> \set PROMPT1 '%[%033[1;33;40m%]%n@%/%R%[%033[0m%]%#'
会在兼容VT100的有颜色的终端上显示黑底黄字(33;40
)的粗体(1;
)。
要将百分号插入提示中,请输入%%
。
对于提示1和2,默认提示为'%/%R%# '
,对于提示3,默认提示为'>> '
。
命令行编辑
psql
支持NetBSD libedit库,用于方便的行编辑和检索。
当psql
退出时,命令历史记录将自动保存,而在psql
启动时,将重新加载命令历史记录。
尽管补全逻辑不声称是SQL解析器,但也支持制表符补全。
制表符补全生成的查询也可能会干扰其他SQL命令,例如SET TRANSACTION ISOLATION LEVEL
。
如果由于某种原因您不喜欢制表符补全,可以通过将其放在主目录中名为.inputrc
的文件中来将其关闭:
$if psql
set disable-completion on
$endif
环境变量
COLUMNS
如果\pset columns
为零,
则控制换行格式的宽度和以确定宽度输出是需要分页器还是应在扩展自动模式下切换为垂直格式的宽度。
PAGER
如果查询结果无法显示在屏幕上,则通过此命令通过管道传递查询结果。
典型值为more
或less
。默认值取决于平台。
可以通过将PAGER设置为空或使用\pset
命令中与分页器相关的选项来禁用该分页器的使用。
PGDATABASE PGHOST PGPORT PGUSER 默认连接参数。 PSQL_EDITOR EDITOR VISUAL
\e
和\ef
命令使用的编辑器。
按照列出的顺序检查变量;使用设置的第一个。
内置的默认编辑器在Unix系统上为vi
,在Windows系统上为notepad.exe
。
PSQL_EDITOR_LINENUMBER_ARG
当\e
或\ef
与行号参数一起使用时,此变量指定用于将起始行号传递给用户的编辑器的命令行参数。
对于Emacs或vi
等编辑器,这是一个加号。
如果选项名称和行号之间需要有空格,请在变量的值中包含尾随空格。例子:
PSQL_EDITOR_LINENUMBER_ARG='+'
PSQL_EDITOR_LINENUMBER_ARG='--line '
在Unix系统上,默认值为+
(与默认编辑器vi
对应,对许多其他常用编辑器很有用);但Windows系统上没有默认设置。
PSQL_HISTORY
命令历史记录文件的备用位置。进行波浪(~
)扩展。
PSQLRC
用户的.psqlrc
文件的备用位置。进行波浪(〜)扩展。
SHELL
命令由\!
命令执行。
TMPDIR
用于存储临时文件的目录。默认值为/tmp
。
文件
psqlrc和~/.psqlrc
除非传递了-X
或-c
选项,
否则psql
在连接数据库之后接受正常的命令之前,
尝试从系统范围的启动文件(psqlrc
),然后用户的启动文件(~/.psqlrc
)读取并执行命令。
系统范围的启动文件名为psqlrc
,可在安装的“系统配置”目录中查找,
该目录可以通过运行pg_config --sysconfdir
来准确获取。
默认情况下,相对于包含Greenplum数据库可执行文件的目录,该目录为 ../etc/
。
可以通过PGSYSCONFDIR
环境变量显式设置此目录的名称。
用户的个人启动文件名为.psqlrc
,在用户的主目录中查找。
在缺少这种概念的Windows上,个人启动文件名为%APPDATA%\postgresql\psqlrc.conf
。
可以通过PSQLRC
环境变量显式设置用户启动文件的位置。
通过在文件名后附加破折号和基础的PostgreSQL主要或次要发行版号(例如~/.psqlrc-9.4
),
可以使系统范围内的启动文件和用户的个人启动文件都特定于psql版本。
与非版本特定的文件相比,将优先读取最特定的版本匹配文件。
.psql_history
命令行历史存储在~/.psql_history
文件中,
或者在Windows里是%APPDATA%\postgresql\psql_history
文件。
历史文件的位置可以通过PSQL_HISTORY
环境变量来明确设置。
注解
psql
与相同或较旧的主要版本的服务器一起使用时效果最佳。
如果服务器的版本比psql
本身新,则反斜杠命令很可能会失败。
但是,\d
系列的反斜杠命令可以与较旧的服务器版本一起使用,尽管不一定与psql
本身更新的服务器一起使用。
运行SQL命令和显示查询结果的常规功能也应与较新的主要版本的服务器一起使用,但这不能在所有情况下都得到保证。
如果要使用psql
连接到多个具有不同主要版本的服务器,则建议使用最新版本的psql
。
另外,您可以保留每个主要版本的psql
副本,并确保使用与各自服务器匹配的版本。
但是在实践中,这种额外的复杂性应该没有必要。
Windows用户注解
psql
被构建为控制台应用程序。
由于Windows控制台窗口使用与系统其余部分不同的编码,因此在psql
中使用8位字符时必须格外小心。
如果psql
检测到有问题的控制台代码页,它将在启动时警告您。
要更改控制台代码页,需要做两件事:
通过输入以下内容来设置代码页:
cmd.exe /c chcp 1252
1252
是拉丁字母的字符编码,Microsoft 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