polar_sql_inception（SQL 監査） - PolarDB - Alibaba Cloud ドキュメントセンター

チーム連携や自動リリースプロセスにおいて、SQL 標準の不統一や監査されていない変更操作は、データエラー、パフォーマンスボトルネック、あるいは本番環境での障害を引き起こす可能性があります。polar_sql_inception プラグインは、監査と実行を統合した自動 SQL 監査エンジンを提供することで、この課題に対応します。開発・テスト・リリース各フェーズで SQL を自動チェックし、コーディング標準を強制するとともに、高リスク操作をブロックすることで、データベース変更の品質とセキュリティを確保できます。

クイックスタート

このセクションでは、簡単な例を使用して polar_sql_inception のコア機能である、3 分未満で準拠していない `CREATE TABLE` 文をブロックする方法を説明します。

データベース内で次のコマンドを実行して、polar_sql_inception プラグインをインストールします。
```
CREATE EXTENSION polar_sql_inception;
```
すべての新規テーブルに主キーを必須とする監査ルールを設定します。SET コマンドを実行して、現在のセッションでこのルールを有効化します。
```
SET polar_sql_inception.table_rule_check_primary_key = ON;
```
主キーを含まない CREATE TABLE ステートメントを監査するため、監査関数を呼び出します。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;
```
- データベース単位の構成：
```
-- 現在のデータベースでのみ有効
ALTER databasename SET polar_sql_inception.dml_rule_check_dml_where = ON;
```

実行モデル

polar_sql_inception 関数を呼び出し、複数の SQL ステートメントを渡すと、以下の処理フローに従って実行されます。

逐次処理：プラグインは、SQL ステートメントを順番に 1 つずつ処理します。処理フローは以下のとおりです：ステートメント 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`	監査対象の 1 つ以上の SQL ステートメント。	機能の適用範囲と同一。
`execute`	監査成功後に SQL ステートメントを実行します。デフォルト値は `FALSE`（監査のみ、実行しない）です。	実行可能な SQL ステートメント： `INSERT`、`UPDATE`、`DELETE` `CREATE TABLE`、`ALTER TABLE`、`DROP TABLE`、`TRUNCATE TABLE` `CREATE INDEX`、`ALTER INDEX`、`DROP INDEX` `CREATE VIEW`、`DROP VIEW` `COMMENT`
`schema`	SQL ステートメントの実行時に依存するデフォルトスキーマを指定します。説明このパラメーターは、監査実行中に内部的に一時的に `SET search_path TO 'your_schema'` を実行することと等価です。実行終了後に自動的に復元され、現在のセッションの `search_path` 設定には影響しません。`NULL`（デフォルト値）の場合、現在のセッションの `search_path` を使用します。

操作例

シナリオ 1：複数の SQL ステートメントを監査のみ実行

主キー必須ルールに準拠しているかどうかを、2 つの 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 ステートメントはルール違反のためエラーを報告します。2 番目の 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) |         |             |                     |

シナリオ 2：監査通過後に実行

DML ステートメントに WHERE 句が必要というルールに準拠しているかどうかを、UPDATE ステートメントで検証します。準拠している場合は、実行します。

-- テストデータを準備
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 ステートメント 1 件に対する監査および実行結果に対応します。

フィールド	説明
`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` が含まれます。
`polar_sql_inception.ignore_warning_when_executing`	`FALSE`	`executed` ステージにおいて、`warning` エラーを `check` ステージから無視し、実行を続行します。説明

ルール構成

テーブル関連ルール

ルール名	パラメーター	デフォルト値	トリガー条件
テーブルには主キーが必要	`polar_sql_inception.table_rule_check_primary_key`	`FALSE`	`CREATE TABLE` に主キーが指定されていない。 `ALTER TABLE` で主キー制約（PRIMARY KEY constraint）が削除された。 `ALTER TABLE` でプライマリキー列（primary key column）が削除された。
パーティションテーブルは許可されない	`polar_sql_inception.table_rule_enable_partition`	`TRUE`	`CREATE TABLE` でパーティションテーブルが作成された。
外部キーは許可されない	`polar_sql_inception.table_rule_enable_foreign_key`	`TRUE`	`CREATE TABLE` に外部キー制約（foreign key constraint）が指定されている。 `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` で存在しないテーブルが参照された。
主キーは 1 つだけ許可	デフォルトルール	-	`CREATE TABLE` で複数の主キーが定義された。 `ALTER TABLE` で既に存在する主キーインデックスの上に新しい主キーインデックスが作成された、または 2 つ以上の主キーインデックスが作成された。
LIKE で参照されるテーブルが存在しない	デフォルトルール	-	`CREATE TABLE LIKE` で存在しないテーブルが参照された。
ユーザーに権限が必要	デフォルトルール	-	`CREATE TABLE` のターゲットスキーマに対する権限がない。 `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` カラムで `CURRENT_TIMESTAMP` を `DEFAULT` 句に使用できるのは 1 つまで	`polar_sql_inception.column_rule_check_timestamp_count`	`FALSE`	`CREATE TABLE` は、`CURRENT_TIMESTAMP` をデフォルト値とする2つの `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` で、既存のインデックス数が `index_rule_max_keys` に達した状態で主キーまたは UNIQUE インデックスが作成された。
インデックス作成時に指定されたカラムは存在する必要があります	デフォルトルール	-	`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 ルール

ルール名	パラメーター	デフォルト値	トリガーシナリオ
INSERT リストを指定する必要があります	`polar_sql_inception.dml_rule_check_insert_field`	`FALSE`	`INSERT/INSERT SELECT` で INSERT リストが指定されていない。
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` が使用された。
更新行数を制限	`polar_sql_inception.dml_rule_max_update_rows`	`0`	`UPDATE` で、`dml_rule_max_update_rows` を超える推定行数が影響を受ける。
挿入行数を制限	`polar_sql_inception.dml_rule_max_insert_rows`	`0`	`INSERT` で、`dml_rule_max_insert_rows` を超える推定行数が挿入される。
削除行数を制限	`polar_sql_inception.dml_rule_max_delete_rows`	`0`	`DELETE` で、`dml_rule_max_delete_rows` を超える推定行数が影響を受ける。
テーブルおよびカラムは存在する必要があります	デフォルトルール	-	DML ステートメントで存在しないテーブルまたはカラムが参照された。
ユーザーに権限が必要	デフォルトルール	-	DML ステートメントでテーブルに対する権限がない。

その他のルール

ルール名	パラメーター	デフォルト値	トリガー条件
スキーマの一貫性をチェック	`polar_sql_inception.check_schema_consistency`	`FALSE`	DML または DDL ステートメントで明示的に指定されたスキーマが、polar_sql_inception 関数の schema パラメーターで指定されたスキーマと異なる場合にトリガーされます。説明