PostgreSQL：文件：17：9.27. 系統資訊函數和運算子

9.27. 系統資訊函數和運算子
上一個	上一層	第 9 章. 函數和運算子	首頁	下一個

9.27.1. 工作階段資訊函數 #

表 9.69 顯示了幾個提取工作階段和系統資訊的函數。

除了本節列出的函數外，還有一些與統計系統相關的函數也提供系統資訊。有關更多資訊，請參閱第 27.2.26 節。

表 9.69. 工作階段資訊函數

函數描述
`current_catalog` → `name` `current_database` () → `name` 傳回目前資料庫的名稱。（在 SQL 標準中，資料庫稱為「目錄」，因此 `current_catalog` 是標準的拼寫。）
`current_query` () → `text` 傳回目前正在執行的查詢的文字，由用戶端提交（可能包含多個陳述式）。
`current_role` → `name` 這等同於 `current_user`。
`current_schema` → `name` `current_schema` () → `name` 傳回搜尋路徑中第一個結構描述的名稱（如果搜尋路徑為空，則傳回空值）。這是將用於任何在未指定目標結構描述的情況下建立的資料表或其他具名物件的結構描述。
`current_schemas` ( `include_implicit` `boolean` ) → `name[]` 以優先順序傳回目前有效搜尋路徑中所有結構描述名稱的陣列。（目前的 search_path 設定中，不對應於現有、可搜尋結構描述的項目將被省略。）如果布林引數為 `true`，則隱式搜尋的系統結構描述（例如 `pg_catalog`）將包含在結果中。
`current_user` → `name` 傳回目前執行環境的使用者名稱。
`inet_client_addr` () → `inet` 傳回目前用戶端的 IP 位址，如果目前的連線是透過 Unix 網域 socket，則傳回 `NULL`。
`inet_client_port` () → `integer` 傳回目前用戶端的 IP 埠號，如果目前的連線是透過 Unix 網域 socket，則傳回 `NULL`。
`inet_server_addr` () → `inet` 傳回伺服器接受目前連線的 IP 位址，如果目前的連線是透過 Unix 網域 socket，則傳回 `NULL`。
`inet_server_port` () → `integer` 傳回伺服器接受目前連線的 IP 連接埠號碼，如果目前連線是透過 Unix 網域 Socket，則傳回 `NULL`。
`pg_backend_pid` () → `integer` 傳回附加到目前連線的伺服器進程 ID。
`pg_blocking_pids` ( `integer` ) → `integer[]` 傳回一個陣列，其中包含因無法取得鎖定而阻擋具有指定進程 ID 的伺服器進程的連線之進程 ID。如果沒有此伺服器進程或未被阻擋，則傳回一個空陣列。如果一個伺服器進程持有與被阻擋進程的鎖定請求衝突的鎖定（硬阻擋），或者正在等待與被阻擋進程的鎖定請求衝突的鎖定，並且在等待佇列中排在其前面（軟阻擋），則會阻擋另一個伺服器進程。當使用並行查詢時，結果總是列出客戶端可見的進程 ID（也就是 `pg_backend_pid` 的結果），即使實際的鎖定是由子工作進程持有或等待。因此，結果中可能會有重複的 PID。另請注意，當預備交易持有衝突鎖定時，將以零進程 ID 表示。頻繁呼叫此函數可能會對資料庫效能產生一些影響，因為它需要在短時間內獨佔存取鎖定管理器的共享狀態。
`pg_conf_load_time` () → `timestamp with time zone` 傳回上次載入伺服器組態檔案的時間。如果目前的連線在該時間存在，這將是連線本身重新讀取組態檔案的時間（因此，不同連線的讀取時間會略有不同）。否則，這是 postmaster 進程重新讀取組態檔案的時間。
`pg_current_logfile` ( [ `text` ] ) → `text` 傳回日誌收集器目前使用的日誌檔的路徑名稱。該路徑包括 log_directory 目錄和個別日誌檔名。如果已停用日誌收集器，則結果為 `NULL`。如果存在多個日誌檔案，每個檔案的格式不同，則沒有參數的 `pg_current_logfile` 會傳回檔案路徑，該檔案具有在排序清單中找到的第一個格式：`stderr`、`csvlog`、`jsonlog`。如果沒有任何日誌檔案具有這些格式，則會傳回 `NULL`。若要請求有關特定日誌檔案格式的資訊，請提供 `csvlog`、`jsonlog` 或 `stderr` 作為可選參數的值。如果在 log_destination 中未配置請求的日誌格式，則結果為 `NULL`。結果反映了 `current_logfiles` 檔案的內容。預設情況下，此函數僅限於超級使用者和具有 `pg_monitor` 角色權限的角色，但可以授予其他使用者 EXECUTE 權限來執行該函數。
`pg_my_temp_schema` () → `oid` 傳回目前連線的暫時 Schema 的 OID，如果沒有（因為尚未建立任何暫時資料表），則傳回零。
`pg_is_other_temp_schema` ( `oid` ) → `boolean` 如果給定的 OID 是另一個連線的暫時 Schema 的 OID，則傳回 true。（例如，這可用於從目錄顯示中排除其他連線的暫時資料表。）
`pg_jit_available` () → `boolean` 如果JIT編譯器擴充功能可用（請參閱第 30 章）並且 jit 組態參數設定為 `on`，則傳回 true。
`pg_listening_channels` () → `setof text` 傳回目前連線正在監聽的非同步通知通道名稱的集合。
`pg_notification_queue_usage` () → `double precision` 傳回目前被等待處理的通知佔用的非同步通知佇列最大大小的分數 (0–1)。有關更多資訊，請參閱 LISTEN 和 NOTIFY。
`pg_postmaster_start_time` () → `timestamp with time zone` 傳回伺服器啟動的時間。
`pg_safe_snapshot_blocking_pids` ( `integer` ) → `integer[]` 傳回一個陣列，其中包含因無法取得安全快照而阻擋具有指定進程 ID 的伺服器進程的連線之進程 ID。如果沒有此伺服器進程或未被阻擋，則傳回一個空陣列。執行 `SERIALIZABLE` 交易的連線會阻擋 `SERIALIZABLE READ ONLY DEFERRABLE` 交易取得快照，直到後者確定可以安全地避免取得任何謂詞鎖定為止。有關可序列化和可延遲交易的更多資訊，請參閱第 13.2.3 節。頻繁呼叫此函數可能會對資料庫效能產生一些影響，因為它需要在短時間內存取謂詞鎖定管理器的共享狀態。
`pg_trigger_depth` () → `integer` 傳回 PostgreSQL 觸發程序的目前巢狀層級 (如果不是直接或間接從觸發程序內部呼叫，則為 0)。
`session_user` → `name` 傳回連線使用者的名稱。
`system_user` → `text` 傳回使用者在被分配資料庫角色之前，在驗證週期中提供的驗證方法和身份（如果有的話）。它表示為 `auth_method:identity`，如果使用者未通過驗證（例如，如果使用了信任驗證），則表示為 `NULL`。
`user` → `name` 這等同於 `current_user`。

函數

描述

current_catalog → name

current_database () → name

傳回目前資料庫的名稱。（在 SQL 標準中，資料庫稱為「目錄」，因此 current_catalog 是標準的拼寫。）

current_query () → text

傳回目前正在執行的查詢的文字，由用戶端提交（可能包含多個陳述式）。

current_role → name

這等同於 current_user。

current_schema → name

current_schema () → name

傳回搜尋路徑中第一個結構描述的名稱（如果搜尋路徑為空，則傳回空值）。這是將用於任何在未指定目標結構描述的情況下建立的資料表或其他具名物件的結構描述。

current_schemas ( include_implicit boolean ) → name[]

以優先順序傳回目前有效搜尋路徑中所有結構描述名稱的陣列。（目前的 search_path 設定中，不對應於現有、可搜尋結構描述的項目將被省略。）如果布林引數為 true，則隱式搜尋的系統結構描述（例如 pg_catalog）將包含在結果中。

current_user → name

傳回目前執行環境的使用者名稱。

inet_client_addr () → inet

傳回目前用戶端的 IP 位址，如果目前的連線是透過 Unix 網域 socket，則傳回 NULL。

inet_client_port () → integer

傳回目前用戶端的 IP 埠號，如果目前的連線是透過 Unix 網域 socket，則傳回 NULL。

inet_server_addr () → inet

傳回伺服器接受目前連線的 IP 位址，如果目前的連線是透過 Unix 網域 socket，則傳回 NULL。

inet_server_port () → integer

傳回伺服器接受目前連線的 IP 連接埠號碼，如果目前連線是透過 Unix 網域 Socket，則傳回 NULL。

pg_backend_pid () → integer

傳回附加到目前連線的伺服器進程 ID。

pg_blocking_pids ( integer ) → integer[]

傳回一個陣列，其中包含因無法取得鎖定而阻擋具有指定進程 ID 的伺服器進程的連線之進程 ID。如果沒有此伺服器進程或未被阻擋，則傳回一個空陣列。

如果一個伺服器進程持有與被阻擋進程的鎖定請求衝突的鎖定（硬阻擋），或者正在等待與被阻擋進程的鎖定請求衝突的鎖定，並且在等待佇列中排在其前面（軟阻擋），則會阻擋另一個伺服器進程。當使用並行查詢時，結果總是列出客戶端可見的進程 ID（也就是 pg_backend_pid 的結果），即使實際的鎖定是由子工作進程持有或等待。因此，結果中可能會有重複的 PID。另請注意，當預備交易持有衝突鎖定時，將以零進程 ID 表示。

頻繁呼叫此函數可能會對資料庫效能產生一些影響，因為它需要在短時間內獨佔存取鎖定管理器的共享狀態。

pg_conf_load_time () → timestamp with time zone

傳回上次載入伺服器組態檔案的時間。如果目前的連線在該時間存在，這將是連線本身重新讀取組態檔案的時間（因此，不同連線的讀取時間會略有不同）。否則，這是 postmaster 進程重新讀取組態檔案的時間。

pg_current_logfile ( [ text ] ) → text

傳回日誌收集器目前使用的日誌檔的路徑名稱。該路徑包括 log_directory 目錄和個別日誌檔名。如果已停用日誌收集器，則結果為 NULL。如果存在多個日誌檔案，每個檔案的格式不同，則沒有參數的 pg_current_logfile 會傳回檔案路徑，該檔案具有在排序清單中找到的第一個格式：stderr、csvlog、jsonlog。如果沒有任何日誌檔案具有這些格式，則會傳回 NULL。若要請求有關特定日誌檔案格式的資訊，請提供 csvlog、jsonlog 或 stderr 作為可選參數的值。如果在 log_destination 中未配置請求的日誌格式，則結果為 NULL。結果反映了 current_logfiles 檔案的內容。

預設情況下，此函數僅限於超級使用者和具有 pg_monitor 角色權限的角色，但可以授予其他使用者 EXECUTE 權限來執行該函數。

pg_my_temp_schema () → oid

傳回目前連線的暫時 Schema 的 OID，如果沒有（因為尚未建立任何暫時資料表），則傳回零。

pg_is_other_temp_schema ( oid ) → boolean

如果給定的 OID 是另一個連線的暫時 Schema 的 OID，則傳回 true。（例如，這可用於從目錄顯示中排除其他連線的暫時資料表。）

pg_jit_available () → boolean

如果JIT編譯器擴充功能可用（請參閱第 30 章）並且 jit 組態參數設定為 on，則傳回 true。

pg_listening_channels () → setof text

傳回目前連線正在監聽的非同步通知通道名稱的集合。

pg_notification_queue_usage () → double precision

傳回目前被等待處理的通知佔用的非同步通知佇列最大大小的分數 (0–1)。有關更多資訊，請參閱 LISTEN 和 NOTIFY。

pg_postmaster_start_time () → timestamp with time zone

傳回伺服器啟動的時間。

pg_safe_snapshot_blocking_pids ( integer ) → integer[]

傳回一個陣列，其中包含因無法取得安全快照而阻擋具有指定進程 ID 的伺服器進程的連線之進程 ID。如果沒有此伺服器進程或未被阻擋，則傳回一個空陣列。

執行 SERIALIZABLE 交易的連線會阻擋 SERIALIZABLE READ ONLY DEFERRABLE 交易取得快照，直到後者確定可以安全地避免取得任何謂詞鎖定為止。有關可序列化和可延遲交易的更多資訊，請參閱第 13.2.3 節。

頻繁呼叫此函數可能會對資料庫效能產生一些影響，因為它需要在短時間內存取謂詞鎖定管理器的共享狀態。

pg_trigger_depth () → integer

傳回 PostgreSQL 觸發程序的目前巢狀層級 (如果不是直接或間接從觸發程序內部呼叫，則為 0)。

session_user → name

傳回連線使用者的名稱。

system_user → text

傳回使用者在被分配資料庫角色之前，在驗證週期中提供的驗證方法和身份（如果有的話）。它表示為 auth_method:identity，如果使用者未通過驗證（例如，如果使用了信任驗證），則表示為 NULL。

user → name

這等同於 current_user。

注意

current_catalog、current_role、current_schema、current_user、session_user 和 user 在SQL中具有特殊的語法狀態：它們必須在沒有尾隨括號的情況下呼叫。在 PostgreSQL 中，可以選擇性地與 current_schema 一起使用括號，但不能與其他括號一起使用。

session_user 通常是啟動目前資料庫連線的使用者；但超級使用者可以使用SET SESSION AUTHORIZATION來變更此設定。current_user 則是適用於權限檢查的使用者識別符。通常它與 session user 相同，但可以使用SET ROLE來變更。它也會在使用具有 SECURITY DEFINER 屬性的函數執行期間發生變更。在 Unix 術語中，session user 是「真實使用者 (real user)」，而 current user 是「有效使用者 (effective user)」。current_role 和 user 是 current_user 的同義詞。（SQL 標準區分了 current_role 和 current_user，但 PostgreSQL 沒有區分，因為它將使用者和角色統一為單一類型的實體。）

9.27.2. 存取權限查詢函數 #

表 9.70 列出了允許以程式方式查詢物件存取權限的函數。（有關權限的更多資訊，請參閱第 5.8 節。）在這些函數中，可以透過名稱或 OID (pg_authid.oid) 指定要查詢其權限的使用者，如果名稱給定為 public，則會檢查 PUBLIC 偽角色的權限。此外，user 參數可以完全省略，在這種情況下，會假定為 current_user。要查詢的物件也可以透過名稱或 OID 來指定。以名稱指定時，如果相關，則可以包含綱要名稱。感興趣的存取權限由文字字串指定，該字串必須評估為物件類型的適當權限關鍵字之一（例如，SELECT）。或者，可以在權限類型中新增 WITH GRANT OPTION，以測試是否持有具有授權選項的權限。此外，可以列出多個以逗號分隔的權限類型，在這種情況下，如果持有任何列出的權限，則結果將為 true。（權限字串的大小寫並不重要，並且允許在權限名稱之間但不在權限名稱內使用額外的空白。）一些範例：

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

表 9.70. 存取權限查詢函數

函數描述
`has_any_column_privilege` ( [ `user` `name` 或 `oid`, ] `table` `text` 或 `oid`, `privilege` `text` ) → `boolean` 使用者是否對表格的任何欄位具有權限？如果對整個表格持有權限，或者如果至少有一個欄位具有欄位層級的權限授予，則此函數成功。允許的權限類型為 `SELECT`、`INSERT`、`UPDATE` 和 `REFERENCES`。
`has_column_privilege` ( [ `user` `name` 或 `oid`, ] `table` `text` 或 `oid`, `column` `text` 或 `smallint`, `privilege` `text` ) → `boolean` 使用者是否對指定的表格欄位具有權限？如果對整個表格持有權限，或者如果該欄位具有欄位層級的權限授予，則此函數成功。可以依名稱或屬性編號 (`pg_attribute`.`attnum`) 指定欄位。允許的權限類型為 `SELECT`、`INSERT`、`UPDATE` 和 `REFERENCES`。
`has_database_privilege` ( [ `user` `name` 或 `oid`, ] `database` `text` 或 `oid`, `privilege` `text` ) → `boolean` 使用者是否對資料庫具有權限？允許的權限類型為 `CREATE`、`CONNECT`、`TEMPORARY` 和 `TEMP`（與 `TEMPORARY` 等效）。
`has_foreign_data_wrapper_privilege` ( [ `user` `name` 或 `oid`, ] `fdw` `text` 或 `oid`, `privilege` `text` ) → `boolean` 使用者是否對外部資料包裝器具有權限？唯一允許的權限類型為 `USAGE`。
`has_function_privilege` ( [ `user` `name` 或 `oid`, ] `function` `text` 或 `oid`, `privilege` `text` ) → `boolean` 使用者是否對函數具有權限？唯一允許的權限類型為 `EXECUTE`。以名稱而非 OID 指定函數時，允許的輸入與 `regprocedure` 資料類型相同（請參閱第 8.19 節）。一個例子是： SELECT has_function_privilege('joeuser', 'myfunc(int, text)', 'execute');
`has_language_privilege` ( [ `user` `name` 或 `oid`, ] `language` `text` 或 `oid`, `privilege` `text` ) → `boolean` 使用者是否對語言具有權限？唯一允許的權限類型為 `USAGE`。
`has_parameter_privilege` ( [ `user` `name` 或 `oid`, ] `parameter` `text`, `privilege` `text` ) → `boolean` 使用者是否對組態參數具有權限？參數名稱不區分大小寫。允許的權限類型為 `SET` 和 `ALTER SYSTEM`。
`has_schema_privilege` ( [ `user` `name` 或 `oid`, ] `schema` `text` 或 `oid`, `privilege` `text` ) → `boolean` 使用者是否具有 schema 的權限？允許的權限類型為 `CREATE` 和 `USAGE`。
`has_sequence_privilege` ( [ `user` `name` 或 `oid`, ] `sequence` `text` 或 `oid`, `privilege` `text` ) → `boolean` 使用者是否具有 sequence 的權限？允許的權限類型為 `USAGE`、`SELECT` 和 `UPDATE`。
`has_server_privilege` ( [ `user` `name` 或 `oid`, ] `server` `text` 或 `oid`, `privilege` `text` ) → `boolean` 使用者是否具有外部伺服器的權限？唯一允許的權限類型為 `USAGE`。
`has_table_privilege` ( [ `user` `name` 或 `oid`, ] `table` `text` 或 `oid`, `privilege` `text` ) → `boolean` 使用者是否具有 table 的權限？允許的權限類型為 `SELECT`、`INSERT`、`UPDATE`、`DELETE`、`TRUNCATE`、`REFERENCES`、`TRIGGER` 和 `MAINTAIN`。
`has_tablespace_privilege` ( [ `user` `name` 或 `oid`, ] `tablespace` `text` 或 `oid`, `privilege` `text` ) → `boolean` 使用者是否具有 tablespace 的權限？唯一允許的權限類型為 `CREATE`。
`has_type_privilege` ( [ `user` `name` 或 `oid`, ] `type` `text` 或 `oid`, `privilege` `text` ) → `boolean` 使用者是否具有 data type 的權限？唯一允許的權限類型為 `USAGE`。當依名稱而非 OID 指定 type 時，允許的輸入與 `regtype` 資料類型相同（請參閱第 8.19 節）。
`pg_has_role` ( [ `user` `name` 或 `oid`, ] `role` `text` 或 `oid`, `privilege` `text` ) → `boolean` 使用者是否具有 role 的權限？允許的權限類型為 `MEMBER`、`USAGE` 和 `SET`。`MEMBER` 表示直接或間接屬於該 role，而無需考慮可能授予的特定權限。`USAGE` 表示是否可以直接使用該 role 的權限而無需執行 `SET ROLE`，而 `SET` 表示是否可以使用 `SET ROLE` 命令變更為該 role。可以將 `WITH ADMIN OPTION` 或 `WITH GRANT OPTION` 新增到任何這些權限類型，以測試是否持有 `ADMIN` 權限（所有六種拼字方式都測試相同的事情）。此函數不允許將 `user` 設定為 `public` 的特殊情況，因為 PUBLIC 偽角色永遠不可能是真實 role 的成員。
`row_security_active` ( `table` `text` 或 `oid` ) → `boolean` 在目前使用者和目前環境的上下文中，是否為指定的 table 啟用 row-level security？

函數

描述

has_any_column_privilege ( [ user name 或 oid, ] table text 或 oid, privilege text ) → boolean

使用者是否對表格的任何欄位具有權限？如果對整個表格持有權限，或者如果至少有一個欄位具有欄位層級的權限授予，則此函數成功。允許的權限類型為 SELECT、INSERT、UPDATE 和 REFERENCES。

has_column_privilege ( [ user name 或 oid, ] table text 或 oid, column text 或 smallint, privilege text ) → boolean

使用者是否對指定的表格欄位具有權限？如果對整個表格持有權限，或者如果該欄位具有欄位層級的權限授予，則此函數成功。可以依名稱或屬性編號 (pg_attribute.attnum) 指定欄位。允許的權限類型為 SELECT、INSERT、UPDATE 和 REFERENCES。

has_database_privilege ( [ user name 或 oid, ] database text 或 oid, privilege text ) → boolean

使用者是否對資料庫具有權限？允許的權限類型為 CREATE、CONNECT、TEMPORARY 和 TEMP（與 TEMPORARY 等效）。

has_foreign_data_wrapper_privilege ( [ user name 或 oid, ] fdw text 或 oid, privilege text ) → boolean

使用者是否對外部資料包裝器具有權限？唯一允許的權限類型為 USAGE。

has_function_privilege ( [ user name 或 oid, ] function text 或 oid, privilege text ) → boolean

使用者是否對函數具有權限？唯一允許的權限類型為 EXECUTE。

以名稱而非 OID 指定函數時，允許的輸入與 regprocedure 資料類型相同（請參閱第 8.19 節）。一個例子是：

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

has_language_privilege ( [ user name 或 oid, ] language text 或 oid, privilege text ) → boolean

使用者是否對語言具有權限？唯一允許的權限類型為 USAGE。

has_parameter_privilege ( [ user name 或 oid, ] parameter text, privilege text ) → boolean

使用者是否對組態參數具有權限？參數名稱不區分大小寫。允許的權限類型為 SET 和 ALTER SYSTEM。

has_schema_privilege ( [ user name 或 oid, ] schema text 或 oid, privilege text ) → boolean

使用者是否具有 schema 的權限？允許的權限類型為 CREATE 和 USAGE。

has_sequence_privilege ( [ user name 或 oid, ] sequence text 或 oid, privilege text ) → boolean

使用者是否具有 sequence 的權限？允許的權限類型為 USAGE、SELECT 和 UPDATE。

has_server_privilege ( [ user name 或 oid, ] server text 或 oid, privilege text ) → boolean

使用者是否具有外部伺服器的權限？唯一允許的權限類型為 USAGE。

has_table_privilege ( [ user name 或 oid, ] table text 或 oid, privilege text ) → boolean

使用者是否具有 table 的權限？允許的權限類型為 SELECT、INSERT、UPDATE、DELETE、TRUNCATE、REFERENCES、TRIGGER 和 MAINTAIN。

has_tablespace_privilege ( [ user name 或 oid, ] tablespace text 或 oid, privilege text ) → boolean

使用者是否具有 tablespace 的權限？唯一允許的權限類型為 CREATE。

has_type_privilege ( [ user name 或 oid, ] type text 或 oid, privilege text ) → boolean

使用者是否具有 data type 的權限？唯一允許的權限類型為 USAGE。當依名稱而非 OID 指定 type 時，允許的輸入與 regtype 資料類型相同（請參閱第 8.19 節）。

pg_has_role ( [ user name 或 oid, ] role text 或 oid, privilege text ) → boolean

使用者是否具有 role 的權限？允許的權限類型為 MEMBER、USAGE 和 SET。MEMBER 表示直接或間接屬於該 role，而無需考慮可能授予的特定權限。USAGE 表示是否可以直接使用該 role 的權限而無需執行 SET ROLE，而 SET 表示是否可以使用 SET ROLE 命令變更為該 role。可以將 WITH ADMIN OPTION 或 WITH GRANT OPTION 新增到任何這些權限類型，以測試是否持有 ADMIN 權限（所有六種拼字方式都測試相同的事情）。此函數不允許將 user 設定為 public 的特殊情況，因為 PUBLIC 偽角色永遠不可能是真實 role 的成員。

row_security_active ( table text 或 oid ) → boolean

在目前使用者和目前環境的上下文中，是否為指定的 table 啟用 row-level security？

表 9.71 顯示 aclitem 類型的可用運算子，它是存取權限的目錄表示。有關如何讀取存取權限值的資訊，請參閱第 5.8 節。

表 9.71. aclitem 運算子

運算子描述範例
`aclitem` `=` `aclitem` → `boolean` `aclitem` 是否相等？（請注意，`aclitem` 類型缺少通常的比較運算子集；它只有相等性。反過來，只能比較 `aclitem` 陣列是否相等。） `'calvin=rw/hobbes'::aclitem = 'calvin=rw*/hobbes'::aclitem` → `f`
`aclitem[]` `@>` `aclitem` → `boolean` 陣列是否包含指定的權限？（如果有一個陣列項目符合 `aclitem` 的 grantee 和 grantor，並且至少具有指定的權限集，則此為 true。） `'{calvin=rw/hobbes,hobbes=rw/postgres}'::aclitem[] @> 'calvin=r/hobbes'::aclitem` → `t`
`aclitem[]` `~` `aclitem` → `boolean` 這是 `@>` 的已棄用別名。 `'{calvin=rw/hobbes,hobbes=rw/postgres}'::aclitem[] ~ 'calvin=r/hobbes'::aclitem` → `t`

運算子

描述

範例

aclitem = aclitem → boolean

aclitem 是否相等？（請注意，aclitem 類型缺少通常的比較運算子集；它只有相等性。反過來，只能比較 aclitem 陣列是否相等。）

'calvin=r*w/hobbes'::aclitem = 'calvin=r*w*/hobbes'::aclitem → f

aclitem[] @> aclitem → boolean

陣列是否包含指定的權限？（如果有一個陣列項目符合 aclitem 的 grantee 和 grantor，並且至少具有指定的權限集，則此為 true。）

'{calvin=r*w/hobbes,hobbes=r*w*/postgres}'::aclitem[] @> 'calvin=r*/hobbes'::aclitem → t

aclitem[] ~ aclitem → boolean

這是 @> 的已棄用別名。

'{calvin=r*w/hobbes,hobbes=r*w*/postgres}'::aclitem[] ~ 'calvin=r*/hobbes'::aclitem → t

表 9.72 顯示一些其他函數來管理 aclitem 類型。

表 9.72. aclitem 函數

函數描述
`acldefault` ( `type` `"char"`, `ownerId` `oid` ) → `aclitem[]` 建構一個 `aclitem` 陣列，其中包含屬於 OID 為 `ownerId` 的 role 的 `type` 類型物件的預設存取權限。這表示當物件的 ACL 條目為 null 時將假設的存取權限。（預設存取權限在第 5.8 節中描述。）`type` 參數必須是 'c'（表示 `COLUMN`）、'r'（表示 `TABLE` 和類似 table 的物件）、's'（表示 `SEQUENCE`）、'd'（表示 `DATABASE`）、'f'（表示 `FUNCTION` 或 `PROCEDURE`）、'l'（表示 `LANGUAGE`）、'L'（表示 `LARGE OBJECT`）、'n'（表示 `SCHEMA`）、'p'（表示 `PARAMETER`）、't'（表示 `TABLESPACE`）、'F'（表示 `FOREIGN DATA WRAPPER`）、'S'（表示 `FOREIGN SERVER`）或 'T'（表示 `TYPE` 或 `DOMAIN`）之一。
`aclexplode` ( `aclitem[]` ) → `setof record` ( `grantor` `oid`, `grantee` `oid`, `privilege_type` `text`, `is_grantable` `boolean` ) 將 `aclitem` 陣列以一組列的方式傳回。如果被授權者是虛擬角色 PUBLIC，則在 `grantee` 欄位中會以零表示。每個授權的權限都以 `SELECT`、`INSERT` 等等表示（完整清單請參閱表 5.1）。請注意，每個權限都會分成一個獨立的列，因此在 `privilege_type` 欄位中只會出現一個關鍵字。
`makeaclitem` ( `grantee` `oid`, `grantor` `oid`, `privileges` `text`, `is_grantable` `boolean` ) → `aclitem` 使用給定的屬性建構一個 `aclitem`。`privileges` 是一個以逗號分隔的權限名稱清單，例如 `SELECT`、`INSERT` 等等，所有這些都會在結果中設定。（權限字串的大小寫並不重要，並且允許在權限名稱之間存在額外的空白，但不允許在權限名稱內部存在空白。）

函數

描述

acldefault ( type "char", ownerId oid ) → aclitem[]

建構一個 aclitem 陣列，其中包含屬於 OID 為 ownerId 的 role 的 type 類型物件的預設存取權限。這表示當物件的 ACL 條目為 null 時將假設的存取權限。（預設存取權限在第 5.8 節中描述。）type 參數必須是 'c'（表示 COLUMN）、'r'（表示 TABLE 和類似 table 的物件）、's'（表示 SEQUENCE）、'd'（表示 DATABASE）、'f'（表示 FUNCTION 或 PROCEDURE）、'l'（表示 LANGUAGE）、'L'（表示 LARGE OBJECT）、'n'（表示 SCHEMA）、'p'（表示 PARAMETER）、't'（表示 TABLESPACE）、'F'（表示 FOREIGN DATA WRAPPER）、'S'（表示 FOREIGN SERVER）或 'T'（表示 TYPE 或 DOMAIN）之一。

aclexplode ( aclitem[] ) → setof record ( grantor oid, grantee oid, privilege_type text, is_grantable boolean )

將 aclitem 陣列以一組列的方式傳回。如果被授權者是虛擬角色 PUBLIC，則在 grantee 欄位中會以零表示。每個授權的權限都以 SELECT、INSERT 等等表示（完整清單請參閱表 5.1）。請注意，每個權限都會分成一個獨立的列，因此在 privilege_type 欄位中只會出現一個關鍵字。

makeaclitem ( grantee oid, grantor oid, privileges text, is_grantable boolean ) → aclitem

使用給定的屬性建構一個 aclitem。privileges 是一個以逗號分隔的權限名稱清單，例如 SELECT、INSERT 等等，所有這些都會在結果中設定。（權限字串的大小寫並不重要，並且允許在權限名稱之間存在額外的空白，但不允許在權限名稱內部存在空白。）

9.27.3. Schema可見性查詢函數 #

表 9.73 顯示判斷特定物件在目前 schema 搜尋路徑中是否可見的函數。例如，如果一個 table 的 containing schema 在搜尋路徑中，並且在搜尋路徑中沒有較早出現相同名稱的 table，則該 table 被認為是可見的。這等同於聲明該 table 可以通過名稱引用，而無需顯式的 schema 限定詞。因此，要列出所有可見 table 的名稱

SELECT relname FROM pg_class WHERE pg_table_is_visible(oid);

對於函數和運算符，如果搜尋路徑中沒有相同名稱和參數資料類型的物件較早出現，則該物件被認為是可見的。對於運算符類別和系列，將同時考慮名稱和關聯的索引存取方法。

表 9.73. Schema可見性查詢函數

函數描述
`pg_collation_is_visible` ( `collation` `oid` ) → `boolean` 定序在搜尋路徑中是否可見？
`pg_conversion_is_visible` ( `conversion` `oid` ) → `boolean` 轉換在搜尋路徑中是否可見？
`pg_function_is_visible` ( `function` `oid` ) → `boolean` 函數在搜尋路徑中是否可見？（這也適用於程序和聚合。）
`pg_opclass_is_visible` ( `opclass` `oid` ) → `boolean` 運算符類別在搜尋路徑中是否可見？
`pg_operator_is_visible` ( `operator` `oid` ) → `boolean` 運算符在搜尋路徑中是否可見？
`pg_opfamily_is_visible` ( `opclass` `oid` ) → `boolean` 運算符系列在搜尋路徑中是否可見？
`pg_statistics_obj_is_visible` ( `stat` `oid` ) → `boolean` 統計物件在搜尋路徑中是否可見？
`pg_table_is_visible` ( `table` `oid` ) → `boolean` table 在搜尋路徑中是否可見？（這適用於所有類型的關聯，包括 view、實體化 view、索引、序列和外部 table。）
`pg_ts_config_is_visible` ( `config` `oid` ) → `boolean` 文字搜尋組態在搜尋路徑中是否可見？
`pg_ts_dict_is_visible` ( `dict` `oid` ) → `boolean` 文字搜尋字典在搜尋路徑中是否可見？
`pg_ts_parser_is_visible` ( `parser` `oid` ) → `boolean` 文字搜尋剖析器在搜尋路徑中是否可見？
`pg_ts_template_is_visible` ( `template` `oid` ) → `boolean` 文字搜尋模板在搜尋路徑中是否可見？
`pg_type_is_visible` ( `type` `oid` ) → `boolean` 類型（或網域）在搜尋路徑中是否可見？

函數

描述

pg_collation_is_visible ( collation oid ) → boolean

定序在搜尋路徑中是否可見？

pg_conversion_is_visible ( conversion oid ) → boolean

轉換在搜尋路徑中是否可見？

pg_function_is_visible ( function oid ) → boolean

函數在搜尋路徑中是否可見？（這也適用於程序和聚合。）

pg_opclass_is_visible ( opclass oid ) → boolean

運算符類別在搜尋路徑中是否可見？

pg_operator_is_visible ( operator oid ) → boolean

運算符在搜尋路徑中是否可見？

pg_opfamily_is_visible ( opclass oid ) → boolean

運算符系列在搜尋路徑中是否可見？

pg_statistics_obj_is_visible ( stat oid ) → boolean

統計物件在搜尋路徑中是否可見？

pg_table_is_visible ( table oid ) → boolean

table 在搜尋路徑中是否可見？（這適用於所有類型的關聯，包括 view、實體化 view、索引、序列和外部 table。）

pg_ts_config_is_visible ( config oid ) → boolean

文字搜尋組態在搜尋路徑中是否可見？

pg_ts_dict_is_visible ( dict oid ) → boolean

文字搜尋字典在搜尋路徑中是否可見？

pg_ts_parser_is_visible ( parser oid ) → boolean

文字搜尋剖析器在搜尋路徑中是否可見？

pg_ts_template_is_visible ( template oid ) → boolean

文字搜尋模板在搜尋路徑中是否可見？

pg_type_is_visible ( type oid ) → boolean

類型（或網域）在搜尋路徑中是否可見？

所有這些函數都需要物件 OID 來識別要檢查的物件。如果您想按名稱測試物件，使用 OID 別名類型（regclass、regtype、regprocedure、regoperator、regconfig 或 regdictionary）會很方便，例如

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

請注意，以這種方式測試非 schema 限定的類型名稱沒有多大意義——如果該名稱可以被識別，它一定是可見的。

9.27.4. 系統目錄資訊函數 #

表 9.74 列出從系統目錄中提取資訊的函數。

表 9.74. 系統目錄資訊函數

函數描述
`format_type` ( `type` `oid`, `typemod` `integer` ) → `text` 傳回由其類型 OID 和可能的類型修飾符標識的資料庫資料類型之 SQL 名稱。如果沒有特定的修飾符，則將 NULL 傳遞給類型修飾符。
`pg_basetype` ( `regtype` ) → `regtype` 傳回由其類型 OID 識別的網域之基本類型 OID。如果參數是非網域類型的 OID，則按原樣傳回參數。如果參數不是有效的類型 OID，則傳回 NULL。如果存在網域相依性的鏈，它將遞迴直到找到基本類型。假設 `CREATE DOMAIN mytext AS text` `pg_basetype('mytext'::regtype)` → `text`
`pg_char_to_encoding` ( `encoding` `name` ) → `integer` 將提供的編碼名稱轉換為一個整數，表示某些系統目錄 table 中使用的內部識別碼。如果提供了未知的編碼名稱，則傳回 `-1`。
`pg_encoding_to_char` ( `encoding` `integer` ) → `name` 將某些系統目錄表中所使用的編碼內部識別碼整數，轉換為人類可讀的字串。如果提供了無效的編碼數字，則返回空字串。
`pg_get_catalog_foreign_keys` () → `setof record` ( `fktable` `regclass`, `fkcols` `text[]`, `pktable` `regclass`, `pkcols` `text[]`, `is_array` `boolean`, `is_opt` `boolean` ) 傳回一組描述 PostgreSQL 系統目錄中存在之外鍵關係的記錄。`fktable` 欄位包含參考目錄的名稱，而 `fkcols` 欄位包含參考欄位的名稱。同樣地，`pktable` 欄位包含被參考目錄的名稱，而 `pkcols` 欄位包含被參考欄位的名稱。如果 `is_array` 為 true，則最後一個參考欄位是一個陣列，其每個元素都應與被參考目錄中的某個條目相符。如果 `is_opt` 為 true，則允許參考欄位包含零而不是有效的參考。
`pg_get_constraintdef` ( `constraint` `oid` [, `pretty` `boolean` ] ) → `text` 重建約束的建立指令。（這是反編譯重建，而不是指令的原始文字。）
`pg_get_expr` ( `expr` `pg_node_tree`, `relation` `oid` [, `pretty` `boolean` ] ) → `text` 反編譯儲存在系統目錄中的表達式的內部形式，例如欄位的預設值。如果表達式可能包含 Vars，請將它們引用的關係的 OID 指定為第二個參數；如果預期沒有 Vars，則傳遞零就足夠了。
`pg_get_functiondef` ( `func` `oid` ) → `text` 重建函式或程序的建立指令。（這是反編譯重建，而不是指令的原始文字。）結果是一個完整的 `CREATE OR REPLACE FUNCTION` 或 `CREATE OR REPLACE PROCEDURE` 陳述式。
`pg_get_function_arguments` ( `func` `oid` ) → `text` 重建函式或程序的引數列表，其形式與在 `CREATE FUNCTION` 中所需的形式相同（包括預設值）。
`pg_get_function_identity_arguments` ( `func` `oid` ) → `text` 重建識別函式或程序所需的引數列表，其形式與在 `ALTER FUNCTION` 等指令中所需的形式相同。這種形式省略了預設值。
`pg_get_function_result` ( `func` `oid` ) → `text` 重建函式的 `RETURNS` 子句，其形式與在 `CREATE FUNCTION` 中所需的形式相同。對於程序，返回 `NULL`。
`pg_get_indexdef` ( `index` `oid` [, `column` `integer`, `pretty` `boolean` ] ) → `text` 重建索引的建立指令。（這是反編譯重建，而不是指令的原始文字。）如果提供了 `column` 且不為零，則僅重建該欄位的定義。
`pg_get_keywords` () → `setof record` ( `word` `text`, `catcode` `"char"`, `barelabel` `boolean`, `catdesc` `text`, `baredesc` `text` ) 傳回一組描述伺服器識別之 SQL 關鍵字的記錄。`word` 欄位包含關鍵字。`catcode` 欄位包含類別代碼：`U` 代表未保留的關鍵字，`C` 代表可以是欄位名稱的關鍵字，`T` 代表可以是型別或函式名稱的關鍵字，或 `R` 代表完全保留的關鍵字。`barelabel` 欄位包含 `true`，如果關鍵字可以用作 `SELECT` 列表中的「裸」欄位標籤，或者包含 `false`，如果它只能在 `AS` 之後使用。`catdesc` 欄位包含描述關鍵字類別的可能已本地化的字串。`baredesc` 欄位包含描述關鍵字欄位標籤狀態的可能已本地化的字串。
`pg_get_partkeydef` ( `table` `oid` ) → `text` 重建分割資料表分割鍵的定義，其形式與 `CREATE TABLE` 的 `PARTITION BY` 子句中的形式相同。（這是反編譯重建，而不是指令的原始文字。）
`pg_get_ruledef` ( `rule` `oid` [, `pretty` `boolean` ] ) → `text` 重建規則的建立指令。（這是反編譯重建，而不是指令的原始文字。）
`pg_get_serial_sequence` ( `table` `text`, `column` `text` ) → `text` 傳回與欄位關聯的序列名稱，如果欄位未與任何序列關聯，則傳回 NULL。如果欄位是識別欄位，則關聯的序列是為該欄位內部建立的序列。對於使用其中一種序列類型（`serial`、`smallserial`、`bigserial`）建立的欄位，它是為該序列欄位定義建立的序列。在後一種情況下，可以使用 `ALTER SEQUENCE OWNED BY` 修改或移除關聯。（這個函數可能應該命名為 `pg_get_owned_sequence`；它目前的名稱反映了它歷史上一直與序列類型欄位一起使用。）第一個參數是帶有可選綱要的表名稱，第二個參數是欄位名稱。因為第一個參數可能同時包含綱要和表名稱，所以它會按照通常的 SQL 規則進行剖析，這意味著預設情況下它會轉換為小寫。第二個參數只是一個欄位名稱，會被視為字面值，因此會保留其大小寫。結果會被適當地格式化，以便傳遞給序列函數（請參閱第 9.17 節）。一個典型的用途是讀取識別欄位或序列欄位的序列的當前值，例如 SELECT currval(pg_get_serial_sequence('sometable', 'id'));
`pg_get_statisticsobjdef` ( `statobj` `oid` ) → `text` 重建擴充統計物件的建立命令。（這是一個反編譯的重建，而不是命令的原始文字。）
`pg_get_triggerdef` ( `trigger` `oid` [, `pretty` `boolean` ] ) → `text` 重建觸發器的建立命令。（這是一個反編譯的重建，而不是命令的原始文字。）
`pg_get_userbyid` ( `role` `oid` ) → `name` 根據角色 OID 傳回角色的名稱。
`pg_get_viewdef` ( `view` `oid` [, `pretty` `boolean` ] ) → `text` 重建視窗或具體化視窗的底層 `SELECT` 命令。（這是一個反編譯的重建，而不是命令的原始文字。）
`pg_get_viewdef` ( `view` `oid`, `wrap_column` `integer` ) → `text` 重建視窗或具體化視窗的底層 `SELECT` 命令。（這是一個反編譯的重建，而不是命令的原始文字。）在這種函數形式中，總是啟用美化列印，並且長行會被換行，以盡量保持它們短於指定的欄位數。
`pg_get_viewdef` ( `view` `text` [, `pretty` `boolean` ] ) → `text` 從視窗的文字名稱而不是其 OID 重建視窗或具體化視窗的底層 `SELECT` 命令。（這個函數已過時；請改用 OID 變體。）
`pg_index_column_has_property` ( `index` `regclass`, `column` `integer`, `property` `text` ) → `boolean` 測試索引欄位是否具有指定的屬性。常見的索引欄位屬性列在表格 9.75中。（請注意，擴充存取方法可以為其索引定義其他屬性名稱。）如果屬性名稱未知或不適用於特定物件，或者 OID 或欄位編號未識別有效的物件，則傳回 `NULL`。
`pg_index_has_property` ( `index` `regclass`, `property` `text` ) → `boolean` 測試索引是否具有指定的屬性。常見的索引屬性列在表格 9.76中。（請注意，擴充存取方法可以為其索引定義其他屬性名稱。）如果屬性名稱未知或不適用於特定物件，或者 OID 未識別有效的物件，則傳回 `NULL`。
`pg_indexam_has_property` ( `am` `oid`, `property` `text` ) → `boolean` 測試索引存取方法是否具有指定的屬性。存取方法屬性列在表格 9.77中。如果屬性名稱未知或不適用於特定物件，或者 OID 未識別有效的物件，則傳回 `NULL`。
`pg_options_to_table` ( `options_array` `text[]` ) → `setof record` ( `option_name` `text`, `option_value` `text` ) 傳回由 `pg_class`.`reloptions` 或 `pg_attribute`.`attoptions` 中的值表示的儲存選項集合。
`pg_settings_get_flags` ( `guc` `text` ) → `text[]` 傳回與給定 GUC 關聯的旗標陣列，如果該 GUC 不存在，則傳回 `NULL`。如果 GUC 存在但沒有要顯示的旗標，則結果是一個空陣列。只有表格 9.78中列出的最有用的旗標才會公開。
`pg_tablespace_databases` ( `tablespace` `oid` ) → `setof oid` 傳回具有儲存在指定表空間中的物件的資料庫的 OID 集合。如果此函數傳回任何列，則表示表空間不為空，無法卸除。若要識別填入表空間的特定物件，您需要連線到由 `pg_tablespace_databases` 識別的資料庫，並查詢其 `pg_class` 目錄。
`pg_tablespace_location` ( `tablespace` `oid` ) → `text` 傳回此表空間所在的檔案系統路徑。
`pg_typeof` ( `"any"` ) → `regtype` 傳回傳遞給它的值的資料類型 OID。這對於疑難排解或動態建構 SQL 查詢很有幫助。該函數宣告為傳回 `regtype`，它是一個 OID 別名類型（請參閱第 8.19 節）；這表示它在比較目的上與 OID 相同，但顯示為類型名稱。 `pg_typeof(33)` → `integer`
`COLLATION FOR` ( `"any"` ) → `text` 傳回傳遞給它的值的排序規則名稱。如有必要，該值會加上引號並限定綱要。如果沒有為引數表達式衍生出排序規則，則傳回 `NULL`。如果引數不是可排序的資料類型，則會引發錯誤。 `collation for ('foo'::text)` → `"default"` `collation for ('foo' COLLATE "de_DE")` → `"de_DE"`
`to_regclass` ( `text` ) → `regclass` 將文字關係名稱轉換為其 OID。將字串轉換為 `regclass` 類型會得到類似的結果（請參閱第 8.19 節）；但是，如果找不到名稱，此函數會傳回 `NULL`，而不是拋出錯誤。
`to_regcollation` ( `text` ) → `regcollation` 將文字排序規則名稱轉換為其 OID。將字串轉換為 `regcollation` 類型會得到類似的結果（請參閱第 8.19 節）；但是，如果找不到名稱，此函數會傳回 `NULL`，而不是拋出錯誤。
`to_regnamespace` ( `text` ) → `regnamespace` 將文字綱要名稱轉換為其 OID。將字串轉換為 `regnamespace` 類型會得到類似的結果（請參閱第 8.19 節）；但是，如果找不到名稱，此函數會傳回 `NULL`，而不是拋出錯誤。
`to_regoper` ( `text` ) → `regoper` 將文字運算子名稱轉換為其 OID。將字串轉換為 `regoper` 類型會得到類似的結果（請參閱第 8.19 節）；但是，如果找不到名稱或不明確，此函數會傳回 `NULL`，而不是拋出錯誤。
`to_regoperator` ( `text` ) → `regoperator` 將文字運算子名稱（帶有參數類型）轉換為其 OID。將字串轉換為 `regoperator` 類型會得到類似的結果（請參閱第 8.19 節）；但是，如果找不到名稱，此函數會傳回 `NULL`，而不是拋出錯誤。
`to_regproc` ( `text` ) → `regproc` 將文字函數或程序名稱轉換為其 OID。將字串轉換為 `regproc` 類型會得到類似的結果（請參閱第 8.19 節）；但是，如果找不到名稱或不明確，此函數會傳回 `NULL`，而不是拋出錯誤。
`to_regprocedure` ( `text` ) → `regprocedure` 將文字函數或程序名稱（帶有引數類型）轉換為其 OID。將字串轉換為 `regprocedure` 類型會得到類似的結果（請參閱第 8.19 節）；但是，如果找不到名稱，此函數會傳回 `NULL`，而不是拋出錯誤。
`to_regrole` ( `text` ) → `regrole` 將文字角色名稱轉換為其 OID。將字串轉換為 `regrole` 類型會得到類似的結果（請參閱第 8.19 節）；但是，如果找不到名稱，此函數會傳回 `NULL`，而不是拋出錯誤。
`to_regtype` ( `text` ) → `regtype` 剖析文字字串，從中提取可能的類型名稱，然後將該名稱轉換為類型 OID。字串中的語法錯誤將導致錯誤；但是，如果該字串是語法上有效的類型名稱，但恰好在目錄中找不到，則結果為 `NULL`。將字串轉換為 `regtype` 類型會得到類似的結果（請參閱第 8.19 節），但如果找不到名稱，則會拋出錯誤。
`to_regtypemod` ( `text` ) → `integer` 剖析文字字串，從中提取可能的類型名稱，然後轉換其類型修飾詞（如果有的話）。字串中的語法錯誤將導致錯誤；但是，如果該字串是語法上有效的類型名稱，但恰好在目錄中找不到，則結果為 `NULL`。如果沒有類型修飾詞，則結果為 `-1`。 `to_regtypemod` 可以與 to_regtype 結合使用，以產生 format_type 的適當輸入，從而允許將表示類型名稱的字串規範化。 `format_type(to_regtype('varchar(32)'), to_regtypemod('varchar(32)'))` → `character varying(32)`

函數

描述

format_type ( type oid, typemod integer ) → text

傳回由其類型 OID 和可能的類型修飾符標識的資料庫資料類型之 SQL 名稱。如果沒有特定的修飾符，則將 NULL 傳遞給類型修飾符。

pg_basetype ( regtype ) → regtype

傳回由其類型 OID 識別的網域之基本類型 OID。如果參數是非網域類型的 OID，則按原樣傳回參數。如果參數不是有效的類型 OID，則傳回 NULL。如果存在網域相依性的鏈，它將遞迴直到找到基本類型。

假設 CREATE DOMAIN mytext AS text

pg_basetype('mytext'::regtype) → text

pg_char_to_encoding ( encoding name ) → integer

將提供的編碼名稱轉換為一個整數，表示某些系統目錄 table 中使用的內部識別碼。如果提供了未知的編碼名稱，則傳回 -1。

pg_encoding_to_char ( encoding integer ) → name

將某些系統目錄表中所使用的編碼內部識別碼整數，轉換為人類可讀的字串。如果提供了無效的編碼數字，則返回空字串。

pg_get_catalog_foreign_keys () → setof record ( fktable regclass, fkcols text[], pktable regclass, pkcols text[], is_array boolean, is_opt boolean )

傳回一組描述 PostgreSQL 系統目錄中存在之外鍵關係的記錄。fktable 欄位包含參考目錄的名稱，而 fkcols 欄位包含參考欄位的名稱。同樣地，pktable 欄位包含被參考目錄的名稱，而 pkcols 欄位包含被參考欄位的名稱。如果 is_array 為 true，則最後一個參考欄位是一個陣列，其每個元素都應與被參考目錄中的某個條目相符。如果 is_opt 為 true，則允許參考欄位包含零而不是有效的參考。

pg_get_constraintdef ( constraint oid [, pretty boolean ] ) → text

重建約束的建立指令。（這是反編譯重建，而不是指令的原始文字。）

pg_get_expr ( expr pg_node_tree, relation oid [, pretty boolean ] ) → text

反編譯儲存在系統目錄中的表達式的內部形式，例如欄位的預設值。如果表達式可能包含 Vars，請將它們引用的關係的 OID 指定為第二個參數；如果預期沒有 Vars，則傳遞零就足夠了。

pg_get_functiondef ( func oid ) → text

重建函式或程序的建立指令。（這是反編譯重建，而不是指令的原始文字。）結果是一個完整的 CREATE OR REPLACE FUNCTION 或 CREATE OR REPLACE PROCEDURE 陳述式。

pg_get_function_arguments ( func oid ) → text

重建函式或程序的引數列表，其形式與在 CREATE FUNCTION 中所需的形式相同（包括預設值）。

pg_get_function_identity_arguments ( func oid ) → text

重建識別函式或程序所需的引數列表，其形式與在 ALTER FUNCTION 等指令中所需的形式相同。這種形式省略了預設值。

pg_get_function_result ( func oid ) → text

重建函式的 RETURNS 子句，其形式與在 CREATE FUNCTION 中所需的形式相同。對於程序，返回 NULL。

pg_get_indexdef ( index oid [, column integer, pretty boolean ] ) → text

重建索引的建立指令。（這是反編譯重建，而不是指令的原始文字。）如果提供了 column 且不為零，則僅重建該欄位的定義。

pg_get_keywords () → setof record ( word text, catcode "char", barelabel boolean, catdesc text, baredesc text )

傳回一組描述伺服器識別之 SQL 關鍵字的記錄。word 欄位包含關鍵字。catcode 欄位包含類別代碼：U 代表未保留的關鍵字，C 代表可以是欄位名稱的關鍵字，T 代表可以是型別或函式名稱的關鍵字，或 R 代表完全保留的關鍵字。barelabel 欄位包含 true，如果關鍵字可以用作 SELECT 列表中的「裸」欄位標籤，或者包含 false，如果它只能在 AS 之後使用。catdesc 欄位包含描述關鍵字類別的可能已本地化的字串。baredesc 欄位包含描述關鍵字欄位標籤狀態的可能已本地化的字串。

pg_get_partkeydef ( table oid ) → text

重建分割資料表分割鍵的定義，其形式與 CREATE TABLE 的 PARTITION BY 子句中的形式相同。（這是反編譯重建，而不是指令的原始文字。）

pg_get_ruledef ( rule oid [, pretty boolean ] ) → text

重建規則的建立指令。（這是反編譯重建，而不是指令的原始文字。）

pg_get_serial_sequence ( table text, column text ) → text

傳回與欄位關聯的序列名稱，如果欄位未與任何序列關聯，則傳回 NULL。如果欄位是識別欄位，則關聯的序列是為該欄位內部建立的序列。對於使用其中一種序列類型（serial、smallserial、bigserial）建立的欄位，它是為該序列欄位定義建立的序列。在後一種情況下，可以使用 ALTER SEQUENCE OWNED BY 修改或移除關聯。（這個函數可能應該命名為 pg_get_owned_sequence；它目前的名稱反映了它歷史上一直與序列類型欄位一起使用。）第一個參數是帶有可選綱要的表名稱，第二個參數是欄位名稱。因為第一個參數可能同時包含綱要和表名稱，所以它會按照通常的 SQL 規則進行剖析，這意味著預設情況下它會轉換為小寫。第二個參數只是一個欄位名稱，會被視為字面值，因此會保留其大小寫。結果會被適當地格式化，以便傳遞給序列函數（請參閱第 9.17 節）。

一個典型的用途是讀取識別欄位或序列欄位的序列的當前值，例如

SELECT currval(pg_get_serial_sequence('sometable', 'id'));

pg_get_statisticsobjdef ( statobj oid ) → text

重建擴充統計物件的建立命令。（這是一個反編譯的重建，而不是命令的原始文字。）

pg_get_triggerdef ( trigger oid [, pretty boolean ] ) → text

重建觸發器的建立命令。（這是一個反編譯的重建，而不是命令的原始文字。）

pg_get_userbyid ( role oid ) → name

根據角色 OID 傳回角色的名稱。

pg_get_viewdef ( view oid [, pretty boolean ] ) → text

重建視窗或具體化視窗的底層 SELECT 命令。（這是一個反編譯的重建，而不是命令的原始文字。）

pg_get_viewdef ( view oid, wrap_column integer ) → text

重建視窗或具體化視窗的底層 SELECT 命令。（這是一個反編譯的重建，而不是命令的原始文字。）在這種函數形式中，總是啟用美化列印，並且長行會被換行，以盡量保持它們短於指定的欄位數。

pg_get_viewdef ( view text [, pretty boolean ] ) → text

從視窗的文字名稱而不是其 OID 重建視窗或具體化視窗的底層 SELECT 命令。（這個函數已過時；請改用 OID 變體。）

pg_index_column_has_property ( index regclass, column integer, property text ) → boolean

測試索引欄位是否具有指定的屬性。常見的索引欄位屬性列在表格 9.75中。（請注意，擴充存取方法可以為其索引定義其他屬性名稱。）如果屬性名稱未知或不適用於特定物件，或者 OID 或欄位編號未識別有效的物件，則傳回 NULL。

pg_index_has_property ( index regclass, property text ) → boolean

測試索引是否具有指定的屬性。常見的索引屬性列在表格 9.76中。（請注意，擴充存取方法可以為其索引定義其他屬性名稱。）如果屬性名稱未知或不適用於特定物件，或者 OID 未識別有效的物件，則傳回 NULL。

pg_indexam_has_property ( am oid, property text ) → boolean

測試索引存取方法是否具有指定的屬性。存取方法屬性列在表格 9.77中。如果屬性名稱未知或不適用於特定物件，或者 OID 未識別有效的物件，則傳回 NULL。

pg_options_to_table ( options_array text[] ) → setof record ( option_name text, option_value text )

傳回由 pg_class.reloptions 或 pg_attribute.attoptions 中的值表示的儲存選項集合。

pg_settings_get_flags ( guc text ) → text[]

傳回與給定 GUC 關聯的旗標陣列，如果該 GUC 不存在，則傳回 NULL。如果 GUC 存在但沒有要顯示的旗標，則結果是一個空陣列。只有表格 9.78中列出的最有用的旗標才會公開。

pg_tablespace_databases ( tablespace oid ) → setof oid

傳回具有儲存在指定表空間中的物件的資料庫的 OID 集合。如果此函數傳回任何列，則表示表空間不為空，無法卸除。若要識別填入表空間的特定物件，您需要連線到由 pg_tablespace_databases 識別的資料庫，並查詢其 pg_class 目錄。

pg_tablespace_location ( tablespace oid ) → text

傳回此表空間所在的檔案系統路徑。

pg_typeof ( "any" ) → regtype

傳回傳遞給它的值的資料類型 OID。這對於疑難排解或動態建構 SQL 查詢很有幫助。該函數宣告為傳回 regtype，它是一個 OID 別名類型（請參閱第 8.19 節）；這表示它在比較目的上與 OID 相同，但顯示為類型名稱。

pg_typeof(33) → integer

COLLATION FOR ( "any" ) → text

傳回傳遞給它的值的排序規則名稱。如有必要，該值會加上引號並限定綱要。如果沒有為引數表達式衍生出排序規則，則傳回 NULL。如果引數不是可排序的資料類型，則會引發錯誤。

collation for ('foo'::text) → "default"

collation for ('foo' COLLATE "de_DE") → "de_DE"

to_regclass ( text ) → regclass

將文字關係名稱轉換為其 OID。將字串轉換為 regclass 類型會得到類似的結果（請參閱第 8.19 節）；但是，如果找不到名稱，此函數會傳回 NULL，而不是拋出錯誤。

to_regcollation ( text ) → regcollation

將文字排序規則名稱轉換為其 OID。將字串轉換為 regcollation 類型會得到類似的結果（請參閱第 8.19 節）；但是，如果找不到名稱，此函數會傳回 NULL，而不是拋出錯誤。

to_regnamespace ( text ) → regnamespace

將文字綱要名稱轉換為其 OID。將字串轉換為 regnamespace 類型會得到類似的結果（請參閱第 8.19 節）；但是，如果找不到名稱，此函數會傳回 NULL，而不是拋出錯誤。

to_regoper ( text ) → regoper

將文字運算子名稱轉換為其 OID。將字串轉換為 regoper 類型會得到類似的結果（請參閱第 8.19 節）；但是，如果找不到名稱或不明確，此函數會傳回 NULL，而不是拋出錯誤。

to_regoperator ( text ) → regoperator

將文字運算子名稱（帶有參數類型）轉換為其 OID。將字串轉換為 regoperator 類型會得到類似的結果（請參閱第 8.19 節）；但是，如果找不到名稱，此函數會傳回 NULL，而不是拋出錯誤。

to_regproc ( text ) → regproc

將文字函數或程序名稱轉換為其 OID。將字串轉換為 regproc 類型會得到類似的結果（請參閱第 8.19 節）；但是，如果找不到名稱或不明確，此函數會傳回 NULL，而不是拋出錯誤。

to_regprocedure ( text ) → regprocedure

將文字函數或程序名稱（帶有引數類型）轉換為其 OID。將字串轉換為 regprocedure 類型會得到類似的結果（請參閱第 8.19 節）；但是，如果找不到名稱，此函數會傳回 NULL，而不是拋出錯誤。

to_regrole ( text ) → regrole

將文字角色名稱轉換為其 OID。將字串轉換為 regrole 類型會得到類似的結果（請參閱第 8.19 節）；但是，如果找不到名稱，此函數會傳回 NULL，而不是拋出錯誤。

to_regtype ( text ) → regtype

剖析文字字串，從中提取可能的類型名稱，然後將該名稱轉換為類型 OID。字串中的語法錯誤將導致錯誤；但是，如果該字串是語法上有效的類型名稱，但恰好在目錄中找不到，則結果為 NULL。將字串轉換為 regtype 類型會得到類似的結果（請參閱第 8.19 節），但如果找不到名稱，則會拋出錯誤。

to_regtypemod ( text ) → integer

剖析文字字串，從中提取可能的類型名稱，然後轉換其類型修飾詞（如果有的話）。字串中的語法錯誤將導致錯誤；但是，如果該字串是語法上有效的類型名稱，但恰好在目錄中找不到，則結果為 NULL。如果沒有類型修飾詞，則結果為 -1。

to_regtypemod 可以與 to_regtype 結合使用，以產生 format_type 的適當輸入，從而允許將表示類型名稱的字串規範化。

format_type(to_regtype('varchar(32)'), to_regtypemod('varchar(32)')) → character varying(32)

大多數重建（反編譯）資料庫物件的函數都有一個可選的 pretty 旗標，如果為 true，則會導致結果「美化列印」。美化列印會抑制不必要的括號，並增加空格以提高可讀性。美化列印的格式更易於閱讀，但預設格式更有可能被未來版本的 PostgreSQL 以相同方式解讀；因此，避免將美化列印的輸出用於傾印目的。為 pretty 參數傳遞 false 會產生與省略該參數相同的結果。

表 9.75. 索引欄屬性

名稱	描述
`asc`	該欄是否在正向掃描時以遞增順序排序？
`desc`	該欄是否在正向掃描時以遞減順序排序？
`nulls_first`	該欄是否在正向掃描時以空值優先順序排序？
`nulls_last`	該欄是否在正向掃描時以空值最後順序排序？
`orderable`	該欄是否具有任何已定義的排序順序？
`distance_orderable`	是否可以按「距離」運算子依順序掃描該欄，例如 `ORDER BY col <-> constant`？
`returnable`	是否可以通過僅索引掃描返回該欄的值？
`search_array`	該欄是否原生支援 `col = ANY(array)` 搜尋？
`search_nulls`	該欄是否支援 `IS NULL` 和 `IS NOT NULL` 搜尋？

表 9.76. 索引屬性

名稱	描述
`clusterable`	索引是否可用於 `CLUSTER` 指令？
`index_scan`	索引是否支援純粹的（非點陣圖）掃描？
`bitmap_scan`	索引是否支援點陣圖掃描？
`backward_scan`	掃描方向是否可以在掃描中途變更（以便在不需要物化的情況下，支援游標的 `FETCH BACKWARD`）？

表 9.77. 索引存取方法屬性

名稱	描述
`can_order`	存取方法是否支援 `CREATE INDEX` 中的 `ASC`、`DESC` 和相關關鍵字？
`can_unique`	存取方法是否支援唯一索引？
`can_multi_col`	存取方法是否支援具有多個欄位的索引？
`can_exclude`	存取方法是否支援排除約束？
`can_include`	存取方法是否支援 `CREATE INDEX` 的 `INCLUDE` 子句？

表 9.78. GUC 旗標

旗標	描述
`EXPLAIN`	帶有此旗標的參數會包含在 `EXPLAIN (SETTINGS)` 指令中。
`NO_SHOW_ALL`	帶有此旗標的參數會從 `SHOW ALL` 指令中排除。
`NO_RESET`	帶有此旗標的參數不支援 `RESET` 指令。
`NO_RESET_ALL`	帶有此旗標的參數會從 `RESET ALL` 指令中排除。
`NOT_IN_SAMPLE`	預設情況下，帶有此旗標的參數不會包含在 `postgresql.conf` 中。
`RUNTIME_COMPUTED`	帶有此旗標的參數是執行階段計算的參數。

9.27.5. 物件資訊和定址函數 #

表 9.79 列出了與資料庫物件識別和定址相關的函數。

表 9.79. 物件資訊和定址函數

函數描述
`pg_describe_object` ( `classid` `oid`, `objid` `oid`, `objsubid` `integer` ) → `text` 傳回由目錄 OID、物件 OID 和子物件 ID（例如資料表中的欄位編號；當參考整個物件時，子物件 ID 為零）識別的資料庫物件的文字描述。此描述旨在讓人們可以閱讀，並且可能會根據伺服器配置進行翻譯。這對於確定 `pg_depend` 目錄中引用的物件的身分特別有用。此函數會針對未定義的物件傳回 `NULL` 值。
`pg_identify_object` ( `classid` `oid`, `objid` `oid`, `objsubid` `integer` ) → `record` ( `type` `text`, `schema` `text`, `name` `text`, `identity` `text` ) 傳回一個資料列，其中包含足夠的資訊來唯一識別由目錄 OID、物件 OID 和子物件 ID 指定的資料庫物件。此資訊旨在供機器讀取，並且永遠不會翻譯。 `type` 識別資料庫物件的類型；`schema` 是物件所屬的綱要名稱，對於不屬於綱要的物件類型，則為 `NULL`；如果名稱（以及相關的綱要名稱）足以唯一識別物件，則 `name` 是物件的名稱，必要時會加上引號，否則為 `NULL`；`identity` 是完整的物件身分，其精確格式取決於物件類型，並且格式中的每個名稱都會經過綱要限定並加上引號（如有必要）。未定義的物件會以 `NULL` 值識別。
`pg_identify_object_as_address` ( `classid` `oid`, `objid` `oid`, `objsubid` `integer` ) → `record` ( `type` `text`, `object_names` `text[]`, `object_args` `text[]` ) 傳回一個資料列，其中包含足夠的資訊來唯一識別由目錄 OID、物件 OID 和子物件 ID 指定的資料庫物件。傳回的資訊與目前伺服器無關，也就是說，它可以被用來識別另一個伺服器中具有相同名稱的物件。 `type` 識別資料庫物件的類型；`object_names` 和 `object_args` 是文字陣列，它們共同組成對物件的參考。這三個值可以傳遞給 `pg_get_object_address` 以取得物件的內部位址。
`pg_get_object_address` ( `type` `text`, `object_names` `text[]`, `object_args` `text[]` ) → `record` ( `classid` `oid`, `objid` `oid`, `objsubid` `integer` ) 傳回一個資料列，其中包含足夠的資訊來唯一識別由類型代碼和物件名稱及引數陣列指定的資料庫物件。傳回的值將會用於系統目錄中，例如 `pg_depend`；它們可以傳遞給其他系統函數，例如 `pg_describe_object` 或 `pg_identify_object`。`classid` 是包含物件的系統目錄的 OID；`objid` 是物件本身的 OID，而 `objsubid` 是子物件 ID，如果沒有，則為零。此函數是 `pg_identify_object_as_address` 的反函數。未定義的物件會以 `NULL` 值識別。

函數

描述

pg_describe_object ( classid oid, objid oid, objsubid integer ) → text

傳回由目錄 OID、物件 OID 和子物件 ID（例如資料表中的欄位編號；當參考整個物件時，子物件 ID 為零）識別的資料庫物件的文字描述。此描述旨在讓人們可以閱讀，並且可能會根據伺服器配置進行翻譯。這對於確定 pg_depend 目錄中引用的物件的身分特別有用。此函數會針對未定義的物件傳回 NULL 值。

pg_identify_object ( classid oid, objid oid, objsubid integer ) → record ( type text, schema text, name text, identity text )

傳回一個資料列，其中包含足夠的資訊來唯一識別由目錄 OID、物件 OID 和子物件 ID 指定的資料庫物件。此資訊旨在供機器讀取，並且永遠不會翻譯。 type 識別資料庫物件的類型；schema 是物件所屬的綱要名稱，對於不屬於綱要的物件類型，則為 NULL；如果名稱（以及相關的綱要名稱）足以唯一識別物件，則 name 是物件的名稱，必要時會加上引號，否則為 NULL；identity 是完整的物件身分，其精確格式取決於物件類型，並且格式中的每個名稱都會經過綱要限定並加上引號（如有必要）。未定義的物件會以 NULL 值識別。

pg_identify_object_as_address ( classid oid, objid oid, objsubid integer ) → record ( type text, object_names text[], object_args text[] )

傳回一個資料列，其中包含足夠的資訊來唯一識別由目錄 OID、物件 OID 和子物件 ID 指定的資料庫物件。傳回的資訊與目前伺服器無關，也就是說，它可以被用來識別另一個伺服器中具有相同名稱的物件。 type 識別資料庫物件的類型；object_names 和 object_args 是文字陣列，它們共同組成對物件的參考。這三個值可以傳遞給 pg_get_object_address 以取得物件的內部位址。

pg_get_object_address ( type text, object_names text[], object_args text[] ) → record ( classid oid, objid oid, objsubid integer )

傳回一個資料列，其中包含足夠的資訊來唯一識別由類型代碼和物件名稱及引數陣列指定的資料庫物件。傳回的值將會用於系統目錄中，例如 pg_depend；它們可以傳遞給其他系統函數，例如 pg_describe_object 或 pg_identify_object。classid 是包含物件的系統目錄的 OID；objid 是物件本身的 OID，而 objsubid 是子物件 ID，如果沒有，則為零。此函數是 pg_identify_object_as_address 的反函數。未定義的物件會以 NULL 值識別。

9.27.6. 註解資訊函數 #

表 9.80 中顯示的函數會擷取先前使用 COMMENT 指令儲存的註解。如果找不到指定參數的註解，則傳回 null 值。

表 9.80. 註解資訊函數

函數描述
`col_description` ( `table` `oid`, `column` `integer` ) → `text` 傳回資料表欄位的註解，該欄位由其資料表的 OID 和其欄位編號指定。（`obj_description` 不能用於資料表欄位，因為欄位沒有自己的 OID。）
`obj_description` ( `object` `oid`, `catalog` `name` ) → `text` 傳回由其 OID 和包含系統目錄的名稱指定的資料庫物件的註解。例如，`obj_description(123456, 'pg_class')` 會擷取 OID 為 123456 的資料表的註解。
`obj_description` ( `object` `oid` ) → `text` 傳回僅由其 OID 所指定的資料庫物件的註解。由於無法保證 OID 在不同的系統目錄中是唯一的，因此此功能已棄用；因此，可能會傳回錯誤的註解。
`shobj_description` ( `object` `oid`, `catalog` `name` ) → `text` 傳回由其 OID 和包含的系統目錄名稱所指定的共用資料庫物件的註解。這與 `obj_description` 類似，不同之處在於它用於檢索共用物件（即資料庫、角色和表空間）的註解。某些系統目錄對於每個叢集中的所有資料庫都是全域的，並且其中物件的描述也以全域方式儲存。

函數

描述

col_description ( table oid, column integer ) → text

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

obj_description ( object oid, catalog name ) → text

傳回由其 OID 和包含系統目錄的名稱指定的資料庫物件的註解。例如，obj_description(123456, 'pg_class') 會擷取 OID 為 123456 的資料表的註解。

obj_description ( object oid ) → text

傳回僅由其 OID 所指定的資料庫物件的註解。由於無法保證 OID 在不同的系統目錄中是唯一的，因此此功能已棄用；因此，可能會傳回錯誤的註解。

shobj_description ( object oid, catalog name ) → text

傳回由其 OID 和包含的系統目錄名稱所指定的共用資料庫物件的註解。這與 obj_description 類似，不同之處在於它用於檢索共用物件（即資料庫、角色和表空間）的註解。某些系統目錄對於每個叢集中的所有資料庫都是全域的，並且其中物件的描述也以全域方式儲存。

9.27.7. 資料有效性檢查函數 #

表 9.81 中顯示的函數對於檢查提議的輸入資料的有效性很有幫助。

表 9.81. 資料有效性檢查函數

函數描述範例
`pg_input_is_valid` ( `string` `text`, `type` `text` ) → `boolean` 測試給定的 `string` 是否為指定資料類型的有效輸入，並傳回 true 或 false。只有在資料類型的輸入函數已更新為將無效輸入報告為「軟性」錯誤時，此函數才能如預期般運作。否則，無效輸入將中止交易，就像直接將字串強制轉換為類型一樣。 `pg_input_is_valid('42', 'integer')` → `t` `pg_input_is_valid('42000000000', 'integer')` → `f` `pg_input_is_valid('1234.567', 'numeric(7,4)')` → `f`
`pg_input_error_info` ( `string` `text`, `type` `text` ) → `record` ( `message` `text`, `detail` `text`, `hint` `text`, `sql_error_code` `text` ) 測試給定的 `string` 是否為指定資料類型的有效輸入；如果不是，則傳回將擲出的錯誤的詳細資訊。如果輸入有效，則結果為 NULL。輸入與 `pg_input_is_valid` 相同。只有在資料類型的輸入函數已更新為將無效輸入報告為「軟性」錯誤時，此函數才能如預期般運作。否則，無效輸入將中止交易，就像直接將字串強制轉換為類型一樣。 `SELECT * FROM pg_input_error_info('42000000000', 'integer')` → message \| detail \| hint \| sql_error_code ------------------------------------------------------+--------+------+---------------- value "42000000000" is out of range for type integer \| \| \| 22003

函數

描述

範例

pg_input_is_valid ( string text, type text ) → boolean

測試給定的 string 是否為指定資料類型的有效輸入，並傳回 true 或 false。

只有在資料類型的輸入函數已更新為將無效輸入報告為「軟性」錯誤時，此函數才能如預期般運作。否則，無效輸入將中止交易，就像直接將字串強制轉換為類型一樣。

pg_input_is_valid('42', 'integer') → t

pg_input_is_valid('42000000000', 'integer') → f

pg_input_is_valid('1234.567', 'numeric(7,4)') → f

pg_input_error_info ( string text, type text ) → record ( message text, detail text, hint text, sql_error_code text )

測試給定的 string 是否為指定資料類型的有效輸入；如果不是，則傳回將擲出的錯誤的詳細資訊。如果輸入有效，則結果為 NULL。輸入與 pg_input_is_valid 相同。

只有在資料類型的輸入函數已更新為將無效輸入報告為「軟性」錯誤時，此函數才能如預期般運作。否則，無效輸入將中止交易，就像直接將字串強制轉換為類型一樣。

SELECT * FROM pg_input_error_info('42000000000', 'integer') →

                       message                        | detail | hint | sql_error_code
------------------------------------------------------+--------+------+----------------
 value "42000000000" is out of range for type integer |        |      | 22003

9.27.8. 交易 ID 和快照資訊函數 #

表 9.82 中顯示的函數以可匯出的形式提供伺服器交易資訊。這些函數的主要用途是確定兩個快照之間已提交哪些交易。

表 9.82. 交易 ID 和快照資訊函數

函數描述
`pg_current_xact_id` () → `xid8` 傳回目前交易的 ID。如果目前的交易尚未有 ID（因為它尚未執行任何資料庫更新），則將分配一個新的 ID；請參閱第 66.1 節以取得詳細資訊。如果在子交易中執行，這將傳回頂層交易 ID；請參閱第 66.3 節以取得詳細資訊。
`pg_current_xact_id_if_assigned` () → `xid8` 傳回目前交易的 ID，如果尚未分配 ID，則傳回 `NULL`。（如果交易可能以其他方式是唯讀的，則最好使用此變體，以避免不必要地消耗 XID。）如果在子交易中執行，這將傳回頂層交易 ID。
`pg_xact_status` ( `xid8` ) → `text` 報告最近交易的提交狀態。結果是 `in progress`、`committed` 或 `aborted` 之一，前提是交易最近才發生，系統才會保留該交易的提交狀態。如果它夠舊，系統中沒有任何對交易的引用存在，並且提交狀態資訊已被丟棄，則結果為 `NULL`。例如，應用程式可以使用此函數來確定在應用程式和資料庫伺服器在 `COMMIT` 進行中時斷開連線後，其交易是提交還是中止。請注意，準備好的交易會報告為 `in progress`；如果應用程式需要確定交易 ID 是否屬於準備好的交易，則必須檢查`pg_prepared_xacts`。
`pg_current_snapshot` () → `pg_snapshot` 傳回目前的快照，這是一種資料結構，顯示哪些交易 ID 目前正在進行中。快照中僅包含頂層交易 ID；不顯示子交易 ID；請參閱第 66.3 節以取得詳細資訊。
`pg_snapshot_xip` ( `pg_snapshot` ) → `setof xid8` 傳回快照中包含的正在進行中的交易 ID 的集合。
`pg_snapshot_xmax` ( `pg_snapshot` ) → `xid8` 傳回快照的 `xmax`。
`pg_snapshot_xmin` ( `pg_snapshot` ) → `xid8` 傳回快照的 `xmin`。
`pg_visible_in_snapshot` ( `xid8`, `pg_snapshot` ) → `boolean` 根據此快照，給定的交易 ID 是否可見（也就是說，它是否在建立快照之前完成）？請注意，此函數不會針對子交易 ID (subxid) 提供正確的答案；請參閱第 66.3 節以取得詳細資訊。

函數

描述

pg_current_xact_id () → xid8

傳回目前交易的 ID。如果目前的交易尚未有 ID（因為它尚未執行任何資料庫更新），則將分配一個新的 ID；請參閱第 66.1 節以取得詳細資訊。如果在子交易中執行，這將傳回頂層交易 ID；請參閱第 66.3 節以取得詳細資訊。

pg_current_xact_id_if_assigned () → xid8

傳回目前交易的 ID，如果尚未分配 ID，則傳回 NULL。（如果交易可能以其他方式是唯讀的，則最好使用此變體，以避免不必要地消耗 XID。）如果在子交易中執行，這將傳回頂層交易 ID。

pg_xact_status ( xid8 ) → text

報告最近交易的提交狀態。結果是 in progress、committed 或 aborted 之一，前提是交易最近才發生，系統才會保留該交易的提交狀態。如果它夠舊，系統中沒有任何對交易的引用存在，並且提交狀態資訊已被丟棄，則結果為 NULL。例如，應用程式可以使用此函數來確定在應用程式和資料庫伺服器在 COMMIT 進行中時斷開連線後，其交易是提交還是中止。請注意，準備好的交易會報告為 in progress；如果應用程式需要確定交易 ID 是否屬於準備好的交易，則必須檢查pg_prepared_xacts。

pg_current_snapshot () → pg_snapshot

傳回目前的快照，這是一種資料結構，顯示哪些交易 ID 目前正在進行中。快照中僅包含頂層交易 ID；不顯示子交易 ID；請參閱第 66.3 節以取得詳細資訊。

pg_snapshot_xip ( pg_snapshot ) → setof xid8

傳回快照中包含的正在進行中的交易 ID 的集合。

pg_snapshot_xmax ( pg_snapshot ) → xid8

傳回快照的 xmax。

pg_snapshot_xmin ( pg_snapshot ) → xid8

傳回快照的 xmin。

pg_visible_in_snapshot ( xid8, pg_snapshot ) → boolean

根據此快照，給定的交易 ID 是否可見（也就是說，它是否在建立快照之前完成）？請注意，此函數不會針對子交易 ID (subxid) 提供正確的答案；請參閱第 66.3 節以取得詳細資訊。

內部交易 ID 類型 xid 是 32 位元寬，並且每 40 億筆交易會循環一次。但是，表 9.82 中顯示的函數使用 64 位元類型 xid8，在安裝的生命週期內不會循環，並且如果需要，可以轉換為 xid，方法是使用型別轉換；詳情請參閱第 66.1 節。資料類型 pg_snapshot 儲存特定時間點的交易 ID 可見性資訊。其組成部分在表 9.83 中描述。pg_snapshot 的文字表示形式為 xmin:xmax:xip_list。例如，10:20:10,14,15 表示 xmin=10, xmax=20, xip_list=10, 14, 15。

表 9.83. 快照組成部分

名稱	描述
`xmin`	仍在活動中的最低交易 ID。所有小於 `xmin` 的交易 ID 要么已提交並可見，要么已回滾且已失效。
`xmax`	超過已完成的最高交易 ID 一個單位。所有大於或等於 `xmax` 的交易 ID 在快照時尚未完成，因此不可見。
`xip_list`	快照時正在進行中的交易。如果交易 ID `xmin <= X < xmax` 且不在這個列表中，則在快照時已經完成，因此根據其提交狀態，要么可見，要么已失效。此列表不包括子交易 (subxids) 的交易 ID。

在 13 之前的 PostgreSQL 版本中，沒有 xid8 類型，因此提供了使用 bigint 表示 64 位元 XID 的這些函數的變體，以及相應不同的快照資料類型 txid_snapshot。這些較舊的函數名稱中包含 txid。為了向後相容，仍然支援它們，但可能會在未來的版本中移除。請參閱表 9.84。

表 9.84. 已棄用的交易 ID 和快照資訊函數

函數描述
`age` ( `xid` ) → `integer` 傳回提供的交易 ID 和目前交易計數器之間的交易數量。
`mxid_age` ( `xid` ) → `integer` 傳回提供的 multixact ID 和目前的 multixacts 計數器之間的 multixact ID 數量。
`txid_current` () → `bigint` 請參閱 `pg_current_xact_id()`。
`txid_current_if_assigned` () → `bigint` 請參閱 `pg_current_xact_id_if_assigned()`。
`txid_current_snapshot` () → `txid_snapshot` 請參閱 `pg_current_snapshot()`。
`txid_snapshot_xip` ( `txid_snapshot` ) → `setof bigint` 請參閱 `pg_snapshot_xip()`。
`txid_snapshot_xmax` ( `txid_snapshot` ) → `bigint` 請參閱 `pg_snapshot_xmax()`。
`txid_snapshot_xmin` ( `txid_snapshot` ) → `bigint` 請參閱 `pg_snapshot_xmin()`。
`txid_visible_in_snapshot` ( `bigint`, `txid_snapshot` ) → `boolean` 請參閱 `pg_visible_in_snapshot()`。
`txid_status` ( `bigint` ) → `text` 請參閱 `pg_xact_status()`。

函數

描述

age ( xid ) → integer

傳回提供的交易 ID 和目前交易計數器之間的交易數量。

mxid_age ( xid ) → integer

傳回提供的 multixact ID 和目前的 multixacts 計數器之間的 multixact ID 數量。

txid_current () → bigint

請參閱 pg_current_xact_id()。

txid_current_if_assigned () → bigint

請參閱 pg_current_xact_id_if_assigned()。

txid_current_snapshot () → txid_snapshot

請參閱 pg_current_snapshot()。

txid_snapshot_xip ( txid_snapshot ) → setof bigint

請參閱 pg_snapshot_xip()。

txid_snapshot_xmax ( txid_snapshot ) → bigint

請參閱 pg_snapshot_xmax()。

txid_snapshot_xmin ( txid_snapshot ) → bigint

請參閱 pg_snapshot_xmin()。

txid_visible_in_snapshot ( bigint, txid_snapshot ) → boolean

請參閱 pg_visible_in_snapshot()。

txid_status ( bigint ) → text

請參閱 pg_xact_status()。

9.27.9. 已提交交易資訊函數 #

表 9.85 中顯示的函數提供有關過去交易何時提交的資訊。只有在啟用 track_commit_timestamp 配置選項後，並且僅適用於在其啟用後提交的交易，它們才提供有用的資料。提交時間戳記資訊通常在 vacuum 期間移除。

表 9.85. 已提交交易資訊函數

函數描述
`pg_xact_commit_timestamp` ( `xid` ) → `timestamp with time zone` 傳回交易的提交時間戳記。
`pg_xact_commit_timestamp_origin` ( `xid` ) → `record` ( `timestamp` `timestamp with time zone`, `roident` `oid`) 傳回交易的提交時間戳記和複寫來源。
`pg_last_committed_xact` () → `record` ( `xid` `xid`, `timestamp` `timestamp with time zone`, `roident` `oid` ) 傳回最新提交交易的交易 ID、提交時間戳記和複寫來源。

函數

描述

pg_xact_commit_timestamp ( xid ) → timestamp with time zone

傳回交易的提交時間戳記。

pg_xact_commit_timestamp_origin ( xid ) → record ( timestamp timestamp with time zone, roident oid)

傳回交易的提交時間戳記和複寫來源。

pg_last_committed_xact () → record ( xid xid, timestamp timestamp with time zone, roident oid )

傳回最新提交交易的交易 ID、提交時間戳記和複寫來源。

9.27.10. 控制資料函數 #

表 9.86 中顯示的函數會印出在 initdb 期間初始化的資訊，例如目錄版本。它們還顯示有關預寫記錄和檢查點處理的資訊。此資訊是叢集範圍的，而不是特定於任何一個資料庫。這些函數提供與 pg_controldata 應用程式相同的大部分資訊，來自相同的來源。

表 9.86. 控制資料函數

函數描述
`pg_control_checkpoint` () → `record` 傳回有關目前檢查點狀態的資訊，如表 9.87 中所示。
`pg_control_system` () → `record` 傳回關於目前控制檔狀態的資訊，如表 9.88所示。
`pg_control_init` () → `record` 傳回關於叢集初始化狀態的資訊，如表 9.89所示。
`pg_control_recovery` () → `record` 傳回關於復原狀態的資訊，如表 9.90所示。

函數

描述

pg_control_checkpoint () → record

傳回有關目前檢查點狀態的資訊，如表 9.87 中所示。

pg_control_system () → record

傳回關於目前控制檔狀態的資訊，如表 9.88所示。

pg_control_init () → record

傳回關於叢集初始化狀態的資訊，如表 9.89所示。

pg_control_recovery () → record

傳回關於復原狀態的資訊，如表 9.90所示。

表 9.87. pg_control_checkpoint 輸出欄位

欄位名稱	資料類型
`checkpoint_lsn`	`pg_lsn`
`redo_lsn`	`pg_lsn`
`redo_wal_file`	`text`
`timeline_id`	`integer`
`prev_timeline_id`	`integer`
`full_page_writes`	`boolean`
`next_xid`	`text`
`next_oid`	`oid`
`next_multixact_id`	`xid`
`next_multi_offset`	`xid`
`oldest_xid`	`xid`
`oldest_xid_dbid`	`oid`
`oldest_active_xid`	`xid`
`oldest_multi_xid`	`xid`
`oldest_multi_dbid`	`oid`
`oldest_commit_ts_xid`	`xid`
`newest_commit_ts_xid`	`xid`
`checkpoint_time`	`timestamp with time zone`

表 9.88. pg_control_system 輸出欄位

欄位名稱	資料類型
`pg_control_version`	`integer`
`catalog_version_no`	`integer`
`system_identifier`	`bigint`
`pg_control_last_modified`	`timestamp with time zone`

表 9.89. pg_control_init 輸出欄位

欄位名稱	資料類型
`max_data_alignment`	`integer`
`database_block_size`	`integer`
`blocks_per_segment`	`integer`
`wal_block_size`	`integer`
`bytes_per_wal_segment`	`integer`
`max_identifier_length`	`integer`
`max_index_columns`	`integer`
`max_toast_chunk_size`	`integer`
`large_object_chunk_size`	`integer`
`float8_pass_by_value`	`boolean`
`data_page_checksum_version`	`integer`

表 9.90. pg_control_recovery 輸出欄位

欄位名稱	資料類型
`min_recovery_end_lsn`	`pg_lsn`
`min_recovery_end_timeline`	`integer`
`backup_start_lsn`	`pg_lsn`
`backup_end_lsn`	`pg_lsn`
`end_of_backup_record_required`	`boolean`

9.27.11. 版本資訊函數 #

表 9.91中顯示的函數會印出版本資訊。

表 9.91. 版本資訊函數

函數描述
`version` () → `text` 傳回一個字串，描述 PostgreSQL 伺服器的版本。您也可以從server_version取得此資訊，或者若要取得機器可讀的版本，請使用server_version_num。軟體開發人員應使用 `server_version_num` (自 8.2 起可用) 或 `PQserverVersion`，而不是剖析文字版本。
`unicode_version` () → `text` 傳回一個字串，表示 PostgreSQL 使用的 Unicode 版本。
`icu_unicode_version` () → `text` 如果伺服器是使用 ICU 支援建置的，則傳回一個字串，表示 ICU 使用的 Unicode 版本；否則傳回 `NULL`

函數

描述

version () → text

傳回一個字串，描述 PostgreSQL 伺服器的版本。您也可以從server_version取得此資訊，或者若要取得機器可讀的版本，請使用server_version_num。軟體開發人員應使用 server_version_num (自 8.2 起可用) 或 PQserverVersion，而不是剖析文字版本。

unicode_version () → text

傳回一個字串，表示 PostgreSQL 使用的 Unicode 版本。

icu_unicode_version () → text

如果伺服器是使用 ICU 支援建置的，則傳回一個字串，表示 ICU 使用的 Unicode 版本；否則傳回 NULL

9.27.12. WAL 摘要資訊函數 #

表 9.92中顯示的函數會印出關於 WAL 摘要狀態的資訊。請參閱summarize_wal。

表 9.92. WAL 摘要資訊函數

函數描述
`pg_available_wal_summaries` () → `setof record` ( `tli` `bigint`, `start_lsn` `pg_lsn`, `end_lsn` `pg_lsn` ) 傳回關於資料目錄中 `pg_wal/summaries` 下存在的 WAL 摘要檔案的資訊。每個 WAL 摘要檔案會傳回一列。每個檔案摘要在指示的 LSN 範圍內，於指示的 TLI 上的 WAL。此函數可能有助於判斷伺服器上是否存在足夠的 WAL 摘要，以根據已知啟始 LSN 的先前備份進行增量備份。
`pg_wal_summary_contents` ( `tli` `bigint`, `start_lsn` `pg_lsn`, `end_lsn` `pg_lsn` ) → `setof record` ( `relfilenode` `oid`, `reltablespace` `oid`, `reldatabase` `oid`, `relforknumber` `smallint`, `relblocknumber` `bigint`, `is_limit_block` `boolean` ) 傳回關於由 TLI 以及啟始和結束 LSN 所識別的單一 WAL 摘要檔案內容的資訊。每個 `is_limit_block` 為 false 的列表示由其餘輸出欄位識別的區塊，已由該檔案摘要的記錄範圍內，至少一個 WAL 記錄修改。每個 `is_limit_block` 為 true 的列表示 (a) 關係叢集已截斷為相關 WAL 記錄範圍內，由 `relblocknumber` 給定的長度，或 (b) 關係叢集已在相關 WAL 記錄範圍內建立或刪除；在這種情況下，`relblocknumber` 將為零。
`pg_get_wal_summarizer_state` () → `record` ( `summarized_tli` `bigint`, `summarized_lsn` `pg_lsn`, `pending_lsn` `pg_lsn`, `summarizer_pid` `int` ) 傳回關於 WAL 摘要工具進度的資訊。如果 WAL 摘要工具自實例啟動以來從未執行過，則 `summarized_tli` 和 `summarized_lsn` 將分別為 `0` 和 `0/0`；否則，它們將是寫入磁碟的最後一個 WAL 摘要檔案的 TLI 和結束 LSN。如果 WAL 摘要工具目前正在執行，`pending_lsn` 將是它已使用的最後一個記錄的結束 LSN，它必須始終大於或等於 `summarized_lsn`；如果 WAL 摘要工具未執行，它將等於 `summarized_lsn`。`summarizer_pid` 是 WAL 摘要工具進程的 PID，如果它正在執行，否則為 NULL。作為一個特殊的例外，如果 WAL 是在 `wal_level=minimal` 下生成的，WAL 摘要工具將拒絕生成 WAL 摘要檔案，因為此類摘要不能安全地用作增量備份的基礎。在這種情況下，上面的欄位將繼續推進，就像正在生成摘要一樣，但不會將任何內容寫入磁碟。一旦摘要工具到達在 `wal_level` 設定為 `replica` 或更高版本時生成的 WAL，它將恢復將摘要寫入磁碟。

函數

描述

pg_available_wal_summaries () → setof record ( tli bigint, start_lsn pg_lsn, end_lsn pg_lsn )

傳回關於資料目錄中 pg_wal/summaries 下存在的 WAL 摘要檔案的資訊。每個 WAL 摘要檔案會傳回一列。每個檔案摘要在指示的 LSN 範圍內，於指示的 TLI 上的 WAL。此函數可能有助於判斷伺服器上是否存在足夠的 WAL 摘要，以根據已知啟始 LSN 的先前備份進行增量備份。

pg_wal_summary_contents ( tli bigint, start_lsn pg_lsn, end_lsn pg_lsn ) → setof record ( relfilenode oid, reltablespace oid, reldatabase oid, relforknumber smallint, relblocknumber bigint, is_limit_block boolean )

傳回關於由 TLI 以及啟始和結束 LSN 所識別的單一 WAL 摘要檔案內容的資訊。每個 is_limit_block 為 false 的列表示由其餘輸出欄位識別的區塊，已由該檔案摘要的記錄範圍內，至少一個 WAL 記錄修改。每個 is_limit_block 為 true 的列表示 (a) 關係叢集已截斷為相關 WAL 記錄範圍內，由 relblocknumber 給定的長度，或 (b) 關係叢集已在相關 WAL 記錄範圍內建立或刪除；在這種情況下，relblocknumber 將為零。

pg_get_wal_summarizer_state () → record ( summarized_tli bigint, summarized_lsn pg_lsn, pending_lsn pg_lsn, summarizer_pid int )

傳回關於 WAL 摘要工具進度的資訊。如果 WAL 摘要工具自實例啟動以來從未執行過，則 summarized_tli 和 summarized_lsn 將分別為 0 和 0/0；否則，它們將是寫入磁碟的最後一個 WAL 摘要檔案的 TLI 和結束 LSN。如果 WAL 摘要工具目前正在執行，pending_lsn 將是它已使用的最後一個記錄的結束 LSN，它必須始終大於或等於 summarized_lsn；如果 WAL 摘要工具未執行，它將等於 summarized_lsn。summarizer_pid 是 WAL 摘要工具進程的 PID，如果它正在執行，否則為 NULL。

作為一個特殊的例外，如果 WAL 是在 wal_level=minimal 下生成的，WAL 摘要工具將拒絕生成 WAL 摘要檔案，因為此類摘要不能安全地用作增量備份的基礎。在這種情況下，上面的欄位將繼續推進，就像正在生成摘要一樣，但不會將任何內容寫入磁碟。一旦摘要工具到達在 wal_level 設定為 replica 或更高版本時生成的 WAL，它將恢復將摘要寫入磁碟。

9.27. 系統資訊函數和運算子 #