9.25. 系統資訊函數

Table 9.60 列出了一些取得連線和系統資訊的函數。

除了本節中列出的功能之外，還有一些與統計系統相關的功能也提供系統訊息。有關更多訊息，請參閱第 28.2.2 節。

Table 9.60. 連線資訊函數

注意

current_catalog,current_role,current_schema,current_user,session_user, 和user 在 SQL 中有特殊的語法狀態：他們必須以沒有括號的方式呼叫。（在PostgreSQL中，括號可以選擇性地與 current_schema 一起使用，但不能與其他的函數一起使用。）

session_user 通常是發起目前資料庫連線的使用者；但超級使用者可以利用 SET SESSION AUTHORIZATION 更改此設定。current_user 是適用於權限檢查的使用者識別方式。通常它與連線中的使用者相同，但也可以使用 SET ROLE 進行更改。在使用 SECURITY DEFINER 屬性執行功能期間，它也會發生變化。用 Unix 的說法，連線使用者是「real user」，而目前使用者是「effective user」。current_role 和 user 是 current_user 的同義詞。 （標準 SQL 區分了 current_role 和 current_user，但 PostgreSQL 並沒有，因為它將使用者和角色統合為一種實體。）

current_schema 回傳搜尋路徑中的第一個 schema 名稱（如果搜尋路徑為空值，則回傳空值）。這將會用於在沒有指定 schema 的情況下建立的任何資料表或其他物件的 schema。current_schemas（boolean）回傳目前搜尋路徑中所有 schema 名稱的陣列。 布林選項表示隱含的系統 schema（如pg_catalog）是否包含在回傳的搜尋路徑中。

注意

搜尋路徑可以在執行中時更改。該指令是：

SET search_path TO schema [, schema, ...]

inet_client_addr 回傳目前用戶端的 IP 位址、inet_client_port 回傳連接埠、inet_server_addr 回傳伺服器接受目前連線的 IP 位址、inet_server_port 回傳連接埠。 如果目前連線是透過 Unix-domain socker，那這些函數都會回傳 NULL。

pg_blocking_pids 會回傳連線中阻擋指定 Process ID 的 Process ID 陣列，如果沒有這樣的 Process 或未被阻擋，則回傳一個空的陣列。如果一個伺服器的 Process 阻擋了其他 Process 的鎖定請求（Hard block），或者正在與其他請求鎖定的 Process 在等待佇列之前即發生衝突（Soft block）。在使用平行查詢時，即使實際的 lock 被子程序持有或等待，結果也都會列出用戶端可見的 Process ID（即 pg_backend_pid 結果）。因此，結果中可能會有重複的 PID。還要注意的是，當準備好的交易事務持有衝突的鎖定時，它將在此函數的結果中以 zero process ID 表示。頻繁呼叫此函數可能會對資料庫效能產生一些影響，因為它需要短時間獨佔鎖定管理器的共享狀態。

pg_conf_load_time 回傳上次載入伺服器設定檔的時間戳記，帶有時區記錄。 （如果目前的連線仍然存在的話，這將是連線本身重新讀取設定檔的時間，因此在不同的連線中讀取會有所不同，否則會是 postmaster 重新讀取設定檔的時間。）

pg_current_logfile 以 text 型別回傳日誌收集器目前使用的日誌檔的路徑。該路徑包括log_directory目錄和日誌檔名稱。日誌收集必須啟用或回傳值為 NULL。當存在多個日誌檔（每個檔案格式不同）時，呼叫不帶參數的 pg_current_log 將回傳具有在有序列表中找到的第一個格式的檔案路徑：stderr，csvlog。 沒有任何日誌檔具有這些格式時，將回傳 NULL。 要以文字形式請求特定的檔案格式，請將 csvlog 或 stderr 作為參數。當請求的日誌格式不是設定的 log_destination 時，回傳值為 NULL。pg_current_log 檔案反映了 current_logfiles 檔案的內容。

pg_my_temp_schema 回傳目前連線臨時 schema 的 OID，如果沒有的話（因為沒有建立任何臨時資料表），則回傳零。pg_is_other_temp_schema 如果給予的 OID 是另一個連線的臨時 schema OID，則回傳 true。 （舉個例子，這可以用於從列表顯示中排除其他連線的臨時資料表。）

pg_listening_channels 回傳目前連線正在監聽的一組非同步監聽通道的名稱。 pg_notification_queue_usage 回傳目前正在等待處理的監聽佔用的總可用空間的比率，範圍為 0-1。 有關更多訊息，請參閱 LISTEN 和 NOTIFY。

pg_postmaster_start_time 回傳伺服器啟動時帶有時區的時間戳記。

pg_safe_snapshot_blocking_pids 回傳阻擋具有指定 Process ID的取得安全快照的連線 Process ID 陣列，如果沒有這樣的 Process 或未有阻擋的情況，則回傳一個空陣列。執行 SERIALIZABLE 交易事務的連線會阻止另一個 SERIALIZABLE READ ONLY DEFERRABLE 交易事務取得快照，直到後者確定避免使用任何謂 predicate lock 是安全的。有關可序列化 SERIALIZABLE 和可延期 DEFERRABLE 交易的更多訊息，請參閱第 13.2.3 節。頻繁呼叫此函數可能會對資料庫效能產生一些影響，因為它需要短時間詢問 predicate lock 管理器的共享狀態。

version 回傳一個說明 PostgreSQL 伺服器版本的字串。你也可以從 server_version 或適於機器讀取的 server_version_num 取得此信息。軟體研發人員應該使用 server_version_num（自8.2起可用）或 PQserverVersion，而不用需要解析文字的版本。

Table 9.61 列出了允許使用者以程式控制的方式查詢資料庫物件存取權限的函數。有關權限的更多訊息，請參閱第 5.6 節。

Table 9.61. 存取權限查詢功能

has_table_privilege 用於檢查使用者是否可以以特定的方式存取資料表。使用者可以透過 name、OID（pg_authid.oid）、public 來指定 PUBLIC 的虛擬角色，如果省略參數的話，預設為 current_user。該資料表可以使用名稱或 OID 來指定。（因此，has_table_privilege 實際上有六種變形，以它們的參數數量和型別加以區分。）以資料表名稱指定時，如果需要的，名稱可以加上 schema。所需的存取權限類型由文字字串指定，該文字字串必須為 SELECT、INSERT、UPDATE、DELETE、TRUNCATE、REFERENCES 或 TRIGGER 之一。或者，可以將 WITH GRANT OPTION 加到權限型別中以測試權限是否與授予的選項一起保存。此外，多個權限型別可以用逗號分隔列出，在這種情況下，如果列出的任何權限被保留，將會是 True 的結果。（權限字串的大小寫不重要，可以允許在權限名稱之間，但不在權限名稱內有額外的空白）。一些範例：

SELECT has_table_privilege('myschema.mytable', 'select');
SELECT has_table_privilege('joe', 'mytable', 'INSERT, SELECT WITH GRANT OPTION');

has_sequence_privilege 用於檢查使用者是否能以特定方式存取序列物件。其參數類似於 has_table_privilege。所需的存取權限類型必須為 USAGE、SELECT 或 UPDATE 之一。

has_any_column_privilege 用於檢查使用者是否能以特定方式存取資料表中的任何欄位。它的參數類似於 has_table_privilege，只是所需的存取權限類型必須為 SELECT、INSERT、UPDATE 或 REFERENCES 的組合。請注意，在資料表等級具有這些權限中的任何一項，都自然地授予該資料表的每一欄位。因此如果 has_table_privilege 對相同參數執行操作，has_table_privilege 始終都會回傳 true。但是，如果至少有一欄位有欄位級的欄限授予，則 has_any_column_privilege 也會為 true。

has_column_privilege 用於檢查使用者是否能以特定方式存取欄位。它的參數類似於 has_table_privilege，該欄位可以透過名稱或屬性編號指定。所需的存取權限類型必須為 SELECT、INSERT、UPDATE 或 REFERENCES 的某種組合。請注意，在資料表級擁有的權限中的任何一項都會自動授予該資料表的每一個欄位。

has_database_privilege 用於檢查使用者是否能以特定方式存取資料庫。它的參數與 has_table_privilege 類似。所需的存取權限類型必須為 CREATE、CONNECT、TEMPORARY 或 TEMP（相當於 TEMPORARY）的某種組合。

has_function_privilege 用於檢查使用者是否可以以特定方式存取函數。它的參數類似於 has_table_privilege。 當透過文字字串而不是 OID 指定函數時，允許的輸入與regprocedure 資料型別相同（請參閱第 8.18 節）。所需的存取權限類型必須為 EXECUTE。例如：

SELECT has_function_privilege('joeuser', 'myfunc(int, text)', 'execute');

has_foreign_data_wrapper_privilege 用於檢查使用者是否能以特定方式存取 FDW。 它的參數類似於 has_table_privilege。所需的存取權限類型必須為 USAGE。

has_language_privilege 用於檢查使用者是否能以特定方式存 procedure 的程式語言。 它的參數類似於 has_table_privilege。所需的存取權限類型必須為 USAGE。

has_schema_privilege 用於檢查使用者是否能以特定方式存取 schema。它的參數類似於 has_table_privilege。所需的存取權限類型必須為 CREATE 或 USAGE 的組合。

has_server_privilege 用於檢查使用者是否能以特定方式存取 foreign server。它的參數類似於 has_table_privilege。所需的存取權限類型必須為 USAGE。

has_tablespace_privilege 用於檢查使用者是否能以特定方式存取資料表空間。它的參數類似於 has_table_privilege。所需的存取權限類型必須為 CREATE。

has_type_privilege 用於檢查使用者是否能以特定方式存取資料型別。它的參數類似於 has_table_privilege。當使用文字字串而不是 OID 指定資料型別時，允許的輸入與 regtypedata 型別相同（參閱第 8.18 節）。所需的存取權限類型必須為 USAGE。

pg_has_role 用於檢查使用者是否能以特定方式存取角色。它的參數類似於 has_table_privilege，而 public 不允許作為使用者名稱。所需的存取權限類型必須為 MEMBER 或 USAGE 的組合。MEMBER 表示角色中的直接或間接成員資格（即俱備 SET ROLE 的權力），而 USAGE 表示角色的權限是否立即可用而不需要執行 SET ROLE。

row_security_active 用於檢查 current_user 和 environment 的上下文中的資料列級的安全性是否對指定的資料表是有效的。該資料表可以使用名稱或 OID 來指定。

Table 9.62 列出想要確定某個物件在目前 schema 搜尋路徑中是否可見的函數。例如，如果一個資料表所包含的 schema 位於搜尋路徑中，並且在搜尋路徑的前面沒有出現同名的資料表，則稱該資料表是可見的。這相當於可以透過名稱引用資料表而不需要明確指定 schema 限定的語法。要列出所有可見資料表的名稱：

SELECT relname FROM pg_class WHERE pg_table_is_visible(oid);

Table 9.62. Schema 可見性的查詢函數

每個函數都對一種類型的資料庫物件執行可見性檢查。請注意，pg_table_is_visible 也可以用於 view、materialized view、索引、序列和外部資料表；pg_type_is_visible 也可以用於 domain。對於函數和運算子，如果在路徑的前面沒有名稱和參數資料型別相同的物件，則搜尋路徑中的物件是可見的。對於運算子，名稱和相關的索引存取方法都應該考慮在內。

所有這些功能都需要物件的 OID 來識別要檢查的物件。如果要按名稱測試物件，則使用 OID 別名型別（regclass、regtype、regprocedure、regoperator、regconfig 或 regdictionary）會比較方便，例如：

SELECT pg_type_is_visible('myschema.widget'::regtype);

請注意，以這種方式測試非 schema 限定的型別名稱沒有什麼意義 - 因為如果名稱可以被識別，則它必然是可見的。

Table 9.63 列出了從系統目錄中取得資訊的功能。

Table 9.63. System Catalog Information Functions

format_type 回傳由其 OID 查得的可能資料型別 SQL 名稱。如果沒有特定的型別名稱修飾字的話，則設定為 NULL。

pg_get_keywords 回傳一組描述伺服器識別的 SQL 關鍵字記錄。單詞欄位包含關鍵字。catcode 欄位包含一個類別代碼：U 表示未保留，C 表示欄位名，T 表示型別或函數名，或 R 表示保留字。catdesc列包含描述類別的可能本地化的字串。

pg_get_constraintdef、pg_get_indexdef、pg_get_ruledef、pg_get_statisticsobjdef 和

pg_get_triggerdef 分別重建限制條件、索引、規則、延伸統計物件或觸發器的建立指令。（請注意，這是一個反組譯的的功能，並不是原本初始建立的指令內容。）pg_get_expr 反組譯單一個表示式的內部形式，例如欄位的預設值。在檢查系統目錄的內容時會很有用。如果表示式可能包含 Vars，則指定它們引用關係的 OID 作為第二個參數；如果沒有 Vars，那就填上零。pg_get_viewdef 重建定義視圖的 SELECT 查詢。這些功能中的大多數都有兩種變形，其中一種可以選擇性地輸出結果。使用「pretty-print」則能使輸出的格式更具可讀性，不過預設格式更可能被未來版本的
PostgreSQL 以相同方式解釋；避免以轉存目的 pretty-print 輸出。為 pretty-print 給予
false 就會得到與根本沒有參數的變形相同結果。

pg_get_functiondef 為某個函數回傳一個完整的 CREATE OR REPLACE FUNCTION 語句。pg_get_function_arguments 回傳函數的參數列表，格式為需要在 CREATE FUNCTION 中出現的格式。pg_get_function_result 同樣回傳該函數的相對應的 RETURNS 子句。例如，pg_get_function_identity_arguments 回傳識別函數所需的參數列表，例如，它需要在 ALTER FUNCTION 中出現的形式，該形式會省略預設值。

pg_get_serial_sequence 回傳與欄位關聯的序列的名稱，如果沒有序列與欄位關聯，則回傳 NULL。第一個輸入參數是資料表名稱，你可以視情況使用 schema，第二個參數是欄位名稱。由於第一個參數可能是 schema 和資料表，因此不會將其視為雙引號識別符號，這意味著它預設就是小寫字母，而第二個參數（僅作為欄位名稱）被視為雙引號識別符號，並且會保留其大小寫模樣。該函數回傳一個適當格式的內容以傳遞給序列函數（參閱第 9.16 節）。該關聯可以用於 ALTER SEQUENCE OWNED BY 進行修改或刪除。（函數可能應該被稱為 pg_get_owned_sequence；它的目前名稱反映了它通常用於 serial 或 bigserial 欄位的現況。）

pg_get_userbyid 根據其 OID 取得角色的名稱。

pg_index_column_has_property、pg_index_has_property 和 pg_indexam_has_property 回傳指定的索引欄位、索引或索引存取方法是否擁有指定的屬性。如果屬性名稱未知或不適用於特定的物件，或者 OID 或欄位編號未標識有效物件，則回傳 NULL。 請參閱 Table 9.64 欄位屬性，Table 9.65 索引屬性以及 Table 9.66 存取方法屬性。 （請注意，延伸套件的存取方法可以為其索引定義其他屬性名稱。）

Table 9.64. 索引欄位屬性

Table 9.65. 索引屬性

Table 9.66. 索引存取方式屬性

pg_options_to_table 會回傳一組儲存選項 name/value 的組合（option_name / option_value），當參數傳送 pg_class.reloptions 或 pg_attribute.attoptions 時。

pg_tablespace_databases 用於檢查資料表空間。它回傳儲在在資料表空間中的資料庫 OID 集合。如果此函數有回傳任何資料，則表示資料表空間不是空的，並且不能被刪除。要顯示使用資料表空間的特定對象，你需要連線到 pg_tablespace_databases 所登記的資料庫並查詢其系統目錄中的 pg_class 資料表。

pg_typeof 回傳其所接受參數的資料型別 OID。這對於問題除錯或動態構建 SQL 查詢很有幫助。該函數宣告的為回傳型別為 regtype，這是一個 OID 別名型別（詳見第 8.18 節）；這意味著它與用於比較 OID 相同，但顯示為型別名稱。 例如：

SELECT pg_typeof(33);
 pg_typeof 
-----------
 integer
(1 row)
SELECT typlen FROM pg_type WHERE oid = pg_typeof(33);
 typlen 
--------
      4
(1 row)

表示式 collation for 用於回傳其參數的 collation。例如：

SELECT collation for (description) FROM pg_description LIMIT 1;
 pg_collation_for 
------------------
 "default"
(1 row)
SELECT collation for ('foo' COLLATE "de_DE");
 pg_collation_for 
------------------
 "de_DE"
(1 row)

該值可能會有括號和 schema-qualified。如果沒有能對應的 collation，則回傳 NULL。 如果參數不是能有 collation 的資料內容，則會產生錯誤。

to_regclass、to_regproc、to_regprocedure、to_regoper、to_regoperator、to_regtype、to_regnamespace 和 to_regrole 函數將關連、函數、運算子、資料型別、schema 和角色名稱（文字型別輸入）分別轉換為 regclass、regproc、regprocedure、regoper、regoperator、regtype、regnamespace 和 regrole。這些函數不同於型別轉換，因為它們不接受 OID，那將會回傳 null，而不是在找不到名稱時拋出錯誤（或者會回傳 forto_regproc 和 to_regoper，如果輸入的名稱與多個物件吻合時）。

Table 9.67 列出與資料庫物件識別和定址的相關函數。

Table 9.67. 物件資訊與定址函數

pg_describe_object 回傳由系統目錄 OID、物件 OID和子物件 ID（可能為零） 指定的資料庫物件的文字描述訊息。根據伺服器配置，此描述旨在提供操作人員的可讀性，並且可能會進行翻譯。這對確定儲存在 pg_depend 系統目錄中的物件識別非常有用。

pg_identify_object 回傳一個包含足夠訊息的資料列，以唯一識別由目錄 OID、物件 OID和（可能為零）子物件 ID 指定的資料庫物件。此函數旨在於機器可讀，所以不會進行翻譯。type 為識別資料庫物件的類型；schema 是物件所屬的 schema 名稱，而對於不屬於 schema 的物件類型為NULL；name 是物件的名稱，在必要時引用，只有在可以使用時才存在（ 與 schema 名稱一樣，如果需要才使用）作為物件的唯一識別符，否則為 NULL；識別是完整的物件識別，其精確格式取決於物件類型，格式中的每個部分都根據需要進行 schema-qualified 和使用括號。

pg_identify_object_as_address 回傳一個包含足夠訊息的資料列，以唯一識別由系統目錄 OID、物件 OID 和（可能為零）子物件 ID 指定的資料庫物件。回傳的訊息獨立於目前的伺服器。也就是說，它可以用來識別另一台伺服器中同名的物件。type 識別資料庫物件的型別；name 和 args 是文字陣列，它們一起組成對該物件的引用。這三個欄位傳遞給 pg_get_object_address 以取得物件的內部位址。這個函數是pg_get_object_address 的反函數。

pg_get_object_address 回傳一個包含足夠訊息的資料列，以唯一識別由其型別和物件名稱及其參數陣列所指定的資料庫物件。回傳的內容和系統目錄中使用的相同。例如pg_depend，可用於傳遞給其他系統函數，如 pg_identify_object 或pg_describe_object。catalog_id是包含物件的系統目錄 OID；object_id 是物件本身的OID，object_sub_id 是物件子 ID，如果沒有則為零。 這個函數是 pg_identify_object_as_address 的反函數。

Table 9.68 中列出的功能用於取得先前與 COMMENT 指令一起儲存的註解。如果未找到指定參數的註解，則回傳 NULL。

Table 9.68. Comment Information Functions

col_description 回傳資料表欄位的註解，由其資料庫的 OID 及欄位編號指定。 （obj_description 不能用於資料表欄位，因為欄位沒有自己的 OID。）

obj_description 以雙參數的形式回傳由其 OID 指定的資料庫物件註釋以及所包含的系統目錄名稱。 例如，obj_description(123456, ‘pg_class’) 將檢索 OID 為 123456 的資料表註釋。obj_description 的單參數形式僅需要物件的 OID。由於不能保證 OID 在不同的系統目錄中是唯一的，因此不推薦再使用它；否則可能會回傳錯誤的註解。

shobj_description 和 obj_description 用法相同，只是它用於檢索共享物件上的註解。 某些系統目錄對每個叢取中的所有資料庫都是全域的，並且其中的物件註解也全域存放的。

Table 9.69 中列出可匯出形式的函數以提供伺服器交易事務的訊息。這些函數的主要用途在於確定兩個快照之間提交了哪些交易事務。

Table 9.69. Transaction IDs and Snapshots

內部事務 ID 型別（xid）為 32位元大小，大約每 40 億次事務輪迴一次。但是，這些函數會導出 64 位元格式，該格式通過「epoch」計數器進行擴展，因此在安裝過程中不會輪迴。這些函數使用的資料型別 txid_snapshot 在特定時刻儲存有關事務 ID 可見性的訊息。Table 9.70 描述了它的相關功能。

Table 9.70. Snapshot Components

txid_snapshot的文字字串表示是 xmin:xmax:xip_list。例如 10:20:10,14,15 意味著xmin = 10，xmax = 20，xip_list = 10,14,15。

txid_status(bigint) 回報最近事務的提交狀態。應用程式可以使用它來確定在 COMMIT正在進行時，應用程式和資料庫伺服器連線中斷時是否提交或中止事務。如果交易時間足夠短以至於系統能保留該交易的提交狀態，則交易狀態將被回報為正在進行、已提交或已中止。如果太長以至於在系統中不存在對該交易事務的引用，而提交狀態訊息已被丟棄，則該函數將回傳 NULL。請注意，prepared transaction 會回報為正在進行中；如果需要確定 txid 是否為 prepared transaction，則應用程式必須使用checkpg_prepared_xacts。

Table 9.71 中列出的函數用於取得關於已經提交的事務訊息。這些功能主要提供有關交易何時發生的訊息。當啟用 track_commit_timestamp 配置選項時，它們可以提供一些有用的資料，只是僅用於啟用後所提交的事務。

Table 9.71. Committed transaction information

Table 9.72 中列出的函數為在 initdb 期間輸出的初始化訊息，例如系統目錄版本。它們還顯示關於 WAL 和查核點的處理訊息。這些訊息都是 cluster 範圍內的，並非特定於任何一個資料庫。它們提供了與 pg_control 資料相同的大部分訊息，儘管它們的形式更適合用於 SQL 函數。

Table 9.72. Control Data Functions

pg_control_checkpoint 回傳一筆記錄，如 Table 9.73 所示

Table 9.73. pg_control_checkpointColumns

pg_control_system 回傳一筆記錄，如 Table 9.74 所示

Table 9.74. pg_control_systemColumns

pg_control_init 回傳一筆記錄，如 Table 9.75 所示

Table 9.75. pg_control_initColumns

pg_control_recovery 回傳一筆記錄，如 Table 9.76 所示

Table 9.76. pg_control_recoveryColumns