44.9. ユーティリティ関数

plpyモジュールでは以下の関数も提供しています。

plpy.debug(msg, **kwargs)

plpy.log(msg, **kwargs)

plpy.info(msg, **kwargs)

plpy.notice(msg, **kwargs)

plpy.warning(msg, **kwargs)

plpy.error(msg, **kwargs)

plpy.fatal(msg, **kwargs)

plpy.errorおよびplpy.fatalは、実際にPythonの例外を発生させます。 これが捕捉されない場合、呼び出し中の問い合わせに伝わり、その結果、現在のトランザクションもしくはサブトランザクションがアボートします。 raise plpy.Error(msg)およびraise plpy.Fatal(msg)は、それぞれplpy.errorおよびplpy.fatalの呼び出しと同じですが、raise形式ではキーワード引数を渡すことができません。 他の関数は異なる重要度のメッセージを生成するだけです。 log_min_messagesとclient_min_messages設定変数は、特定の重要度のメッセージをクライアントに報告するか、サーバのログに書き出すか、あるいはその両方かを制御します。 詳細は第19章を参照してください。

msg引数は位置引数として与えられます。 後方互換性のために、2つ以上の位置引数を与えることができます。 その場合、位置引数のタプルの文字列表現がクライアントに報告されるメッセージになります。

以下のキーワードのみの引数を受け付けます。

detail

hint

sqlstate

schema_name

table_name

column_name

datatype_name

constraint_name

キーワードのみの引数として渡されたオブジェクトの文字列表現は、クライアントへ報告されるメッセージを豊富にするのに使われます。 例えば、

CREATE FUNCTION raise_custom_exception() RETURNS void AS $$
plpy.error("custom exception message",
           detail="some info about exception",
           hint="hint for users")
$$ LANGUAGE plpythonu;

=# SELECT raise_custom_exception();
ERROR:  plpy.Error: custom exception message
DETAIL:  some info about exception
HINT:  hint for users
CONTEXT:  Traceback (most recent call last):
  PL/Python function "raise_custom_exception", line 4, in <module>
    hint="hint for users")
PL/Python function "raise_custom_exception"

この他のユーティリティ関数群にはplpy.quote_literal(string)、plpy.quote_nullable(string)およびplpy.quote_ident(string)があります。 これらは項9.4で説明する組み込みの引用符付け関数と同等です。 これらはその場限りの問い合わせを構築する時に有用です。 例41-1の動的SQLと同等なPL/Pythonを以下に示します。

plpy.execute("UPDATE tbl SET %s = %s WHERE key = %s" % (
    plpy.quote_ident(colname),
    plpy.quote_nullable(newvalue),
    plpy.quote_literal(keyvalue)))