如果因为任何原因而无法与数据库相联(例如,权限不够,postmaster 没有运行等),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 命令的格式是反斜杠后面紧跟一个命令动词,然后是任意参数.参数与命令动词和其他参数以任意个空白字符间隔.
要在参数里面包含空白,你必须用单引号把它包围起来。要在这样的参数里包含单引号,前面加一个反斜杠。任何包含在单引号里的东西会被进一步进行类 C 的替换,把 \n (新行),\t (tab), \digits,\0digits 和 \0xdigits (给出的十进制,八进制,或十六进制码的字符)替换掉。
如果一个不带引号的参数以冒号(:)开头,它会被当作一个变量,并且该变量的值会最终成为真正的参数值。(译注:类似嵌入SQL的变量用法。)
用“反勾号” (backticks(`))引起的内容被当作一个命令行传入 shell。该命令的输出(删除了结尾的新行)被当作参数值。上面描述的转意(字符)序列在反勾号里也生效。(译注:与 shell 程序类似)
有些命令以一个 SQL 标识的名称(如,一个表名)为参数。这些参数遵循SQL 语法关于双引号的规则:不带双引号的标识强制成小写。对于所有其他命令,双引号没有特殊含义并且将被当成参数的一部分。
对参数的分析在碰到另一个不带引号的反斜杠时停止。这里会认为是一个新的专有命令的开始。特殊序列 \\ (双反斜杠)标识参数的结尾并将继续分析后面的SQL 查询(如果存在的话)。这样 SQL 和 psql 命令可以自由的在一行里面混合。但是在任何情况下,一条专有命令的参数不能延续超过行尾。
下列专有命令是已定义的:
如果省略 username,则假设是当前用户名。
作为一条特殊规则,不带任何参数运行 \connect 将以缺省用户身份与缺省数据库连接(正如你不带任何参数运行psql 一样。)
如果联接失败(用户名错,访问拒绝等),那么将保留前面的联接--仅仅是在psql
处于交互模式下如此。如果运行的是非交互的脚本,处理会马上停止,并返回一个错误。选择这样的区别是一方面为用户使用方便考虑,另一方面为保证脚本不会碰巧操作了错误的数据库的安全机制考虑的。
这条命令的语法是模拟SQL COPY 命令的,参考它的描述获取细节。要注意的是由此而来,有一些特殊的分析规则应用于 \copy 命令。尤其是变量替换规则和反斜杠代换规则不起作用。
小技巧:此操作不象 SQLCOPY 命令这样高效,因为所有数据必须通过(客户/服务器))client/server IP 或套接字联接.对于大数据量的操作,另一种方法更可行。注意:注意在前端和后端拷贝时对 stdin 和 stdout 的解释的区别:在前端拷贝时,这些总是指psql 的输入和输出流。在后端拷贝时 stdin 来自 COPY 本身的标准输入(比如,一个带有-f 选项的脚本),而 stdout 指的是查询输出流(参阅下面的 \o 专有命令)。
从 \d+ 来的命令也是一样的,只不过还显示与表的列关联的注解。
注意:如果不带任何参数调用 \d,等效于 \dtvs,将显示一个所有表,视图和序列的列表。这完全是出于方便的考虑。
=> \dd version Object descriptions Name | What | Description ---------+----------+--------------------------- version | function | PostgreSQL version string (1 row)
可以用 COMMENT ONSQL 命令生成对对象的描述。
注意:PostgreSQL 在 pg_description 系统表里存储对象描述。
如果声明了 pattern,它是一个规则表达式把输出限制在那些匹配的条目上。如果我们在命令名称后面加一个 "+" ,那么每个对象存在的相关描述也会显示出来。
然后根据一般的psql 规则重新分析查询缓冲区,这时整个缓冲区当作一个单行。(因此你无法用这个方法制作“脚本”,用 \i 做脚本。)这还意味着如果该查询以分号结尾(或者包含分号),它就会马上被执行。否则它只是在查询缓冲区里等待。
小技巧:psql 搜索环境变量 PSQL_EDITOR,EDITOR 和 VISUAL(以此顺序)查找要用到哪个编辑器。如果上面的都没有设置,使用 /bin/vi。
=> \echo `date` Tue Oct 26 21:40:57 CEST 1999
如果第一个参数是一个无引号的 -n,那么不会写出结尾的新行。小技巧:如果你使用 \o 命令重定向你的查询的输出,你可能会用 \qecho 取代这条命令。
注意:为简化敲击,包含多个单字的命令不需要引起。因此键入 \help alter table 是正确的。
从文件 filename 中读取并把其内容当作从键盘输入的那样执行查询。注意:如果你想在屏幕上看到读入的行,你必须对所有行设置变量 ECHO 。
列出服务器上所有数据库和它们的所有者。在命令名称后面加一个 "+" 还可以看到对数据库的任何描述。如果你的Postgres 节点是带着多字节支持编译的,还可以看到每个数据库的编码方式。
小技巧:使用 \lo_list 查看大对象的 OID。注意:参阅变量 LO_TRANSACTION 的描述获取关于所有大对象操作的重要信息。
foo=> \lo_import '/home/peter/pictures/photo.xcf' 'a picture of me' lo_import 152801响应表明此大对象得到一个对象标识 152801,如果你还想访问该对象,就应该把这个对象标识记住。因此,我们建议总是给每个对象关联一个人类可读的注解。那样就可以用 \lo_list 命令看到这些注解。
注意这条命令与服务器端的 lo_import 有一些区别,因为这条命令是本地用户在本地文件系统上操作,而不是以服务器用户在服务器文件系统上操作。
注意:参阅变量 LO_TRANSACTION 的描述获取关于所有大对象操作的重要信息。
从数据库里删除 OID 是 loid 的大对象。
小技巧:使用 \lo_list 查找大对象的 OID。注意:参阅变量 LO_TRANSACTION 的描述获取关于所有大对象操作的重要信息。
把后面的查询结果保存到文件 filename 里或者把后面的查询结果定向到一个独立的 Unix shell 执行 command。如果没有声明参数,查询输出重置为 stdout。
“查询结果”包括所有表,命令响应和从数据库服务器来的提示,同样还有各种各样查询数据库的反斜杠命令的输出(如 \d),但是没有错误信息。
小技巧:要分散查询结果之间的输出,用 \qecho。
设置输出格式为 unaligned,aligned,html 或 latex 之一。允许使用唯一的缩写。(这也意味着一个字母就够了。)
“Unaligned” (不对齐)把一条记录的所有域都都输出到一行,用当前有效的域分隔符分隔。这主要用于生成那些要被其他程序读取的输出(tab分隔,逗号分隔)。“Aligned”(对齐)模式是标准的,人类可读的,格式化好了的文本输出,也是缺省。“HTML”
和“LaTeX” 模式把表输出为可用于文档里的对应标记语言。它们还不是完整的文档!(可能对于HTML
变化还不是太大,但是在 LaTeX 里,你必须有一个完整的文档包装器。)
第二个参数必须是一个数字。通常,数字越大,表就有越宽的边界和越多的线,但是这个参数取决于实际的格式。在HTML
模式里,这个参数会直接翻译成 border=... 属性,在其他的模式里,只有值
0 (无边界),1 (内部分隔线)和 2 (表框架)有意义。
所有四种输出模式都支持扩展模式。
第二个参数是一个字串,用以代表域的值为 null 打印。缺省是什么都不打,这样很容易和类似一个空字串混淆。因此,我们可能选择
\pset
null "(null)"。
声明在非对齐模式时的域分隔符。这样我们就可以创建其他程序希望的 tab-
或逗号分隔的输出。要设置 tab 域分隔符,键入 \pset fieldsep "\t"。缺省域分隔符是“|”
(一个“管道”符号)。
在完全显示和只显示记录之间切换。完全显示将显示象列头,标题和各种脚注等信息。只显示记录模式将只显示实际的表数据。
为任何随后打印的表设置标题。这个参数可以用于给你的输出一个描述性标记。如果不带参数,重置标题。
注意:以前这个参数只影响HTML 模式,现在你可以在任何输出模式里设置标题。
允许你声明放在 HTML table
标记里的任何属性。例如,可以是 cellpadding 或者 bgcolor。注意你可能不需要在这里声明
border,因为已经在
\pset
border 里用过了。
激活分页器进行表输出。如果设置了环境变量 PAGER,输出被定向到指定程序,否则使用 more。
不管怎样,psql 只在它认为需要的时候使用分页器。这意味着输出是到终端去的而那个表很可能无法与屏幕匹配。因为打印过程的模块化天性,我们不可能每次都准确预计出实际打印的行数。因此psql
在决定何时分页时可能显得不是很有识别力。
小技巧:有很多用于 \pset 的快速命令。参阅 \a,\C,\H,\t,\T 和 \x。注意:无参数运行 \pset 是错误的。以后这样调用将显示当前打印选项状态。
注意:对于 psql v7.0,这个( GNU 历史库)不再是必须的了,实际上,在程序结束时自动保存命令行历史。每次psql 启动都会装载命令行历史。
有效的变量名可以包含字符,数字和下划线。参阅关于psql 变量的章节获取细节。
尽管你可以设置任何变量为任意值,psql 对一些变量特殊对待。它们在关于变量的节里面有文档。
- 注意:这条命令是完全和 SQL 命令 SET不一样的。
test=> \z Access permissions for database "test" Relation | Access permissions ----------+------------------------------------- my_table | {"=r","joe=arwR", "group staff=ar"} (1 row )
"joe=arwR": 用户 joe 拥有读,写(UPDATE,DELETE),“追加”(INSERT)权限,以及在表上创建规则的权限。
query 必须是一条完全可以被后端分析的查询字串(也就是说,它不包含psql
特有的特性),或者是一个反斜杠命令。这样你就不会混合SQL
和 psql 专有命令。要想混合使用,你可以把字串定向到psql
里,象这样:echo "\x \\ select * from foo;" | psql。
使用这个选项与用 psql < filename 有微小的区别。通常,两者都回按照你预期那样运行,但是使用
-f
打开了一些很好的特性,比如带行号的错误信息。而且,使用这个选项还有可能有减小启动负荷的机会。另一方面,如果你把所有内容手工输入,使用
shell 输入定向的方式(理论上)能保证生成和你已经得到的完全一样的输出(译注:重复运行命令)。
进入单行运行模式,这时每个查询都将由换行符结束,象分号那样。注意:注意这个模式是给那些坚持要这个特性的人的,我们不鼓励你这么用。实际上,如果你在一行里混合使用SQL 和专有命令,执行的顺序对不熟练的用户而言不总是清晰的。
我们不赞成使用这个选项,因为它在概念上有漏洞。(提示输入非缺省用户名和提示输入后端要求的口令是完全两码事。)我们鼓励你用-U 和 -W 选项取代。
对于版本7.0,如果后端要求口令认证,psql 自动提出一个口令提示符。因为目前这个特性是以一个“hack”为基础,自动识别有可能神秘地失效,因此用这个选项强制一个提示符。如果没有声明口令提示符而后端要求口令认证,那么联接企图将失败。
testdb=> \set foo bar把变量“foo” 设置为值“bar”。要检索变量的内容,在变量名前面放上冒号然后把它用在任意斜杠命令里:
testdb=> \echo :foo bar
注意:\set 的参数服从和其他命令一样的替换规则。因此你可以构造有趣的引用,象 \set :foo 'something' 这样,获得分别象Perl 或 PHP那样有名的“软链接”(“soft links”)或“变量 变量”(“variable variables”)。不幸的是(或者 万幸的?),用这些构造不能做任何有用的事情。另一方面,\set bar :foo 是一个非常有效的拷贝变量的方法。
psql 的内部变量可以包括任意顺序,任意数量的字母,数字和下划线。有一些常用变量被psql 另眼相待。它们是一些选项设置,这些选项在运行时可以通过改变变量的值或者改变一些应用的表现状态而改变。尽管你可以把这些变量用于其他用途,但是我们不鼓励这么做,因为程序的特性可能会很快变得非常奇怪。通常,所有特殊对待的变量都是由大写字母组成(可能还有数字和下划线)。为了保证和未来的最大限度的兼容性,请避免使用这样的变量。下面是一个所有特殊对待的变量列表。
存在命令历史里的命令的个数。缺省值是 500。
要选择你希望做的事,你可以把此变量设置为“rollback”,“commit”或“nothing”之一。缺省是回卷事务。如果你只是希望装载一个或者少数几个对象,这个方法很好。但是如果你希望传输许多大对象,我们建议给所有命令提供一个显式的事务块。
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 扩展,因此有冲突。)
相应的提示符变量的值是按字面打印的,除非碰到一个百分号(“%”)。这时某些其他的文本被替换,替换为何物取决于下一个字符。已定义的替换是:
要在提示符里插入百分号,键入 %%。缺省提示符等效于 '%/%R%# ' 用于 prompts 1 和 2,以及 '>> ' 用于 prompt 3。
注意:这个特性是无耻地从 tcsh 里剽窃来的。
在启动之前,psql 试图读取并执行文件 $HOME/.psqlrc 里的命令。这个特性可以用来按口味设置客户端或者服务器(用 \set 和 SET 命令)。
$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 行读库可以从 GNU
计划的 FTP 服务器 ftp://ftp.gnu.org
得到。
注意:本节只是显示了 psql 少数几个例子。如果你希望学习 SQL 或者熟悉 Postgres,你可能愿意阅读一下包含在这个版本里的教程。
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)注意 int4 列是怎样右对齐的以及 text 列是如何左对齐的。你可以用 \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
testdb=> \foo Field separator is "oo".可能不是你想要的东西。