配置 polar_sql_inception 自動審核 SQL - 雲原生資料庫 PolarDB

在團隊協作或自動化發布流程中，不一致的SQL規範和未經審核的變更操作可能引入資料錯誤、效能瓶頸甚至生產環境故障。polar_sql_inception外掛程式通過提供一個集審核與執行於一體的自動化SQL審核引擎，解決了這一痛點。您可以通過自訂規則，在開發、測試及發布階段自動檢查SQL，強制執行編碼通訊協定，攔截高風險操作，從而保障資料庫變更的品質與安全。

適用範圍

支援的PolarDB PostgreSQL版（相容Oracle）的版本： Oracle文法相容 2.0，且核心小版本需為2.0.14.19.38.0及以上。

說明

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

快速入門

本節將通過一個簡單的樣本，快速展示polar_sql_inception的核心功能：在3分鐘內攔截一條不符合規範的建表語句。

安裝polar_sql_inception外掛程式：在您的資料庫中執行以下命令。
```
CREATE EXTENSION polar_sql_inception;
```
設定一條審核規則，強制所有建立的表都必須包含主鍵。執行SET命令，在當前會話中開啟該規則。
```
SET polar_sql_inception.table_rule_check_primary_key = ON;
```
調用審核函數，檢查一條不含主鍵的建表語句。執行以下查詢。將execute參數設定為FALSE，表示只審核，不執行。
```
SELECT * FROM polar_sql_inception(
    sql_statements := 'CREATE TABLE users (id INT, name TEXT);',
    execute := FALSE
);
```

預期結果：審核不通過，並返回明確的錯誤資訊。 error_level欄位為error，error_message欄位清晰地指出了set a primary key的違規原因。這表明該外掛程式已成功攔截了不合規的SQL。

 sql_id |             sql_statement              |  stage  | error_level |   error_message   | affected_rows 
--------+----------------------------------------+---------+-------------+-------------------+---------------
      1 | CREATE TABLE users (id INT, name TEXT) | checked | warning     | set a primary key+|             0
        |                                        |         |             |                   |

工作原理

配置模式

您可以根據需求選擇不同的方式來組態稽核規則。

通過SET命令在當前資料庫中設定參數。此方式靈活便捷，無需重啟叢集，配置僅對應用範圍生效。

會話級配置：

-- 僅在當前會話生效
SET polar_sql_inception.dml_rule_check_dml_where = ON;

使用者層級：

-- 僅在目前使用者生效
ALTER username SET polar_sql_inception.dml_rule_check_dml_where = ON;

DATABASE層級：

-- 僅在當前資料庫生效
ALTER databasename SET polar_sql_inception.dml_rule_check_dml_where = ON;

執行模型

當您調用polar_sql_inception函數並傳入多條SQL語句時，它遵循以下處理流程：

串列處理：外掛程式按順序逐條處理SQL語句，流程為：審核語句A -> （若通過且execute為TRUE）執行語句A -> 審核語句B -> （若通過且execute為TRUE）執行語句B -> ...。
錯誤中斷：在審核或執行過程中，一旦某條語句觸發了error層級的錯誤，或者觸發了warning層級錯誤且未設定忽略警告（ignore_warning_when_executing = OFF），後續所有語句的執行流程都將被中斷。但外掛程式會繼續完成對剩餘所有語句的審核，並返回完整的審核結果。

執行SQL審核與變更

本節介紹如何通過polar_sql_inception函數執行SQL審核，並根據需要執行變更。

函數定義

polar_sql_inception(
    sql_statements TEXT,
    execute BOOLEAN DEFAULT FALSE,
    schema TEXT DEFAULT NULL
)

參數說明

參數	說明
`sql_statements`	需要審核的一條或多條SQL語句。
`execute`	是否在審核通過後執行SQL語句。預設為`FALSE`，表示只審核不執行。

操作樣本

情境一：僅審核多條SQL語句

檢查兩句CREATE TABLE語句是否符合必須有主鍵的規則，但不實際建立表。

-- 開啟“表必須有主鍵”的規則
SET polar_sql_inception.table_rule_check_primary_key = ON;

-- 調用函數進行審核
SELECT * FROM polar_sql_inception(
    sql_statements := $$
        -- 錯誤樣本：沒有主鍵
        CREATE TABLE t1 (id INT);

        -- 正確樣本：有主鍵
        CREATE TABLE t2 (id INT PRIMARY KEY);
    $$,
    execute := FALSE
);

返回結果：第一條SQL因違反規則而報錯，第二條SQL審核通過。

 sql_id |                sql_statement                 |  stage  | error_level |    error_message    | affected_rows 
--------+----------------------------------------------+---------+-------------+---------------------+---------------
      1 |                                             +| checked | warning     | set a primary key  +|             0
        |         -- 錯誤樣本：沒有主鍵                  +|         |             |                     | 
        |         CREATE TABLE t1 (id INT)             |         |             |                     | 
      2 |                                             +| checked | success     | no violations found |             0
        |                                             +|         |             |                     | 
        |         -- 正確樣本：有主鍵                    +|         |             |                     | 
        |         CREATE TABLE t2 (id INT PRIMARY KEY) |         |             |                     |

情境二：審核並通過後執行

審核一條UPDATE語句是否符合DML必須帶WHERE子句的規則，如果符合則執行它。

-- 準備測試資料
CREATE TABLE products (id INT, stock INT);
INSERT INTO products VALUES (1, 100);

-- 開啟“DML必須帶WHERE”的規則
SET polar_sql_inception.dml_rule_check_dml_where = ON;

-- 調用函數，審核並執行
SELECT * FROM polar_sql_inception(
    sql_statements := 'UPDATE products SET stock = 99 WHERE id = 1;',
    execute := TRUE
);

返回結果：SQL語句審核通過並成功執行（stage: executed且error_level: success），affected_rows欄位顯示有1行資料被更新。

 sql_id |                sql_statement                |  stage   | error_level |    error_message    | affected_rows 
--------+---------------------------------------------+----------+-------------+---------------------+---------------
      1 | UPDATE products SET stock = 99 WHERE id = 1 | executed | success     | no violations found |             1

結果集詳解

polar_sql_inception函數返回一個結果集，每一行對應您輸入的一條SQL語句的審核與執行結果。

欄位	說明
`sql_id`	SQL語句的序號，從1開始。
`sql_statement`	當前處理的SQL語句原文。
`stage`	表示當前SQL語句的處理階段： `none`：未做任何處理，通常因為前面的語句存在語法錯誤導致解析提前終止。 `checked`：已完成審核，但未執行。 executed：已執行。無論執行成功或失敗，都為此狀態。
`error_level`	表示結果的嚴重層級： `checked`階段： `success`：審核通過。 `warning`：違反了配置的規則，不影響執行。 `error`：違反了預設規則，影響執行。 `executed`階段： `success`：執行成功。 `warning`：一般情況不存在，除非您配置了`ignore_warning_when_executing`運行參數，忽略了`checked`階段的`warning`報錯進行執行，執行成功。 `error`：執行失敗。
`error_message`	詳細的審核意見或錯誤資訊。如果有多條違規，資訊會用分行符號分隔。審核通過時，返回`no violations found`。
`affected_rows`	受影響的行數。 `checked`階段：預設返回最佳化器預估的影響行數。如果開啟了`get_real_affected_rows`，會將`UPDATE`、`DELETE`、`INSERT`語句轉化為對應的`SELECT`語句並執行，以擷取實際影響行數。如果執行失敗，也會拋出`ERROR`級錯誤。 `executed`階段：返回SQL執行後真實影響的行數。

配置模板

為協助您大量設定規則參數，PolarDB提供以下設定模板。您可以根據實際業務需求，設定對應的規則。

-- 回合組態
SET polar_sql_inception.get_real_affected_rows = OFF;
SET polar_sql_inception.enable_utility_parse_analysis = ON;
SET polar_sql_inception.ignore_warning_when_executing = OFF;

-- 表相關規則
SET polar_sql_inception.table_rule_enable_partition = ON;
SET polar_sql_inception.table_rule_check_primary_key = OFF;
SET polar_sql_inception.table_rule_enable_foreign_key = ON;
SET polar_sql_inception.table_rule_merge_alter_table = OFF;
SET polar_sql_inception.table_rule_must_have_columns ='column1,column2,column3';

-- 列相關規則
SET polar_sql_inception.column_rule_max_char_length = 0;
SET polar_sql_inception.column_rule_enable_text_type = ON;
SET polar_sql_inception.column_rule_enable_json_type = ON;
SET polar_sql_inception.column_rule_check_not_null = OFF;
SET polar_sql_inception.column_rule_enable_timestamp_type = ON;
SET polar_sql_inception.column_rule_check_timestamp_default = OFF;
SET polar_sql_inception.column_rule_check_timestamp_count = OFF;
SET polar_sql_inception.column_rule_check_default_value = OFF;

-- 索引相關規則
SET polar_sql_inception.index_rule_enable_null_index_name = ON;
SET polar_sql_inception.index_rule_max_key_parts = 0;
SET polar_sql_inception.index_rule_max_primary_key_parts = 0;
SET polar_sql_inception.index_rule_check_pk_columns_only_int = OFF;
SET polar_sql_inception.index_rule_max_keys = 0;

-- 命名相關規則
SET polar_sql_inception.naming_rule_check_char = OFF;
SET polar_sql_inception.naming_rule_check_keyword = OFF;

-- DML 相關規則
SET polar_sql_inception.dml_rule_check_insert_field = OFF;
SET polar_sql_inception.dml_rule_check_dml_where = OFF;
SET polar_sql_inception.dml_rule_enable_select_star = ON;
SET polar_sql_inception.dml_rule_enable_orderby_rand = ON;
SET polar_sql_inception.dml_rule_max_update_rows = 0;
SET polar_sql_inception.dml_rule_max_insert_rows = 0;
SET polar_sql_inception.dml_rule_max_delete_rows = 0;

-- 其他規則
SET polar_sql_inception.check_schema_consistency = OFF;

配置項參考

回合組態

參數	預設值	說明
`polar_sql_inception.get_real_affected_rows`	`FALSE`	在`checked`階段，當配置`polar_sql_inception.get_real_affected_rows`時，會將`UPDATE`、`DELETE`、`INSERT`語句轉化為對應的`SELECT`語句並執行，以擷取實際影響行數，而非最佳化器的估算值。
`polar_sql_inception.enable_utility_parse_analysis`	`TRUE`	在`checked`階段，檢查SQL語句的語義錯誤。目前支援的語句：DML語句、DDL語句、`CREATE TABLE`、`ALTER TABLE`、`CREATE INDEX`、`ALTER INDEX`、`COMMENT`。說明支援的叢集版如下：（核心小版本2.0.16.10.10.0及以上）（核心小版本2.0.15.15.7.0及以上）（核心小版本2.0.14.19.38.0及以上）
`polar_sql_inception.ignore_warning_when_executing`	`FALSE`	在`executed`階段，將忽略`check`階段的`warning`報錯進行執行。說明（核心小版本2.0.16.10.11.11及以上）（核心小版本2.0.15.15.7.0及以上）（核心小版本2.0.14.19.40.0及以上）

規則配置

表相關規則

規則名稱	參數	預設值	觸發情境
表必須包含主鍵	`polar_sql_inception.table_rule_check_primary_key`	`FALSE`	`CREATE TABLE`沒有主鍵。 `ALTER TABLE`刪除主鍵約束。 `ALTER TABLE`刪除主鍵列。
禁止建立分區表	`polar_sql_inception.table_rule_enable_partition`	`TRUE`	`CREATE TABLE`建立分區表。
禁止使用外鍵	`polar_sql_inception.table_rule_enable_foreign_key`	`TRUE`	`CREATE TABLE`有外鍵約束。 `ALTER TABLE`新增外鍵約束。
表必須包含指定列	`polar_sql_inception.table_rule_must_have_columns`	`""`，即不檢查	`CREATE TABLE`必須包含某些列。 `ALTER TABLE`刪除這些列。
合并多個ALTER TABLE	`polar_sql_inception.table_rule_merge_alter_table`	`FALSE`	多個連續的針對同一個表的`ALTER TABLE`。
建立的表不存在	預設規則	-	`CREATE TABLE`表不存在。
只能有一個主鍵	預設規則	-	`CREATE TABLE`有多個主鍵。 `ALTER TABLE`在已有主鍵的情況下建立主鍵索引，或者建立兩個及以上的主鍵索引。
LIKE的表不存在	預設規則	-	`CREATE TABLE LIKE`的表不存在。
使用者必須有許可權	預設規則	-	`CREATE TABLE`所在Schema沒有許可權。 `CREATE TABLE LIKE`的表沒有許可權。 `ALTER TABLE`的表沒有許可權。

列相關規則

規則名稱	參數	預設值	觸發情境
CHAR長度限制	`polar_sql_inception.column_rule_max_char_length`	`0`，即不檢查	`CREATE TABLE`建立列為`CHAR`類型。 `ALTER TABLE`修改列為`CHAR`類型。 `ALTER TABLE`新增列為`CHAR`類型。
禁止使用TEXT類型	`polar_sql_inception.column_rule_enable_text_type`	`TRUE`	`CREATE TABLE`建立列為`TEXT`類型。 `ALTER TABLE`修改列為`TEXT`類型。 `ALTER TABLE`新增列為`TEXT`類型。
禁止使用JSON類型	`polar_sql_inception.column_rule_enable_json_type`	`TRUE`	`CREATE TABLE`建立列為`JSON`類型。 `ALTER TABLE`修改列為`JSON`類型。 `ALTER TABLE`新增列為`JSON`類型。
列必須有NOT NULL約束	`polar_sql_inception.column_rule_check_not_null`	`FALSE`	`CREATE TABLE`建立列為`NOT NULL`類型。 `ALTER TABLE`修改列為`NOT NULL`類型。 `ALTER TABLE`新增列為`NOT NULL`類型。
禁止使用TIMESTAMP類型	`polar_sql_inception.column_rule_enable_timestamp_type`	`TRUE`	`CREATE TABLE`建立列為`TIMESTAMP`類型。 `ALTER TABLE`修改列為`TIMESTAMP`類型。 `ALTER TABLE`新增列為`TIMESTAMP`類型。
TIMESTAMP列必須有預設值	`polar_sql_inception.column_rule_check_timestamp_default`	`FALSE`	`CREATE TABLE`建立`TIMESTAMP`類型列沒有預設值。 `ALTER TABLE`修改`TIMESTAMP`類型列沒有預設值。 `ALTER TABLE`新增`TIMESTAMP`類型列沒有預設值。
只能有一個 `TIMESTAMP`欄位在`DEFAULT`指定 `CURRENT_TIMESTAMP`	`polar_sql_inception.column_rule_check_timestamp_count`	`FALSE`	`CREATE TABLE`建立兩個`TIMESTAMP`類型的列，預設值為`CURRENT_TIMESTAMP`。
每個列都需要定義預設值，除了 `TIMESTAMP`/自增列/主鍵/`JSON`/計算資料行/以及`BYTEA`列以外	`polar_sql_inception.column_rule_check_default_value`	`FALSE`	`CREATE TABLE`建立列沒有預設值。 `ALTER TABLE`新增列沒有預設值。 `ALTER TABLE`刪除列的預設值。
不能有重複的列名	預設規則	-	`CREATE TABLE`有重複的列名。 `ALTER TABLE`列名重新命名與已有的列名重複。 `ALTER TABLE`新增列的列名與已有的列名重複。

索引相關規則

規則名稱	參數	預設值	觸發情境
索引必須有名稱	`polar_sql_inception.index_rule_enable_null_index_name`	`TRUE`	`CREATE INDEX`索引沒有名稱。
普通索引的列數限制	`polar_sql_inception.index_rule_max_key_parts`	`0`	`CREATE INDEX`普通索引的列數超過`max_key_parts`。
主鍵索引的列數限制	`polar_sql_inception.index_rule_max_primary_key_parts`	`0`	`CREATE TABLE`主鍵索引的列數超過參數指定列數。 `ALTER TABLE`建立的主鍵索引的列數超過參數指定列數。
主鍵列必須為整數類型	`polar_sql_inception.index_rule_check_pk_columns_only_int`	`FALSE`	`CREATE TABLE`主鍵索引所包含的列的類型不是`INT`類型。 `ALTER TABLE`建立主鍵索引所包含的列的類型不是`INT`類型。
單表索引總數限制	`polar_sql_inception.index_rule_max_keys`	`0`	`CREATE TABLE`索引的數量超過`index_rule_max_keys`。 `CREATE INDEX`已存在的索引數量已經達到`index_rule_max_keys`。 `ALTER TABLE` 建立主鍵/UNIQUE 索引，已存在的索引數量已經達到`index_rule_max_keys`。
建索引時，指定的列必須存在。	預設規則	-	`CREATE INDEX`指定列不存在。 `CREATE TABLE`主鍵/UNIQUE 指定列不存在。 `ALTER TABLE`建立主鍵索引所包含的列不存在。
建索引時，指定的列必須存在。	預設規則	-	`CREATE INDEX`索引中的列重複。 `CREATE TABLE`主鍵/UNIQUE 指定的列存在重複。 `ALTER TABLE`建立主鍵索引指定的列存在重複。
索引名不能重複	預設規則	-	`CREATE INDEX`索引名與已有的索引名重複。 `ALTER INDEX`索引重新命名與已有的索引名重複。 `ALTER TABLE`建立主鍵索引名與已有的索引名重複。
使用者必須有許可權	預設規則	-	`CREATE INDEX`的表沒有許可權。

命名相關規則

規則名稱	參數	預設值	觸發情境
檢查名稱字元集	`polar_sql_inception.naming_rule_check_char`	`FALSE`	`CREATE TABLE`表名、列名使用了[a-zA-Z0-9]之外的字元。 `CREATE INDEX`索引名使用了[a-zA-Z0-9]之外的字元。 `CREATE TABLE`表級主鍵和UNIQUE索引名使用了[a-zA-Z0-9]之外的字元。 `ALTER TABLE`重新命名表名使用了[a-zA-Z0-9]之外的字元。 `ALTER TABLE`新增的列的使用了[a-zA-Z0-9]之外的字元。 `ALTER TABLE`新增的主鍵索引使用了[a-zA-Z0-9]之外的字元。 `ALTER INDEX`重新命名索引使用了[a-zA-Z0-9_]之外的字元。
檢查是否為關鍵字	`polar_sql_inception.naming_rule_check_keyword`	`FALSE`	`CREATE TABLE`表名、列名使用了關鍵字。 `CREATE INDEX`索引名使用了關鍵字。 `CREATE TABLE`表級主鍵和UNIQUE索引名使用了關鍵字。 `ALTER TABLE`重新命名表名使用了關鍵字。 `ALTER TABLE`新增的列的使用了關鍵字。 `ALTER TABLE`新增的主鍵索引使用了關鍵字。 `ALTER INDEX` 重新命名索引使用了關鍵字。

DML 相關規則

規則名稱	參數	預設值	觸發情境
必須指定插入列表	`polar_sql_inception.dml_rule_check_insert_field`	`FALSE`	`INSERT/INSERT SELECT`沒有指定插入列表。
DML必須有WHERE條件	`polar_sql_inception.dml_rule_check_dml_where`	`FALSE`	`UPDATE/DELETE/SELECT/INSERT SELECT`沒有`WHERE`條件。
禁止使用`SELECT *`	`polar_sql_inception.dml_rule_enable_select_star`	`TRUE`	`SELECT/INSERT SELECT`使用了`SELECT *`。
禁止使用`ORDER BY RAND()`	`polar_sql_inception.dml_rule_enable_orderby_rand`	`TRUE`	`SELECT/INSERT SELECT`使用了`ORDER BY RANDOM`。
限制UPDATE行數	`polar_sql_inception.dml_rule_max_update_rows`	`0`	`UPDATE`操作影響的預估行數超過`dml_rule_max_update_rows`。
限制INSERT行數	`polar_sql_inception.dml_rule_max_insert_rows`	`0`	`INSERT`操作插入的預估行數超過`dml_rule_max_insert_rows`。
限制DELETE行數	`polar_sql_inception.dml_rule_max_delete_rows`	`0`	`DELETE`操作影響的預估行數超過`dml_rule_max_delete_rows`。
表、列必須存在	預設規則	-	DML語句中表、列並不存在。
使用者必須有許可權	預設規則	-	DML語句使用者對錶沒有許可權。

其他規則

規則名稱	參數	預設值	觸發情境
檢查Schema一致性	`polar_sql_inception.check_schema_consistency`	`FALSE`	當DML和DDL語句顯式指定的Schema與polar_sql_inception函數指定的Schema參數不一致時觸發。說明僅支援，且核心小版本需為2.0.16.10.12.0及以上