CONNECTING TO A DATABASE 与一个数据库联接¶

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

ENTERING SQL COMMANDS 输入 SQL 命令¶

$psql testdb
Welcome to psql 7.4beta5, 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 [listen(7)] 和 NOTIFY [notify(7)] 生成的异步通知信号。

META-COMMANDS 元命令¶

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

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

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

用反引号 （"backticks" `） 包围的内容被当作一个命令行传入 shell。 该命令的输出（删除了结尾的新行）被当作参数值。上面描述的逃逸（字符）序列在反引号里也生效。

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

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

下列元命令是已定义的：

\a

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

\cd [directory]

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

\C [title ]

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

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

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

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

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

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

\copytable

执行前端（客户端）拷贝。这是一个运行 SQL COPY 命令的操作， 不同的是 SQL COPY 是服务器在读写指明的文件，而 psql 读写文件并作为本地的文件系统和服务器之间的路由取出或写入数据。 这意味着文件访问性和权限都是本地用户的，而不是服务器的，因此不需要 SQL 超级用户权限。

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

\copyright

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

\d [pattern ]

对于每个匹配pattern的关系（表，视图，索引或者序列）， 显示所有列，它们的类型，和任何特殊属性，象NOT NULL或缺省等－－只要存在。 如果实际上这个关系是一个表，任何已定义的索引，主键，唯一约束相关的索引，规则，约束，和触发器也同样显示出来， 如果关系是一个视图，还显示视图的定义。 （"匹配模式"在下面定义。）

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

\da [pattern ]

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

\dc [pattern ]

列出所有字符集之间的可用转换。如果声明了 pattern， 则只列出那些匹配模式的转换。

\dC

列出所有类型转换。

\dd [pattern ]

显示所有匹配 pattern 的描述，如果没有给出参数，显示所有可视对象。 但是不管怎样，只有那些有描述内容的对象才显示出来。 （"对象"包括聚集，函数，操作符，类型， 关系（表，视图，索引，序列，大对象），规则和触发器。）例如：

=>\dd version
                     Object descriptions
   Schema   |  Name   |  Object  |        Description
------------+---------+----------+---------------------------
 pg_catalog | version | function | PostgreSQL version string
(1 row)

    

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

\dD [pattern ]

列出所有可用域。如果声明了 pattern，那么只显示匹配的域。

\df [pattern ]

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

\distvS [pattern ]

这不是一个实际上的命令名称：字母 i，s，t，v，S 分别代表索引（index）， 序列（sequence），表（table），视图（view）和系统表（system table）。 你可以以任意顺序声明任意或者所有这些字母获得这些对象的一个列表。 字幕 S 把列表限制于系统对象；如果没有 S，则只显示非系统对象。 如果在命令名上附加了 +，那么还会列出和每个对象相关联的描述，如果有的话。

如果声明了 pattern，那么只列出匹配模式的对象。

\dl

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

\dn [pattern ]

列出所有可用模式（名字空间）。如果声明了 pattern （一个正则表达式），那么只列出匹配模式的模式名。

\do [pattern ]

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

\dp [pattern ]

生成一列可用的表和它们相关的权限。 如果声明了 pattern， 那么只列出名字可以匹配模式的表。

命令grant(7) 和revoke(7) 用于设置访问权限。参阅grant(7) 获取更多信息。

\dT [pattern ]

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

\du [pattern ]

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

\edit (or\e) [filename ]

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

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

\echotext [ ... ]

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

=>\echo `date`
Tue Oct 26 21:40:57 CEST 1999

    

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

\encoding [encoding ]

设置客户端字符编码方式。不带参数时，这条命令显示当前的编码方式。

\f [string ]

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

\g [ {filename | |command } ]

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

\help (or\h) [command ]

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

\H

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

\ifilename

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

\l (or\list)

列出服务器上所有数据库的名字和它们的所有者以及字符集编码。在命令名称后面加一个 "+" 还可以看到对数据库的描述。

\lo_exportloidfilename

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

\lo_importfilename [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_unlinkloid

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

\o [ {filename | |command} ]

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

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

\p

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

\psetparameter [value ]

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

可调节的打印选项有：

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

\q

退出 psql 程序。

\qechotext [ ... ]

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

\r

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

\s [filename ]

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

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

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

有效的变量名可以包含字符，数字和下划线。 参阅下面的 "Variables 变量" 获取细节。

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

\t

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

\Ttable_options

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

\timing

切换每个 SQL 语句使用的时间，单位是毫秒。

\w {filename ||command}

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

\x

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

\z [pattern ]

生成一个带有访问权限列表的数据库中所有表的列表。 如果给出任何pattern，则被当成一个规则表达式， 只显示匹配的表。

命令grant(7) 和revoke(7) 用于设置访问权限。 参阅grant(7) 获取更多信息。

这是\dp（"显示权限"）的别名。

\! [command ]

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

\?

获得关于反斜杠命令的帮助信息。

各种\d 命令都接受一个 pattern 参数，声明要显示的对象名字。* 表示"任何字符序列"， 而 ? 表示"任何单个字符"。（这个表示法和 Unix 的 shell 文件名模式兼容。） 高级用户也可以使用正则表达式表示法，比如字符表，[0-9] 这样的东西来匹配"任意数字"。 要让任何这些模式匹配字符可以安字面方式解析，那就应该用双引号包围它们。

一个包含（无引号的）句点的模式会被解析承一个模式名的模式后面跟着一个对象名的模式。 比如，\dt foo*.bar* 显示所有以foo 开头的模式里的以 bar 开头的表名字。 如果没有出现句点，那么这个模式只匹配在当前模式搜索路径中可见的对象。

如果完全省略 pattern 参数， 那么\d 命令显示所有在当前模式搜索路径中可见的对象。 要查阅在数据库中的所有对象，使用模式 *.*。

ADVANCED FEATURES 高级特性¶

VARIABLES 变量¶

testdb=>\set foo bar

testdb=>\echo :foo
bar

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

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

AUTOCOMMIT

如果是 on（缺省），那么每个 SQL 命令都在成功完成后自动提交。 要推迟这种模式下的提交，你必须输入一个 BEGIN 或者 START TRANSACTION SQL 命令。 如果是 off 或者未设置，SQL 命令不会提交，知道你明确地发出 COMMIT 或者 END。 关闭自动提交的模式是通过为你明确发出一个 BEGIN 实现的， 它是放在任何尚未在一个事务块中并且自己不是 BEGIN 或者其它事务控制命令的前面。

DBNAME

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

ECHO

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

ECHO_HIDDEN

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

ENCODING

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

HISTCONTROL

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

HISTSIZE

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

HOST

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

IGNOREEOF

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

LASTOID

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

ON_ERROR_STOP

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

PORT

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

PROMPT1

PROMPT2

PROMPT3

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

QUIET

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

SINGLELINE

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

SINGLESTEP

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

USER

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

VERBOSITY

这个选项可以设置为值 default，verbose，或者 terse 以控制错误报告的冗余行。

SQL INTERPOLATION 代换¶

testdb=>\set foo 'my_table'
testdb=>SELECT * FROM :foo;

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

testdb=>\set content '\'' `cat my_file.txt` '\''
testdb=>INSERT INTO my_table VALUES (:content);

testdb=>\set content '\'' `sed -e "s/'/\\\\\\'/g" < my_file.txt` '\''

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

PROMPTING 提示符¶

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

%M

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

%m

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

%>

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

%n

数据库会话的用户名。 （这个值的扩展可能在一个数据库会话过程中因为SET SESSION AUTHORIZATION 命令而改变。）

%/

当前数据库名称。

%~

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

%#

如果会话用户是数据库超级用户，使用 "#"，否则用">"。 （这个值的扩展可能在一个数据库会话过程中因为SET SESSION AUTHORIZATION 命令而改变。）

%R

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

%x

事务状态：如果不在事务块里，是一个空字串，如果在事务块里，是 *， 如果在一个失败的事务块里是 !，或者无法判断事务状态时为 ? （比如，因为没有连接）。

%digits

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

%:name:

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

%`command`

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

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

COMMAND-LINE EDITING 命令行编辑¶

$if psql
set disable-completion on
$endif