PSQL(1) | PostgreSQL Client Applications | PSQL(1) |
psql - PostgreSQL 交互終端
psql [option...] [dbname [username]]
psql 是一個以終端爲基礎的 PostgreSQL 前端。它允許你交互地鍵入查詢,把它們發出給 PostgreSQL, 然後看看查詢的結果。另外,輸入可以來自一個文件。還有, 它提供了一些元命令和多種類 shell 地特性來實現書寫腳本以及對大量任務的自動化。
如果命令字串包含多個
SQL
命令,那麼他們在一個事務裏處理,
除非在字串裏包含了明確的
BEGIN/COMMIT
命令把他們分成多個事務。
這個和從 psql
的標準輸入裏給它填充相同字串不同。
如果filename 是- (連字符),則從標準輸入讀取。
使用這個選項與用 psql
< filename
有微小的區別。通常,兩者都回按照你預期那樣運行,但是使用
-f打開了一些很好的特性,
比如帶行號的錯誤信息。而且,使用這個選項還有可能有減小啓動負荷的機會。
另一方面,如果你把所有內容手工輸入,
使用 shell
輸入定向的方式(理論上)能保證生成和你已經得到的完全一樣的輸出(譯註:重複運行命令)。
這個選項已經廢棄了,因爲它在概念上有漏洞。
(提示輸入非缺省用戶名和提示輸入服務器要求的口令是完全兩碼事。)我們鼓勵你用
-U 和 -W 選項取代。
在當前版本里,如果服務器要求口令認證,psql 自動提出一個口令提示符。因爲目 前這個特性是以一個“hack”爲基礎, 自動識別有可能奇怪地失效,因此用這個選項 強制一個提示符。 如果沒有聲明口令提示符而服務器要求口令認證,那麼聯接企圖 將失敗。
如果正常結束,那麼psql 向 shell 返回 0,如果自身發生致命錯誤,則返回 1(內存用盡,未找到文件等), 如果和數據庫的連接失效而且會話不再活躍則返回 2,如果腳本中發生錯誤並且設置了 ON_ERROR_STOP 則返回 3。
psql 是一個普通的 PostgreSQL 客戶端應用。爲了與一個數據庫聯接,你需要知道你的目標數據庫, 服務器的主機名和端口號以及你希望以哪個用戶的身份進行聯接等信息。 我們可以通過命令行參數告訴 psql 這些信息,分別是 -d, -h,-p,和 -U。 如果有個參數不屬於任何選項開關,那麼它會被解釋成數據庫名(或者是用戶名-如果數據庫名稱也給出了。)。 不是所有這些選項都是必須的,缺省的也可以。如果你省略主機名, psql 將通過 Unix 域套接字與本地主機的服務器相聯。 缺省的端口號是編譯時確定的。因爲數據庫服務器使用同樣的缺省值, 所以在大多數設置下,你可能不需要聲明端口號。缺省的用戶名是你的 Unix 用戶名,與數據庫同名。 要注意的是你不能用任意用戶名與任何數據庫相聯。你的數據庫管理員應該告訴你你的訪問權限。 你可以通過設置幾個環境變量 PGDATABASE, PGHOST,PGPORT 和 PGUSER 爲對應的值的方法節約幾次敲擊。
如果因爲任何原因而無法與數據庫相聯(例如,權限不夠,服務器沒有運行等),
psql
將返回一個錯誤並退出。
通常狀況下,psql 提供一個帶有 psql 正在與之聯接的接數據庫名的,後綴 =>的提示符。例如,
$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)]
生成的異步通知信號。
你在 psql 裏輸入的任何以不帶引號的反斜槓('\')開頭的東西都是 psql 元命令,這些命令是由 psql 自己處理的。這些命令也是令 psql 可用於管理或書寫腳本的原因。 元命令更常見的叫法是斜槓或反斜槓命令。
一個 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命令可以自由的在一行裏面混合。
但是在任何情況下,一條元命令的參數不能延續超過行尾。
下列元命令是已定義的:
如果省略
username,則假設是當前用戶名。
作爲一條特殊規則,不帶任何參數運行\connect
將以缺省用戶身份與缺省數據庫連接(正如你不帶任何參數運行
psql 一樣。)
如果聯接失敗(用戶名錯,訪問拒絕等),那麼將保留前面的聯接--當且僅當在
psql
處於交互模式下如此。
如果運行的是非交互的腳本,處理會馬上停止,並返回一個錯誤。
選擇這樣的區別是一方面爲用戶使用方便考慮,另一方面爲保證腳本不會碰巧操作了錯誤的數據庫的安全機制考慮的。
這條命令的語法是模擬
SQL COPY
命令的。(參考它的描述獲取細節。)
要注意的是由此而來,有一些特殊的分析規則應用於\copy
命令。
尤其是變量替換規則和反斜槓代換規則不起作用。
從\d+ 來的命令也是一樣的,只不過還顯示與表的列關聯的註解。
=>\dd version
Object descriptions
Schema | Name | Object | Description ------------+---------+----------+---------------------------
pg_catalog | version | function | PostgreSQL version string (1 row)
可以用COMMENT SQL
命令生成對對象的描述。
如果聲明瞭
pattern,那麼只列出匹配模式的對象。
然後根據一般的psql規則重新分析查詢緩衝區, 這時整個緩衝區當作一個單行。 (因此你無法用這個方法制作“腳本”,用\i 做腳本。) 這還意味着 如果該查詢以分號結尾(或者包含分號),它就會馬上被執行。否則它只是在查詢 緩衝區裏等待。
=>\echo `date` Tue Oct 26 21:40:57 CEST 1999
foo=>\lo_import '/home/peter/pictures/photo.xcf' 'a picture of me' lo_import 152801
注意這條命令與服務器端的
lo_import
有一些區別,因爲這條命令是本地用戶在本地文件系統上操作,
而不是以服務器用戶在服務器文件系統上操作。
"查詢結果"包括所有表,命令響應和從數據庫服務器來的提示, 同樣還有各種各樣查詢數據庫的反斜槓命令的輸出(如\d),但是沒有錯誤信息。
可調節的打印選項有:
"Unaligned" (不對齊)把一條記錄的所有字段都輸出到一行, 用當前有效的域分隔符分隔。這主要用於生成那些要被其他程序讀取的輸出(tab分隔,逗號分隔)。 "Aligned" (對齊)模式是標準的,人類可讀的,格式化好了的文本輸出,也是缺省。 "HTML" 和 "LaTeX" 模式把表輸出爲可用於文檔裏的對應標記語言。它們還不是完整的文檔! (可能對於 HTML 變化還不是太大,但是在 LaTeX 裏,你必須有一個完整的文檔包裝器。)
所有四種輸出模式都支持擴展格式。
如果關閉了分頁器,則不使用它,如果打開了,程序只在需要的時候使用分頁器,也就是說,
輸出是到終端,而且那個表很可能無法與屏幕匹配。
(psql
在決定何時分頁時不是很完美。)\pset
pager
開關分頁器。我們也可以把分頁器設置爲
always,導致我們在任何情況下都使用分頁器。
可以在 "Examples 例子"
節看到這些不同格式輸出的示例。
有效的變量名可以包含字符,數字和下劃線。
參閱下面的 "Variables
變量" 獲取細節。
儘管你可以設置任何變量爲任意值,
psql對一些變量特殊對待。它們在關於變量的節裏面有文檔。
命令grant(7) 和revoke(7)
用於設置訪問權限。
參閱grant(7)
獲取更多信息。
這是\dp("顯示權限")的別名。
各種\d 命令都接受一個
pattern
參數,聲明要顯示的對象名字。*
表示"任何字符序列",
而 ?
表示"任何單個字符"。(這個表示法和
Unix 的 shell
文件名模式兼容。)
高級用戶也可以使用正則表達式表示法,比如字符表,[0-9]
這樣的東西來匹配"任意數字"。
要讓任何這些模式匹配字符可以安字面方式解析,那就應該用雙引號包圍它們。
一個包含(無引號的)句點的模式會被解析承一個模式名的模式後面跟着一個對象名的模式。
比如,\dt foo*.bar*
顯示所有以foo
開頭的模式裏的以 bar
開頭的表名字。
如果沒有出現句點,那麼這個模式只匹配在當前模式搜索路徑中可見的對象。
如果完全省略 pattern
參數, 那麼\d
命令顯示所有在當前模式搜索路徑中可見的對象。
要查閱在數據庫中的所有對象,使用模式
*.*。
psql 提供類似通常 Unix 命令 shell 那樣的變量替換特性。 變量只是簡單的名稱/數值對, 這裏的值可以是任何長度的任何值。要設置一個變量,使用 psql 元命令 \set:
testdb=>\set foo bar
testdb=>\echo :foo bar
如果你不帶第二個參數調用\set,
那麼只是設置這個變量而沒有值。
要重置(或刪除)一個變量,使用命令\unset。
psql 的內部變量可以包括任意順序, 任意數量的字母,數字和下劃線。 有一些常用變量被 psql 另眼相待。它們是一些選項設置, 這些選項在運行時可以通過改變變量的值或者改變一些應用的表現狀態而改變。 儘管你可以把這些變量用於其他用途,但是我們不鼓勵這麼做,因爲程序的特性可能會很快變得非常奇怪。 通常,所有特殊對待的變量都是由大寫字母組成(可能還有數字和下劃線)。 爲了保證和未來的最大限度的兼容性,請避免使用這樣的變量。 下面是一個所有特殊對待的變量列表。
一個附加的 psql 變量的有用特性是你可以把它們替換("代換")成正規的 SQL 語句。這樣做的語法同樣還是變量名前面加一個冒號(:)。
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
擴展,因此有衝突。)
psql 使用的提示符可以根據你的喜好客戶化。三個變量 PROMPT1,PROMPT2,和 PROMPT3 包含描述提示符的外觀的字串和特殊逃逸序列。Prompt 1 是 psql 請求一個新命令時的使用的正常提示符。 Prompt 2 是在一個命令輸入期待更多輸入時(因爲查詢沒有用一個分號結束或者引號沒有關閉)顯示的提示符。 Prompt 3 在你運行一個 SQL COPY 命令和等待你在終端上鍵入記錄時使用。
相應的提示符變量的值是按字面打印的,除非碰到一個百分號(%)。這時某些其他的文本被替換,
替換爲何物取決於下一個字符。已定義的替換是:
要在提示符裏插入百分號,鍵入%%。缺省提示符等效於
'%/%R%# ' 用於 prompts 1 和
2,以及'>> ' 用於 prompt 3。
psql 爲了編輯和檢索命令行的方便支持 readline 和歷史庫。 命令歷史存放在你的家目錄的一個叫 .psql_history 的文件裏, 並且當 psql 啓動的時候會裝載進來。 還支持 Tab 補齊,儘管該補齊邏輯並不是一個 SQL 分析器必備的。 如果因某些原因你不喜歡 tab 補齊,你可以把下面幾行放在你的家目錄的一個叫.inputrc 的文件裏關閉這個特性:
$if psql set disable-completion on $endif(這不是 psql 的特性, 是Readline 的。參考它的文檔獲取更多細節。)
testdb=>\foo Field separator is "oo".
第一個例子演示瞭如何把一個查詢分成多個行進行輸入。注意提示符的變化:
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)
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
Postgresql 中文網站 何偉平 <laser@pgsqldb.org>
本頁面中文版由中文
man 手冊頁計劃提供。
中文 man
手冊頁計劃:https://github.com/man-pages-zh/manpages-zh
2003-11-02 | Application |