您的位置：寻梦网首页＞编程乐园＞数据库＞PostgreSQL 7.2 Documentation
PostgreSQL 7.2 Documentation
Prev Next

psql

Name

psql  --  PostgreSQL 交互终端

Synopsis

psql [ 

options

 ] [ 

dbname

 [ 

user

 ] ]

概述

psql 是一个以基于终端的 PostgreSQL 前端。 它允许你交互地输入查询，将它们提交给 PostgreSQL 然后阅读查询结果． 输入也可以来自一个文件。 另外，它还提供一些元命令（meta-commands）和许多类似 shell 风格的特性供你书写脚本和完成非常广泛任务的自动化工作。

描述

与一个数据库联接

psql 是一个普通的 PostgreSQL 客户端应用。为了与一个数据库联接，你需要知道你的目标数据库， 服务器的主机名和端口号以及你希望以 哪个用户的身份进行联接等信息。我们可以通过命令行参数告诉 psql 这些信息，分别是 -d ， -h ， -p ，和 -U 。 如果有个参数不属于任何选 项开关，那么它会被解释成数据库名 （或者是用户名－如果数据库名称也给出了．）。 不是所有这些选项都是必须的，缺省的也可以。如 果你省略主机名， psql 将通过 Unix 域套接字与本地主机的服务器相联。 缺省的端口号是编译时确定的。因为数据库服务器使用同样的缺省值， 所以在大多数设置下，你可能不需要声明端口号。 缺省的用户名是你的 Unix 用户名，与数据库同名。 要注意的是你不能用任意用户名与 任何数据库相联。你的数据库管理员应该告诉你你的访问权限。 你可以通过设置几个环境变量 PGDATABASE ， PGHOST ， PGPORT 和 PGUSER 为对应的值的方法节约几次敲击。

如果因为任何原因而无法与数据库相联 （例如，权限不够，postmaster 没有运行等）， psql 将返回一个错误并退出。

输入查询

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

$ 

psql testdb


Welcome to psql, the PostgreSQL interactive terminal.

Type:  \copyright for distribution terms
       \h for help with SQL commands
       \? for help on internal slash commands
       \g or terminate with semicolon to execute query
       \q to quit

testdb=>

用户可以在这个提示符下键入 SQL 查询． 通常，输入的行将在查询终止分号出现时送到后端． 一行的终止并不结束查询！因此查询可以 因清晰起见跨越好几行。如果查询发送出去而且没有错误， 查询结果会显示在屏幕上。

当查询正在进行时， psql 同样还轮询由 LISTEN 和 NOTIFY . 生成的异步通知信号．

psql 元命令

你在 psql 里输入的任何以不带引号的反斜杠（'\'）开头的东西都是 psql 元命令，这些命令是由 psql 自己处理的。这些命令也是令 psql 可用于管理或书写脚本的原因。 元命令更常见的叫法是斜杠或反斜杠命令。

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

要在参数里面包含空白，你必须用单引号把它包围起来。 要在这样的参数里包含单引号，前面加一个反斜杠。 任何包含在单引号里的东西 会被进一步进行类 C 的替换，把 \n （新行）， \t （tab）， \ digits ， \0 digits 和 \0x digits （给出的十进制，八进制，或十六进制码的字符）替换掉。

如果一个不带引号的参数以冒号（ : ） 开头，它会被当作一个变量，并且该变量的值会最终成为真正的参数值。 （译注：类似 ecpg 和 pl/pgsql 的变量用法。）

用“反勾号” （ "backticks" ` ） 引起的内容被当作一个命令行传入 shell。 该命令的输出（删除了结尾的新行）被当作参数值。上面描述 的转意（字符）序列在反勾号里也生效。（译注：与 shell 程序类似）

有些命令以一个 SQL 标识的名称（如，一个表名）为参数。 这些参数遵循 SQL 语法关于双引号的规则： 不带双引号的标识强制成小写。 对于所有其他命令，双引号没有特殊含义并且将被当成参数的一部分。

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

下列元命令是已定义的：

\a

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

\cd [ directory ]

把当前工作目录改变到 directory ． 没有参数是则改变到当前用户的家目录．

小技巧: 要打印出你的当前工作目录，使用 \!pwd ．

\C [ title ]

把正在打印的表的标题设置为一个查询的结果或者取消这样的设置。 这条命令等效于 \pset title title . （这条命令的名称源于 "caption" ，因为以前只是用于在一个 HTML 表里面设置标题。）

\connect (or \c ) [ dbname [ username ] ]

与一个新的数据库建立一个联接，使用/不用一个用户名。 前面的联接将关闭。如果 dbname 是 - ，那么就假设是当前数据库名称。

如果省略 username ， 则假设是当前用户名。

作为一条特殊规则，不带任何参数运行 \connect 将以缺省用户身份与缺省数据库连接（正如你不带任何参数运行 psql 一样。）

如果联接失败（用户名错，访问拒绝等），那么将保留前面的联接--仅仅是在 psql 处于交互模式下如此。 如果运行的是非交互的脚 本，处理会马上停止，并返回一个错误。 选择这样的区别是一方面为用户使用方便考虑， 另一方面为保证脚本不会碰巧操作了错误 的数据库的安全机制考虑的。

\copy table [ with oids ] { from | to } filename | stdin | stdout [ using delimiters ' characters ' ] [ with null as ' string ' ]

执行前端（客户端）拷贝．这是一个运行 SQL COPY 命令的操作， 不同的是 SQL COPY 是后端在读写指明的文件，对应地需要 访问后端和特殊的用户权限，以及受到后端对文件系统的访问权限的限制， 而在此命令中 psql 读写文件并通过一个本地的文件系统 路由从后端中取出或写入数据．

这条命令的语法是模拟 SQL COPY 命令的，参考它的描述获取细节。 要注意的是由此而来，有一些特殊的分析规则应用于 \copy 命令。 尤其是变量替换规则和反斜杠代换规则不起作用。

小技巧: 此操作不象 SQL COPY 命令这样高效， 因为所有数据必须通过（客户/服务器)）client/server IP 或套接字联接．对于大数据量的操作，另一种方法更可行。

注意: 注意在前端和后端拷贝时对 stdin 和 stdout 的解释的区别：在前端拷贝时，这些总是指 psql 的输入和输出流。在后端拷贝时 stdin 来自 COPY 本身的标准输入（比如，一个带有 -f 选项的脚 本），而 stdout 指的是查询输出流（参阅下面的 \o 元命令）。

\copyright

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

\d relation

显示 relation （可以是表，视图，索引或序列）的所有列，如果存在地话， 它们的类型和存在的任何特殊属性（象 NOT NULL 或缺省等）也显示出来。 如果实际上这个关系是一个表，任何已定义的索引，主键，唯一约束 以及检查约束也会列出来。 如果该关系是一个视图，视图的定义也会显示出来。

从 \d+ 来的命令也是一样的， 只不过还显示与表的列关联的注解。

注意: 如果如果不带任何参数调用 \d ，等效于 \dtvs ，将显示一个所有表，视图和序列的列表。 这完全是出于方便的考虑。

\da [ pattern ]

列出所有可用聚集函数，以及它们操作的数据类型。如果声明了 pattern （一个正则表达式），那么只显示匹配（正则表达式）的聚集函数。

\dd [ object ]

object （可以是一个正则表达式）的描述，如果没有给出参数，显示所有对象。 （ "对象" 包括聚集，函数，操作符，类型， 关系（表，视图，索引，序列，大对象），规则和触发器。）例如： 

=> 

\dd version


              Object descriptions
  Name   |   What   |        Description
---------+----------+---------------------------
 version | function | PostgreSQL version string
(1 row)

可以用 COMMENT ON SQL 命令生成对对象的描述。

注意: PostgreSQL 在 pg_description 系统表里存储对象描述。

\df [ pattern ]

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

\distvS [ pattern ]

这不是一个实际上的命令名称：字母 i，s，t，v，S 分别代表索引（index）， 序列（sequence），表（table），视图（view）和系 统表（system table）。 你可以以任意顺序声明任意或者所有这些字母获得这些对象的一个列表， 以及它们的所有者。

如果声明了 pattern ，它是一个正则表达式把输出限制在那些匹配的条目上。 如果我们在命令名称后面加一个 "+" ，那么每个对 象存在的相关描述也会显示出来。

\dl

这是 \lo_list 的别名，显示一个大对象的列表。

\do [ name ]

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

\dp [ pattern ]

这是一个 \z 的别名， 包括它是为了保留其巨大的记忆性价值（显示权限 "display permissions" ）。

\dT [ pattern ]

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

\du [ pattern ]

列出所有已配置用户或者只列出那些匹配 pattern 的用户．

\edit (or \e ) [ filename ]

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

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

小技巧: psql 搜索环境变量 PSQL_EDITOR ， EDITOR 和 VISUAL （以此顺序）查找要用到哪个编辑器。如果上面的 都没有设置，使用 /bin/vi 。

\echo text [ ... ]

向标准输出打印参数，用一个空格分隔并且最后跟着一个新行。 这个特性在显示脚本的输出时会有用。例如： 

=> 

\echo `date`


Tue Oct 26 21:40:57 CEST 1999

果第一个参数是一个无引号的 -n ， 那么不会写出结尾的新行。

小技巧: 如果你使用 \o 命令重定向你的查询的输出，你可能会用 \qecho 取代这条命令。

\encoding [ encoding ]

如果你使用多字节编码，设置客户端编码方式。 不带参数时，这条命令显示当前的编码方式。

\f [ string ]

为不对齐的查询输出设置域分隔符。缺省时是 （ | ）。 参阅 \pset 获取设置输出选项的通用方法。

\g [ { filename | | command } ]

把当前的查询输入缓冲区的内容发送给后端并且把输出输出到可选的 filename 或者把输出定向到一个独立的 Unix shell 执行 command 。 单独一个 \g 实际上等效于一个分号。一个带有参数 的 \g 是 "一次性" 的 \o 命令的代用品。

\help (or \h ) [ command ]

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

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

\H

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

\i filename

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

注意: 如果你想在屏幕上看到读入的行，你必须对所有行设置变量 ECHO 为 all 。

\l (或 \list )

列出服务器上所有数据库和它们的所有者。在命令名称后面加一个 "+" 还可以看到对数据库的任何描述。如果你的 PostgreSQL 节点是带着多字节支持编译的，还可以看到每个数据库的编码方式。

\lo_export loid filename

从数据库里读取 OID 为 loid 的大对象并把她写到 filename 里。 注意这个功能与服务器函数 lo_export 有些微小的区别， lo_export 运行时带着运行数据库服务器的用户权限， 而且是在服务器的文件系统上。

小技巧: 使用 \lo_list 查看大对象的 OID 。

注意: 参阅变量 LO_TRANSACTION 的描述获取关于所有大对象操作的重要信息。

\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_TRANSACTION 的描述获取关于所有大对象操作的重要信息。

\lo_list

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

\lo_unlink loid

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

小技巧: 使用 \lo_list 查找大对象的 OID 。

注意: 参阅变量 LO_TRANSACTION 的描述获取关于所有大对象操作的重要信息。

\o [ { filename | | command } ]

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

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

小技巧: 要用文本分散查询结果之间的输出，用 \qecho 。

\p

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

\pset parameter [ value ]

这条命令设置影响查询结果表输出的选项。 parameter 描述要设置的选项是哪一个。 value 的语意也取决于它。

可调节的打印选项有：

format

设置输出格式为 unaligned ， aligned ， html ， 或 latex 之一。 允许使用唯一的缩写。（这也意味着一个字母就够了。）

"Unaligned" （不对齐）把一条记录的所有域都都输出到一行， 用当前有效的域分隔符分隔。 这主要用于生成那些要被其他程序读取的输出（tab分隔，逗号分隔）。 "Aligned" （对齐）模式是标准的，人类可读的， 格式化好了的文本输出，也是缺省。 " HTML " 和 "LaTeX" 模式把表输出为可用于文档里的对应标记语言。它们还不是完整的文档！ （可能对于 HTML 变化还不是太 大，但是在 LaTeX 里，你必须有一个完整的文档包装器。）

border

第二个参数必须是一个数字。通常，数字越大， 表就有越宽的边界和越多的线， 但是这个参数取决于实际的格式。在 HTML 模式 里，这个参数会直接翻译成 border=... 属性，在其他的模式里， 只有值 0 （无边界），1 （内部分隔线）和 2 （表框架）有意义。

expanded (or x )

在正常和扩展格式之间切换。当打开扩展格式时，所有的输出都是两列， 域名称在左，数据在右。 这个模式在数据无法放进通常的 "水平" 模式的屏幕时很有用。

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

null

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

fieldsep

声明在非对齐模式时的域分隔符。 这样我们就可以创建其他程序希望的tab- 或逗号分隔的输出。要设置 tab 域分隔符，键入 \pset fieldsep '\t' 。缺省域分隔符是 '|' （一个 "管道" 符号）。

recordsep

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

tuples_only (or t )

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

title [ text ]

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

注意: 以前这个参数只影响 HTML 模式， 现在你可以在任何输出模式里设置标题。

tableattr (or T ) [ text ]

允许你声明放在 HTML table 标记里的任何属性。例如，可以是 cellpadding 或 bgcolor 。注意你可能不需要在这里声明 border ，因为已经在 \pset border 里用过了。

pager

激活分页器进行表输出。如果设置了环境变量 PAGER ，输出被定向到指定程序，否则使用 more 。

不管怎样， psql 只在它认为需要的时候使用分页器。 这意味着输出是到终端去的而那个表很可能无法与屏幕匹配。 因为打印过程的模块化天性，我们不可能每次都准确 预计出实际打印的行数。因此 psql 在决定何时分页时可能显得不是很有识别力。

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

小技巧: 有很多用于 \pset 的快速命令。参阅 \a ， \C ， \H ， \t ， \T ，和 \x 。

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

\q

退出 psql 程序．

\qecho text [ ... ]

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

\r

重置（清空）查询缓冲区。

\s [ filename ]

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

注意: 在当前版本里， 这个（ GNU 历史库）不再是必须的了， 实际上，在程序结束时自动保存命令行历史。每次 psql 启动都会装载命令行历史。

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

设置内部变量 name 为 value 或着如果给出了多于一个值， 设置为所有这些值的联接结果。如果没有给出第二个参数， 只设变量不设值。要重置一个变量，使用 \unset 命令。

有效的变量名可以包含字符，数字和下划线。 参阅关于 psql 变量的章节获取细节。

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

注意: 这条命令是完全和 SQL 命令 SET 不一样的。

\t

切换输出的列/字段名的信息头和行记数脚注。 这条命令等效于 \pset tuples_only ，提供主要为了方便。

\T table_options

允许你在使用 HTML 输出模式时声明放在 table 标记里的选项。这条命令等效于 \pset tableattr table_options 。

\w { filename | |command }

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

\x

切换扩展行格式．等效于 \pset expanded .

\z [ pattern ]

生成一个带有访问权限列表的数据库中所有表的列表。 如果给出任何参数，则被当成一个规则表达式， 把列表输出限制为那些可以匹配的表。 

test=> 

\z


Access permissions for database "test"
 Relation |           Access permissions
----------+-------------------------------------
 my_table | {"=r","joe=arwR", "group staff=ar"}
(1 row )

意思如下：

  • "=r" : PUBLIC 拥有对此表的读（ SELECT ）权限。

  • "joe=arwR" : 用户 joe 拥有读，写（ UPDATE ， DELETE ， "追加" （ INSERT ）权限， 以及在表上创建规则的权限。

  • "group staff=ar" : 组 staff 拥有 SELECT 和 INSERT 权限。

命令 GRANT 和 REVOKE 用于设置访问权限。

\! [ command ]

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

\?

获得关于反斜杠（ "\" ）命令的帮助信息。

命令行选项

如果配置好了， psql 理解标准的 Unix 短选项和 GNU 风格的长选项。后者不是在所有系统上都能获得。

-a, --echo-all

在读取行时向屏幕打印所有内容。 这个选项在脚本处理时比交互模式时更有用。这个选项等效于设置变量 ECHO 为 all 。

-A, --no-align

切换为非对齐输出模式。（缺省输出模式是对齐的。）

-c, --command query

声明 psql 将执行一条查询字串， query ，然后退出．这一点在 shell 脚本里很有用。

query 必须是一条完全可以被后端分析的查询字串（ 也就是说，它不包含 psql 特有的特性）， 或者是一个反斜杠命令。这样你就 不会混合 SQL 和 psql 元命令。要想混合使用，你可以把字串定向到 psql 里，象这样： echo "\x \\ select * from foo;" | psql 。

-d, --dbname dbname

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

-e, --echo-queries

显示所由发送给后端的查询． 等效于把变量 ECHO 为 queries 。

-E, --echo-hidden

回显由 \d 和其他反斜杠命令生成的实际查询。 如果你希望在你自己的程序里包含类似的功能， 你就可以使用这个选项。这等效于 在 psql 里设置变量 ECHO_HIDDEN 。

-f, --file filename

使用 filename 作为查询的语句源而不是交互式读入查询。 在处理完文件后， psql 结束。这个选项在很多方面等效于内部命令 \i 。

如果 filename 是 - (连字符)，则从标准输入读取．

使用这个选项与用 psql < filename 有微小的区别。通常，两者都回按照你预期那样运行， 但是使用 -f 打开了一些很好的特 性，比如带行号的错误信息。而且，使用这个选项还有可能有减小启动负荷的机会。 另一方面，如果你把所有内容手工输入，使用 shell 输入定向的方式（理论上）能保证生成和你已经得到的完全一样的输出 （译注：重复运行命令）。

-F, --field-separator separator

使用 separator 作为域分隔符．等效于 \pset fieldsep 或 \f 。

-h, --host hostname

声明正在运行 postmaster 的主机名． 如果主机名以斜扛开头，则它被用做到 Unix 域套接字的路径．

-H, --html

打开 HTML 格式输出。等效于 \pset format html 或 \H 命令。

-l, --list

列出所有可用的数据库，然后退出．其他非联接选项将被忽略．类似于内部命令 \list 。

-o, --output filename

将所有查询输出定向到文件 filename 。这个选项等效于命令 \o 。

-p, --port port

声明被 postmaster 用于侦听的 TCP/IP 端口或使用的缺省本地 Unix 主控套接字文件句柄． 缺省的是环境变量 PGPORT 的值，如果 没有设置的话是编译是声明的端口，通常是 5432。

-P, --pset assignment

允许你在命令行上以 \pset 的风格设置打印选项。 要注意的是你在这里用等号分割名称和值，而不能用空格。 因此要把输出格式设置为 LaTeX，你可以敲入 -P format=latex 。

-q

声明 psql 将"安静地"执行处理任务． 缺省时 psql 将打印欢迎和许多其他输出信息。 如果使用了此选项，这些都不出现。这在和 -c 选项一起使用时很有效．在 psql 里，你可以通过设置 QUIET 变量实现同样效果。

-R, --record-separator separator

使用 separator 做为记录分隔符。 等效于 \pset recordsep 命令。

-s, --single-step

进入单步模式运行。意味着每个查询在发往后端之前都要提示用户， 用这个选项也可以取消执行。此选项主要用于调试脚本。

-S, --single-line

进入单行运行模式，这时每个查询都将由换行符结束，象分号那样。

注意: 注意这个模式是给那些坚持要这个特性的人的，我们不鼓励你这么用。 实际上，如果你在一行里混合使用 SQL 和 元命令，执行的顺序对不熟练的用户而言不总是清晰的。

-t, --tuples-only

关闭打印列名称和结果行计数脚注等信息。完全等效于 元命令 \t 。

-T, --table-attr table_options

允许你声明放在 HTML table 标记里的选项。 参阅 \pset 获取细节。

-u

让 psql 在和数据库联接之提示输入用户的用户名和口令。

我们不赞成使用这个选项，因为它在概念上有漏洞。 （提示输入非缺省用户名和提示输入后端要求的口令是完全两码事。）我们鼓 励你用 -U 和 -W 选项取代。

-U, --username username

以用户 username 代替缺省用户与数据库联接。（当然，你必须有这么做的权限。）

-v, --variable, --set assignment

进行一次变量分配，象内部命令 \set 那样。 注意，如果有变量名和值的话，你必须在命令行上用等号分隔它们。要重置一个变 量，去掉等号。这个分配是在启动的很早的阶段进行的， 所以为内部使用保留的变量可能被再次覆盖。

-V, --version

显示 psql 版本。

-W, --password

要求 psql 在与一个数据库联接前提示输入口令。 这个选项将在整个会话过程中有效，即使你用元命令 \connect 改变了所联接的数据库。

在当前版本里，如果后端要求口令认证， psql 自动提出一个口令提示符。因为目前这个特性是以一个“hack”为基础， 自动识别有 可能神秘地失效，因此用这个选项强制一个提示符。 如果没有声明口令提示符而后端要求口令认证，那么联接企图将失败。

-x, --expanded

打开扩展行格式模式．等效于 \x 。

-X, --no-psqlrc

不读取启动文件 ~/.psqlrc 。

-?, --help

显示关于 psql 命令行参数的帮助。

高级特性

变量

psql 提供类似通常 Unix 命令 shell 那样的变量替换特性。 这个特性是新引入的还不是很复杂，但是我们计划在今后扩展它。 变量只是简单的名称/数值对， 这里的值可以是任何长度的任何值。要设置一个变量，使用 psql 元命令 \set ： 

testdb=> 

\set foo bar

把变量 "foo" 设置为值 "bar" 。 要检索变量的内容，在变量名前面放上冒号然后把它用在任意斜杠命令里： 

testdb=> 

\echo :foo


bar

注意: \set 的参数服从和其他命令一样的替换规则。 因此你可以构造有趣的引用，象 \set :foo 'something' 这样，获得分别象 Perl 或 PHP 那样有名的 "软连接（soft links）" 或 "变量 变量" 不幸的是（或者 万幸的？），用这些构造不能做任何有用的事情。另一方面， \set bar :foo 是一个非常有效的拷贝变量的方法。

如果你不带第二个参数调用 \set ， 那么只是设置这个变量而没有值。 要重置（或删除）一个变量，使用命令 \unset 。

psql 的内部变量可以包括任意顺序， 任意数量的字母，数字和下划线。 有一些常用变量被 psql 另眼相待。它们是一些选项设置，这些选 项在运行时可以通过改变变量的值或者改变一些应用的表现状态而改变。 尽管你可以把这些变量用于其他用途，但是我们不鼓励这么 做，因为程序的特性可能会很快变得非常奇怪。 通常，所有特殊对待的变量都是由大写字母组成（可能还有数字和下划线）。 为了保证 和未来的最大限度的兼容性，请避免使用这样的变量。 下面是一个所有特殊对待的变量列表。

DBNAME

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

ECHO

如果置为 " all " ， 输入的或者来自一个脚本的所有行在分析或执行前都写到标准输出。 要在程序启动时声明这些，使用 -a 如果设置为 " queries " ， psql 只是在查询发送给后端之前打印出来。 实现这个功能的命令行选项是 -e 。

ECHO_HIDDEN

当设置了这个变量并且一个反斜杠命令查询数据库时，首先显示查询。 这样你可以学习 PostgreSQL 内部的东西并且在你自己的程 序里提供类似功能。如果你设置该变量的值为 "noexec" ，查询只是显示出来但是实际上不发送到后端和执行。

ENCODING

当前的客户端多字节编码方式。 如果你没有设置使用多字节字符，这个变量将总是包含 "SQL_ASCII" 。

HISTCONTROL

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

注意: 这个特性是无耻地从 bash 里剽窃来的。 （译注：老兄，太客气了吧，要不freesoft有何意义？！：）

HISTSIZE

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

Note: 这个特性是无耻地从 bash 里剽窃来的。：-）

HOST

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

IGNOREEOF

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

注意: 这个特性是无耻地从 bash 里剽窃来的。

LASTOID

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

LO_TRANSACTION

如果你使用 PostgreSQL 大对象接口存储无法放进一条记录里的特殊数据， 所有操作必须包含在一个事务块里面。 （参阅关于大对象接 口的文档获取更多信息。）因为 psql 在你调用它的内部命令 \lo_export ， \lo_import ， \lo_unlink 之一时无法跟踪你是否有一个正在处理 的事务，所以它必须采取一些任意的动作。 这个动作可能是回卷任何正在处理的事务，或者提交这样的事务， 或者什么也不做。对于后 面一种情况，你必须提交你自己的 BEGIN TRANSACTION / COMMIT 块否则结果将是不可预料的（通常导致在任何情况下希望的 动作都不会发生）。

要选择你希望做的事，你可以把此变量设置为 "rollback" ， "commit" ， 或 "nothing" 之一。缺省是回卷事务。如果你只是希望装载一个 或者少数几个对象，这个方法很好。但是如果你希望传输许多大对象， 我们建议给所有命令提供一个明确的事务块。

ON_ERROR_STOP

缺省时，如果非交互的脚本碰到一个错误，象一条错误的 SQL 查询或者内部元命令，处理会继续进行。这是 psql 的传统特性， 但是有时候我们不太希望这样。如果设置了这个变量，脚本处理将马上停止。 如果该脚本是从另外一个脚本调用的，那个脚本也会 按同样的方式停止。如果最外层的脚本不是从一次交互的 psql 会话中调用的而是用 -f 选项调用的， psql 将返回错误代码 3，以示 这个情况与致命错误条件的区别（错误代码 1）。

PORT

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

PROMPT1 , PROMPT2 , PROMPT3

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

QUIET

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

SINGLELINE

这个变量等效于设置命令行选项 -S 。你可以在运行时删除或设置它。

SINGLESTEP

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

USER

当前你正用于联接的数据库用户。 这是在每次你与数据库联接时（包括程序启动）设置的，但是可以删除/重置。

SQL 代换

一个附加的 psql 变量的有用特性是你可以把它们替换 （ "代换" ）成正规的 SQL 语句。这样做的语法同样还是变量名前面加一个冒号 （ : ）。 

testdb=> 

\set foo 'my_table'


testdb=> 

SELECT * FROM :foo;

将会查询表 my_table 。变量的值是逐字拷贝的， 所以它甚至可以包含不对称的引号或反斜杠命令。 你必须保证你输入的东西是有意义 的。变量替换将不会在引起来的 SQL 语句里面发生。

利用这个功能的一个时髦的应用是通过使用一个随后的语句中最后插入的 OID 建立一个外键仿真（scenario ？）。 另一个可能用到这个机制的地方是把一个文件的内容拷贝到一个域里面去。 首先把文件装载到一个变量然后象上面那样处理。 

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` '\''

观察正确数量的反斜杠（6）！你可以这样解释它：在 psql 分析完这行后，它把 sed -e "s/'/\\\'/g" < my_file.txt 传递给shell。 shell 将对双引号里的东西做其处理然后用参数 -e 和 s/'/\\'/g 执行 sed 。当 sed 分析这些时， 它将把双反斜杠替换为单个反斜杠然后进行替换。 可能有时候你认为所有 Unix 命令使用同一个转意字符是个好事。 但具有讽刺意味的事实是你可能不得不转意所有反斜杠，因为 SQL 文本常量同样也惨遭这种解释。 这种情况下你可能最好在外部准备文件。

因为冒号也可以合法的出现在查询里，便有下面规则的应用： 如果没有设置变量，字符序列 "冒号+名称" 不会被改变。 在任何情况下你 都可以用反斜杠转意冒号以保护它免于被解释。 （变量的冒号语法是 SQL 用于嵌入查询语言的标准，如 ecpg 。用于数组片段和类型转换的冒号语法是 PostgreSQL 扩展，因此有冲突。）

提示符

psql 使用的提示符可以根据你的喜好客户化。三个变量 PROMPT1 ， PROMPT2 ， 和 PROMPT3 包含描述提示符的外观的字串和特殊转意序列。 Prompt 1 是 psql 请求一个新查询时的使用的正常提示符。 Prompt 2 是在一个查询输入期待更多输入时（因为查询没有用一个分号 结束或者引号没有关闭）显示的提示符。 Prompt 3 在你运行一个 SQL COPY 命令和等待你在终端上键入记录时使用。

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

%M

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

%m

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

%>

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

%n

你联接使用的用户名（不是你的本地系统用户名）。

%/

当前数据库名称。

%~

类似 %/ ， 但如果数据库是你的缺省数据库输出是 "~" （波浪线（tilde））。

%#

如果当前用户是数据库超级用户，使用 "#" ，否则用 ">" 。

%R

对于 prompt 1 通常是 "=" ，但是如果是单行模式则是 "^" ，而如果会话与数据库断开（如果 \connect 失败可能发生）是 "!" 。对于prompt 2 该序列被 "-" ， "*" ，一个单引号或者一个双引号代替， 这取决于 psql 是否等待更多的输入（因为查询没有终止， 或着正在一个 /* ... */ 注释里面，或者因为你在引号里面）。对于 prompt 3 该序列不解释成任何东西。

% digits

如果 digits 以 0x 开头， 那么其余字符被解释成一个十六进制数字并且替换为对应 （十六进制码）的字符。如果第一个数字是 0 ，该字符被解释成一个八进制数字并且替换为对应的? （八进制码）的字符。否则认为是一个十进制数字。

%: name :

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

%` command `

command 的输出， 类似于通常的 "反勾号（back-tick）" 替换。

要在提示符里插入百分号，键入 %% 。缺省提示符等效于 '%/%R%# ' 用于 prompts 1 和 2，以及 '>> ' 用于 prompt 3。

注意: 这个特性是无耻地从 tcsh 里剽窃来的。

杂项

psql 正常结束时向 shell 返回 0， 发生自身致命错误（用光内存，文件没有找到）时返回 1， 与后端联接出错和会话不是交互的时候返回 2，如果在一个脚本里面发生错误或者变量 ON_ERROR_STOP 被设置了返回 3。

在启动之前， psql 试图读取并执行文件 $HOME/.psqlrc 里的命令。 这个特性可以用来按口味设置客户端或者服务器（用 \set 和 SET 命令）。

GNU readline

psql 为了编辑和检索命令行的方便支持 readline 和历史库。 命令历史存放在你的家目录的一个叫 .psql_history 的文件里，并且当 psql 启动的时候会装载进来。 Tab-补齐同样也被支持，尽管该补齐逻辑并不是一个 SQL 分析器必备的。如果可能， psql 会自动制作成使用这些特性。 如果因某些原因你不喜欢 tab 补齐，你可以把下面几行放在你的家目录的一个叫 .inputrc 的文件里关闭这个特性： 

$if psql
set disable-completion on
$endif

（这不是 psql 的特性， 是 readline 的。参考它的文档获取更多细节。）

如果你安装了readline库，但是 psql 好象没有使用它，你必须确保 PostgreSQL 的顶级 configure 脚本可以找到该库。 configure 需要能够在合适的目录里找到库 libreadline.a （或者一个等效的共享库） 和 头文件 readline.h 和 history.h （或者 readline/readline.h 和 readline/history.h ）。 如果你的库和头文件安装在某个阴暗的角落，你必须告诉 configure 它们在哪里，例如： 

$ ./configure --with-includes=/opt/gnu/include --with-libs=/opt/gnu/lib  ...

然后你不得不重新编译 psql （不必重新编译整个代码树）。

GNU readline 库可以从 GNU 计划的 FTP 服务器 ftp://ftp.gnu.org 得到。

例子

注意: 本节只是显示了 psql 少数几个例子。如果你希望学习 SQL 或者熟悉 PostgreSQL ，你可能愿意阅读一下包含在这个版本 里的教程。

第一个例子演示了如何把一个查询分成多个行进行输入。注意提示符的变化： 

testdb=> 

CREATE TABLE my_table (


testdb(> 

 first integer not null default 0,


testdb(> 

 second text


testdb-> 

);


CREATE

现在再看看表定义： 

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

附录

虫子和说明

  • 一些 psql 的早期版本允许第一个参数（单字母） 直接跟在命令后面。 出于兼容性原因，这个特性仍然在某些程度上被支持，但是 我不准备在这里详细解释，因为我不鼓励这样使用。 不过如果你收到莫名其妙的信息，想想这个用法。例如 

    testdb=> 

\foo


Field separator is "oo",

    可能不是你想要的东西。

  • psql 只能与同版本的服务器平稳地工作。 这不意味着其他组合会完全失败，但是可能有微小的或者不那么微小的问题。

  • 在一个 "拷贝入（copy in）" （数据发送给服务器）过程中按下 Control-C 并不显示出最典型的特征。 如果你收到一条类似于下面这样的信息 "COPY state must be terminated first" ，只需要输入 \c - - 重置联接即可。

Prev Home Next
pg_restore Up pgtclsh