PostgreSQL 9.4.4 中文手册
上一页 | 上一级 |  | 下一页

# psql

## 名称

psql -- PostgreSQL 交互终端

## 大纲

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

## 描述

psql是一个以终端为基础的PostgreSQL 前端。它允许你交互地键入查询，然后把它们发出给PostgreSQL， 再显示查询的结果。另外，输入可以来自一个文件。还有，它提供了一些元命令和多种类似 shell的特性来实现书写脚本以及对大量任务的自动化。

## 选项

`-a`
`--echo-all`

  在读取行时向标准输出打印所有非空内容。（这个选项不适用于交互模式读取行。） 这个选项等效于设置`ECHO`变量为`all`。

`-A`
`--no-align`

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

`-c `command``
`--command=`command``

  声明psql将执行一条命令字符串 `command`，然后退出。 这一点在 shell 脚本里很有用。这个选项忽略启动文件 (`psqlrc`和`~/.psqlrc`)。

  `command`必须是一条完全可以被服务器分析的字符串 (也就是不包含psql特有的特性)，或者是一个反斜杠命令。 这样你就不会混合SQL和psql元命令。 要想混合使用，你可以把字符串重定向到psql里， 例如：`echo '\x \\ SELECT * FROM foo;' | psql` (`\\`用于隔开元命令)。

  如果命令字符串包含多个 SQL 命令，那么他们将在一个事务里处理， 除非在字符串里包含了明确的`BEGIN`/`COMMIT`命令把他们分成多个事务。 这个和从psql的标准输入里给它填充相同字符串不同。 另外，只返回最后一条SQL命令的结果。

  因为这些遗留行为，在`-c`字符串中放置多于一个命令经常会有意想不到的结果。 最好是在psql的标准输入中放置多个命令， 而不是使用上面阐述的echo，或者通过这里记录的shell， 例如：

      psql <<EOF
      \x
      SELECT * FROM foo;
      EOF

`-d `dbname``
`--dbname=`dbname``

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

  如果这个参数包含一个`=`号，或者以一个有效的URI 前缀(`postgresql://`或`postgres://`)开头， 那么将它看做一个`conninfo`字符串。 参阅第 31.1.1 节获取更多信息。

`-e`
`--echo-queries`

  把所有发送给服务器的查询同时也回显到标准输出。等效于把变量 `ECHO`设置为`queries`。

`-E`
`--echo-hidden`

  回显由`\d`和其它反斜杠命令生成的实际查询。 你可以使用这个命令学习psql的内部操作。 这等效于在设置变量`ECHO_HIDDEN`为`on`。

`-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`。

`-L `filename``
`--log-file=`filename``

  除了正常的输出源之外，把所有查询输出记录到文件`filename`。

`-n`
`--no-readline`

  在行编辑中不使用Readline，并且不使用命令历史。 这可以在剪切和粘贴时用于关闭tab扩展。

`-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应该安静地执行处理任务。缺省时， 它将打印欢迎和许多其它输出信息。如果使用了此选项，这些都不会出现。 这在和`-c`选项一起使用时很有效。这等效于设置变量 `QUIET`为`on`。

`-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 `username``
`--username=`username``

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

`-v `assignment``
`--set=`assignment``
`--variable=`assignment``

  像元命令`\set`那样进行一次变量分配。注意，如果有变量名和值的话， 你必须在命令行上用等号分隔它们。去掉等号则重置变量。要设置一个带有空值的变量， 可以保留等号但是不指定值。这个分配是在启动之初进行的， 所以为内部使用而保留的变量可能被再次覆盖。

`-V`
`--version`

  打印psql版本信息然后退出。

`-w`
`--no-password`

  从不提示密码。如果服务器需要密码验证而密码不可通过其他方式 （比如`.pgpass`文件）获得，则连接尝试将失败。 该选项在批量工作和不存在用户输入密码的脚本中很有帮助。

  请注意，这个选项对整个会话有效，所以它影响元命令`\connect`的使用， 还有初始连接尝试。

`-W`
`--password`

  强制psql在与一个数据库连接前提示输入口令。

  这个选项从来不是至关重要的，因为如果服务器需求密码认证， 则psql自动提示一个密码。不过，psql 将在找出服务器想要一个密码上浪费一个连接尝试。在某些情况下， 值得输入`-W`以避免额外的连接尝试。

  请注意，这个选项对整个会话有效，所以它影响元命令`\connect`的使用， 还有初始连接尝试。

`-x`
`--expanded`

  打开扩展表格式模式。等效于`\x`命令。

`-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命令行参数的帮助然后退出。

## 退出状态

如果正常结束，那么psql向 shell 返回 0 ， 如果自身发生致命错误，则返回 1(比如内存用尽，未找到文件等)， 如果和数据库的连接失效而且会话不再活跃则返回 2 ， 如果脚本中发生错误并且设置了`ON_ERROR_STOP`则返回 3 。

## 用法

### 连接一个数据库

psql是一个普通的PostgreSQL 客户端应用。为了与一个数据库连接，你需要知道目标数据库、服务器的主机名和端口号、 以及你希望以哪个用户的身份进行连接等信息。可以通过命令行参数`-d`, `-h`, `-p`, `-U`告诉 psql这些信息。如果某个参数不属于任何选项， 那么它会被解释成数据库名或者是用户名(如果数据库名称已经给出了)。 不是所有这些选项都是必须的，有的缺省就存在。如果你省略主机名，psql 将通过Unix域套接字与本地主机的服务器相联，或者在没有unix域套接字的机器上， 通过TCP/IP与`localhost`连接。缺省的端口号是编译时确定的。 因为数据库服务器使用同样的缺省值，所以在大多数设置下，你可能不需要声明端口号。 缺省的用户名是你的操作系统用户名，与数据库同名。 要注意的是你不能用任意用户名与任何数据库相联。你的数据库管理员应该告诉你有哪些访问权限。

如果缺省不太正确，那么你可以通过设置几个环境变量`PGDATABASE`, `PGHOST`,`PGPORT`和/或`PGUSER` 的方法节约几次敲击。其它环境变量的信息，参阅第 31.14 节。 另外，用一个`~/.pgpass`文件来避免输入密码也是很方便的。 参阅第 31.15 节获取更多信息。

声明连接参数的另一种方式是在`conninfo`字符串或 URI中，代替数据库名字。这种机制让你非常广泛的控制连接。 例如：

    $ psql "service=myservice sslmode=require"
    $ psql postgresql://dbmaster:5433/mydb?sslmode=require

这种方式你也可以使用LDAP查找连接参数，就像 第 31.17 节里描述的那样。参阅第 31.1.2 节 获取所有可用的连接选项的信息。

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

如果标准输入和标准输出都是一个终端，那么psql 设置客户端编码为"自动"，这将从本地设置中检测合适的客户端编码 （在Unix系统上是`LC_CTYPE`环境变量）。如果不像预期的那样工作， 客户端编码可以使用环境变量`PGCLIENTENCODING`重写。

### 输入 SQL 命令

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

    $ psql testdb
    psql (9.4.4)
    Type "help" for help.

    testdb=>

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

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

当C风格的块注释传递到服务器等待处理和移除时， SQL标准的注释通过psql移除了。

### 元命令

你在psql里输入的任何以不带引号的反斜杠开头的东西都是 psql元命令，这些命令是将由psql 自己处理的。这些命令使得psql 更便于管理或书写脚本。元命令通常被称为斜杠或反斜杠命令。

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

要在参数里面包含空白，你必须用单引号把它包围起来。要在参数里包含单引号， 在单引号包围的文本里写两个单引号。任何包含在单引号里的东西都会被进一步进行类 C的替换：`\n`(新行)、`\t`(制表符)、 `\b`（退格）、`\r`（回车）、 `\f`（换页）、`\``digits` (八进制表示的字符)、`\x` `digits` (十六进制表示的字符)。在单引号包围的文本中，反斜杠前导任何其他字符， 都表示是该单个字符，不管它是什么。

在一个参数中，加上反勾号(```)的文本被看做是一个命令行， 传递给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` 连接字符串（在第 31.1.1 节中详细说明）指定。

  当使用位置参数时，如果省略了`dbname`、 `username`、 `host`或 `port`中的任意一个， 或者声明为`-`，则该参数使用前一个连接的参数值； 如果没有前一个连接，则使用libpq 对该参数的缺省值。当使用`conninfo`字符串时， 新连接不会使用前一个连接的参数值。

  如果成功制作了新连接，那么关闭以前的连接。 如果连接失败(用户名错、访问被拒绝等)，那么仅当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 `title``。 这条命令的名称源于"caption"，因为以前只是用于在一个 HTML表格里面设置标题。

`\cd [ `directory` ]`

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

  > 提示: 使用`\! pwd`打印出当前工作目录。

`\conninfo`

  输出关于当前数据库连接的信息。

`\copy { `table` [ ( `column_list` ) ] | ( `query` ) } { `from` | `to` } { `'filename'` | program `'command'` | stdin | stdout | pstdin | pstdout } [ [ with ] ( `option` [, ...] ) ]`

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

  当指定了`program`时，`command` 是通过psql执行的，并且来自或到达 `command` 的数据在服务器和客户端之间传送。再次，文件访问性和权限都是本地用户的， 而不是服务器的，因此不需要 SQL 超级用户权限。

  对于`\copy ... from stdin`，所有行都从发出命令的同一个源读取，直到读到了`\.` 或者流达到EOF。这个选项用于填充SQL 脚本文件中嵌入的表很有用。 对于`\copy ... to stdout`，输出发送到和psql 命令输出相同的位置。并且不输出`COPY `count`` 命令状态（因为它可能会和一个数据行混淆）。要从psql 的标准输入或者输出读/写，而不管当前命令源或`\o`选项， 可以使用`pstdin`或`pstdout`。

  这条命令的语法是类似于SQL COPY命令。 所有选项除了数据源/目的地都是按照COPY指定的。 因此带来一些应用于`\copy`命令的特殊分析规则。 尤其是psql的变量替换规则和反斜杠逃逸规则将不起作用。

  > 提示: 此操作不像SQL `COPY`命令这样高效， 因为所有数据必须通过客户端/服务器连接。对于大数据量的操作， SQL命令的方法更可行。

`\copyright`

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

`\d[S+] [ `pattern` ]`

  对于每个匹配`pattern`的关系 (表、视图、索引、序列或外部表)或复合类型，显示所有列、它们的类型、 表空间(如果不是缺省的)和任何特殊属性(诸如`NOT NULL`或缺省等)。 相关的索引、约束、规则、触发器也同样显示出来。对于外部表，也显示相关的外部服务器。 "匹配模式"在下面的匹配模式 中定义。

  对于一些关系类型，`\d`为每个字段显示了额外的信息：序列的字段值， 索引的索引表达式和外部表的外部数据封装器选项。

  从`\d+`来的命令也是一样的，只不过显示更多信息： 任何与表的列关联的注释也都会显示，还有就是表中出现的 OID ， 如果关系是一个视图、一个非缺省的复制身份设置，那么也显示视图定义。

  缺省的，只显示用户创建的对象；应用一个模式或`S` 修饰符包含系统对象。

  > 注意: 如果不带任何`pattern`参数调用 `\d`，那么等效于`\dtvsE`， 将显示一个所有可见表，视图，序列和外部表的列表。这完全是出于方便的考虑。

`\da[S] [ `pattern` ]`

  列出聚合函数，以及它们的返回类型和操作的数据类型。如果声明了 `pattern`， 那么只显示匹配模式的聚合函数。缺省的，只显示用户创建的对象； 应用一个模式或`S`修饰符包含系统对象。

`\db[+] [ `pattern` ]`

  列出表空间。如果声明了`pattern`， 那么只显示那些匹配模式的表空间。如果在命令名上附加了`+`， 那么每个对象都和与之相关的权限一起列出。

`\dc[S+] [ `pattern` ]`

  列出字符集编码之间的转换。如果声明了`pattern`， 则只列出那些匹配模式的转换。缺省的，只显示用户创建的对象； 应用一个模式或`S`修饰符包含系统对象。如果在命令名上附加了 `+`，那么每个对象都和与之相关的描述一起列出。

`\dC[+] [ `pattern` ]`

  列出类型转换。如果声明了`pattern`， 则只列出源或目标类型匹配该模式的转换。如果在命令名上附加了 `+`，那么每个对象都和与之相关的描述一起列出。

`\dd[S] [ `pattern` ]`

  显示类型为`constraint`、`operator class`、`operator family`、 `rule`和`trigger`的对象的描述。 所有其他的注释可以通过各自对象类型的反斜杠命令看到。

  `\dd`显示匹配`pattern` 的对象的描述，或者如果没有给出参数，显示适当类型的可视对象。但是不管怎样， 只有那些有描述内容的对象才显示出来。缺省的，只显示用户创建的对象； 应用一个模式或`S`修饰符包含系统对象。

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

`\ddp [ `pattern` ]`

  列出缺省访问权限设置。为缺省权限设置已经从内建的缺省改变了的每个角色 （还有模式，如果适用）显示一个记录。如果声明了 `pattern`， 则只列出角色名或模式名匹配该模式的记录。

  ALTER DEFAULT PRIVILEGES命令用来设置缺省访问权限。 权限显示的含义在GRANT中解释。

`\dD[S+] [ `pattern` ]`

  列出域。如果声明了`pattern`， 那么只显示匹配该模式的域。缺省的，只显示用户创建的对象； 应用一个模式或`S`修饰符包含系统对象。如果在命令名上附加了 `+`，那么每个对象都和与之相关的权限和描述一起列出。

`\dE[S+] [ `pattern` ]`
`\di[S+] [ `pattern` ]`
`\dm[S+] [ `pattern` ]`
`\ds[S+] [ `pattern` ]`
`\dt[S+] [ `pattern` ]`
`\dv[S+] [ `pattern` ]`

  在这组命令中，字母`E`、`i`、`m`、 `s`、`t`和`v` 分别代表外部表、索引、物化视图、序列、表和视图。 你可以以任意的顺序声明任意或所有这些字母，获取这些类型的对象的列表。 例如，`\dit`列出索引和表。如果在命令名上附加了`+`， 那么每个对象都和它在磁盘上的物理尺寸和与之相关的描述一起列出，如果有。 如果声明了`pattern`， 那么只列出匹配该模式的对象。缺省的，只显示用户创建的对象； 提供一个模式或`S`修饰符包含系统对象。

`\des[+] [ `pattern` ]`

  列出外部服务器（助记："扩展服务器"）。如果声明了 `pattern`， 那么只列出匹配该模式的服务器。如果使用了`\des+`格式， 则显示每个服务器的全部描述，包括服务器的ACL、类型、版本、选项和描述。

`\det[+] [ `pattern` ]`

  列出外部表（助记："扩展表"）。如果声明了 `pattern`， 那么只列出表名或模式名匹配该模式的记录。如果使用了`\det+` 格式，那么也显示通用选项和外部表描述。

`\deu[+] [ `pattern` ]`

  列出用户映射（助记："外部用户"）。如果声明了 `pattern`， 那么只列出用户名匹配该模式的那些映射。如果使用了`\deu+`格式， 那么也显示关于每个映射的额外的信息。

  小心
  `\deu+`可能也显示远程用户的用户名和密码， 所以要小心不要透漏它们。

`\dew[+] [ `pattern` ]`

  列出外部数据封装器（助记："扩展的封装器"）。如果声明了 `pattern`， 那么只显示名字匹配该模式的外部数据封装器。如果使用了`\dew+`格式， 则外部数据封装器的ACL、选项和描述也显示。

`\df[antwS+] [ `pattern` ]`

  列出分类为"agg" (aggregate)、"normal"、"trigger"或 "window"的函数和它们的参数、返回类型和函数类型。 要想只显示指定类型的函数，在命令中添加对应的字母`a`、 `n`、`t`或`w`。如果声明了 `pattern`， 那么只显示名字匹配该模式的函数。 缺省的，只显示用户创建的对象；提供一个模式或`S` 修饰符包含系统对象。如果使用了`\df+`格式， 则也显示关于每个函数的额外信息，包括安全等级、波动性、所有者、 语言、源代码和描述。

  > 提示: 要查找接受或者返回特定类型的函数，使用你的分页器搜索功能来滚动`\df`的输出。

`\dF[+] [ `pattern` ]`

  列出文本搜索配置。如果声明了`pattern`， 那么只显示名字匹配该模式的配置。如果使用了`\dF+`格式， 则显示每个配置的全部描述，包括底层的文本搜索解析器和为每个解析器标记类型列出的字典。

`\dFd[+] [ `pattern` ]`

  列出文本搜索字典。如果声明了`pattern`， 那么只显示名字匹配该模式的字典。如果使用了`\dFd+`格式， 则显示关于每个选中的字典的额外信息，包括底层的文本搜索模板和选项值。

`\dFp[+] [ `pattern` ]`

  列出文本搜索解析器。如果声明了`pattern`， 只显示名字匹配该模式的解析器。如果使用了`\dFp+`格式， 则显示每个解析器的全部描述，包括底层的函数和识别的标记类型的列表。

`\dFt[+] [ `pattern` ]`

  列出文本搜索模板。如果声明了`pattern`， 则只显示名字匹配该模式的模板。如果使用了`\dFt+`格式， 则显示关于每个模板的额外的信息，包括底层的函数名。

`\dg[+] [ `pattern` ]`

  列出数据库角色。（因为"用户"和"组"的概念已经统一成"角色"， 所以这个命令现在等于`\du`。）如果声明了 `pattern`，则只列出名字匹配该模式的那些角色。 如果使用了`\dg+`格式，则显示关于每个角色的额外信息； 目前这增加了每个角色的注释。

`\dl`

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

`\dL[S+] [ `pattern` ]`

  列出过程语言。如果声明了`pattern`， 则只列出名字匹配该模式的语言。缺省的，只显示用户创建的语言； 提供`S`修饰符包含系统对象。如果在命令名上附加了`+`， 那么每个语言的调用处理器、验证器、访问权限和它是否是一个系统对象也和语言一起列出。

`\dn[S+] [ `pattern` ]`

  列出模式(名字空间)。如果声明了`pattern`， 那么只列出匹配模式的模式名。缺省的，只显示用户创建的对象；提供一个模式或 `S`修饰符包含系统对象。如果在命令名上附加了`+`， 那么每个对象都和与之相关的权限和注释一起列出(如果有的话)。

`\do[S+] [ `pattern` ]`

  列出操作符，以及它们的操作数和结果类型。如果声明了 `pattern`，那么只显示匹配模式的操作符。 缺省的，只显示用户创建的对象；提供一个模式或`S` 修饰符包含系统对象。如果命令名后面附加了`+`， 那么也显示关于每个操作符的信息，当前只显示底层函数的名字。

`\dO[S+] [ `pattern` ]`

  列出排序规则。如果声明了`pattern`， 则只列出名字匹配该模式的排序规则。缺省的，只显示用户创建的对象； 提供一个模式或`S`修饰符包含系统对象。如果在命令名上附加了 `+`，则每个排序规则与和它相关的描述一起列出，如果有的话。 请注意，只显示可用于当前数据库的编码的排序规则，所以相同安装的不同数据库的结果可能不同。

`\dp [ `pattern` ]`

  列出表、视图和序列和它们相关的访问权限。如果声明了 `pattern`， 则只列出名字匹配该模式的表、视图和序列。

  GRANT和REVOKE 命令用于设置访问权限。权限显示的含义在GRANT中解释。

`\drds [ `role-pattern` [ `database-pattern` ] ]`

  列出定义的配置设置。这些设置可以是角色特定的、数据库特定的，或两者都有。 `role-pattern`和`database-pattern` 分别用于选择要列出的特定角色和数据库。如果省略了，或者声明了`*`， 那么列出所有设置，包括那些非角色特定的或非数据库特定的。

  ALTER ROLE和ALTER DATABASE 命令用于定义每用户和每数据库配置设置。

`\dT[S+] [ `pattern` ]`

  列出数据类型。如果声明了`pattern`， 则只列出名字匹配该模式的类型。如果在命令名上附加了`+`， 那么每个类型和它的内部名字和尺寸、它允许的值（如果它是`enum`类型） 和它相关的权限一起列出。缺省的，只显示用户创建的对象；提供一个模式或 `S`修饰符包含系统对象。

`\du[+] [ `pattern` ]`

  列出数据库角色。（因为"用户"和"组"的概念已经统一成"角色"， 所以这个命令现在等于`\du`。）如果声明了 `pattern`，则只列出名字匹配该模式的那些角色。 如果使用了`\du+`格式，则显示关于每个角色的额外信息； 目前这增加了每个角色的注释。

`\dx[+] [ `pattern` ]`

  列出安装了的扩展。如果声明了`pattern`， 则只列出那些名字匹配该模式的扩展。如果使用了`\dx+`格式， 则列出所有属于每个匹配的扩展的对象。

`\dy[+] [ `pattern` ]`

  列出事件触发器。如果声明了`pattern`， 则只列出那些名字匹配该模式的事件触发器。如果在命令名上附加了`+`， 则每个对象都和与其相关的描述一起列出。

`\e` 或 `\edit` `[ `filename` ] [ `line_number` ]`

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

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

  如果声明了行号，psql将在文件或查询缓冲区的指定行上定位游标。 请注意，如果给出了一个数字参数，psql将假设它是一个行号， 而不是文件名。

  > 提示: 参阅下面的环境变量 获取如何配置和自定义你的编辑器。

`\echo `text` [ ... ]`

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

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

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

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

`\ef [ `function_description` [ `line_number` ] ]`

  这个命令抓取并编辑命名函数的定义，以`CREATE OR REPLACE FUNCTION` 命令的形式。编辑处理的方式和`\edit`相同。在编辑退出之后， 更新的命令等待在查询缓冲区中；分号或`\g`发送，或`\r`取消。

  目标函数可以只通过名字指定，或者通过名字和参数指定，例如 `foo(integer, text)`。如果有多个相同名字的函数， 则必须给出参数类型。

  如果没有指定函数，则提供一个空白的`CREATE FUNCTION`模板以供编辑。

  如果声明了行号，psql将在函数体的指定行定位游标。 （请注意，函数体通常不在文件的第一行开始。）

  > 提示: 参阅下面的环境变量 获取如何配置和自定义你的编辑器的信息。

`\encoding [ `encoding` ]`

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

`\f [ `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` `[ `command` ]`

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

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

`\H`或`\html`

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

`\i`或`\include` `filename`

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

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

`\ir`或`\include_relative` `filename`

  `\ir`命令类似于`\i`，但是对相关文件名的解析不同。 当在交互模式执行时，两个命令的表现相同。不过，当在脚本中调用时， `\ir`解释文件名关系为脚本所在的目录，而不是当前工作目录。

`\l[+]` 或 `\list[+] [ `pattern` ]`

  列出服务器上的数据库并显示它们的名字、所有者、字符集编码和访问权限。 如果声明了`pattern`， 则只列出名字匹配该模式的数据库。如果在命令名称后面加一个`+`， 则也显示数据库尺寸、缺省表空间和描述。（尺寸信息只在当前用户可以联接的数据库上可用。）

`\lo_export `loid` `filename``

  从数据库里读取OID为`loid` 的大对象并把它写到`filename`里。 注意这个功能与服务器函数`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`命令看到OID和注解。

  注意这条命令与服务器端的`lo_import`有一些区别， 因为这条命令是本地用户在本地文件系统上操作， 而不是以服务器用户在服务器文件系统上操作。

`\lo_list`

  显示一个目前存储在该数据库里的所有PostgreSQL 大对象和为它们提供的任意注解的列表。

`\lo_unlink `loid``

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

  > 提示: 使用`\lo_list`查找大对象的OID。

`\o`或`\out [ `filename` ]`
`\o`或`\out [ |`command` ]`

  把后面的查询结果分类保存到文件`filename` 里或者把后面的查询结果重定向到shell命令 `command`。 如果没有声明参数，查询输出将被重置为标准输出。

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

  > 提示: 要分散查询结果之间的文本输出，用`\qecho`。

`\p`或`\print`

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

`\password [ `username` ]`

  更改指定用户的口令，缺省为当前用户。该命令将提示口令输入， 然后将加密过的口令使用`ALTER ROLE`之类的命令发送给服务器。 这可以保证新口令不会以明文形式出现在命令历史、服务器日志、或其他什么地方。

`\prompt [ `text` ] `name``

  提示用户提供文本，分配给变量`name`。 可以声明可选的提示字符串`text`。 （对于多个字的提示，用单引号包围文本。）

  缺省的，`\prompt`使用终端输入和输出。不过，如果使用了`-f` 命令行开关，`\prompt`使用标准的输入和输出。

`\pset [ `option` [ `value` ] ]`

  这条命令设置影响查询结果表输出的选项。`option` 描述要设置的选项是哪一个。`value` 的语意也取决于选取的选项。对于一些选项，省略`value`导致选项切换或复位， 就像特定的选项中描述的那样。如果没有提及这样的行为，那么省略 `value`只会导致显示当前的设置。

  没有任何参数的`\pset`显示所有打印选项的当前状态。

  可调节的打印选项有：

  `border`

    `value`必须是一个数字。通常， 数字越大，表就有越宽的边界和越多的线，但是这个参数取决于实际的格式。 在HTML格式中，这个参数会直接翻译成`border=...` 属性，在其它的模式里，只有值 0(无边界)、1(内部分隔线)、2(表框架)有意义。 `latex`和`latex-longtable` 也支持`border`值为3，在每行之间添加一个分隔线。

  `columns`

    为`wrapped`格式设置目标宽度，并且宽度限制决定输出是否太宽需要分页， 或在自动扩展模式下切换到垂直显示。0（缺省）代表目标宽度受到环境变量 `COLUMNS`的控制，或者如果没有设置`COLUMNS`， 则是受到检测到的屏幕宽度的限制。另外，如果`columns`为0， 那么`wrapped`格式只影响屏幕输出。如果`columns`非0， 那么字段和管道输出也包装为那个宽度。

  `expanded` (或 `x`)

    如果声明了`value`，则必须是 `on`或者`off`（这将启用或禁用扩展模式） 或者`auto`。如果省略了`value`， 那么命令在正常和扩展格式之间切换。当打开扩展格式时，查询结果用两列显示， 字段名称在左、数据在右。这个模式在数据无法放进通常的"水平" 模式的屏幕时很有用。在自动设置模式下，扩展模式在查询输出比屏幕宽时使用， 否则使用正常模式。自动设置只在对齐和封装格式下有效。在其他格式下， 它总是表现的好像扩展模式为关闭一样。

  `fieldsep`

    声明在非对齐格式时的域分隔符。这样就可以创建其它程序希望的输出， 例如制表符或逗号分隔的输出。要设置制表符作为域分隔符， 键入`\pset fieldsep '\t'`。缺省域分隔符是 `'|'`(竖条符)。

  `fieldsep_zero`

    设置非对齐输出格式中使用的域分隔符为0字节。

  `footer`

    如果声明了`value`， 它必须是`on`或者`off`， 这将启用或禁用表的脚注的显示（`(`n` rows)`计数）。 如果省略了`value`， 那么命令切换脚注显示为on或off。

  `format`

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

    `unaligned`(不对齐)格式把一条记录的所有字段都输出到一行， 用当前有效的域分隔符分隔。这主要用于生成那些要被其它程序读取的输出 (比如，制表符分隔或逗号分隔格式)。

    `aligned`(对齐)模式是标准的，人类可读的， 格式化好了的文本输出，也是缺省。

    `wrapped`格式类似于`aligned`，但是包装跨行的宽数据值， 使其适应目标字段的宽度输出。目标宽度的确定如`columns`选项中的描述。 请注意，psql将不会尝试包装字段标题：因此， 如果字段标题所需的总宽度超过目标宽度，则`wrapped`格式的行为和 `aligned`相同。

    `html`、`latex`、`latex-longtable`和 `troff-ms`模式把表输出为可用于文档里的对应标记语言。 它们还不是完整的文档！可能对于HTML变化还不是太大， 但是在LaTeX里，你必须有一个完整的文档包装器。 `latex-longtable`也需要LaTeX `longtable`和`booktabs`包装器。

  `linestyle`

    设置边界线绘画风格为`ascii`、`old-ascii` 或`unicode`之一。允许独特的缩写。（这意味着一个字母就足够了。） 缺省设置是`ascii`。这个选项只影响`aligned`和 `wrapped`输出格式。

    `ascii`风格使用纯ASCII字母。 数据中的换行使用一个`+`符号在右手边显示。 当`wrapped`格式从一行到下一行包装数据而不带有换行符时， 一个点(`.`)显示在第一行的右手边，在下一行的左手边。

    `old-ascii`风格使用纯ASCII字符， 使用在PostgreSQL 8.4及更早版本中使用的格式风格。 数据中的换行使用一个`:`符号显示，代替左侧的域分隔符。 当数据从一行包装到下一行而不带有换行符时，使用一个`;`符号， 代替左侧的域分隔符。

    `unicode`风格使用Unicode box-drawing字符。 数据中的换行在右侧使用一个回车符显示。当数据从一行包装到下一行而不带有换行符时， 一个省略号显示在第一行的右手边，在下一行的左手边。

    当`border`设置大于0时，这个选项也决定画边界线的字符。 纯ASCII字符无处不在， 但是Unicode字符看起来显示的更好，更容易辨认。

  `null`

    设置打印出来替换空值的字符串。缺省是什么都不输出， 这样很容易和一个空字符串混淆。例如，可能更喜欢 `\pset null '(null)'`。

  `numericlocale`

    如果声明了`value`，那么它必须是 `on`或`off`，这将启用或禁用区域特定的字符的显示， 分隔小数点左边的数值组。如果省略了`value`， 那么该命令在普通和区域特定的数值输出之间切换。

  `pager`

    控制查询和psql帮助输出的分页器程序的使用。 如果设置了环境变量`PAGER`，那么输出被定向到指定程序， 否则使用系统缺省(比如`more`)。

    如果`pager`选项为`off`，则不使用分页器程序。如果`pager` 选项是`on`，则在适当的时候使用分页器，也就是说，输出是到终端， 而且很可能无法与屏幕匹配。也可以把`pager`选项设置为`always`， 导致在所有终端输出中都使用分页器，而不管它是否适合屏幕。不带有 `value`的`\pset pager` 切换分页器的使用与否。

  `recordsep`

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

  `recordsep_zero`

    设置在非对齐输出格式中使用的记录分隔符为0字节。

  `tableattr` (或 `T`)

    在HTML格式下，这指定了要放置在`table` 标签中的属性。例如`cellpadding`或`bgcolor`。 请注意，你可能不需要在这里声明`border`， 因为已经在`\pset border`里用过了。如果没有给出 `value`，那么表的属性是未设置的。

    在`latex-longtable`格式中，这控制每个包含左对齐数据类型的字段的比例宽度。 它声明为空白分隔的值列表，比如`'0.2 0.2 0.6'`。 为指明的输出列使用最后指定的值。

  `title`

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

  `tuples_only` (或 `t`)

    如果声明了`value`，那么必须是 `on`或`off`，这将启用或禁用仅元组模式。 如果省略了`value`， 那么该命令在普通和仅元组输出间切换。普通输出包括额外的信息， 比如列头、标题、各种脚注等。在仅元组模式下，只显示实际的表数据。

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

  > 提示: 有很多用于`\pset`的快速命令。 参阅`\a`、`\C`、`\H`、 `\t`、`\T`和`\x`。

`\q` 或 `\quit`

  退出psql程序。在脚本文件中，只终止该脚本的执行。

`\qecho `text` [ ... ]`

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

`\r`或`\reset`

  重置(清空)查询缓冲区

`\s [ `filename` ]`

  打印psql的命令行历史到 `filename`。 如果省略则输出到标准输出（适当时使用分页）。 如果psql没有使用Readline 支持建立，那么这个命令是不可用的。

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

  设置psql变量`name` 为`value`，或者如果给出了多于一个值， 设置为所有这些值的连接结果。如果只给出了一个参数，那么只设带有空值的变量。 要重置一个变量，使用`\unset`命令。

  不带有任何参数的`\set`显示所有当前设置的psql 变量的名字和值。

  有效的变量名可以包含字母，数字和下划线。参阅下面的变量获取细节。变量名是大小写敏感的。

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

  > 注意: 这条命令和SQL命令SET是没有关系的。

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

  切换输出的字段名标题和行记数脚注的显示。这条命令等效于`\pset tuples_only`，提供它主要为了方便。

`\T `table_options``

  声明HTML输出格式中放在`table`标记里的属性。 这条命令等效于`\pset tableattr `table_options``。

`\timing [ `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` ]`

  列出带有相关访问权限的表、视图和序列。如果声明了 `pattern`， 则只显示名字匹配该模式的表、视图和序列。

  这是`\dp`("显示权限")的别名。

`\! [ `command` ]`

  返回到一个单独的 shell 或者执行 shell 命令 `command`。参数不会被进一步解释， shell 将看到全部参数。特别的，变量替换规则和反斜杠逃逸并不适用。

`\?`

  显示关于反斜杠命令的帮助信息。

#### 匹配模式

各种`\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`的表。

如果完全省略`pattern`参数， 那么`\d`命令显示所有在当前模式搜索路径中可见的对象， 等价于使用`*`作为匹配模式。（如果一个对象的包含模式在搜索路径中， 并且没有相同类型、名字的对象出现在搜索路径中的更早位置，那么就说该对象是 可见的。这就等于可以通过名字引用而不明确模式限定的语句。） 要查阅在数据库中的所有对象，使用`*.*`模式。

pattern 中的`*`匹配任何字符序列，包括没有字符，而`?` 匹配任何单个字符。这个表示法和 Unix 的 shell 文件名模式兼容。 比如`\dt int*`显示所有名字以`int`开头的表。 但是在双引号内部的`*`和`?`不具有匹配的功能，它们只代表自身。

包含点(`.`)的pattern将被解释成模式名pattern后面跟一个对象名pattern。 例如`\dt foo*.*bar*`显示所有名字以`foo` 开头的模式中的所有名字包含`bar`的表。如果没有出现句点， 那么这个模式只匹配在当前模式搜索路径中可见的对象。同样， 在双引号内的点没有这个含义，它只代表其自身。

还可以使用正则表达式语法，比如字符类等等。例如用`[0-9]`匹配所有数字。 所有正则表达式中的特殊字符都按照第 9.7.3 节 里面描述的规则进行解析，除了`.`如上所述被当做分隔符，`*` 将被理解成`.*`，`?`将被理解成`.`，`$` 逐字匹配之外。这样一来，你就可以用`?`代替`.`、 用`(`R`+|)`代替 ``R`*`、 用`(`R`|)`代替 ``R`?`。 不需要`$`作为正则表达式字符，因为模式必须匹配整个名称， 而不是一般理解的匹配一部分即可（换句话说，`$`自动附加到你的模式）。 如果你只想匹配一部分，可以在 pattern 的开头和结尾使用`*`。 还需要注意的是在双引号内部的所有正则表达式特殊字符都将失去其特殊含义。 同样，在对操作符(也就是作为`\do`参数的时候) 进行匹配时正则表达式特殊字符也将失去其特殊含义。

### 高级特性

#### 变量

psql提供类似通常Unix命令shell那样的变量替换特性。 变量只是简单的名称/值对，这里的值可以是任何长度的任何值。 名字必须由字母（包括非拉丁字母）、数字和下划线组成。

要设置一个变量，使用psql元命令`\set`，例如：

    testdb=> \set foo bar

把变量`foo`的值设置为`bar`。 要检索变量的内容，在变量名前面放上冒号，例如：

    testdb=> \echo :foo
    bar

这在SQL命令和元命令中都能运行；更详细信息在下面的 SQL 代换 中给出。

如果你不带第二个参数调用`\set`，那么设置这个变量， 带有一个空字符串作为值。要重置(也就是删除)一个变量，使用`\unset`命令。 要显示所有变量的值，不带有任何参数的调用`\set`。

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

有一些常用变量被psql特殊相待。它们代表特定的选项设置， 这些选项在运行时可以通过改变变量的值而改变，或者在某些情况下代表 psql的可变状态。尽管你可以把这些变量用于其它用途， 但是不鼓励这么做，因为程序的行为可能会变得非常奇怪。通常， 所有特殊对待的变量名都是由大写ASCII字母组成(可能还有数字和下划线)。 为了保证和未来的最大限度的兼容性，请避免使用这样的变量。 下面是一个所有特殊对待的变量列表。

`AUTOCOMMIT`

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

  > 注意: 在关闭自动提交的模式下，你必须明确放弃任何失败的事务，方法是执行`ABORT` 或`ROLLBACK`。还要注意，如果你不提交就退出会话，所做的工作会丢失。

  > 注意: 打开自动提交是PostgreSQL的传统行为，但是关闭自动提交更接近SQL规范。 如果你更喜欢关闭自动提交，你可以在系统范围的`psqlrc` 或`~/.psqlrc`文件中设置它。

`COMP_KEYWORD_CASE`

  在完成SQL关键字时决定哪个字母使用大小写。如果设置为`lower` 或`upper`，则完成的单词将分别为小写或大写。如果设置为 `preserve-lower`或`preserve-upper`（缺省）， 那么完成的单词将是输入时的情况，但是单词在没有任何输入的情况下完成， 将分别是小写或大写的情况。

`DBNAME`

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

`ECHO`

  如果设为`all`，那么所有非空输入行在读取时都回显到标准输出。 （这不适用于交互式读取的行。） 使用`-a`选项声明在程序启动时就默认这样做。如果设置为`queries`， 那么psql只是在查询发送给服务器时打印到标准输出。 实现这个功能的命令行选项是`-e`。

`ECHO_HIDDEN`

  当这个变量设置为`on`并且一个反斜杠命令查询数据库时，首先显示查询。 这个特性帮助你学习PostgreSQL内部的东西， 并且在你自己的程序里提供类似功能。要在程序一起动的时候就启用这个行为， 可以使用`-E`选项。如果你设置该变量的值为`noexec`， 那么查询只是显示出来但是实际上不发送到服务器去执行。

`ENCODING`

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

`FETCH_COUNT`

  如果该变量的值大于零，`SELECT`查询的结果将按此值分批返回和显示， 而不是缺省的一次取出和显示所有结果。这样就可以无论结果集有多大都只使用很少量的内存。 一般来说，设为 100 到 1000 之间的值比较合理。需要注意的是，使用此特性后， 一个查询可能在显示了一部分结果之后遭遇失败。

  > 提示: 虽然该特性可以用于所有输出格式。但是并不适合在缺省的`aligned` 格式上使用这个特性，因为每一批`FETCH_COUNT`行会被单独的分开格式化， 这样一来每一批输出结果的列宽就可能各不相等。不过对于其他格式这个特性工作的很好。

`HISTCONTROL`

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

  > 注意: 这个特性是从Bash偷学来的。

`HISTFILE`

  此文件将用于存储历史列表。缺省值是`~/.psql_history`。 比如，在`~/.psqlrc`里使用：

      \set HISTFILE ~/.psql_history- :DBNAME

  将使得psql为每个数据库维护一个独立的历史。

  > 注意: 这个特性是从Bash偷学来的。

`HISTSIZE`

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

  > 注意: 这个特性是从Bash偷学来的。

`HOST`

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

`IGNOREEOF`

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

  > 注意: 这个特性是从Bash偷学来的。

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

  设置这个变量为`on`，等效于命令行选项`-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标准。用于数组片段和类型转换的冒号语法是 PostgreSQL扩展，有时与标准的用法会有冲突。 逃逸变量值为SQL文本或标识符的冒号引号语法是psql扩展。

#### 提示符

psql使用的提示符可以根据你的喜好自定义。 三个变量`PROMPT1`、`PROMPT2`、`PROMPT3` 包含描述提示符的外观的字符串和特殊逃逸序列。PROMPT1 是psql 请求一个新命令时使用的正常提示符。PROMPT2 是在一个命令输入期待更多输入时 (因为查询没有用一个分号结束或者引号没有关闭)显示的提示符。 PROMPT3 在你运行一个SQL `COPY` 命令和等待你在终端上键入记录时使用。

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

`%M`

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

`%m`

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

`%>`

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

`%n`

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

`%/`

  当前数据库名称。

`%~`

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

`%#`

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

`%R`

  对于 PROMPT1 通常是`=`，但是如果是单行模式则是`^`， 而如果会话与数据库断开(如果`\connect`失败可能发生) 则是`!`。对于 PROMPT2 该序列被`-`、 `*`、一个单引号/双引号/美元符(取决于psql 是否等待更多的输入：查询没有终止、正在一个`/* ... */` 注释里、正在引号或者美元符逃逸字符串里)代替。对于 PROMPT3 该序列不解释成任何东西。

`%x`

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

`%``digits`

  指定字节值的字符将被替换到该位置。

`%:``name``:`

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

`%```command````

  `command`的输出， 类似于通常的"反勾号"替换。

`%[` ... `%]`

  提示可以包含终端控制字符，这些字符可以改变颜色、背景、提示文本的风格、 终端窗口的标题。为了让Readline的行编辑特性正确运行， 这些不可打印的控制字符必须设计成不可见的，方法是用`%[` 和`%]`包围它们。在提示符里可能出现这些东西的多个配对。例如：

      testdb=> \set PROMPT1 '%[%033[1;33;40m%]%n@%/%R%[%033[0m%]%# '

  的结果是在 VT100 兼容的可显示彩色的终端上的一个宽体(`1;`) 黑底黄字(`33;40`)。

键入`%%`可以在提示符里插入百分号。 缺省提示符为`'%/%R%# '`用于第一二个提示符， `'>> '`用于第三个提示符。

> 注意: 这个特性是从tcsh偷学来的。

#### 命令行编辑

psql为了编辑和检索命令行的方便支持 Readline库。命令历史在psql 退出的时候自动保存，在psql启动的时候加载。 还支持 Tab 补齐，尽管该补齐逻辑并不是一个SQL分析器必备的。 tab补齐产生的查询也可以与其他SQL命令交互，比如`SET TRANSACTION ISOLATION LEVEL`。 如果因某些原因你不喜欢 tab 补齐，可以把下面几行放在你的家目录下的 `.inputrc`文件里关闭这个特性：

    $if psql
    set disable-completion on
    $endif

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

## 环境变量

`COLUMNS`

  如果`\pset columns`为0，控制`wrapped` 格式的宽度和宽度确定（如果宽的输出需要分页或在自动扩展模式应该切换为垂直模式）。

`PAGER`

  如果查询结果在一页里放不下，那么它们被重定向到这个命令。 典型的值是`more`或`less`。 缺省值是平台相关的。可以用`\pset`命令关闭分页器。

`PGDATABASE`
`PGHOST`
`PGPORT`
`PGUSER`

  缺省连接的参数（参阅第 31.14 节）。

`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`。

这个工具，像大多数其他PostgreSQL工具一样， 也使用libpq提供的环境变量（参阅第 31.14 节）。

## 文件

`psqlrc`和`~/.psqlrc`

  除非传递了`-X`或`-c`选项， psql尝试读取和执行来自系统范围的 `psqlrc`启动文件的命令，然后是用户 `~/.psqlrc`启动文件里面的命令， 在连接到数据库之后，接受普通命令之前。 这些文件可以用来按需求设置客户端或者服务器， 典型的是使用`\set`和`SET`命令。

  系统范围的启动文件名为`psqlrc`， 在安装的"系统配置"目录下查找，可以通过运行`pg_config --sysconfdir`可靠的识别。缺省情况下，这个目录是 `../etc/`，相对于包含PostgreSQL 可执行文件的目录。这个目录的名字可以通过`PGSYSCONFDIR` 环境变量明确的设置。

  用户的启动文件名为`.psqlrc`，在用户的根目录下查找。 在Windows上，缺乏这样一个概念，用户个人的启动文件名为 `%APPDATA%\postgresql\psqlrc.conf`。 用户的启动文件的位置可以通过`PSQLRC`环境变量明确的设置。

  系统范围的启动文件和用户自己的启动文件都可以是psql 版本特定的，通过在后面附着一个破折号和PostgreSQL 主要或次要版本号， 比如`~/.psqlrc-9.2`或`~/.psqlrc-9.2.5`。 更确切的版本匹配文件比无版本的文件优先读取。

`.psql_history`

  命令行历史存储在`~/.psql_history`文件中， 或者在 Windows 里是`%APPDATA%\postgresql\psql_history`文件。

  历史文件的位置可以通过`PSQL_HISTORY`环境变量来明确设置。

## 注意

- 一些psql的早期版本允许一个单字母的反斜杠命令 (元命令)的第一个参数直接跟在命令后面，而不用空白间隔。 到了PostgreSQL 8.4就不再允许这样使用了。

- psql能与同版本或更老主要版本的服务器工作。 如果服务器的版本比psql本身要新，则反斜杠命令是特别容易失效的。 不过，`\d`家族的反斜杠命令应该在7.4的服务器版本上工作， 尽管不必要用比psql本身更新的服务器。 运行SQL命令和显示查询结果的通用功能也应该在更新主版本的服务器上工作， 但是并不保证所有情况都没问题。

  如果你想要使用psql连接几个不同主版本的服务器， 建议你使用psql的最新版本。或者， 你可以保存每个主版本的psql的拷贝， 确保使用匹配各自服务器的版本。但是在实际中，不必要弄的这么复杂。

## Windows 用户需要注意的地方

psql是以一种"控制台应用"的方式制作的。 因为 Windows 控制台窗口和系统其它部分使用不同的编码，所以在 psql里使用 8 位字符的时候必须采取特殊的注意措施。 如果psql检测到一个有问题的控制台代码页， 那么它在启动的时候会警告你。要修改控制台代码页，有两件事是必须做的：

- 通过输入`cmd.exe /c chcp 1252`设置代码页。 （1252 是适用于德语的代码页；请换成合适你的数值。） 如果你使用 Cygwin ，你可以在`/etc/profile`里面输入这条命令。

- 控制台字体设置为`Lucida Console`，因为光栅字体(点阵字体) 不能在 ANSI 代码页下工作。

## 例子

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

    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    |

把提示符变成更有趣的东西：

    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

上一页 | 起始页 | 下一页
pg_restore | 上一级 | reindexdb