audit-trigger源码解读：核心函数if_modified_func如何捕获PostgreSQL数据变更

【免费下载链接】audit-triggerSimple, easily customised trigger-based auditing for PostgreSQL (Postgres). See also pgaudit.项目地址: https://gitcode.com/gh_mirrors/au/audit-trigger

audit-trigger是PostgreSQL数据库中一款轻量级的审计工具，能够通过触发器机制捕获数据变更事件。本文将深入解析其核心函数if_modified_func的工作原理，帮助新手理解PostgreSQL数据审计的实现方式。

1. 审计触发的基础架构

在开始分析函数前，我们需要先了解audit-trigger的整体架构。审计系统主要由以下组件构成：

• 审计日志表：audit.logged_actions存储所有数据变更记录，包含操作类型、时间戳、用户信息等关键字段
• 核心触发器函数：audit.if_modified_func()作为触发器逻辑的载体，处理INSERT/UPDATE/DELETE/TRUNCATE事件
• 审计配置函数：audit.audit_table()用于为目标表启用审计功能

1.1 审计日志表设计

审计日志表audit.logged_actions是数据变更记录的存储核心，其结构定义如下（简化版）：

CREATE TABLE audit.logged_actions ( event_id bigserial primary key, schema_name text not null, table_name text not null, action TEXT NOT NULL CHECK (action IN ('I','D','U', 'T')), row_data hstore, changed_fields hstore, action_tstamp_tx TIMESTAMP WITH TIME ZONE NOT NULL );

其中关键字段说明：

• action：记录操作类型（I=插入，D=删除，U=更新，T=截断）
• row_data：存储变更前的完整记录（INSERT时为新记录）
• changed_fields：仅UPDATE操作时记录变更的字段

2. if_modified_func函数工作原理

if_modified_func是整个审计系统的灵魂，作为触发器函数，它在数据变更发生后被自动调用。其核心逻辑可分为三个阶段：初始化审计记录→处理不同操作类型→写入审计日志。

2.1 审计记录初始化

函数首先构造一条审计记录骨架，填充基础元数据：

audit_row = ROW( nextval('audit.logged_actions_event_id_seq'), -- 自增ID TG_TABLE_SCHEMA::text, -- 表所在 schema TG_TABLE_NAME::text, -- 表名 TG_RELID, -- 表OID session_user::text, -- 操作用户 current_timestamp, -- 事务时间戳 statement_timestamp(), -- 语句时间戳 clock_timestamp(), -- 时钟时间戳 txid_current(), -- 事务ID current_setting('application_name'), -- 应用名称 inet_client_addr(), -- 客户端IP inet_client_port(), -- 客户端端口 current_query(), -- 执行的SQL substring(TG_OP,1,1), -- 操作类型(I/U/D/T) NULL, NULL, -- 预留字段 'f' -- 是否为语句级触发 );

这段代码利用PostgreSQL的系统函数获取了丰富的上下文信息，为审计提供了完整的操作背景。

2.2 操作类型分支处理

函数通过TG_OP和TG_LEVEL系统变量判断当前操作类型，执行不同的处理逻辑：

2.2.1 UPDATE操作处理

当触发级别为行级（ROW）且操作为UPDATE时：

IF (TG_OP = 'UPDATE' AND TG_LEVEL = 'ROW') THEN audit_row.row_data = hstore(OLD.*) - excluded_cols; audit_row.changed_fields = (hstore(NEW.*) - audit_row.row_data) - excluded_cols; IF audit_row.changed_fields = hstore('') THEN -- 所有变更字段都被忽略，跳过此次更新记录 RETURN NULL; END IF; END IF;

这里使用hstore类型（键值对存储）来高效计算新旧记录的差异，同时支持通过excluded_cols参数排除不需要审计的字段。

2.2.2 INSERT/DELETE操作处理

对于INSERT和DELETE操作，处理逻辑相对简单：

ELSIF (TG_OP = 'DELETE' AND TG_LEVEL = 'ROW') THEN audit_row.row_data = hstore(OLD.*) - excluded_cols; ELSIF (TG_OP = 'INSERT' AND TG_LEVEL = 'ROW') THEN audit_row.row_data = hstore(NEW.*) - excluded_cols;

INSERT操作记录新插入的数据，DELETE操作记录被删除的数据。

2.2.3 语句级操作处理

对于TRUNCATE或语句级（STATEMENT）触发的操作：

ELSIF (TG_LEVEL = 'STATEMENT' AND TG_OP IN ('INSERT','UPDATE','DELETE','TRUNCATE')) THEN audit_row.statement_only = 't';

这类操作不记录具体行数据，仅记录操作事件本身。

2.3 审计日志写入

完成记录构建后，函数将审计记录写入日志表：

INSERT INTO audit.logged_actions VALUES (audit_row.*);

至此，一次数据变更审计流程完成。

3. 触发器的创建与绑定

if_modified_func函数通过audit.audit_table函数绑定到目标表：

CREATE OR REPLACE FUNCTION audit.audit_table(target_table regclass) RETURNS void AS $body$ SELECT audit.audit_table($1, BOOLEAN 't', BOOLEAN 't'); $body$ LANGUAGE 'sql';

调用示例：

SELECT audit.audit_table('public.users');

这会为public.users表创建两个触发器：

• audit_trigger_row：行级触发器，捕获INSERT/UPDATE/DELETE操作
• audit_trigger_stm：语句级触发器，捕获TRUNCATE操作

4. 实际应用场景与优化建议

4.1 关键应用场景

• 数据变更追踪：完整记录谁在何时修改了什么数据
• 合规审计：满足金融、医疗等行业的数据监管要求
• 故障恢复：在数据错误修改时可通过审计日志找回原始数据

4.2 性能优化建议

1. 合理设置忽略字段：通过excluded_cols参数排除频繁更新但无需审计的字段（如最后登录时间）
2. 定期归档日志：审计表会随时间快速增长，建议定期归档历史数据
3. 索引优化：根据查询需求创建合适的索引，如：

   CREATE INDEX idx_logged_actions_table ON audit.logged_actions(schema_name, table_name); CREATE INDEX idx_logged_actions_time ON audit.logged_actions(action_tstamp_tx);

5. 总结

audit-trigger通过if_modified_func函数巧妙利用PostgreSQL的触发器机制，实现了轻量级yet功能完善的数据审计方案。其核心设计思想包括：

• 基于hstore的差异计算：高效捕获变更字段
• 灵活的触发级别：支持行级和语句级审计
• 丰富的上下文记录：提供完整的操作背景信息

对于需要实现数据变更追踪的PostgreSQL应用，audit-trigger提供了开箱即用的解决方案，同时其简洁的源码也为定制化审计需求提供了良好的参考。

要开始使用audit-trigger，只需执行以下命令部署：

git clone https://gitcode.com/gh_mirrors/au/audit-trigger cd audit-trigger psql -f audit.sql

然后通过SELECT audit.audit_table('your_table')为目标表启用审计功能即可。

【免费下载链接】audit-triggerSimple, easily customised trigger-based auditing for PostgreSQL (Postgres). See also pgaudit.项目地址: https://gitcode.com/gh_mirrors/au/audit-trigger