psql
Name
psql --
Synopsis
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。
-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 将安静地执行处理任务。 缺省时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 那样。 注意,如果有变量名和值的话,你必须在命令行上用等号分隔它们。要重置一个变量,去掉等号。这个分配是在启动的很早的阶段进行的,所以为内部使用保留的变量可能被再次覆盖。
-W
--password
导致 psql 在与一个数据库联接前提示输入口令。 这个选项将在整个会话过程中有效,即使你用元命令 \connect 改变了所联接的数据库。
在当前版本里,如果服务器要求口令认证,psql 自动提出一个口令提示符。因为目前这个特性是以一个“hack”为基础,自动识别有可能奇怪地失效,因此用这个选项强制一个提示符。 如果没有声明口令提示符而服务器要求口令认证,那么联接企图将失败。
-x
--expanded
打开扩展表格式模式。等效于 \x。
-X,
--no-psqlrc
不读取启动文件(系统的 psqlrc 或者你的 ~/.psqlrc 都不读取)。
-?
--help
显示关于psql命令行参数的帮助然后退出。
退出状态
如果正常结束,那么 psql 向 shell 返回 0, 如果自身发生致命错误,则返回 1(内存用尽,未找到文件等),如果和数据库的连接失效而且会话不再活跃则返回 2, 如果脚本中发生错误并且设置了 ON_ERROR_STOP 则返回 3。
用法
与一个数据库联接
psql 是一个普通的 Postgresql 客户端应用。为了与一个数据库联接,你需要知道你的目标数据库,服务器的主机名和端口号以及你希望以哪个用户的身份进行联接等信息。 我们可以通过命令行参数告诉 psql 这些信息,分别是 -d, -h,-p,和 -U。 如果有个参数不属于任何选项开关,那么它会被解释成数据库名(或者是用户名——如果数据库名称已经给出了。)。不是所有这些选项都是必须的,有缺省存在。如果你省略主机名, psql 将通过 Unix 域套接字与本地主机的服务器相联, 或者在没有 unix 域套接字的机器上,通过 TCP/IP 与 localhost 连接。缺省的端口号是编译时确定的。因为数据库服务器使用同样的缺省值, 所以在大多数设置下,你可能不需要声明端口号。缺省的用户名是你的 Unix 用户名,与数据库同名。 要注意的是你不能用任意用户名与任何数据库相联。你的数据库管理员应该告诉你你的访问权限。
如果缺省不太正确,那么你可以通过设置几个环境变量 PGDATABASE, PGHOST,PGPORT 和/或 PGUSER 为对应的值的方法节约几次敲击。
如果因为任何原因而无法与数据库相联(例如,权限不够,服务器没有运行等), psql 将返回一个错误并退出。
输入 sql 命令
通常状况下,psql 提供一个带有 psql 正在与之联接的接数据库名的,后缀 =>的提示符。例如,
$ psql testdb
Welcome to psql 8.0.0,the Postgresql interactive terminal.
Type:
testdb=>
用户可以在这个提示符下键入sql 查询。 通常,输入的行将在命令终止分号出现时送到服务器。一行的终止并不结束命令!因此命令可以因清晰起见跨越好几行。如果命令发送出去而且执行没有错误, 命令结果会显示在屏幕上。
当命令正在进行时,psql 同样还轮询由 LISTEN 和 NOTIFY. 生成的异步通知信号。
元命令
你在 psql 里输入的任何以不带引号的反斜杠('\')开头的东西都是 psql 元命令,这些命令是由 psql 自己处理的。这些命令也是令 psql 更可用于管理或书写脚本的原因。 元命令更常见的叫法是斜杠或反斜杠命令。
一个 psql 命令的格式是反斜杠后面紧跟一个命令动词,然后是任意参数。 参数与命令动词和其他参数以任意个空白字符间隔。
要在参数里面包含空白,你必须用单引号把它包围起来。 要在这样的参数里包含单引号,前面加一个反斜杠。任何包含在单引号里的东西会被进一步进行类 C 的替换,把 \n (新行),\t (tab),\digits, \0digits和 \0xdigits (给出的十进制,八进制,或十六进制码的字符)替换掉。
如果一个不带引号的参数以冒号(:)开头, 它会被当作一个psql 变量,并且该变量的值会最终成为真正的参数值。 (译注:类似 ecpg 和 pl/pgsql 的变量用法。)
用“反勾号” ("backticks" `) 包围的内容被当作一个命令行传入 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 ] ]
与一个新的数据库建立一个联接,使用/不用一个用户名。 前面的联接将关闭。如果 dbname 是 -,那么就假设是当前数据库名称。
如果省略 username,则假设是当前用户名。
作为一条特殊规则,不带任何参数运行\connect 将以缺省用户身份与缺省数据库连接(正如你不带任何参数运行 psql 一样。)
如果联接失败(用户名错,访问拒绝等),那么将保留前面的联接--当且仅当在 psql 处于交互模式下如此。如果运行的是非交互的脚本,处理会马上停止,并返回一个错误。选择这样的区别是一方面为用户使用方便考虑,另一方面为保证脚本不会碰巧操作了错误的数据库的安全机制考虑的。
\copy table [ ( column_list ) ] { from | to } { filename | stdin | stdout | pstdin | pstdout } [ with ] [ oids ] [ delimiter [ as ] 'character' ] [ null [ as ] 'string' ] [ csv [ quote [ as ] 'character' ] [ escape [ as ] 'character' ] [ force quote column_list ] [ force not null column_list ] ]
执行前端(客户端)拷贝。这是一个运行 sql COPY 命令的操作, 不同的是 sql COPY 是服务器在读写指明的文件,而 psql 读写文件并作为本地的文件系统和服务器之间的路由取出或写入数据。这意味着文件访问性和权限都是本地用户的,而不是服务器的,因此不需要 sql 超级用户权限。
这条命令的语法是模拟 sql COPY 命令的。 要注意的是由此而来,有一些特殊的分析规则应用于 \copy 命令。尤其是变量替换规则和反斜杠代换规则不起作用。
\copy table from stdin | stdout 分别基于命令输入和输出读/写。所有行都从发出命令的同一个源读取,直到读到了 \. 或者流达到 EOF。输出发送到和命令输出相同的位置。要从 psql 的标准输入或者输出读/写, 使用 pstdin 或者 pstdout。这个选项用于把和 sql 脚本嵌在一起的文件填充表很有用。
提示: 此操作不象 sql COPY 命令这样高效,因为所有数据必须通过客户端/服务器联接。对于大数据量的操作,另一种方法更可行。
\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
------------+---------+----------+---------------------------
(1 row)
\dD [ pattern ]
列出所有可用域。如果声明了 pattern,那么只显示匹配的域。
\df [ pattern ]
\df+ [ pattern ]
列出所有可用函数,以及它们的参数和返回的数据类型。如果声明了 pattern,那么只显示匹配(正则表达式)的函数。如果使用了 \df+ 的形式,每个函数的附加信息,包括语言和描述也会显示出来。
注意: 要查找接受或者返回特定类型的函数,使用你的分页器的搜索功能来滚动 \df 的输出。
为了减少混乱,\df 并不显示数据类型的 I/O 函数。 这样是通过忽略那些接受或者返回类型 cstring 的函数实现的。
\dg [ pattern ]
列出所有数据库组。如果声明了 pattern, 只显示那些匹配模式的名字。
\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, 那么只列出名字可以匹配模式的表。
命令 GRANT 和 REVOKE 用于设置访问权限。参阅 GRANT 获取更多信息。
\dT [ pattern ]
\dT+ [ pattern ]
列出所有数据类型或只显示那些匹配 pattern的。这条命令的 \dT+ 形式显示更多信息。
\du [ pattern ]
列出所有已配置用户或者只列出那些匹配 pattern 的用户。
\edit (or \e) [ filename ]
如果声明了 filename, 则编辑此文件并且在编辑器退出后将其内容拷贝回查询缓冲区。如果没有给出参数,则把当前查询缓冲区内容拷贝到一个临时文件然后以相同方式编辑。
然后根据一般的psql规则重新分析查询缓冲区, 这时整个缓冲区当作一个单行。(因此你无法用这个方法制作“脚本”,用 \i 做脚本。) 这还意味着如果该查询以分号结尾(或者包含分号),它就会马上被执行。否则它只是在查询缓冲区里等待。
提示: psql 搜索环境变量 Psql_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_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 里或者把后面的查询结果定向到一个独立的 Unix shell 执行 command。如果没有声明参数,查询输出重置为标准输出。
"查询结果"包括所有表,命令响应和从数据库服务器来的提示, 同样还有各种各样查询数据库的反斜杠命令的输出(如 \d),但是没有错误信息。
\pset parameter [ value ]
这条命令设置影响查询结果表输出的选项。parameter 描述要设置的选项是哪一个。value 的语意也取决于它。
可调节的打印选项有:
format
设置输出格式为 unaligned,aligned,html, 或 latex之一。允许使用唯一的缩写。(这也意味着一个字母就够了。)
"Unaligned" (不对齐)把一条记录的所有字段都输出到一行,用当前有效的域分隔符分隔。这主要用于生成那些要被其他程序读取的输出(tab分隔,逗号分隔)。 "Aligned" (对齐)模式是标准的,人类可读的,格式化好了的文本输出,也是缺省。 "HTML" 和 "LaTeX" 模式把表输出为可用于文档里的对应标记语言。它们还不是完整的文档! (可能对于 HTML 变化还不是太大,但是在 LaTeX 里,你必须有一个完整的文档包装器。)
border
第二个参数必须是一个数字。通常,数字越大,表就有越宽的边界和越多的线, 但是这个参数取决于实际的格式。在HTML模式里,这个参数会直接翻译成border=...属性,在其他的模式里, 只有值 0 (无边界),1 (内部分隔线)和 2 (表框架)有意义。
expanded )(或者 x)
在正常和扩展格式之间切换。当打开扩展格式时,所有的输出都是两列, 字段名称在左,数据在右。这个模式在数据无法放进通常的"水平"模式的屏幕时很有用。
null
第二个参数是一个字串,用以代表字段的值为 null 时的打印输出。 缺省是什么都不打,这样很容易和类似一个空字串混淆。因此,我们可能选择 \pset null '(null)'。
fieldsep
声明在非对齐模式时的域分隔符。 这样我们就可以创建其他程序希望的tab或逗号分隔的输出。要设置 tab 域分隔符, 键入 \pset fieldsep '\t'。缺省域分隔符是 '|' (一个竖条符号)。
footer
切换缺省脚注 (x rows)。
recordsep
声明在非对齐模式时的记录分隔符。缺省是换行符。
tuples_only (或者 t)
在完全显示和只显示记录之间切换。 完全显示将显示象列头,标题和各种脚注等信息。在这个模式下,只显示记录模式将只显示实际的表数据。
title [ text ]
为任何随后打印的表设置标题。 这个参数可以用于给你的输出一个描述性标记。 如果不带参数,重置标题。
tableattr (或者 T)[ text ]
允许你声明放在 HTML table 标记里的任何属性。例如,可以是 cellpadding 或 bgcolor。注意你可能不需要在这里声明 border ,因为已经在 \pset border 里用过了。
pager
控制查询和psql帮助输出的分页器。如果设置了环境变量 PAGER, 输出被定向到指定程序,否则使用系统缺省(比如 more)。
如果关闭了分页器,则不使用它,如果打开了,程序只在需要的时候使用分页器,也就是说,输出是到终端,而且那个表很可能无法与屏幕匹配。 (psql 在决定何时分页时不是很完美。) \pset pager 开关分页器。我们也可以把分页器设置为 always,导致我们在任何情况下都使用分页器。
可以在 例子 节看到这些不同格式输出的示例。
提示: 有很多用于\pset的快速命令。参阅 \a,\C,\H, \t,\T,和 \x。
注意: 无参数运行 \pset是错误的。 以后这样调用将显示当前打印选项状态。
\qecho text [ ... ]
这条命令等效于 \echo ,区别是所有输出将写入由 \o设置的输出通道。
\r
重置(清空)查询缓冲区。
\s [ filename ]
将命令行历史打印出或是存放到 filename。 如果省略 filename, 历史将输出到标准输出。这个选项只有在 psql 配置成使用 GNU Readline 库后才生效。
注意: 在当前版本里,这个( GNU 历史库)不再是必须的了, 实际上,在程序结束时自动保存命令行历史。每次 psql 启动都会装载命令行历史。