Skip to content

Commit 475cef1

Browse files
NotHimmelNotHimmel
committed
Add PgAudit documentation
1 parent 95a776d commit 475cef1

File tree

4 files changed

+223
-0
lines changed

4 files changed

+223
-0
lines changed

‎CN/modules/ROOT/nav.adoc‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -19,6 +19,7 @@
1919
*** xref:master/5.4.adoc[pg_cron]
2020
*** xref:master/5.5.adoc[pgsql-http]
2121
*** xref:master/5.6.adoc[plpgsql_check]
22+
*** xref:master/5.7.adoc[PgAudit]
2223
** IvorySQL架构设计
2324
*** 查询处理
2425
**** xref:master/6.1.1.adoc[双parser]

‎CN/modules/ROOT/pages/master/5.7.adoc‎

Lines changed: 110 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,110 @@
1+
2+
:sectnums:
3+
:sectnumlevels: 5
4+
5+
= PgAudit
6+
7+
== 概述
8+
9+
PgAudit 是一个审计扩展，可以为 DDL、DML、DCL 等关键操作生成可追溯的日志记录。通过审计日志，数据库管理员能够满足合规要求、及时发现异常行为，并在出现问题时快速定位责任主体与影响范围。
10+
11+
== 功能特点
12+
13+
* *全面审计能力*：记录 `SELECT`、`INSERT`、`UPDATE`、`DELETE`、DDL 命令以及权限变更等操作，帮助构建完整的操作轨迹。
14+
* *灵活的审计维度*：支持全局审计、角色审计与对象审计，可按用户、角色、模式或具体操作类型进行精细化配置。
15+
* *平滑集成*：复用 PostgreSQL 标准日志子系统，可与 `syslog`、`logrotate` 等工具联动，兼容现有日志采集与分析方案。
16+
* *合规支撑*：提供结构化审计日志，便于生成符合金融、政企等行业规范的审计报告。
17+
* *安全增强*：通过记录和分析数据库活动，及时发现未授权访问、异常 DML 或潜在数据泄露风险。
18+
* *运维优化*：辅助回放操作行为、定位性能瓶颈，支撑 SQL 优化与问题排查。
19+
20+
== 安装部署
21+
22+
=== 环境准备
23+
24+
* 已安装的 IvorySQL 数据库。
25+
* 编译工具链：`gcc`、`make`、`tar` 等。
26+
* 数据库管理员权限，用于修改 `ivorysql.conf` 并重启数据库实例。
27+
28+
=== 编译安装 PgAudit
29+
30+
以 PgAudit 18.0 为例：
31+
32+
[source,shell]
33+
----
34+
wget https://github.com/pgaudit/pgaudit/archive/refs/tags/18.0.tar.gz
35+
tar -xf 18.0.tar.gz
36+
cd pgaudit-18.0
37+
make install USE_PGXS=1 PG_CONFIG=$PGHOME/bin/pg_config
38+
----
39+
40+
上述命令依赖环境变量 `PGHOME` 指向安装好的 IvorySQL 主目录。安装成功后，`pgaudit.so` 会被放置到 IvorySQL 的扩展目录中。
41+
42+
=== 注册扩展前的基础配置
43+
44+
1. 修改 `ivorysql.conf`，启用插件并设置常用参数：
45+
46+
[source,conf]
47+
----
48+
shared_preload_libraries = 'pgaudit' # 需实例重启生效
49+
pgaudit.log = 'read, write, ddl' # 审计范围示例，可按需调整
50+
----
51+
52+
2. 重启数据库实例，使共享库配置生效。
53+
54+
=== 创建扩展并验证
55+
56+
[source,sql]
57+
----
58+
CREATE EXTENSION IF NOT EXISTS pgaudit;
59+
SELECT name,
60+
default_version,
61+
installed_version,
62+
comment
63+
FROM pg_available_extensions
64+
WHERE name = 'pgaudit';
65+
----
66+
67+
若返回的 `installed_version` 与期望版本一致，说明扩展安装成功。
68+
69+
== 使用
70+
71+
1. 执行如下sql示例：
72+
73+
[source,sql]
74+
----
75+
CREATE TABLE audit_demo(id serial PRIMARY KEY, info text);
76+
INSERT INTO audit_demo(info) VALUES ('pgaudit test');
77+
SELECT * FROM audit_demo;
78+
UPDATE audit_demo SET info = 'pgaudit update' WHERE id = 1;
79+
DELETE FROM audit_demo WHERE id = 1;
80+
----
81+
82+
2. 在数据库服务器上查看审计日志：
83+
84+
[source,shell]
85+
----
86+
tail -f $PGDATA/log/*.log | grep 'AUDIT:'
87+
----
88+
89+
90+
[source,text]
91+
----
92+
2025-10-31 15:56:32.113 CST [11451] LOG: AUDIT: SESSION,1,1,DDL,CREATE SEQUENCE,SEQUENCE,public.audit_demo_id_seq,"CREATE TABLE audit_demo(id serial PRIMARY KEY, info text)",<not logged>
93+
2025-10-31 15:56:32.113 CST [11451] LOG: AUDIT: SESSION,1,1,DDL,CREATE TABLE,TABLE,public.audit_demo,"CREATE TABLE audit_demo(id serial PRIMARY KEY, info text)",<not logged>
94+
2025-10-31 15:56:32.113 CST [11451] LOG: AUDIT: SESSION,1,1,DDL,CREATE INDEX,INDEX,public.audit_demo_pkey,"CREATE TABLE audit_demo(id serial PRIMARY KEY, info text)",<not logged>
95+
2025-10-31 15:56:32.113 CST [11451] LOG: AUDIT: SESSION,1,1,DDL,ALTER SEQUENCE,SEQUENCE,public.audit_demo_id_seq,"CREATE TABLE audit_demo(id serial PRIMARY KEY, info text)",<not logged>
96+
2025-10-31 15:56:32.117 CST [11451] LOG: AUDIT: SESSION,2,1,WRITE,INSERT,,,INSERT INTO audit_demo(info) VALUES ('pgaudit test'),<not logged>
97+
2025-10-31 15:56:32.121 CST [11451] LOG: AUDIT: SESSION,3,1,READ,SELECT,,,SELECT * FROM audit_demo,<not logged>
98+
2025-10-31 15:56:32.122 CST [11451] LOG: AUDIT: SESSION,4,1,WRITE,UPDATE,,,UPDATE audit_demo SET info = 'pgaudit update' WHERE id = 1,<not logged>
99+
2025-10-31 15:56:32.127 CST [11451] LOG: AUDIT: SESSION,5,1,WRITE,DELETE,,,DELETE FROM audit_demo WHERE id = 1,<not logged>
100+
----
101+
102+
-- 若想记录参数的值，打开`pgaudit.log_parameter = 'on'`，效果如下：
103+
[source,text]
104+
----
105+
ivorysql=# SHOW pgaudit.log_parameter;
106+
pgaudit.log_parameter
107+
-----------------------
108+
off
109+
(1 row)
110+
----

‎EN/modules/ROOT/nav.adoc‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -18,6 +18,7 @@
1818
** xref:master/5.4.adoc[pg_cron]
1919
** xref:master/5.5.adoc[pgsql-http]
2020
** xref:master/5.6.adoc[plpgsql_check]
21+
** xref:master/5.7.adoc[PgAudit]
2122
* IvorySQL Architecture Design
2223
** Query Processing
2324
*** xref:master/6.1.1.adoc[Dual Parser]

‎EN/modules/ROOT/pages/master/5.7.adoc‎

Lines changed: 111 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,111 @@
1+
:sectnums:
2+
:sectnumlevels: 5
3+
4+
= PgAudit
5+
6+
== Overview
7+
8+
PgAudit is an auditing extension for IvorySQL that produces traceable log records for critical operations such as DDL, DML, and DCL. With the audit trail, database administrators can meet compliance requirements, quickly detect abnormal behavior, and identify accountability and impact scope when incidents occur.
9+
10+
== Key Features
11+
12+
* *Comprehensive auditing*: Captures `SELECT`, `INSERT`, `UPDATE`, `DELETE`, DDL commands, privilege changes, and more to build a complete activity timeline.
13+
* *Flexible scope control*: Supports global, role-based, and object-level auditing, allowing fine-grained configuration by user, role, schema, or operation type.
14+
* *Seamless integration*: Reuses PostgreSQL's standard logging subsystem and works with tools like `syslog` and `logrotate`, aligning with existing log ingestion and analysis pipelines.
15+
* *Compliance ready*: Generates structured audit logs suitable for meeting regulatory requirements in finance, government, and other regulated industries.
16+
* *Security enhancement*: Records and inspects database activity to surface unauthorized access, anomalous DML, or potential data leakage risks in time.
17+
* *Operations insight*: Helps replay operational actions, locate performance bottlenecks, and support SQL tuning and incident troubleshooting.
18+
19+
== Installation and Deployment
20+
21+
=== Prerequisites
22+
23+
* A IvorySQL installation (recommended version aligned with the targeted PgAudit release).
24+
* Build toolchain: `gcc`, `make`, `tar`, etc.
25+
* Database superuser privileges to modify `ivorysql.conf` and restart the instance.
26+
27+
=== Compile and Install PgAudit
28+
29+
Taking PgAudit 18.0 as an example:
30+
31+
[source,shell]
32+
----
33+
wget https://github.com/pgaudit/pgaudit/archive/refs/tags/18.0.tar.gz
34+
tar -xf 18.0.tar.gz
35+
cd pgaudit-18.0
36+
make install USE_PGXS=1 PG_CONFIG=$PGHOME/bin/pg_config
37+
----
38+
39+
The commands above expect the environment variable `PGHOME` to point to the installed IvorySQL home directory. After installation, `pgaudit.so` will be placed in IvorySQL's extension directory.
40+
41+
=== Baseline Configuration Before Registering the Extension
42+
43+
1. Modify `ivorysql.conf` to load the plugin and configure common parameters:
44+
45+
[source,conf]
46+
----
47+
shared_preload_libraries = 'pgaudit' # Requires an instance restart
48+
pgaudit.log = 'read, write, ddl' # Sample audit scope; adjust as needed
49+
----
50+
51+
2. Restart or reload the database instance so the shared library configuration takes effect.
52+
53+
=== Create the Extension and Verify
54+
55+
[source,sql]
56+
----
57+
CREATE EXTENSION IF NOT EXISTS pgaudit;
58+
SELECT name,
59+
default_version,
60+
installed_version,
61+
comment
62+
FROM pg_available_extensions
63+
WHERE name = 'pgaudit';
64+
----
65+
66+
If the returned `installed_version` matches the expected release, the extension has been installed successfully.
67+
68+
== Usage
69+
70+
1. Execute the following SQL sample:
71+
72+
[source,sql]
73+
----
74+
CREATE TABLE audit_demo(id serial PRIMARY KEY, info text);
75+
INSERT INTO audit_demo(info) VALUES ('pgaudit test');
76+
SELECT * FROM audit_demo;
77+
UPDATE audit_demo SET info = 'pgaudit update' WHERE id = 1;
78+
DELETE FROM audit_demo WHERE id = 1;
79+
----
80+
81+
2. Check the audit logs on the database server:
82+
83+
[source,shell]
84+
----
85+
tail -f $PGDATA/log/*.log | grep 'AUDIT:'
86+
----
87+
88+
Example output:
89+
90+
[source,text]
91+
----
92+
2025-10-31 15:56:32.113 CST [11451] LOG: AUDIT: SESSION,1,1,DDL,CREATE SEQUENCE,SEQUENCE,public.audit_demo_id_seq,"CREATE TABLE audit_demo(id serial PRIMARY KEY, info text)",<not logged>
93+
2025-10-31 15:56:32.113 CST [11451] LOG: AUDIT: SESSION,1,1,DDL,CREATE TABLE,TABLE,public.audit_demo,"CREATE TABLE audit_demo(id serial PRIMARY KEY, info text)",<not logged>
94+
2025-10-31 15:56:32.113 CST [11451] LOG: AUDIT: SESSION,1,1,DDL,CREATE INDEX,INDEX,public.audit_demo_pkey,"CREATE TABLE audit_demo(id serial PRIMARY KEY, info text)",<not logged>
95+
2025-10-31 15:56:32.113 CST [11451] LOG: AUDIT: SESSION,1,1,DDL,ALTER SEQUENCE,SEQUENCE,public.audit_demo_id_seq,"CREATE TABLE audit_demo(id serial PRIMARY KEY, info text)",<not logged>
96+
2025-10-31 15:56:32.117 CST [11451] LOG: AUDIT: SESSION,2,1,WRITE,INSERT,,,INSERT INTO audit_demo(info) VALUES ('pgaudit test'),<not logged>
97+
2025-10-31 15:56:32.121 CST [11451] LOG: AUDIT: SESSION,3,1,READ,SELECT,,,SELECT * FROM audit_demo,<not logged>
98+
2025-10-31 15:56:32.122 CST [11451] LOG: AUDIT: SESSION,4,1,WRITE,UPDATE,,,UPDATE audit_demo SET info = 'pgaudit update' WHERE id = 1,<not logged>
99+
2025-10-31 15:56:32.127 CST [11451] LOG: AUDIT: SESSION,5,1,WRITE,DELETE,,,DELETE FROM audit_demo WHERE id = 1,<not logged>
100+
----
101+
102+
To record parameter values as well, enable `pgaudit.log_parameter = 'on'`:
103+
104+
[source,text]
105+
----
106+
ivorysql=# SHOW pgaudit.log_parameter;
107+
pgaudit.log_parameter
108+
-----------------------
109+
off
110+
(1 row)
111+
----

0 commit comments

Comments
 (0)