ltsql — LightDB的交互式终端
ltsql
[option
...] [dbname
[username
]]
ltsql是一个LightDB的基于终端的前端。它让你能交互式地键入查询,把它们发送给LightDB,并且查看查询结果。或者,输入可以来自于一个文件或者命令行参数。此外,ltsql还提供一些元命令和多种类似 shell 的特性来为编写脚本和自动化多种任务提供便利。
-a
--echo-all
把所有非空输入行按照它们被读入的形式打印到标准输出(不适用于交互式行读取)。这等效于把变量ECHO
设置为
all
。
-A
--no-align
切换到非对齐输出模式(默认输出模式是对齐
的)。这等效于\pset format unaligned
。
-b
--echo-errors
把失败的 SQL 命令打印到标准错误输出。这等效于把变量ECHO
设置为errors
。
-c command
--command=command
指定ltsql执行一个给定的命令字符串command
。这个选项可以重复多次并且以任何顺序与-f
选项组合在一起。当-c
或者-f
被指定时,ltsql不会从标准输入读取命令,直到它处理完序列中所有的-c
和-f
选项之后终止。
command
必须是一个服务器完全可解析的命令字符串(即不包含ltsql相关的特性)或者单个反斜线命令。因此不能在一个-c
选项中混合SQL和ltsql元命令。要那样做,可以使用多个-c
选项或者把字符串用管道输送到ltsql中,例如:
ltsql -c '\x' -c 'SELECT * FROM foo;'
或者
echo '\x \\ SELECT * FROM foo;' | ltsql
(\\
是分隔符元命令)。
每一个被传递给-c
的SQL命令字符串会被当做一个单独的请求发送给服务器。因此,即便该字符串包括多个SQL命令,服务器也会把它当做一个事务来执行,除非在该字符串中有显式的BEGIN
/COMMIT
命令把它划分成多个事务(服务器如何处理多查询字符串的更多细节请参考Section 51.2.2.1)。此外,ltsql只会打印出该字符串中最后一个SQL命令的结果。这和从文件中读取同一字符串或者把同一字符串传给ltsql的标准输出时的行为不同,因为那两种情况下ltsql会独立地发送每一个SQL命令。
由于这种行为,把多于一个SQL命令放在-c
字符串中通常会得到意料之外的结果。最好使用多个-c
命令或者把多个命令输送给ltsql的标准输入,按照上文所说的使用echo或者通过一个 shell,例如:
ltsql <<EOF \x SELECT * FROM foo; EOF
--csv
切换到CSV(逗号分隔值)输出模式。 这相当于\pset format csv
。
-d dbname
--dbname=dbname
指定要连接的数据库的名称。这等效于指定dbname
为命令行上的第一个非选项参数。dbname
可以是 连接字符串。 如果是这样,连接字符串参数将覆盖任何冲突的命令行选项。
-e
--echo-queries
也把发送到服务器的所有 SQL 命令复制到标准输出。这等效于把变量ECHO
设置为queries
。
-E
--echo-hidden
回显\d
以及其他反斜线命令生成的实际查询。可以用它来学习ltsql的内部操作。这等效于把变量ECHO_HIDDEN
设置为on
。
-f filename
--file=filename
从文件filename
而不是标准输入中读取命令。这个选项可以被重复多次,也可以以任意顺序与-c
选项组合。当-c
或者-f
被指定时,ltsql不会从标准输入读取命令,直到它处理完序列中所有的-c
和-f
选项之后终止。除此以外,这个选项很大程度上等价于元命令\i
。
如果filename
是-
(连字符),那么会读取标准输入直到遇见一个 EOF 指示或者\q
元命令。这种方式可以用把自多个文件的输入组合成一种交互式输入。不过注意在这种情况下不会使用 Readline(很像指定了-n
的情况)。
使用这个选项与ltsql <
有细微的不同。通常,两种形式都可以做到我们所期望的,但是使用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
类似。
在使用这个选项时,ltsql将连接到数据库postgres
,除非在命令行上提及一个不同的数据(选项-d
或非选项参数,可能是通过一个服务项,但不能通过一个环境变量)。
-L filename
--log-file=filename
除了把所有查询输出写到普通输出目标之外,还写到文件filename
中。
-n
--no-readline
不使用Readline做行编辑并且不使用命令历史。在剪切和粘贴时,关掉 Tab 展开会有所帮助。
-o filename
--output=filename
把所有查询输出放到文件filename
中。这等效于命令\o
。
-p port
--port=port
指定服务器用于监听连接的 TCP 端口或者本地 Unix 域套接字文件扩展。默认是LTPORT
环境变量的值,如果没有设置,则默认为编译时指定的端口号(通常是5432)。
-P assignment
--pset=assignment
以\pset
的形式指定打印选项。注意,这里你必须用一个等号而不是空格来分隔名称和值。例如,要设置输出格式为LaTeX,应该写成-P format=latex
。
-q
--quiet
指定ltsql应该安静地工作。默认情况下,它会打印出欢迎消息以及多种输出。如果使用了这个选项,以上那些就都不会输出。在使用-c
选项时,配合这个选项很有用。这等效于设置变量QUIET
为on
。
-R separator
--record-separator=separator
把separator
用作非对齐输出的记录分隔符。这等效于\pset recordsep
命令。
-s
--single-step
运行在单步模式中。这意味着在每个命令被发送给服务器之前都会提示用户一个可以取消执行的选项。使用这个选项可以调试脚本。
-S
--single-line
运行在单行模式中,其中新行会终止一个 SQL 命令,就像分号的作用一样。
这种模式被提供给那些坚持使用它的用户,但是并不一定要使用它。特别地,如果在一行中混合了SQL和元命令,那对于没有经的用户来说,它们的执行顺序可能不总是那么清晰。
-t
--tuples-only
关闭打印列名和结果行计数页脚等。这等效于\t
或者\pset tuples_only
命令。
-T table_options
--table-attr=table_options
指定要替换HTML table
标签的选项。详见\pset tableattr
。
-U username
--username=username
作为用户username
而不是默认用户连接到数据库(当然,你必须具有这样做的权限)。
-v assignment
--set=assignment
--variable=assignment
执行一次变量赋值,和\set
元命令相似。注意你必须在命令行上用等号分隔名字和值(如果有)。要重置一个变量,去掉等号就行。要把一个变量置为空值,使用等号但是去掉值。这些赋值在命令行处理期间被完成,因此反映连接状态的变量将在稍后被覆盖。
-V
--version
打印ltsql版本并且退出。
-w
--no-password
从不发出一个口令提示。如果服务器要求口令认证并且口令不能从其他来源(例如一个.pgpass
文件)获得,那儿连接尝试将失败。这个选项对于批处理任务和脚本有用,因为在其中没有一个用户来输入口令。
注意这个选项将对整个会话保持设置,并且因此它会影响元命令\connect
的使用,就像初始的连接尝试那样。
-W
--password
强制ltsql在连接到一个数据库之前提示要求一个口令,即使口令不会被使用。
如果服务器需要口令认证并且口令不能从其他来源获得,例如 .pgpass
文件,ltsql 在任何情况下都会提示输入口令。 然而,ltsql 将浪费一次连接尝试来发现服务器想要一个口令。在某些情况下值得用-W
来避免额外的连接尝试。
注意这个选项将对整个会话保持设置,并且因此它会影响元命令\connect
的使用,就像初始的连接尝试那样。
-x
--expanded
打开扩展表格式模式。这等效于\x
或者\pset expanded
命令。
-X,
--no-ltsqlrc
不读取启动文件(要么是系统范围的ltsqlrc
文件,要么是用户的~/.ltsqlrc
文件)。
-z
--field-separator-zero
设置非对齐输出的域分隔符为零字节。这等效于\pset fieldsep_zero
。
-0
--record-separator-zero
设置非对齐输出的记录分隔符为零字节。例如,这对与xargs -0
配合有关。这等效于\pset recordsep_zero
。
-1
--single-transaction
这个选项只能被用于与一个或者多个-c
以及/或者-f
选项组合。它会让ltsql在第一个上述选项之前发出一条BEGIN
命令并且在最后一个上述选项之后发出一条COMMIT
命令,这样就把所有的命令都包裹在一个事务中。这个选项可以保证要么所有的命令都成功地完成,要么不应用任何更改。
如果命令本身包含BEGIN
、COMMIT
或者ROLLBACK
,这个选项将不会得到想要的效果。还有,如果当个命令不能在一个事务块中执行,指定这个选项将导致整个事务失败。
-?
--help[=topic
]
显示有关ltsql的帮助并且退出。可选的topic
参数(默认为options
)选择要解释哪一部分的ltsql:commands
描述ltsql的反斜线命令;options
描述可以被传递给ltsql的命令行选项;而variables
则显示有关ltsql配置变量的帮助。
如果ltsql正常完成,它会向 shell 返回 0。如果它自身发生一个致命错误(例如内存用完、找不到文件),它会返回 1。如果到服务器的连接出问题并且事务不是交互式的,它会返回 2。如果在脚本中发生错误,它会返回 3 并且变量ON_ERROR_STOP
会被设置。
ltsql是一个常规LightDB客户端应用。为了连接到数据库,你需要知道你的目标数据库的名称、主机名和该服务器的端口号,还有要作为哪个用户名连接。可以通过命令行选项告知ltsql这些参数,分别是-d
、-h
、-p
以及-U
。如果发现一个参数不属于任何选项,它将被解释为数据库名称(如果已经给出数据库名称,就解释为用户名)。并非所有这些选项都是必需的,它们都有可用的默认值。如果省略主机名,ltsql将通过一个 Unix 域套接字连接到本地主机上的服务器,或者通过 TCP/IP 连接到没有 Unix 域套接字的主机上的localhost
。默认端口号则在编译时决定。由于数据库服务器使用相同的默认值,大多数情况下你将不必指定端口。默认的用户名是你的操作系统用户名,它也会是默认的数据库名。注意你不一定能连接到任意用户名下的任何数据库。你的数据库管理员应该已经告知过你有关你的访问权限。
当默认值不是很符合实际时,可以把环境变量LTDATABASE
、LTHOST
、LTPORT
以及LTUSER
设置为适当的值,这样也能节省一些敲打键盘的工作(额外的环境变量可见Section 32.14)。用一个~/.pgpass
文件来避免定期输入密码也很方便。详见Section 32.15。
另一种指定连接参数的方法是用一个conninfo
字符串或者一个URI,它可以被用来替代数据库名。这种机制可以让我们对连接具有很广的控制权。例如:
$ltsql "service=myservice sslmode=require"
$ltsql postgresql://dbmaster:5433/mydb?sslmode=require
可用连接选项的更多信息请见Section 32.1.2。
如果由于任何原因(例如权限不足、服务器没有在目标主机上运行等)导致连接无法建立,ltsql将返回一个错误并且终止。
如果标准输入和标准输出都是一个终端,那么ltsql会把客户端编码设置成“auto”,这会使ltsql从区域设置(Unix 系统上的LC_CTYPE
环境变量)中检测合适的客户端编码。如果这样不起作用,可以使用环境变量LTCLIENTENCODING
覆盖客户端编码。
在正常操作时,ltsql会提供一个提示符,该提示符是ltsql当前连接到的数据库名称后面跟上字符串=>
。例如:
$ ltsql test
ltsql (13.8-24.2)
compatible type: postgresql
Type "help" for help.
test=>
在提示符下,用户可以键入SQL命令。正常情况下,当碰到一个表示命令终结的分号时,输入的行会被发送给服务器。一行的结束并不表示命令的完结。因此,为了清晰,可以把命令散布在多个行上。如果命令被发送并且执行而不产生错误,该命令的结果将会显示在屏幕上。
如果不可信用户对还没有采用安全方案使用模式的一个而数据库拥有访问,通过从search_path
移除公共可写的方案来开始你的会话。人们可以在连接字符串中加入options=-csearch_path=
或者在其他SQL命令之前发出SELECT pg_catalog.set_config('search_path', '', false)
。这种考虑并非专门针对ltsql,它适用于每一种执行任意SQL命令的接口。
只要执行命令,ltsql还会测试LISTEN
和NOTIFY
产生的异步通知。
虽然 C 风格的注释块会被传给服务器处理并且移除,ltsql会自己移除掉 SQL 标准的注释。
命令prompt将提示文本打印到标准输出, 这对于在脚本输出中散布信息很有用,可以通过ltsql -f 文件名的方式使用,也可以在ltsql的交互模式中使用。 命令prompt不区分大小写,允许命令前有注释、SQL命令、空格、制表符和空白行。 例如:
lightdb@postgres=#prompt create table start
create table start lightdb@postgres=#create table test(id int);
CREATE TABLE lightdb@postgres=#Prompt select start
select start lightdb@postgres=#select count(*) from test;
count ------- 0 (1 row) lightdb@postgres=#drop table test; prompt drop table test;
DROP TABLE drop table test; lightdb@postgres=#/* test prompt */ prompt /* test prompt */
/* test prompt */
spool指令来源于oracle的sqlplus工具。在交互模式下该指令可以将sqlplus的输出重定向至指定文件。 此命令是大小写无关的且需要跟随某个文件路径或用关键词'off'将其重定向至标准输出。虽然该指令能忽略 多余的空格,但是值得注意的是,其遇到分号或是换行符时将会停止。 示例:
lightdb@postgres=#spool test_spool.log;
lightdb@postgres=#create table spool1(spool int);
lightdb@postgres=#insert into spool1 values(5);
lightdb@postgres=#select * from spool1;
lightdb@postgres=#spool off;
-- 检查test_spool.log是否包含记录 lightdb@postgres=#\! cat test_spool.log
spool ------- 5 (1 row) lightdb@postgres=#select * from spool1;
spool ------- 5 (1 row) lightdb@postgres=#spool;
lightdb@postgres=#select * from spool1;
spool ------- 5 (1 row)
rename指令来源于oracle的sqlplus工具。在交互模式下该指令可以对一个表或视图通过给定的参数"old_table"及"new_table"进行重命名。 此命令是大小写无关的且忽略自身内部多余的空格但当遇到一个分号或换行符时将停止。因此用户无法跨行使用此命令。 示例:
lightdb@test_mysql_select=# rename table_oldname to table_newname;
ALTER TABLE
你输入到ltsql中的任何以未加引用的反斜线开始的东西都是一个ltsql元命令,它们由ltsql自行处理。这些命令让ltsql对管理和编写脚本更有用。元命令常常被称作斜线或者反斜线命令。
ltsql命令的格式是用反斜线后面直接跟上一个命令动词,然后是一些参数。参数与命令动词和其他参数之间用任意多个空白字符分隔开。
要在一个参数中包括空白,可以将它加上单引号。要在一个参数中包括一个单引号,则需要在文本中写上两个单引号。任何包含在单引号中的东西都服从与 C 语言中\n
(新行)、\t
(制表符)、\b
(退格)、\r
(回车)、\f
(换页)、\
digits
(10 进制)以及\x
digits
(16 进制)类似的替换规则。单引号内文本中的其他任何字符(不管它是什么)前面的反斜线都没有实际意义(会被忽略)。
如果在一个参数中出现一个未加引号的冒号(:
)后面跟着一个ltsql变量名,它会被该变量的值替换,
如下面的SQL Interpolation所述。在其中描述的形式:'
和variable_name
':"
也有同样的效果。variable_name
":{?
语法允许测试一个变量是否被定义。它会被TRUE或FALSE替换。用一个反斜线转义该冒号可以防止它被替换。
variable_name
}
在一个参数中,封闭在反引号(`
)中的文本会被当做一个传递给shell的命令行。该命令的输出(移除任何拖尾的新行)会替换反引号文本。在封闭在反引号的文本中,不会有特别的引号或者其他处理发生,:
的出现除外,其中variable_name
variable_name
是一个会被其值替换的ltsql变量名。此外,Also, appearances of
:'
的出现会被替换为该变量的值,而值会被适当地加以引用以变成一个单一shell命令参数(后一种形式几乎总是优先,除非你非常确定变量中有什么)。因为回车和换行字符在所有的平台上都不能被安全地引用,variable_name
':'
形式会打印一个错误消息并且在这类字符出现在值中时不替换该变量值。
variable_name
'
有些命令把SQL标识符(例如一个表名)当作参数。这些参数遵循SQL的语法规则:无引号的字母被强制变为小写,而双引号("
)可以保护字母避免大小写转换并且允许在标识符中包含空白。 在双引号内,成对的双引号会被缩减为结果名称中的单个双引号。例如,FOO"BAR"BAZ
会被解释成fooBARbaz
,而"A weird"" name"
会变成A weird" name
。
对参数的解析会在行尾或者碰到另一个未加引号的反斜线时停止。一个未加引号的反斜线被当做新元命令的开始。特殊的序列\\
(两个反斜线)表示参数结束并且应继续解析SQL命令(如果还有)。使用这种方法,SQL命令和ltsql命令可以被自由地混合在一行中。但是无论在何种情况中,元命令的参数都无法跨越一行。
很多元命令作用在当前查询缓冲区上。这就是一个缓冲区而已,它保存任何已经被键入但是还没有发送到服务器执行的SQL命令文本。这将包括之前输入的行以及在该元命令同一行上出现在前面的任何文本。
可以使用下列元命令:
\a
如果当前的表输出格式是非对齐的,则切换成对齐格式。如果不是非对齐格式,则设置成非对齐格式。保留这个命令是为了向后兼容性。更一般的方案请见\pset
。
\c
or \connect [ -reuse-previous=on|off
] [ dbname
[ username
] [ host
] [ port
] | conninfo
]
与一台LightDB服务器建立一个新连接。可以使用位置语法(数据库名称、用户、主机和端口中的一个或多个)指定要使用的连接参数,或者使用Section 32.1.1中详细介绍的conninfo
连接串。如果没有给出参数,则使用与以前相同的参数建立新连接。
把dbname
、username
、host
或者port
中的任何一个指定为-
等价于省略该参数。
新连接可以重用之前连接的连接参数;不仅是数据库名称、用户、主机和端口,还有其他设置,例如 sslmode
。
默认情况下,参数会在位置语法中重复使用,但在给出 conninfo
字符串时不会。
传递 -reuse-previous=on
或 -reuse-previous=off
的第一个参数会覆盖该默认值。
如果重复使用参数,则任何未明确指定为位置参数或在 conninfo
字符串中的参数都将从现有连接的参数中获取。
一个例外是,如果 host
设置使用位置语法从其先前的值更改,则现有连接参数中存在的任何 hostaddr
设置都将被删除。
并且,用作已存在的连接的任何密码,只有在用户、主机、和端口设置没有变化的时候,将被重新使用。
当命令既不指定也不重用特定参数时,将使用 libpq 默认值。
如果新连接成功地被建立,之前的连接会被关闭。
如果连接尝试失败(错误的用户名、访问被拒绝等),在ltsql处于交互模式的情况下会保留之前的连接。
但是当执行一个非交互式脚本时出现连接尝试失败,老的连接将关闭,并且报出一个错误。
这可能会也可能不会终止脚本;如果没有,所有的数据库访问命令将失败,直到另一个\connect
命令被成功执行。
这种区别一方面可以帮助用户发现打字错误,另一方面也可以作为一种安全机制防止脚本在错误的数据库上执行动作。
注意每当\connect
命令尝试重用参数,重用的是最后一次成功连接的值,而不是后续任何失败尝试的。
可是,在非交互的\connect
失败的情况下,后续没有参数被允许重新使用,因为脚本会可能期望从失败的\connect
中的值被重新使用。
例子:
=> \c mydb myuser host.dom 6432 => \c service=foo => \c "host=localhost port=5432 dbname=mydb connect_timeout=10 sslmode=disable" => \c -reuse-previous=on sslmode=require -- changes only sslmode => \c postgresql://tom@localhost/mydb?application_name=myapp
\C [ title
]
设置查询结果的任何表的标题,或者重置这类标题。这个命令等效于\pset title
(这个命令的名称来自于“caption”,因为它之前只被用来在HTML表格中设置标题)。
title
\cd [ directory
]
把当前工作目录改为directory
。如果不带参数,则切换到当前用户的主目录。
要打印当前的工作目录,可以使用\! pwd
。
\conninfo
输出有关当前数据库连接的信息。
\copy { table
[ ( column_list
) ] }
from
{ 'filename'
| program 'command'
| stdin | pstdin }
[ [ with ] ( option
[, ...] ) ]
[ where condition
]
\copy { table
[ ( column_list
) ] | ( query
) }
to
{ 'filename'
| program 'command'
| stdout | pstdout }
[ [ with ] ( option
[, ...] ) ]
执行一次前端拷贝。
这个操作会运行一个SQL COPY
命令,不过不是服务器读取或者写入指定的文件,而是由ltsql读写文件并且把数据从本地文件系统导向服务器。
这意味着文件的可访问性和权限是本地用户的而非服务器上的,并且不需要 SQL 超级用户特权。
当program
被指定时,command
被ltsql执行并且传给command
的数据或者从command
传出的数据会在服务器和客户端之间流动。同样地,执行特权是本地用户的而非服务器上的,并且不需要 SQL 超级用户特权。
对于\copy ... from stdin
,数据行从发出该命令的同一来源读取,一直到读到\.
或者数据流到达EOF。这个选项可以用来填充内嵌在一个 SQL 脚本文件中的表。对于\copy ... to stdout
,输出被发送到与ltsql命令输出相同的位置,并且COPY
命令的状态不会被打印(因为它会被一个数据行搞乱)。要读/写ltsql的标准输入或者输出而不管当前命令的来源或者count
\o
选项,可以写from pstdin
或者to pstdout
。
这个命令的语法和SQL COPY
命令类似。
所有除开数据来源/目的地的选项都和COPY
指定的一样。
因此,\copy
元命令由特殊的解析规则。
与大部分其他元命令不同,该行的所有剩余部分总是会被当做\copy
的参数,并且在参数中不会执行变量篡改以及反引号展开。
获得与\copy ... to
相同结果的另一种方法是使用SQL COPY ... TO STDOUT
命令并使用\g
或filename
\ g |
终止它。
与program
\copy
不同,此方法允许命令跨越多行; 此外,可以使用变量插值和反引号扩展。
这些操作不如带有文件或程序数据源或目标的SQL COPY
命令有效,
因为所有数据都必须通过客户端/服务器连接。 对于大量数据,SQL命令可能更可取。
\copyright
显示LightDB的版权以及发布条款。
\crosstabview [
colV
[ colH
[ colD
[ sortcolH
] ] ] ]
执行当前的查询缓冲区(像\g
那样)并且在一个交叉表格子中显示结果。该查询必须返回至少三列。由colV
标识的输出列会成为垂直页眉并且colH
所标识的输出列会成为水平页眉。colD
标识显示在格子中的输出列。sortcolH
标识用于水平页眉的可选的排序列。
每一个列说明可以是一个列编号(从 1 开始)或者一个列名。常用的 SQL 大小写折叠和引用规则适用于列名。如果省略,colV
被当做列 1 并且colH
被当做列 2。colH
必须和colV
不同。如果没有指定colD
,那么在查询结果中必须正好有三列,并且colV
和colH
之外的那一列会被当做colD
。
垂直页眉显示为最左边的列,它包含列colV
中找到的值,值的顺序和查询结果中的顺序相同,但是重复值会被移除。
水平页眉显示为第一行,它包含列colH
中找到的值,其中的重复值被移除。默认情况下,这些值会以查询结果中相同的顺序出现。但是如果给出了可选的sortcolH
参数,它标识一个值必须为整数编号的列,并且来自colH
的值将会根据相应的sortcolH
值排序后出现在水平页眉中。
在交叉表格子中,对于colH
的每一个可区分的值x
以及colV
的每一个可区分的值y
,位于交叉点(x,y)
的单元包含colH
值为x
且colV
值为y
的查询结果行中colD
列的值。如果没有这样的行,则该单元为空。如果有多个这样的行,则会报告一个错误。
\d[S+] [ pattern
]
对于每一个匹配pattern
的关系(表、视图、索引、序列或者外部表)或者组合类型,显示所有的列、它们的类型、表空间(如果非默认表空间)以及任何诸如NOT NULL
或者默认值的特殊属性。相关的索引、约束、规则以及触发器也会被显示。对于外部表,还会显示相关的外部服务器(下文的Patterns中定义了“匹配模式”)。
对于某些类型的关系,\d
会为每一列显示额外的信息:对于序列会显示列值,对于索引显示被索引的表达式,对于外部表显示外部数据包装器选项。
命令形式\d+
相同,只是显示更多的信息:显示与表列相关的任何注释,显示表中OID的存在,如果关系是视图,则显示视图定义,以及非默认的副本标识设置。
默认情况下只会显示用户创建的对象,提供一个模式或者S
修饰符可以把系统对象包括在内。
如果使用\d
但不带有pattern
参数,它等价于\dtvmsE
,后者将显示所有可见的表、视图、序列和外部表的列表。这纯粹是一种便利措施。
\da[S] [ pattern
]
列出聚集函数,以及它们的返回类型和它们所操作的数据类型。如果指定了pattern
,只显示名称匹配该模式的聚集。默认情况下只会显示用户创建的对象,提供一个模式或者S
修饰符可以把系统对象包括在内。
\dA[+] [ pattern
]
列出访问方法。如果指定了pattern
,只显示名称匹配该模式的访问方法。如果在命令名称后面追加+
,则与访问方法相关的处理器函数和描述也会和访问方法本身一起被列出。
\dAc[+]
[access-method-pattern
[input-type-pattern
]]
列出运算符类(请参阅 Section 38.16.1)。
如果指定了 access-method-pattern
,则仅列出与名称与该模式匹配的访问方法关联的运算符类。
如果指定了 input-type-pattern
,则仅列出与名称与该模式匹配的输入类型关联的运算符类。
如果将 +
附加到命令名称,则会列出每个运算符类别及其关联的运算符系列和所有者。
\dAf[+]
[access-method-pattern
[input-type-pattern
]]
列出运算符系列(请参阅 Section 38.16.5)。
如果指定了 access-method-pattern
,则仅列出与名称与该模式匹配的访问方法关联的运算符系列。
如果指定了 input-type-pattern
,则仅列出与名称与该模式匹配的输入类型关联的运算符系列。
如果将 +
附加到命令名称,则会列出每个运算符系列及其所有者。
\dAo[+]
[access-method-pattern
[operator-family-pattern
]]
列出与运算符系列关联的运算符(请参阅 Section 38.16.2)。
如果指定了 access-method-pattern
,则仅列出与名称与该模式匹配的访问方法关联的运算符系列的成员。
如果指定了 operator-family-pattern
,则仅列出名称与该模式匹配的运算符系列的成员。
如果将 +
附加到命令名称,则会列出每个运算符及其排序运算符系列(如果它是排序运算符)。
\dAp[+]
[access-method-pattern
[operator-family-pattern
]]
列出与运算符系列相关的支持函数(请参阅 Section 38.16.3)。
如果指定了 access-method-pattern
,则仅列出与名称与该模式匹配的访问方法关联的运算符系列的函数。
如果指定了 operator-family-pattern
,则仅列出名称与该模式匹配的运算符系列的函数。
如果将 +
附加到命令名称,则会详细显示函数及其实际参数列表。
\db[+] [ pattern
]
列出表空间。如果指定了pattern
,只显示名称匹配该模式的表空间。如果在命令名称后面追加+
,则与表空间相关的选项、磁盘上的尺寸、权限以及描述也会和表空间本身一起被列出。
\dc[S+] [ pattern
]
列出字符集编码之间的转换。如果指定了pattern
,只列出名称匹配该模式的转换。默认情况下只会显示用户创建的对象,提供一个模式或者S
修饰符可以把系统对象包括在内。如果在命令名称后面追加+
,则每一个对象相关的描述也会被列出。
\dC[+] [ pattern
]
列出类型转换。如果指定了pattern
,只列出源类型和目标类型匹配该模式的转换。如果在命令名称后面追加+
,则每一个对象相关的描述也会被列出。
\dd[S] [ pattern
]
显示约束
、操作符类
、操作符族
、规则
以及触发器
类型对象的描述。所有其他注释可以通过那些对象类型相应的反斜线命令查看。
\dd
显示匹配pattern
的对象的描述,如果没有给出参数则显示合适类型的可见对象的描述。但是在任一种情况下都只列出具有描述的对象。默认情况下只会显示用户创建的对象,提供一个模式或者S
修饰符可以把系统对象包括在内。
对象的描述可以用SQL命令COMMENT
创建。
\dD[S+] [ pattern
]
列出域。如果指定了pattern
,只有名称匹配该模式的域会被显示。默认情况下,只有用户创建的对象会被显示,可以提供一个模式或者S
修饰符以包括系统对象。如果+
被追加到命令名称上,每一个被列出的对象会带有其相关的权限和描述。
\ddp [ pattern
]
列出默认的访问特权设置。对那些默认特权设置已经被改变得与内建默认值不同的角色(以及模式,如果适用),为每一个角色(以及模式)显示一项。如果指定了pattern
,只列出角色名称或者模式名称匹配该模式的项。
ALTER DEFAULT PRIVILEGES
命令被用来设置默认访问特权。
在Section 6.7中解释了显示的特权的含义。
\dE[S+] [ pattern
]
\di[S+] [ pattern
]
\dm[S+] [ pattern
]
\ds[S+] [ pattern
]
\dt[S+] [ pattern
]
\dv[S+] [ pattern
]
在这一组命令中,字母E
、i
、m
、s
、t
和v
分别对应着外部表、索引、序列、表和视图。你可以以任何顺序指定这些字母中的任意一个或者多个,这样可以得到这些类型的对象的列表。例如,\dti
会列出表和索引。如果在命令名称后面追加+
,则会列出每个对象及其持久性状态(永久、临时或未记录)、磁盘上的物理大小以及相关的描述(如果有)。如果指定了pattern
,只列出名称匹配该模式的对象。默认情况下只会显示用户创建的对象,提供一个模式或者S
修饰符可以把系统对象包括在内。
\des[+] [ pattern
]
列出外部服务器(助记:“外部服务器”)。如果指定了pattern
,只列出名称匹配该模式的那些服务器。如果使用了\des+
形式,将显示每个服务器的完整描述,包括该服务器的 访问特权、类型、版本、选项和描述。
\det[+] [ pattern
]
列出外部表(助记:“外部表”)。如果指定了pattern
,只列出表名称或者模式名称匹配该模式的项。如果使用了\det+
选项,一般选项和外部表描述也会被显示。
\deu[+] [ pattern
]
列出用户映射(助记:“外部用户”)。如果指定了pattern
,只列出用户名匹配该模式的那些映射。如果使用了\deu+
形式,有关每个映射的额外信息也会被显示。
\deu+
可能也会显示远程用户的用户名和口令,所以要小心不要把它们泄露出去。
\dew[+] [ pattern
]
列出外部数据包装器(助记:“外部包装器”)。如果指定了pattern
,只列出名称匹配该模式的那些外部数据包装器。如果使用了\dew+
形式,外部数据包装器的访问特权、选项和描述也会被显示。
\df[anptwS+] [ pattern
]
列出函数,以及它们的结果数据类型、参数数据类型和函数类型,函数类型被分为“agg”(聚集)、“normal”、“procedure”、“trigger”以及“window”。
如果要只显示指定类型的函数,可以在该命令上增加相应的字母a
、n
、p
、t
或者w
。如果指定了pattern
,只显示名称匹配该模式的函数。
任何附加参数都是类型名称模式,它们与函数的第一个、第二个、以及等等参数的类型名相匹配。
(匹配函数可以有比指定的更多的参数。为了防止这种情况,写入破折号-
作为最后一个arg_pattern
。)
默认情况下只会显示用户创建的对象,提供一个模式或者S
修饰符可以把系统对象包括在内。
如果使用了\df+
形式,则有关每个函数的额外信息也会被显示,包括易失性、并行安全性、拥有者、安全性分类、访问特权、语言、源代码和描述。
要查找接受特定数据类型参数或返回特定数据类型值的函数,请使用分页器的搜索功能在 \df
输出中滚动查找。
\dF[+] [ pattern
]
列出文本搜索配置。如果指定了pattern
,只显示名称匹配该模式的配置。如果使用了\dF+
形式,每种配置的完整描述也会被显示,包括底层的文本搜索解析器和用于每一种解析器记号类型的字典列表。
\dFd[+] [ pattern
]
列出文本搜索字典。如果指定了pattern
,只显示名称匹配该模式的字典。如果使用了\dFd+
形式,有关每一种选中的字典的额外信息也会被显示,包括底层的文本搜索模板和选项值。
\dFp[+] [ pattern
]
列出文本搜索解析器。如果指定了pattern
,只显示名称匹配该模式的解析器。如果使用了\dFp+
形式,每一种解析器的完整描述也会被显示,包括底层的函数和可识别的记号类型列表。
\dFt[+] [ pattern
]
列出文本搜索模板。如果指定了pattern
,只显示名称匹配该模式的模板。如果使用了\dFt+
形式,每一种模板有关的额外信息也会被显示,包括底层的函数名称。
\dg[S+] [ pattern
]
列出数据库角色(因为“用户”和“组”的概念已经被统一成“角色”,这个命令现在等价于\du
)。默认情况下只会显示用户创建的角色,提供一个模式或者S
修饰符可以把系统角色包括在内。如果指定了pattern
,只列出名称匹配该模式的那些角色。如果使用了\dg+
形式,有关每种角色的额外信息也将被显示,当前这种形式会为角色增加显示注释。
\dl
这是\lo_list
的一个别名,它显示大对象的列表。
\dL[S+] [ pattern
]
列出过程语言。如果指定了pattern
,只列出名称匹配该模式的语言。默认情况下只会显示用户创建的语言,提供一个模式或者S
修饰符可以把系统对象包括在内。如果向命令名称追加+
,则每一种语言会和它的调用处理器、验证器、访问特权以及它是否为系统对象一起列出。
\dn[S+] [ pattern
]
列出模式(名字空间)。如果指定了pattern
,只列出名称匹配该模式的模式。默认情况下只会显示用户创建的对象,提供一个模式或者S
修饰符可以把系统对象包括在内。如果向命令名称追加+
,每个对象会与它相关的权限及描述(如果有)一起被列出。
\do[S+] [ pattern
]
列出操作符及其操作数和结果类型。
如果指定了pattern
,只列出名称匹配该模式的操作符。
如果指定了一个arg_pattern
,则只列出右侧参数的类型名称与所列出的模式相匹配的前缀操作符。
如果指定了两个arg_pattern
,则只列出参数类型名称与所列出的模式相匹配的二进制操作符。
(或者,为一元运算符的未使用参数写入-
。)
默认情况下只会显示用户创建的对象,提供一个模式或者S
修饰符可以把系统对象包括在内。
如果向命令名称追加+
,有关每个操作符的额外信息也将被显示,当前只包括底层函数的名称。
\dO[S+] [ pattern
]
列出排序规则。如果指定了pattern
,只列出名称匹配该模式的排序规则。默认情况下只会显示用户创建的对象,提供一个模式或者S
修饰符可以把系统对象包括在内。如果向命令名称追加+
,每个排序规则将和它相关的描述(如果有)一起被列出。注意只有可用于当前数据库编码的排序规则会被显示,因此在同一个安装下的不同数据库中执行此命令可能会得到不同的结果。
\dp [ pattern
]
列出表、视图和序列,包括与它们相关的访问特权。如果指定了pattern
,只列出名称匹配该模式的表、视图以及序列。
GRANT
和REVOKE
命令被用来设置访问特权。
所显示的特权的含义在Section 6.7中有介绍。
\dP[itn+] [ pattern
]
列出分区关系。如果指定了pattern
,则仅列出名称与模式匹配的条目。
修改符t
(表)和i
(索引)可以追加到命令中,筛选要列出的关系类型。默认会列出分区表和索引。
如果用了修饰符n
(“nested”)或指定了模式,则包括非根分区关系,并显示每个分区关系的父级的列。
如果+
被附加到命令名中,那么还会显示每个关系分区的大小总和,以及关系的描述。
如果n
与_
相结合,将显示两种大小:一种包含直接连接的叶分区的总大小,另一种显示所有分区的总大小,包括间接附加的子分区。
\drds [ role-pattern
[ database-pattern
] ]
列出已定义的配置设置。这些设置可以是针对角色的、针对数据库的或者同时针对两者的。role-pattern
和database-pattern
分别被用来选择要列出的角色和数据库。如果省略它们或者指定了*
,则会列出所有设置,分别会包括针对角色和针对数据库的设置。
ALTER ROLE
以及ALTER DATABASE
命令可以用来定义一个角色以及一个数据库的配置设置。
\dRp[+] [ pattern
]
列出复制的publication。如果指定有pattern
,只有那些名称匹配该模式的publication会被列出。如果+
被追加到命令的名称上,与每个publication相关的表也会被显示。
\dRs[+] [ pattern
]
列出复制的订阅。如果指定有pattern
,只有那些名字匹配该模式的订阅才会被列出。如果+
被追加到命令的名称上,订阅的额外属性会被显示。
\dT[S+] [ pattern
]
列出数据类型。如果指定了pattern
,只列出名称匹配该模式的类型。如果向命令名称追加+
,每一种类型、其内部名称和尺寸、允许的值(如果是一种enum
类型)以及相关权限会被一同列出。默认情况下只会显示用户创建的对象,提供一个模式或者S
修饰符可以把系统对象包括在内。
\du[S+] [ pattern
]
列出数据库角色(因为“用户”和“组”的概念已经被统一成“角色”,这个命令现在等价于\dg
)。默认情况下只会显示用户创建的角色,提供一个模式或者S
修饰符可以把系统角色包括在内。如果指定了pattern
,只列出名称匹配该模式的那些角色。如果使用了\du+
形式,有关每一种角色的额外信息也会被显示,当前只会多显示角色的注释。
\dx[+] [ pattern
]
列出已安装的扩展。如果指定了pattern
,只列出名称匹配该模式的那些扩展。如果使用了\dx+
形式,所有属于每个匹配扩展的对象会被列出。
\dy[+] [ pattern
]
列出事件触发器。如果指定了pattern
,只列出名称匹配该模式的事件触发器。如果在命令名称后面加上+
,还会为每个列出的对象显示其相关的描述。
\e
或\edit
[ filename
] [ line_number
]
如果指定了filename
,则它是被编辑的文件,在编辑器退出后,该文件的内容会被拷贝到当前查询缓冲区中。
如果没有给定filename
,当前查询缓冲区会被拷贝到一个临时文件中,并且接着以相同的方式编辑。
或者,如果当前查询缓冲区为空,则最近被执行的查询会被拷贝到一个临时文件并且以同样的方式编辑。
如果你编辑了一个文件或者以前的查询,并且你退出编辑时没有变更文件,查询缓冲将被清除。
否则,会根据ltsql的一般规则重新解析查询缓冲区的新内容,把整个缓冲区当作一个单一行来处理。
任何完整的查询都会立即执行; 也就是说,如果查询缓冲区包含分号或以分号结尾,则执行该点之前的所有内容并将其从查询缓冲区中删除。
查询缓冲区中剩余的内容将重新显示。
输入分号或者\g
会把它发送出去,输入\r
会通过清除查询缓冲区来取消它。
把缓冲区当作单一行主要会影响元命令:缓冲区中在一个元命令之后的任何东西都将被当作该元命令的参数,即便元命令之后的内容跨越多行也是如此。(因此不能以这种方式来制作使用元命令的脚本。应该使用\i
。)
如果指定了一个行号,ltsql将会把游标(注意不是服务器端的游标)定位到文件或者查询缓冲区的指定行上。注意如果给出了一个全是数字的参数,ltsql就会假定它是行号而不是文件名。
有关如何配置和自定义编辑器的信息,请参见下面的Environment。
\echo text
[ ... ]
将经过计算的参数打印到标准输出,以空格分隔,后跟换行符。这可以用来在脚本的输出中间混入信息,例如:
=> \echo `date`
Tue Oct 26 21:40:57 CEST 1999
如果第一个参数是一个没有加引号的-n
,则不会加上最后的新行(第一个参数也不会)。
如果使用\o
命令来重定向查询的输出,你可能希望使用\qecho
来取代这个命令。另请参见\warn
。
\ef [ function_description
[ line_number
] ]
这个命令会以一个CREATE OR REPLACE FUNCTION
或CREATE OR REPLACE PROCEDURE
命令的形式取出并且编辑指定函数或过程的定义。
编辑的方式与\edit
完全相同。
如果你退出编辑器而没有保存,语句会被丢弃。
如果你保存并退出编辑器,如果你给它增加了分号,更新的命令会被立即执行
否则重新显示;可以键入分号或者\g
把它发出,也可以用\r
取消之。
目标函数可以单独用名称或者用名称和参数(例如foo(integer, text)
)来指定。如果有多于一个函数具有同样的名称,则必须给出参数的类型。
如果没有指定函数,将会给出一个空白的CREATE FUNCTION
模板来编辑。
如果指定了一个行号,ltsql将把游标定位在该函数体的指定行上(注意函数体通常不是开始于文件的第一行)。
和大部分其他元命令不同,该行的整个剩余部分总是会被当作\ef
的参数,并且在参数中不会执行变量篡改以及反引号展开。
有关如何配置和自定义编辑器可见下面的Environment。
\encoding [ encoding
]
设置客户端字符集编码。如果没有参数,这个命令会显示当前的编码。
\errverbose
以最详细的程度重复最近的服务器错误消息,就好像VERBOSITY
被设置为verbose
且SHOW_CONTEXT
被设置为always
。
\ev [ view_name
[ line_number
] ]
这个命令会以一个CREATE OR REPLACE VIEW
的形式取出并且编辑指定函数的定义。编辑的方式与\edit
完全相同。
如果你退出编辑器而没有保存,语句会被丢弃。
如果你保存并退出编辑器,如果你给它增加了分号,更新的命令会被立即执行
否则重新显示;可以键入分号或者\g
把它发出,也可以用\r
取消之。
如果没有指定函数,将会给出一个空白的CREATE VIEW
模板来编辑。
如果指定了一个行号,ltsql将把游标定位在该视图定义的指定行上。
和大部分其他元命令不同,该行的整个剩余部分总是会被当作\ev
的参数,并且在参数中不会执行变量篡改以及反引号展开。
\f [ string
]
设置用于非对齐查询输出的域分隔符。默认值是竖线(|
)。它等效于\pset fieldsep
。
\g [ (option
=value
[...]) ] [ filename
]
\g [ (option
=value
[...]) ] [ |command
]
把当前查询缓冲区发送给服务器执行。
如果括号出现在 \g
之后,它们将包围以空格分隔的 option
=
value
格式选项子句列表,其解释方式与 \pset
option
value
命令相同,但仅在此查询期间生效。 在此列表中,=
符号周围不允许有空格,但选项子句之间需要空格。 如果省略 =
value
,命名的 option
的更改方式与 \pset
option
相同,没有明确的 value
。
如果给定了 filename
或 |
command
参数,则查询的输出将写入命名文件或通过管道传输到给定的 shell 命令,而不是像往常一样显示它。 仅当查询成功返回零个或多个元组时才会写入文件或命令,而不是在查询失败或者是不返回数据的 SQL 命令时写入。
如果当前查询缓冲区为空,则重新执行最近一次被发送的查询。除了这种行为之外,没有参数的\g
实际上等效于一个分号。对于参数,\g
提供了一个替代\o
命令的“一次性”,另外还允许对通常由\pset
设置的输出格式选项进行一次性调整。
当最后一个参数以|
开始时,则该行的所有剩余部分总是会被当做要执行的command
,并且在参数中不会执行变量篡改以及反引号展开。该行的剩余部分会被简单地按字面传给shell。
\gdesc
显示当前查询缓冲区的结果的描述(即列名和数据类型)。查询不会被实际执行,不过,如果它含有某种类型的语法错误,该错误将被以通常的方式报出。
如果当前查询缓冲区为空,则会描述最近被发送的查询。
\gexec
把当前查询缓冲区发送到服务器,然后该查询输出(如果有)中的每一行的每一列都当作一个要被执行的 SQL 语句。例如,要在my_table
的每一列上都创建一个索引:
=>SELECT format('create index on my_table(%I)', attname)
->FROM pg_attribute
->WHERE attrelid = 'my_table'::regclass AND attnum > 0
->ORDER BY attnum
->\gexec
CREATE INDEX CREATE INDEX CREATE INDEX CREATE INDEX
产生的查询会按照其所在行被返回的顺序执行,如果有多个列,则同一行中按照从左至右的顺序执行。NULL 域会被忽略。产生的查询会被原样发送给服务器处理,因此它们即不能是ltsql元命令,也不能包含ltsql变量引用。如果其中任何一个查询失败,剩余查询的执行将会继续,除非设置了ON_ERROR_STOP
。每个查询的执行都遵照ECHO
的处理(在使用\gexec
时,通常建议设置ECHO
为all
或者queries
)。查询日志、单步模式、计时以及其他查询执行特性也适用于每一个生成的查询。
如果当前查询缓冲区为空,则会重新执行最近被发送的查询。
\gset [ prefix
]
把当前查询输入缓冲区发送给服务器并且将查询的输出存储在ltsql变量中(参见下面的Variables)。被执行的查询必须只返回一行。该行的每一列会被存储到一个单独的变量中,变量和该列的名字一样。例如:
=>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,那么对应的变量会被重置而不是被设置。
如果查询失败或者没有返回一行,则不会有任何变量被更改。
如果当前查询缓冲区为空,则重新执行最近被发送的查询。
\gx [ (option
=value
[...]) ] [ filename
]
\gx [ (option
=value
[...]) ] [ |command
]
\gx
等效于\g
,\gx
等价于 \g
,除了它强制此查询的扩展输出模式,就好像 expanded=on
被包含在列表中 \pset
选项。请参考\x
。
\h
or \help
[ command
]
给出指定SQL命令的语法帮助。如果没有指定command
,则ltsql会列出可以显示语法帮助的所有命令。如果command
是一个星号(*
),则会显示所有SQL命令的语法帮助。
与大部分其他元命令不同,该行的所有剩余部分总是会被当做\help
的参数,并且在参数中不会执行变量篡改以及反引号展开。
为了简化输入,由几个词构成的命令不需要被加上引号。因此,键入\help alter table
是可以的。
\H
or \html
开启HTML查询输出格式。如果HTML格式已经开启,这会把它切换回默认的对齐文本格式。这个命令是为了兼容性和方便,有关设置其他输出选项请见\pset
。
\i
or \include
filename
从文件filename
读取输入并且把它当作从键盘输入的命令来执行。
如果filename
是-
(连字符),那么会一直读取标准输入直到碰到一个 EOF 指示符或者\q
元命令。这可以用来把交互式输入与文件输入混杂。注意只有在最外层激活了 readline 行为的情况下才将会使用 readline 行为。
如果想在屏幕上看到被读入的行,必须把变量ECHO
设置成all
。
\if
expression
\elif
expression
\else
\endif
这一组命令实现可嵌套的条件块。条件块必须以一个\if
开始并且以一个\endif
结束。两者之间可能有任意数量的\elif
子句,后面也可能有选择地跟着一个单一的\else
子句。一般查询以及其他类型的反斜线命令可以出现在这些命令之间构成条件块。
\if
和\elif
命令读取它们的参数并且将它们作为布尔表达式进行计算。如果表达式得到真
则处理正常继续下去,否则会跳过下面的行直到到达一个匹配的\elif
、\else
或者\endif
。一旦一个\if
或者\elif
测试成功,同一个块中后面的\elif
命令的参数将不会被计算但会被当作为假。跟在一个\else
后面的行只有在先前的匹配的\if
或\elif
成功时才被处理。
就像任何其他反斜线命令参数一样,\if
或者\elif
命令的expression
参数服从变量篡改以及反引号展开。然后会像一个on/off选项变量的值一样来计算它。因此,对下列项无歧义、大小写无关的匹配都是有效的值:true
、false
、1
、0
、on
、off
、yes
、no
。例如,t
、T
以及tR
都将被认为是真
。
无法被正确计算为真或假的表达式将产生一个警告并且被当做假。
正在被跳过的行还是会被正常地解析以标识查询和反斜线命令,但是查询不会被发送到服务器,并且非条件(\if
、\elif
、\else
、\endif
)反斜线命令会被忽略。条件命令会被检查以判断嵌套是否有效。被跳过的行中的变量引用不会被展开,并且也不会执行反引号展开。
一个给定条件块中的所有反斜线命令必须出现在相同的源文件中。如果在所有的本地\if
块被关闭之前,主输入文件或者一个\include
进来的文件上就达到了EOF,则ltsql将产生一个错误。
这里是一个例子:
-- 检查数据库中两个单独记录的存在性并且把结果存在单独的psql变量中 SELECT EXISTS(SELECT 1 FROM customer WHERE customer_id = 123) as is_customer, EXISTS(SELECT 1 FROM employee WHERE employee_id = 456) as is_employee \gset \if :is_customer SELECT * FROM customer WHERE customer_id = 123; \elif :is_employee \echo 'is not a customer but is an employee' SELECT * FROM employee WHERE employee_id = 456; \else \if yes \echo 'not a customer or employee' \else \echo 'this will never print' \endif \endif
\ir
or \include_relative
filename
\ir
命令类似于\i
,但是以不同的方式处理相对路径文件名。在交互模式中执行时,这两个命令的行为相同。不过,当被从脚本中调用时,\ir
相对于脚本所在的目录而不是根据当前工作目录来解释文件名。
\l[+]
or \list[+] [ pattern
]
列出服务器中的数据库并且显示它们的名称、拥有者、字符集编码以及访问特权。如果指定了pattern
,则只列出名称匹配该模式的数据库。如果向命令名称追加+
,则还会显示数据库的尺寸、默认表空间以及描述(尺寸信息只对当前用户能连接的数据库可用)。
\lo_export loid
filename
从数据库中读取具有OID loid
的大对象并且将它写入到filename
。注意这和服务器函数lo_export
有微妙的不同,后者会以运行数据库服务器的用户权限来执行并且运行在服务器的文件系统上。
使用\lo_list
可以找出大对象的OID。
\lo_import filename
[ comment
]
把该文件存储到LightDB大对象。可选地,它可以把给定的注释关联到该对象。例如:
foo=> \lo_import '/home/peter/pictures/photo.xcf' 'a picture of me'
lo_import 152801
该响应表示该大对象得到的对象 ID 是 152801,未来可以用这个 ID 来访问这个新创建的大对象。为了便于阅读,推荐总是给每一个对象都关联人类可读的注释。OID 和注释都可以用\lo_list
命令查看。
注意这个命令和服务器端的lo_import
有微妙的不同,因为它以本地文件系统上的本地用户的身份运行,而不是服务器用户和文件系统。
\lo_list
显示当前存储在数据库中的所有LightDB大对象,同时显示它们的任何注释。
\lo_unlink loid
从数据库中删除OID为loid
的大对象。
使用\lo_list
可以找出该大对象的OID。
\o
or \out [ filename
]
\o
or \out [ |command
]
安排把未来的查询结果保存到文件filename
中或者用管道导向到 shell 命令command
。如果没有指定参数,查询输出会被重置到标准输出。
如果该参数以|
开始,则该行的所有剩余部分总是会被当做要执行的command
,并且在参数中不会执行变量篡改以及反引号展开。该行的剩余部分会被简单地按字面传给shell。
“查询结果”包括从数据库服务器得到的所有表、命令响应和提示,还有查询数据库的各种反斜线命令(如\d
)的输出,但不包括错误消息。
要在查询结果之间混入文本输出,可以使用\qecho
。
\p
or \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(表格边框)有意义,并且 2 以上的值会被视为与border = 2
相同。latex
和latex-longtable
格式会额外地允许一个值 3 表示在数据行之间增加分隔线。
columns
为wrapped
格式设置目标宽度,还有扩展自动模式中决定输出是否足够多到需要分页器或者切换到垂直显示的宽度限制。零(默认)导致目标宽度由环境变量COLUMNS
所控制,如果没有设置COLUMNS
则使用检测到的屏幕宽度。此外,如果columns
为零则wrapped
格式只影响屏幕输出。如果columns
为非零则文件和管道输出也会被包裹成该宽度。
csv_fieldsep
规定要用于CSV输出格式的字段分隔符。如果分隔符出现在字段的值中,则该字段遵循标准CSV规则在双引号中输出。默认值为逗号。
expanded
(or x
)
如果value
被指定,它必须是on
或者off
,它们分别会启用或者禁用扩展模式,也可以是auto
。如果value
被省略,则该命令会在开启和关闭设置之间切换。当扩展模式被启用时,查询结果被显示在两列中,第一列是列名而第二列是列值。如果在通常的“水平”模式中数据不适合屏幕,则可以用这种模式。在自动设置中,只要查询输出有多于一列并且比屏幕宽,就会使用扩展模式。否则,将使用常规模式。只有在对齐格式和 wrapped 格式中自动设置才有效。在其他格式中,它的行为总是像扩展模式被关闭一样。
fieldsep
指定在非对齐输出格式中使用的域分隔符。用那种方式,用户可以创建 tab 分隔的输出,这种形式其他程序可能更喜欢。要设置 tab 为域分隔符,可以键入\pset fieldsep '\t'
。默认的域分隔符是'|'
(一个竖线)。
fieldsep_zero
把用在非对齐输出格式中的域分隔符设置为一个零字节。
footer
如果value
被指定,它必须是on
或者off
,它们分别会启用或者禁用表格页脚((
计数)的显示。如果n
rows)value
被省略,则该命令会切换页脚显示为打开或者关闭。
format
设置输出格式为下列的一种: aligned
,
asciidoc
,
csv
,
html
,
latex
,
latex-longtable
, troff-ms
,
unaligned
, 或 wrapped
。允许唯一的缩写。
aligned
格式是标准,人类可阅读的、良好格式化的文本输出;这是默认值。
unaligned
格式把一个数据行的所有列都写在一行上,之间用当前活动的域分隔符分隔。这可用于生成意图由其他程序读取的输出,例如,tab 分隔或者逗号分隔格式。
但是,如果字段分隔符出现在列的值中,则不专门处理该字符;因此CSV格式可能更适合此类目的。
csv
格式
写入以逗号分隔的列值,应用引号规则描述在RFC 4180。
此输出与服务器COPY
命令的 CSV 格式兼容。
除非tuples_only
参数为on
,否则将生成具有列名称的标头行。不打印标题和页脚。
每行都由系统相关的行尾字符结束,该字符通常是类似 Unix 的系统的单一换行符(\n
)。
除了逗号之外的\pset csv_fieldsep
字段分隔符,还可以使用\pset csv_fieldsep
选择。
wrapped
格式和aligned
相似,但是前者会把过宽的数据值分成多个行以便输出能够适合目标行的宽度。目标行的宽度由columns
选项决定。注意ltsql将不会尝试对列头部标题进行换行,因此如果列头部需要的总宽度超过目标宽度,wrapped
格式的行为就变得和aligned
一样了。
The asciidoc
, html
,latex
, latex-longtable
,
和troff-ms
格式分别用相应的标记语言把要输出的表格放在文档中。不过它们的输出并不是完整的文档。
这在HTML中也许不重要,但是在LaTeX中必须有完整的文档包装器。
latex
格式使用 LaTeX的 tabular
环境。
latex-longtable
格式需要 LaTeX、longtable
和 booktabs
包。
linestyle
设置边框线的绘制样式为ascii
、old-ascii
或者unicode
之一。允许不产生歧义的缩写(这意味着一个字母就足够了)。默认的设置是ascii
。这个选项只影响aligned
以及wrapped
输出格式。
ascii
样式使用纯ASCII字符。数据中的新行使用一个+
符号在右手边的空白处显示。当在wrapped
格式中包裹两行中间没有新行字符的数据时,会在第一行右手边空白处显示一个点号(.
),并且在下一行的左手边空白处也显示一个点号(.
)。
old-ascii
样式使用纯ASCII字符。数据中的新行使用:
符号来代替左手边的列分隔符显示。在包裹两行中间没有新行字符的数据时,会用一个;
符号取代左手边的列分隔符。
unicode
样式使用 Unicode 的方框绘制字符。数据中的新行会使用一个回车符号显示在右手边的空白处。在包裹两行中间没有新行字符的数据时,会在第一行的右手边空白处显示一个省略号,并且在下一行的左手边空白处也显示一个省略号。
当border
设置大于零时,linestyle
选项也决定边框线用什么字符绘制。纯ASCII字符到处都可以使用,但是在识别 Unicode 字符的显示上使用 Unicode 字符会更好看。
null
设置要用来替代空值被打印的字符串。默认是什么也不打印,对于一个空字符串这很容易弄错。例如,有人可能更想用\pset null '(null)'
。
numericlocale
如果value
被指定,它必须是on
或者off
,它们将分别启用或者禁用一个与区域相关的字符来分隔数字和左边的十进制标记。如果value
被省略,该命令会在常规输出和区域相关的数字输出之间切换。
pager
控制对查询和ltsql的帮助输出使用分页器程序。如果环境变量PSQL_PAGER
或PAGER
被设置,输出会被用管道输送到指定的程序。否则将使用与平台相关的默认分页器程序(例如more
)。
如果pager
选项被设为off
,则不会使用分页器程序。如果pager
选项被设为on
,则会在适当的时候使用分页器,即当输出到终端并且无法适合屏幕时就会使用分页器。pager
选项也可以被设置为always
,这会导致对所有的终端输出都是用分页器而不管输出是否适合屏幕。不带value
的\pset pager
会切换分页器开、关状态。
pager_min_lines
如果pager_min_lines
被设置为一个大于页面高度的数字,在至少这么多输出行被显示之前都不会调用分页器程序。默认设置为 0。
recordsep
指定用在非对齐输出格式中的记录(行)分隔符。
recordsep_zero
把用在非对齐输出格式中的记录分隔符设置为一个零字节。
tableattr
(or T
)
在HTML格式中,这会指定要放在table
标记内的属性。例如,这可能是cellpadding
或者bgcolor
。注意你可能不想在这里指定border
,因为那由\pset border
负责。如果没有给出value
,则表属性会被重置。
在latex-longtable
格式中,这个选项控制每个包含左对齐数据类型的列的宽度比例。这个选项的值是一个由空格分隔的值列表,例如'0.2 0.2 0.6'
。没有指定的输出列会使用最后一个指定的值。
title
(or C
)
设置用于任何后续被打印表的表标题。这可以用来给输出加上描述性的标签。如果没有给出value
,这个标题会被复原。
tuples_only
(or t
)
如果value
被指定,它必须是on
或者off
,这个选项将启用或者禁用只显示元组的模式。如果value
被省略,则该命令会在常规输出和只显示元组输出之间切换。常规输出包括列头、标题以及多种页脚之类的额外信息。在只显示元组的模式中,只会显示实际的表数据。
unicode_border_linestyle
设置unicode
线型的边框绘制风格为single
或者double
之一。
unicode_column_linestyle
设置unicode
线型的列绘制风格为single
或者double
之一。
unicode_header_linestyle
设置unicode
线型的页眉绘制风格为single
或者double
之一。
这些不同格式的外观可以在Examples小节的图示中看到。
\pset
有多种快捷命令。请参见\a
、\C
、\f
、\H
、\t
、\T
以及\x
。
\q
or \quit
退出ltsql程序。在一个脚本文件中,只有该脚本的执行会被终止。
\qecho text
[ ... ]
这个命令和\echo
一样,不过输出将被写到\o
所设置的查询输出通道。
\r
or \reset
重置(清除)查询缓冲区。
\s [ filename
]
打印ltsql的命令行历史到filename
。如果省略filename
,该历史会被写入到标准输出(如果适用则使用分页器)。如果编译ltsql时没有加上Readline支持,则这个命令不可用。
\set [ name
[ value
[ ... ] ] ]
设置ltsql变量name
为value
,如果给出了多于一个值,则把该变量的值设置为所有给出的值的串接。如果只给了一个参数,该变量会被设置为空字符串值。要重置一个变量,可以使用\unset
命令。
不带任何参数的\set
显示所有当前设置的ltsql变量的名称和值。
合法的变量名可以包含字母、数字和下划线。详见下文的Variables。变量名是大小写敏感的。
某些变量是特殊的,它们控制ltsql的行为或者会被自动设置以反映连接状态。这些变量在下文的Variables中记录。
这个命令和SQL命令SET
无关。
\setenv name
[ value
]
把环境变量name
设置为value
,如果没有提供value
,则会重置该环境变量。例如:
test=>\setenv PAGER less
test=>\setenv LESS -imx4F
\sf[+] function_description
这个命令以一个CREATE OR REPLACE FUNCTION
命令或者CREATE OR REPLACE PROCEDURE
命令取出并且显示指定函数或者过程的定义。定义会被打印到当前的查询输出渠道,就像\o
所作的那样。
目标函数可以单独用名称指定,也可以用名称和参数指定,例如foo(integer, text)
。如果有多于一个函数具有相同的名字,则必须给出参数的类型。
如果向命令名称追加+
,那么输出行会被编号,函数体的第一行会被编为 1。
与大部分其他元命令不同,该行的所有剩余部分总是会被当做\sf
的参数,并且在参数中不会执行变量篡改以及反引号展开。
\sv[+] view_name
这个命令以一个CREATE OR REPLACE VIEW
命令取出并且显示指定视图的定义。定义会被打印到当前的查询输出渠道,就像\o
所作的那样。
如果在命令名称上追加+
,那么输出行会从 1 开始编号。
与大部分其他元命令不同,该行的所有剩余部分总是会被当做\sv
的参数,并且在参数中不会执行变量篡改以及反引号展开。
\t
切换输出列名标题和行计数页脚的显示。这个命令等效于\pset tuples_only
,提供它只是为了使用方便而已。
\T table_options
指定在HTML输出格式中,要放在table
标签内的属性。这个命令等效于\pset tableattr
。
table_options
\timing [ on
| off
]
如果给出一个参数,这个参数用来打开或者关闭对每个SQL语句执行时长的显示。如果没有参数,则在打开和关闭之间切换。显示的数据以毫秒为单位,超过1秒的区间还会被显示为“分钟:秒”的格式,如果必要还会加上小时和日的字段。
\unset name
重置(删除)ltsql变量name
。
大部分控制ltsql行为的变量不能被重置,相反,\unset
命令会被解释为把它们设置为其默认值。请参考下文的Variables。
\w
or \write
filename
\w
or \write
|
command
把当前查询缓冲区写到文件filename
或者用管道导出到 shell 命令command
。如果当前查询缓冲区为空,则写最近被执行的查询。
如果参数以|
开始,则该行的整个剩余部分会被当做要执行的command
,并且在参数中不会执行变量篡改以及反引号展开。该行的剩余部分会被简单地按字面传递给shell。
\warn text
[ ... ]
此命令与 \echo
相同,只是输出将写入 ltsql 的标准错误通道,而不是标准输出。
\watch [ seconds
]
反复执行当前的查询缓冲区(就像\g
那样)直到被中止或者查询失败。两次执行之间等待指定的秒数(默认是 2 秒)。显示每个查询结果时带上一个由\pset title
字符串(如果有)、从查询开始起的时间以及延时间隔组成的页眉。
如果当前查询缓冲区为空,则会重新执行最近被发送的查询。
\x [ on
| off
| auto
]
设置或者切换扩展表格格式化模式。究其本身而言,这个命令等效于\pset expanded
。
\z [ pattern
]
列出表、视图和序列,以及它们相关的访问特权。如果指定了pattern
,则只会列出名称匹配该模式的表、视图和序列。
这是\dp
(“display privileges”)的一个别名。
\! [ command
]
如果没有参数,就跳出到一个子shell,当子shell退出时ltsql会继续。如果有一个参数,则执行shell命令command
。
与大部分其他元命令不同,该行的所有剩余部分总是会被当做\!
的参数,并且在参数中不会执行变量篡改以及反引号展开。该行的剩余部分会被简单地按字面传递给shell。
\? [ topic
]
显示帮助信息。可选的topic
参数(默认是commands
)选择解释ltsql的哪一部分:commands
表示ltsql的反斜线命令;options
表示可以传递给ltsql的命令行选项;而variables
显示有关ltsql配置变量的帮助。
\;
反斜线分号并非和前述命令相同的元命令,它只是会把一个分号加入到查询缓冲区且不会进一步执行。
通常,只要ltsql达到了命令结束的分号,它就将分发一个SQL命令给服务器,即使在当前行上还留有更多输入。因此,例如输入
select 1; select 2; select 3;
将导致三个SQL命令被逐个发送给服务器,在继续到下一个命令前会显示每一个命令的结果。不过,被输入为\;
的分号将不会触发命令处理,这样在它之前的命令以及其后的命令实际上会被组合在一个请求中发送给服务器。例如
select 1\; select 2\; select 3;
会导致在到达非反斜线分号时用一个单一的请求把三个SQL命令发送给服务器。服务器会把这样一个请求当作单一的事务执行,除非该字符串中有显式的BEGIN
/COMMIT
命令把它划分成多个事务(服务器如何处理多查询字符串的更多细节请参考Section 51.2.2.1)。ltsql对每个请求仅打印出它接收到的最后一个查询结果。在这个例子中,尽管所有三个SELECT
确实都被执行了,但ltsql只会打印出3
。
很多\d
命令都可以用一个pattern
参数来指定要被显示的对象名称。在最简单的情况下,模式正好就是该对象的准确名称。在模式中的字符通常会被变成小写形式(就像在 SQL 名称中那样),例如\dt FOO
将会显示名为foo
的表。就像在 SQL 名称中那样,把模式放在双引号中可以阻止它被转换成小写形式。如果需要在一个模式中包括一个真正的双引号字符,则需要把它写成两个相邻的双引号,这同样是符合 SQL 引用标识符的规则。例如,\dt "FOO""BAR"
将显示名为FOO"BAR
(不是foo"bar
)的表。和普通的 SQL 名称规则不同,你不能只在模式的一部分周围放上双引号,例如\dt FOO"FOO"BAR
将会显示名为fooFOObar
的表。
只要pattern
参数被完全省略,\d
命令会显示在当前 schema 搜索路径中可见的全部对象 — 这等价于用*
作为模式(如果一个对象所在的 schema 位于搜索路径中并且没有同类且同名的对象出现在搜索路径中该 schema 之前的 schema 中,则说该对象是可见的。这表示可以直接用名称引用该对象,而不需要用 schema 来进行限定)。要查看数据库中所有的对象而不管它们的可见性,可以把*.*
用作模式。
如果放在一个模式中,*
将匹配任意字符序列(包括空序列),而?
会匹配任意的单个字符(这种记号方法就像 Unix shell 的文件名模式一样)。例如,\dt int*
会显示名称以int
开始的表。但是如果被放在双引号内,*
和?
就会失去这些特殊含义而变成普通的字符。
包含一个点号(.
)的模式被解释为一个 schema 名称模式后面跟上一个对象名称模式。例如,\dt foo*.*bar*
会显示名称以foo
开始的 schema 中所有名称包括bar
的表。如果没有出现点号,那么模式将只匹配当前 schema 搜索路径中可见的对象。同样,双引号内的点号会失去其特殊含义并且变成普通的字符。
高级用户可以使用字符类等正则表达式记法,如[0-9]
可以匹配任意数字。所有的正则表达式特殊字符都按照Section 10.7.3所说的工作,以下字符除外:.
会按照上面所说的作为一种分隔符,*
会被翻译成正则表达式记号.*
,?
会被翻译成.
,而$
则按字面意思匹配。根据需要,可以通过书写?
、(
、R
+|)(
和R
|)
来分别模拟模式字符R
?.
、
和R
*
。R
?$
不需要作为一个正则表达式字符,因为模式必须匹配整个名称,而不是像正则表达式的常规用法那样解释(换句话说,$
会被自动地追加到模式上)。如果不希望该模式的匹配位置被固定,可以在开头或者结尾写上*
。注意在双引号内,所有的正则表达式特殊字符会失去其特殊含义并且按照其字面意思进行匹配。还有,在操作符名称模式中(即作为\do
的参数),正则表达式特殊字符也按照字面意思进行匹配。
ltsql提供了和普通 Unix 命令 shell 相似的变量替换特性。变量简单来说就是一对名称/值,其中值可以是任意长度的任意字符串。名称必须由字母(包括非拉丁字母)、数字和下划线构成。
要设置一个变量,可以使用ltsql的元命令\set
。例如,
test=> \set foo bar
会设置foo
为值bar
。要检索该变量的内容,可以在名称前放一个分号,例如:
test=> \echo :foo
bar
这在常规 SQL 命令和元命令中均有效,下文的SQL Interpolation中有更多细节。
如果调用\set
时没有第二个参数,该变量会被设置为一个空字符串值。要重置(即删除)一个变量,可以使用命令\unset
。要显示所有变量的值,在调用\set
时不带任何参数即可。
\set
的参数服从与其他命令相同的替换规则。因此可以构造有趣的引用,例如\set :foo 'something'
以及分别得到Perl或者PHP的“软链接”或者“可变变量”。不幸的是(或者幸运的是?),这些构造出来的东西并没有什么用处。在另一方面,\set bar :foo
是一种很好的拷贝变量的方法。
有一些变量会被ltsql特殊对待。它们表示特定的选项设置,运行时这类选项设置可以通过修改该变量的值来改变,或者在某些情况下它们表示ltsql的可更改的状态。按照惯例,所有被特殊对待的变量的名称由全部大写形式的 ASCII 字母(还有可能是数字和下划线)组成。为了确保未来最大的兼容性,最好避免把这类变量名用于自己的目的。
控制ltsql行为的变量通常不能被重置或者设置为无效值。允许\unset
命令,但它会被解释为将变量设置为它的默认值。没有第二参数的\set
命令会被解释为将变量设置为on
(对于接受该值的控制变量),对不接受该值的变量则会拒绝这个命令。此外,接受值on
和off
的控制变量也能接受其他常见的布尔值拼写方式,例如true
和false
。
被特殊对待的变量是:
AUTOCOMMIT
在被设置为on
(默认)时,每一个 SQL 命令在成功完成时会被自动提交。在这种模式中要推迟提交,必须输入一个BEGIN
或者START TRANSACTION
SQL 命令。当被设置为off
或者被重置时,在显式发出COMMIT
或者END
之前,SQL 命令不会被提交。自动提交打开模式会为你发出一个隐式的BEGIN
,这会发生在任何不在一个事务块中且本身即不是BEGIN
及其他事务控制命令且不是无法在事务块中执行的命令(例如VACUUM
)之前。
在自动提交关闭模式中,必须通过ABORT
或者ROLLBACK
显式地放弃任何失败的事务。还要记住,如果退出会话时没有提交,则所有的工作都会丢失。
自动提交打开模式是LightDB的传统行为,但是自动提交关闭模式更接近于 SQL 的规范。如果更喜欢自动提交关闭模式,可以在系统级的ltsqlrc
文件或者个人的~/.ltsqlrc
文件中设置它。
COMP_KEYWORD_CASE
确定在补全一个 SQL 关键词时要使用的大小写形式。如果被设置为lower
或者upper
,补全后的词将分别是小写或者大写形式。如果被设置为preserve-lower
或者preserve-upper
(默认),补全后的词将会保持该词已输入部分的大小写形式,但是如果被补全的词还没有被输入,则它会被分别补全成小写或者大写形式。
DBNAME
当前已连接的数据库名称。每次连接到一个数据库时都会设置该变量(包括程序启动时),但是可以被更改或者重置。
ECHO
如果被设置为all
,所有非空输入行会被按照读入它们的样子打印到标准输出(不适用于交互式读取的行)。要在程序开始时选择这种行为,可以使用开关-a
。如果被设置为queries
,ltsql会在发送每个查询给服务器时将它们打印到标准输出。选择这种行为的开关是-e
。如果被设置为errors
,那么只有失败的查询会被显示在标准错误输出上。这种行为的开关是-b
。如果被重置或者设置为none
(默认值)则不会显示任何查询。
ECHO_HIDDEN
当这个变量被设置为on
且一个反斜线命令查询数据库时,相应的查询会被先显示。这种特性可以帮助我们学习LightDB的内部并且在自己的程序中提供类似的功能(要在程序开始时选择这种行为,可以使用开关-E
)。如果把这个变量设置为值noexec
,则对应的查询只会被显示而并不真正被发送给服务器执行。默认值是off
。
ENCODING
当前的客户端字符集编码。每一次你连接到一个数据库(包括程序启动)时以及当你用\encoding
更改编码时,这个变量都会被设置,但它可以被更改或者重置。
ERROR
如果上一个SQL查询失败则为true
,如果成功则是false
。另见SQLSTATE
。
FETCH_COUNT
如果这个变量被设置为一个大于零的整数值,SELECT
查询的结果会以一组一组的方式取出并且显示(而不是像默认的那样把整个结果集拿到以后再显示),每一组就会包括这么多个行。因此,这种方式只会使用有限的内存量,而不管整个结果集的大小。在启用这个特性时,通常会使用 100 到 1000 的设置。记住在使用这种特性时,一个查询可能会在已经显示了一些行之后失败。
尽管可以把这种特性用于任何的输出格式,但是默认的aligned
格式看起来会比较糟糕,因为每一组的FETCH_COUNT
个行将被单独格式化,这就会导致不同的行组的列宽不同。其他的输出格式会更好。
HIDE_TABLEAM
如果此变量设置为true
,则不显示表的访问方法的详细信息。这主要用于回归测试。
HISTCONTROL
如果这个变量被设置为ignorespace
,则以一个空格开始的行不会被放入到历史列表中。如果被设置为值ignoredups
,则匹配之前的历史行的行不会被放入。值ignoreboth
组合了上述两种值。如果被重置或者被设置为none
(默认值),所有在交互模式中被读入的行都会保存在历史列表中。
这个特性是可耻地从Bash抄袭过来的。
HISTFILE
该文件名将被用于存储历史列表。如果被重设,文件名将从PSQL_HISTORY
环境变量中取得。如果该环境变量也没有被设置,则默认值是~/.psql_history
。例如,
\set HISTFILE ~/.psql_history- :DBNAME
放在~/.ltsqlrc
中将会导致ltsql为每一个数据库维护一个单独的历史。
这个特性是可耻地从Bash抄袭过来的。
HISTSIZE
存储在命令历史中的最大命令数(默认值是500)。如果被设置为一个负值,则不会应用限制。
这个特性是可耻地从Bash抄袭过来的。
HOST
当前连接到的数据库服务器端口。每次连接到一个数据库时都会设置该变量(包括程序启动时),但是可以被更改或者重置。
IGNOREEOF
如果被设置为1或者更小,向一个ltsql的交互式会话发送一个EOF字符(通常是Control+D)将会终止应用。如果设置为一个较大的数字值,则必须键入多个连续的EOF字符才能让交互式会话终止。如果该变量被设置为一个非数字值,则它会被解释为10。默认值为0。
这个特性是可耻地从Bash抄袭过来的。
LASTOID
最后被影响的 OID 的值,这可能会由INSERT
或者\lo_import
命令返回。这个变量只保证在下一个SQL命令被显示完之前有效。
LightDB 服务器从12版开始不再支持 OID 系统列,因此,在面向此类服务器时,跟随在INSERT
后面的 LASTOID 将始终为0。
LAST_ERROR_MESSAGE
LAST_ERROR_SQLSTATE
当前ltsql会话中最近一个失败查询的主错误消息和相关的SQLSTATE代码,如果在当前会话中没有发生错误,则是一个空字符串和00000
。
ON_ERROR_ROLLBACK
当被设置为on
时,如果事务块中的一个语句产生一个错误,该错误会被忽略并且该事务会继续。当被设置为interactive
时,只在交互式会话中忽略这类错误,而读取脚本文件时则不会忽略错误。当被重置或者设置为off
(默认值)时,事务块中产生错误的一个语句会中止整个事务。错误回滚模式的工作原理是在事务块的每个命令之前都为你发出一个隐式的SAVEPOINT
,然后在该命令失败时回滚到该保存点。
ON_ERROR_STOP
默认情况下,出现一个错误后命令处理会继续下去。当这个变量被设置为on
后,出现错误后命令处理会立即停止。在交互模式下,ltsql将会返回到命令提示符;否则,ltsql将会退出并且返回错误代码 3 来把这种情况与致命错误区分开来,致命错误会被报告为错误代码 1。在两种情况下,任何当前正在运行的脚本(顶层脚本以及任何它已经调用的其他脚本)将被立即中止。如果顶层命名字符串包含多个 SQL 命令,将在当前命令处停止处理。
PORT
当前连接到的数据库服务器端口。每次连接到一个数据库时都会设置该变量(包括程序启动时),但是可以被更改或者重置。
PROMPT1
PROMPT2
PROMPT3
这些变量指定ltsql发出的提示符的模样。见下文的Prompting。
QUIET
把这个变量设置为on
等效于命令行选项-q
。在交互模式下可能用处不大。
ROW_COUNT
上一个SQL查询返回的行数或者受影响的行数,如果该查询失败或者没有报告行计数则为0。
SERVER_VERSION_NAME
SERVER_VERSION_NUM
字符串形式的服务器版本号。每次你连接到一个数据库(包括程序启动)时,这些都会被设置,但可以被改变或者重设。
SHOW_CONTEXT
这个变量可以被设置为值never
、errors
或者always
来控制是否在来自服务器的消息中显示CONTEXT
域。默认是errors
(表示在错误消息中显示上下文,但在通知和警告消息中不显示)。
当VERBOSITY
被设置为terse
或sqlstate
时,这个设置无效(另见\errverbose
,它可以用来得到刚遇到的错误的详细信息)。
SINGLELINE
设置这个变量为on
等效于命令行选项-S
。
SINGLESTEP
设置这个变量为on
等效于命令选项-s
。
SQLSTATE
与上一个SQL查询的失败相关的错误代码(见Appendix A),如果上一个查询成功则为00000
。
USER
当前连接的数据库用户。每次连接到一个数据库时都会设置该变量(包括程序启动时),但是可以被更改或者重置。
VERBOSITY
这个变量可以被设置为值default
、verbose
、terse
或者sqlstate
来控制错误报告的详细程度(另见\errverbose
,在想得到之前的错误的详细版本时使用)。
VERSION
VERSION_NAME
VERSION_NUM
这些变量在程序启动时被设置以反映ltsql的版本,分别是一个详细的字符串、一个短字符串以及一个数字。它们可以被更改或重设。
ltsql变量的一个关键特性是可以把它们替换(“插入”)到常规SQL语句中,也可以把它们作为元命令的参数。此外,ltsql还提供了功能来确保被用作 SQL 文字和标识符的变量值会被正确地引用。插入一个值而不需要加引用的语法是在变量名前面加上一个冒号(:
)。例如,
test=>\set foo 'my_table'
test=>SELECT * FROM :foo;
将查询表my_table
。注意这可能会不安全:该变量的值会被按字面拷贝,因此它可能包含不平衡的引号甚至反斜线命令。必须确保把它放在那里是有意义的。
当一个值被用作 SQL 文本或者标识符时,最安全的是把它加上引用。要引用一个变量的值作为 SQL 文本,可以把变量名称放在单引号中并且在引号前面写一个冒号。要引用作为 SQL 标识符,则可以把变量名称放在双引号中并且在引号前面写一个冒号。这种结构可以正确地处理变量值中嵌入的引号和其他特殊字符。之前的例子用这种方法写会更安全:
test=>\set foo 'my_table'
test=>SELECT * FROM :"foo";
在被引用的SQL文本和标识符中将不会执行变量插入。因此,一个诸如':foo'
的结构不会从一个变量的值产生一个被引用的文本(即便能够也会不安全,因为无法正确地处理嵌入在值中的引号)。
使用这种机制的一个例子是把一个文件的内容拷贝到一个表列中。首先把该文件载入到一个变量,然后把该变量的值作为一个被引用的字符串插入:
test=>\set content `cat my_file.txt`
test=>INSERT INTO my_table VALUES (:'content');
(注意如果my_file.txt
包含 NUL 字节,这样也不行。ltsql不支持在变量值中嵌入 NUL 字节)。
因为冒号可以合法地出现在 SQL 命令中,一次明显的插入尝试(即:name
、:'name'
或者:"name"
)不会被替换,除非所提及的变量就是当前被设置的。在任何情况下,可以用一个反斜线对冒号进行转义以避免它被替换。
:{?
特殊语法根据该变量存在与否返回TRUE或者FALSE,并且因此总是会被替换,除非分号被反斜线转义。
name
}
变量的冒号语法对嵌入式查询语言(例如ECPG(Oracle Pro*c兼容))来说是标准的SQL。用于数组切片和类型造型的冒号语法是LightDB扩展,它有时可能会与标准用法冲突。把一个变量值转义成 SQL 文本或者标识符的冒号引用语法是一种ltsql扩展。
ltsql发出的提示符可以根据用户的喜好自定义。PROMPT1
、PROMPT2
和PROMPT3
这三个变量包含了描述提示符外观的字符串和特殊转义序列。Prompt 1 是当ltsql等待新命令时发出的常规提示符。Prompt 2 是在命令输入时需要更多输入时发出的提示符,例如因为当命令没有被分号终止或者引用没有被关闭时就会发出这个提示符。在运行一个SQL COPY FROM STDIN
命令并且需要在终端上输入一个行值时,会发出 Prompt 3。
被选中的提示符变量会被原样打印,除非碰到一个百分号(%
)。百分号的下一个字符会被特定的其他文本替换。预定义好的替换有:
%M
数据库服务器的完整主机名(带有域名),或者当该连接是建立在一个 Unix 域套接字上时则是[local]
,或者当 Unix 域套接字不在编译在系统内的默认位置上时则是[local:
。
/dir/name
]
%m
数据库服务器的主机名称(在第一个点处截断),或者当连接建立在一个 Unix 域套接字上时是[local]
。
%>
数据库服务器正在监听的端口号。
%n
数据库会话的用户名(在数据库会话期间,这个值可能会因为命令SET SESSION AUTHORIZATION
的结果而改变)。
%/
当前数据库的名称。
%~
和%/
类似,但是如果数据库是默认数据库时输出是~
(波浪线)。
%#
如果会话用户时一个数据库超级用户,则是#
,否则是一个>
(在数据库会话期间,这个值可能会因为命令SET SESSION AUTHORIZATION
的结果而改变)。
%p
当前连接到的后端的进程 ID。
%R
在提示符1下通常是=
,但如果会话位于一个条件块的一个非活动分支中则是@
,如果会话处于单行模式中则是^
,如果会话从数据库断开连接(\connect
失败时会发生这种情况)则是!
。在提示符 2 中,根据为什么ltsql期待更多的输入,%R
会被一个相应的字符替换:如果命令还没有被终止是-
,如果有一个未完的/* ... */
注释则是*
,如果有一个未完的被引用字符串则是一个单引号,如果有一个未完的被引用标识符则是一个双引号,如果有一个未完的美元引用字符串则是一个美元符号,如果有一个还没有被配对的左圆括号则是(
。在提示符 3 中%R
不会产生任何东西。
%x
事务状态:当不在事务块中时是一个空字符串,在一个事务块中时是*
,在一个失败的事务块中时是!
,当事务状态是未判定时(例如因为没有连接)为?
。
%l
当前语句中的行号,从1
开始。
%
digits
带有指定的八进制码的字符会被替换。
%:
name
:
ltsql变量name
的值。有关详细信息,请参阅上面的 Variables。
%`
command
`
command
的输出,类似于平常的“反引号”替换。
%[
... %]
提示符可以包含终端控制字符,例如改变提示符文本的颜色、背景或者风格以及更改终端窗口标题的控制字符。为了让Readline的行编辑特性正确工作,这些不可打印的控制字符必须被包裹在%[
和%]
之间以指定它们是不可见的。在提示附中可以出现多个这样的标识对。例如:
test=> \set PROMPT1 '%[%033[1;33;40m%]%n@%/%R%[%033[0m%]%# '
会导致一个在兼容 VT100 的彩色终端上的粗体(1;
)的、黑底黄字(33;40
)的提示符。
%w
与 PROMPT1
的最近输出相同宽度的空白。 这可以用作 PROMPT2
设置,以便多行语句与第一行对齐,但没有可见的辅助提示。
要在你的提示符中插入一个百分号,可以写成%%
。提示符 1 和 2 的默认提示是'%/%R%x%# '
,提示符 3 的提示是'>> '
。
这个特性是可耻地从tcsh抄袭过来的。
为了方便的行编辑和检索,ltsql支持Readline库。ltsql退出时命令历史会被自动保存,而当ltsql启动时命令历史会被重新载入。ltsql也支持 tab 补全,不过补全逻辑绝不是一个SQL解析器。tab 补全产生的查询也可能会受其他 SQL 命令干扰,例如SET TRANSACTION ISOLATION LEVEL
。如果出于某种原因不想用 tab 键补全,可以把下面的代码放在主目录下的名为.inputrc
文件中关闭该特性:
$if ltsql set disable-completion on $endif
(这不是ltsql特性而是Readline的特性。进一步的细节请阅读它的文档。)
set define on/off
命令来源于oracle的sqlplus工具。
set define on/off
命令目前只支持oracle模式的SELECT
语句。
您可以在SELECT
语句的任意位置使用替换变量(SELECT
除外)。
您可以使用&标记变量,&&标记变量不支持。遇到连续三个以上&标记变量取最后一个&。
变量名可以由数字,英文字母,下划线混合组成。
允许&与变量名之间有空格。
当ltsql执行SQL语句遇到替换变量时,ltsql会提示您输入该值。
您可以在提示符下输入任何字符串,即使是包含空格和标点符号的字符串。
输入字符串不超过240个字符。
这个例子展示了如何使用替换变量功能:
lightdb@oracle=# select &a lightdb@oracle-# from &a; Enter value for a : 123 Enter value for a : dual old 1: select &a new 1: select 123 old 2: from &a; new 2: from dual; ?column? ---------- 123 (1 row)
这个例子不支持替换变量功能:
lightdb@oracle=# prepare stmt as select '&name'; PREPARE
为了与 Oracle 数据库兼容,ltsql 执行 windous 下的sql文件会去掉文件中的\r字符。仅在 Oracle 兼容模式下如此执行。
COLUMNS
如果\pset columns
为零,这个环境变量控制用于wrapped
格式的宽度以及用来确定是否输出需要用到分页器或者切换到扩展自动模式中的垂直格式的宽度。
LTDATABASE
LTHOST
LTPORT
LTUSER
默认连接参数(见Section 32.14)。
LT_COLOR
规定在诊断消息中是否使用颜色。可能的值为always
、 auto
、never
。
PSQL_EDITOR
EDITOR
VISUAL
\e
、\ef
以及\ev
命令所使用的编辑器。会按照列出的顺序检查这些变量,第一个被设置的将被使用。如果都没有被设置,默认是使用Unix系统上的vi
。
PSQL_EDITOR_LINENUMBER_ARG
当\e
、\ef
或者\ev
带有一个行号参数时,这个变量指定用于传递起始行号给用户编辑器的命令行参数。对于Emacs或者vi之类的编辑器,这个变量是一个加号。如果需要在选项名称和行号之间有空格,可以在该变量的值中包括一个结尾的空格。例如:
PSQL_EDITOR_LINENUMBER_ARG='+' PSQL_EDITOR_LINENUMBER_ARG='--line '
在 Unix 系统上默认是+
(对应于默认编辑器vi
,且对很多其他常见编辑器可用)。
PSQL_HISTORY
命令历史文件的替代位置。波浪线(~
)扩展会被执行。
PSQL_PAGER
PAGER
如果一个查询的结果在屏幕上放不下,它们会通过这个命令分页显示。典型的值是more
或less
。通过把PSQL_PAGER
或PAGER
设置为空字符串可以禁用分页器的使用,调整\pset
命令与分页器相关的选项也能达到同样的效果。会按照列出的顺序检查这些变量,第一个被设置的将被使用。如果都没有被设置,则大部分平台上默认使用more
。
PSQLRC
用户的.ltsqlrc
文件的替代位置。波浪线(~
)扩展会被执行。
SHELL
被\!
命令执行的命令。
TMPDIR
存储临时文件的目录。默认是/tmp
。
和大部分其他LightDB工具一样,这个工具也使用libpq所支持的环境变量(见Section 32.14)。
ltsqlrc
and ~/.ltsqlrc
如果没有-X
选项,在连接到数据库后但在接收正常的命令之前,ltsql会尝试依次从系统级的启动文件(ltsqlrc
)和用户的个人启动文件(~/.ltsqlrc
)中读取并且执行命令。这些文件可以被用来设置客户端或者服务器,通常是一些\set
和SET
命令。
系统级的启动文件是ltsqlrc
,它应该在安装好的LightDB的“系统配置”目录中,最可靠的定位方法是运行lt_config --sysconfdir
。默认情况下,这个目录将是../etc/
(相对于包含LightDB可执行文件的目录)。可以通过LTSYSCONFDIR
环境变量显式地设置这个目录的名称。
用户个人的启动文件是.ltsqlrc
,它应该在调用用户的主目录中。
系统级和用户个人的启动文件都可以弄成是针对特定ltsql版本的,方法是在文件名后面加上一个横线以及LightDB的主、次版本号,例如~/.ltsqlrc-9.2
或者~/.ltsqlrc-9.2.5
。版本最为匹配的文件会优先于不那么匹配的文件读入。
.psql_history
命令行历史被存储在文件~/.psql_history
中。
历史文件的位置可以通过HISTFILE
ltsql变量或者PSQL_HISTORY
环境变量明确的设置。
ltsql和具有相同主版本或者更老的主版本服务器最为匹配。如果服务器的版本比ltsql本身要高,则反斜线命令尤其容易失败。不过,\d
家族的反斜线命令应该可以和服务器一起使用,但服务器的版本不必比ltsql本身新。运行 SQL 命令并且显示查询结果的一般功能应该也能和具有更新主版本的服务器一起使用,但是并非在所有的情况下都能保证如此。
如果你想用ltsql连接到多个具有不同主版本的服务器,推荐使用最新版本的ltsql。或者,你可以为每一个主版本保留一份ltsql拷贝,并且针对相应的服务器使用匹配的版本。但实际上,这种额外的麻烦是不必要的。
为了与 Oracle 数据库兼容,ltsql 允许用户在单独一行上输入斜杠并忽略它。 此功能仅在 Oracle 兼容模式下可用。支持'/'前后存在空白字符。
lightdb@oracle_test=# show lightdb_dblevel_syntax_compatible_type ; lightdb_dblevel_syntax_compatible_type ---------------------------------------- Oracle (1 row) lightdb@oracle_test=# lightdb@oracle_test=# lightdb@oracle_test=# / lightdb@oracle_test=# / lightdb@oracle_test=# / lightdb@oracle_test=# / lightdb@oracle_test=# ;
第一个例子展示了如何如何跨越多行输入一个命令。注意提示符的改变:
test=>CREATE TABLE my_table (
test(>first integer not null default 0,
test(>second text)
test->;
CREATE TABLE
现在再看看表定义:
test=> \d my_table
Table "public.my_table"
Column | Type | Collation | Nullable | Default
--------+---------+-----------+----------+---------
first | integer | | not null | 0
second | text | | |
现在我们把提示符改一改:
test=> \set PROMPT1 '%n@%m %~%R%# '
peter@localhost test=>
假定已经用数据填充了这个表并且想看看其中的数据:
peter@localhost test=> SELECT * FROM my_table; first | second -------+-------- 1 | one 2 | two 3 | three 4 | four (4 rows)
你可以用\pset
命令以不同的方式显示表:
peter@localhost test=>\pset border 2
Border style is 2. peter@localhost test=>SELECT * FROM my_table;
+-------+--------+ | first | second | +-------+--------+ | 1 | one | | 2 | two | | 3 | three | | 4 | four | +-------+--------+ (4 rows) peter@localhost test=>\pset border 0
Border style is 0. peter@localhost test=>SELECT * FROM my_table;
first second ----- ------ 1 one 2 two 3 three 4 four (4 rows) peter@localhost test=>\pset border 1
Border style is 1. peter@localhost test=>\pset format csv
Output format is csv. peter@localhost test=>\pset tuples_only
Tuples only is on. peter@localhost test=>SELECT second, first FROM my_table;
one,1 two,2 three,3 four,4 peter@localhost test=>\pset format unaligned
Output format is unaligned. peter@localhost test=>\pset fieldsep '\t'
Field separator is " ". peter@localhost test=>SELECT second, first FROM my_table;
one 1 two 2 three 3 four 4
或者使用短命令:
peter@localhost test=>\a \t \x
Output format is aligned. Tuples only is off. Expanded display is on. peter@localhost test=>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
这是一个示例,用\df
命令以发现名称匹配int*pl
并且第二参数是bigint
类型的函数:
peter@localhost test=>SELECT * FROM my_table
peter@localhost test->\g (format=aligned tuples_only=off expanded=on)
-[ RECORD 1 ]- first | 1 second | one -[ RECORD 2 ]- first | 2 second | two -[ RECORD 3 ]- first | 3 second | three -[ RECORD 4 ]- first | 4 second | four
如果需要,可以用\crosstabview
命令以交叉表的形式显示查询结果:
test=>SELECT first, second, first > 2 AS gt2 FROM my_table;
first | second | gt2 -------+--------+----- 1 | one | f 2 | two | f 3 | three | t 4 | four | t (4 rows) test=>\crosstabview first second
first | one | two | three | four -------+-----+-----+-------+------ 1 | f | | | 2 | | f | | 3 | | | t | 4 | | | | t (4 rows)
这第二个例子展示了表的“乘法”(连接),行按照序号降序排序且列按照独立的、升序的方式排序。
test=>SELECT t1.first as "A", t2.first+100 AS "B", t1.first*(t2.first+100) as "AxB",
test(>row_number() over(order by t2.first) AS ord
test(>FROM my_table t1 CROSS JOIN my_table t2 ORDER BY 1 DESC
test(>\crosstabview "A" "B" "AxB" ord
A | 101 | 102 | 103 | 104 ---+-----+-----+-----+----- 4 | 404 | 408 | 412 | 416 3 | 303 | 306 | 309 | 312 2 | 202 | 204 | 206 | 208 1 | 101 | 102 | 103 | 104 (4 rows)