使用SYS_CONTEXT實現Action Trail與應用追蹤-雲原生資料庫 PolarDB-阿里雲

從Oracle遷移應用，或需要在資料庫層面實現精細化的Action Trail與應用追蹤時，SYS_CONTEXT函數提供了一個與 Oracle相容的介面。此函數用於擷取當前會話的使用者、網路、應用等上下文資訊，以支援安全性原則、效能診斷和業務追蹤等進階功能。

核心樣本

以下樣本展示了如何一次性查詢當前會話的關鍵資訊，如資料庫名、會話使用者、用戶端IP地址和正在執行的應用模組，便於快速瞭解其核心用法。

SELECT
  SYS_CONTEXT('USERENV', 'DB_NAME') AS db_name,
  SYS_CONTEXT('USERENV', 'SESSION_USER') AS session_user,
  SYS_CONTEXT('USERENV', 'IP_ADDRESS') AS client_ip,
  SYS_CONTEXT('USERENV', 'MODULE') AS app_module;

預期輸出樣本（輸出內容取決於實際會話環境）：

 db_name | session_user |    client_ip    | app_module 
---------+--------------+-----------------+------------
 testdb  | dev_user     | 172.xx.xx.xx/xx |

適用範圍

您的PolarDB PostgreSQL版（相容Oracle）叢集的修訂版本需為2.0.14.18.37.0及以上

說明

您可在控制台查看核心小版本號碼，也可以通過SHOW polardb_version;語句查看。如未滿足核心小版本要求，請升級核心小版本。

文法說明

SYS_CONTEXT(namespace VARCHAR2, attribute VARCHAR2) RETURN VARCHAR2

參數說明

namespace：命名空間，目前主要支援'USERENV'。
attribute：要擷取的屬性名稱。

傳回值

VARCHAR2類型的屬性值。

使用情境

配置並追蹤應用資訊

在複雜的應用中，追蹤是哪個模組、哪個具體操作觸發了資料庫行為至關重要。SYS_CONTEXT不僅能讀取資訊，還能配合DBMS_APPLICATION_INFO包來設定和讀取應用上下文，形成完整的追蹤鏈路。

目的：為當前資料庫會話設定應用模組和操作資訊，以便後續審計或效能分析。

設定應用上下文資訊。
在應用程式代碼串連資料庫後，調用DBMS_APPLICATION_INFO包中的過程來設定當前會話的模組和操作。
```
-- 假設這是一個處理訂單的後台服務
CALL DBMS_APPLICATION_INFO.SET_MODULE('OrderProcessing', 'CreateNewOrder');
```

在資料庫中查詢上下文資訊。

設定後，可在資料庫的任何地方（例如，在觸發器或日誌記錄函數中）通過SYS_CONTEXT擷取這些資訊。

SELECT
  SYS_CONTEXT('USERENV', 'MODULE') AS current_module,
  SYS_CONTEXT('USERENV', 'ACTION') AS current_action;

預期返回結果如下：

 current_module  | current_action 
-----------------+----------------
 OrderProcessing | CreateNewOrder

在觸發器中實現Action Trail

SYS_CONTEXT在自動化審計情境中尤其有用。可在觸發器中捕獲操作者的環境資訊，並將其存入審計日誌，而無需應用程式層傳遞額外參數。

目的：當employees表的記錄被更新時，自動在audit_log表中記錄操作者的作業系統使用者、用戶端 IP 和會話 ID。

建立目標表並插入樣本資料。

建立employees表並插入一條用於測試的記錄。

CREATE TABLE employees (
    employee_id INT PRIMARY KEY,
    name TEXT,
    salary NUMERIC
);
INSERT INTO employees VALUES (101, 'test_user', 50000);

建立審計日誌表。

用於儲存審計資訊。

CREATE TABLE audit_log (
    log_id SERIAL PRIMARY KEY,
    table_name TEXT NOT NULL,
    os_user TEXT,
    client_ip TEXT,
    session_id TEXT,
    change_time TIMESTAMPTZ DEFAULT NOW()
);

建立審計觸發器函數。

該函數從USERENV命名空間中擷取上下文資訊並插入日誌表。

CREATE OR REPLACE FUNCTION fn_audit_employees_update()
RETURNS TRIGGER AS $$
BEGIN
    INSERT INTO audit_log (table_name, os_user, client_ip, session_id)
    VALUES (
        TG_TABLE_NAME,
        SYS_CONTEXT('USERENV', 'OS_USER'),
        SYS_CONTEXT('USERENV', 'IP_ADDRESS'),
        SYS_CONTEXT('USERENV', 'SESSIONID')
    );
    RETURN NEW;
END;
$$ LANGUAGE plpgsql;

綁定觸發器到目標表。

在employees表每次更新後執行此函數。

CREATE TRIGGER trg_audit_employees_update
AFTER UPDATE ON employees
FOR EACH ROW
EXECUTE FUNCTION fn_audit_employees_update();

驗證審計功能。

執行一次更新操作，然後查詢審計日誌表。

-- 類比一次更新
UPDATE employees SET salary = salary * 1.1 WHERE employee_id = 101;

查詢audit_log表，是否會自動新增一條記錄，包含執行更新操作的使用者的環境資訊。

SELECT * FROM audit_log;

預期返回結果如下：

 log_id | table_name | os_user  |    client_ip        | session_id |          change_time           
--------+------------+----------+---------------------+------------+--------------------------------
      1 | employees  | postgres | 172.xxx.xxx.xxx/xxx | 30         | 2025-10-17 07:41:50.666905 +00

屬性詳解

SYS_CONTEXT函數通過不同的參數擷取多樣的會話資訊。屬性名稱不區分大小寫。

使用者和會話資訊

屬性名稱	詳細說明	樣本
`CURRENT_USER`	當前有效使用者。	`SELECT SYS_CONTEXT('USERENV', 'CURRENT_USER');`
`SESSION_USER`	會話初始使用者。即用戶端初始串連時進行身分識別驗證的使用者名稱，在整個會話期間保持不變。	`SELECT SYS_CONTEXT('USERENV', 'SESSION_USER');`
`CURRENT_USERID`	當前有效使用者的ID。	`SELECT SYS_CONTEXT('USERENV', 'CURRENT_USERID');`
`SESSION_USERID`	會話初始使用者的ID。	`SELECT SYS_CONTEXT('USERENV', 'SESSION_USERID');`
`OS_USER`	串連到資料庫伺服器的用戶端作業系統使用者名稱。	`SELECT SYS_CONTEXT('USERENV', 'OS_USER');`
`ISDBA`	判斷目前使用者是否為資料庫超級管理員（Superuser）。	`SELECT SYS_CONTEXT('USERENV', 'ISDBA');`

會話標識資訊

屬性名稱	詳細說明	樣本
`SESSIONID`	工作階段識別項，通常是資料庫後端的進程ID（PID）。兩者功能相同，互為別名。	`SELECT SYS_CONTEXT('USERENV', 'SESSIONID');`
`SID`	工作階段識別項，通常是資料庫後端的進程ID（PID）。兩者功能相同，互為別名。	`SELECT SYS_CONTEXT('USERENV', 'SESSIONID');`
`CLIENT_IDENTIFIER`	用戶端標識符。	`SELECT SYS_CONTEXT('USERENV', 'CLIENT_IDENTIFIER');`
`CLIENT_INFO`	用戶端資訊。	`SELECT SYS_CONTEXT('USERENV', 'CLIENT_INFO');`

資料庫和模式資訊

屬性名稱	詳細說明	樣本
`DB_NAME`	當前串連的資料庫名稱。	`SELECT SYS_CONTEXT('USERENV', 'DB_NAME');`
`DB_UNIQUE_NAME`	資料庫的唯一名稱。	`SELECT SYS_CONTEXT('USERENV', 'DB_UNIQUE_NAME');`
`CURRENT_SCHEMA`	當前預設的模式名稱。	`SELECT SYS_CONTEXT('USERENV', 'CURRENT_SCHEMA');`
`SESSION_SCHEMA`	會話模式名稱。	`SELECT SYS_CONTEXT('USERENV', 'SESSION_SCHEMA');`
`INSTANCE`	執行個體編號。	`SELECT SYS_CONTEXT('USERENV', 'INSTANCE');`
`INSTANCE_NAME`	執行個體名稱。	`SELECT SYS_CONTEXT('USERENV', 'INSTANCE_NAME');`

網路和串連資訊

屬性名稱	詳細說明	樣本
`IP_ADDRESS`	用戶端的IP地址.	`SELECT SYS_CONTEXT('USERENV', 'IP_ADDRESS');`
`SERVER_HOST`	資料庫伺服器的主機地址。	`SELECT SYS_CONTEXT('USERENV', 'SERVER_HOST');`
`HOST`	用戶端的主機名稱。	`SELECT SYS_CONTEXT('USERENV', 'HOST');`
`TERMINAL`	用戶端的終端標識。	`SELECT SYS_CONTEXT('USERENV', 'TERMINAL');`

應用程式資訊

屬性名稱	詳細說明	樣本
`MODULE`	當前應用程式模組名。	`SELECT SYS_CONTEXT('USERENV', 'MODULE');`
`ACTION`	當前執行的操作名。	`SELECT SYS_CONTEXT('USERENV', 'ACTION');`
`DATABASE_ROLE`	資料庫角色。	`SELECT SYS_CONTEXT('USERENV', 'DATABASE_ROLE');`

語言和本地化資訊

屬性名稱	詳細說明	樣本
`LANG`	當前編碼。	`SELECT SYS_CONTEXT('USERENV', 'LANG');`
`LANGUAGE`	完整的語言和地區設定。	`SELECT SYS_CONTEXT('USERENV', 'LANGUAGE');`
`NLS_DATE_FORMAT`	當前會話的日期顯示格式。	`SELECT SYS_CONTEXT('USERENV', 'NLS_DATE_FORMAT');`

版本資訊

屬性名稱	詳細說明	樣本
`SESSION_EDITION_ID`	會話版本ID。	`SELECT SYS_CONTEXT('USERENV', 'SESSION_EDITION_ID');`
`CURRENT_EDITION_ID`	目前的版本ID。	`SELECT SYS_CONTEXT('USERENV', 'CURRENT_EDITION_ID');`