Trusted Language Extensions for PostgreSQL の関数リファレンス - Amazon Aurora
pgtle.available_extensionspgtle.available_extension_versionspgtle.extension_update_pathspgtle.install_extensionpgtle.install_update_pathpgtle.register_featurepgtle.register_feature_if_not_existspgtle.set_default_versionpgtle.uninstall_extensionpgtle.uninstall_extensionpgtle.uninstall_extension_if_existspgtle.uninstall_update_pathpgtle.uninstall_update_path_if_existspgtle.unregister_featurepgtle.unregister_feature_if_exists

Trusted Language Extensions for PostgreSQL の関数リファレンス

Trusted Language Extensions for PostgreSQL で利用できる関数については、以下のリファレンスドキュメントを参照してください。これらの関数を使用して、TLE 拡張機能、つまり Trusted Language Extensions 開発キットを使用して開発した PostgreSQL 拡張機能のインストール、登録、更新、管理を行います。

pgtle.available_extensions

pgtle.available_extensions 関数は、集合を返す関数です。データベース内の使用可能なすべての TLE 拡張機能を返します。返される各行には、1 つの TLE 拡張機能に関する情報が含まれています。

関数プロトタイプ

pgtle.available_extensions()

ロール

なし。

引数

なし。

出力

  • name – TLE 拡張機能の名前。

  • default_version – バージョンを指定せずに CREATE EXTENSION が呼び出されたときに使用する TLE 拡張機能のバージョン。

  • description – TLE 拡張機能に関するさらに詳細な説明。

使用例

SELECT * FROM pgtle.available_extensions();

pgtle.available_extension_versions

available_extension_versions 関数は、集合を返す関数です。使用可能なすべての TLE 拡張機能とそのバージョンの一覧を返します。各行には、特定のロールが必要かどうかなど、特定の TLE 拡張機能のバージョンに関する情報が含まれています。

関数プロトタイプ

pgtle.available_extension_versions()

ロール

なし。

引数

なし。

出力

  • name – TLE 拡張機能の名前。

  • version – TLE 拡張機能のバージョン。

  • superuser – この値は、TLE 拡張機能では常に false です。TLE 拡張機能の作成または更新に必要なアクセス許可は、特定のデータベースに他のオブジェクトを作成する場合と同じです。

  • trusted – この値は、TLE 拡張機能では常に false です。

  • relocatable – この値は、TLE 拡張機能では常に false です。

  • schema – TLE 拡張機能がインストールされているスキーマの名前を指定します。

  • requires – この TLE 拡張機能に必要な他の拡張機能の名前を含む配列。

  • description – TLE 拡張機能の詳細な説明。

出力値の詳細については、PostgreSQL ドキュメントの [Extension > Extension Files] (拡張機能 > 拡張機能ファイル) にある「関連オブジェクトのパッケージ化」を参照してください。

使用例

SELECT * FROM pgtle.available_extension_versions();

pgtle.extension_update_paths

extension_update_paths 関数は、集合を返す関数です。TLE 拡張機能で使用可能なすべての更新パスのリストを返します。各行には、その TLE 拡張機能で使用可能なアップグレードまたはダウングレードが含まれています。

関数プロトタイプ

pgtle.extension_update_paths(name)

ロール

なし。

引数

name – アップグレードパスを取得する TLE 拡張機能の名前。

出力

  • source – 更新のソースバージョン。

  • target – 更新のターゲットバージョン。

  • path – TLE 拡張機能を source バージョンから target にアップグレードするために使用されるアップグレードパス (例えば 0.1--0.2)。

使用例

SELECT * FROM pgtle.extension_update_paths('your-TLE');

pgtle.install_extension

この install_extension 関数を使用すると、TLE 拡張機能を構成するアーティファクトをデータベースにインストールし、その後、CREATE EXTENSION コマンドを使用して作成できます。

関数プロトタイプ

pgtle.install_extension(name text, version text, description text, ext text, requires text[] DEFAULT NULL::text[])

ロール

なし。

引数

  • name – TLE 拡張機能の名前。この値は CREATE EXTENSION を呼び出すときに使用されます。

  • version – TLE 拡張機能のバージョン。

  • description – TLE 拡張機能に関する詳細な説明。この説明は、pgtle.available_extensions() の comment フィールドに表示されます。

  • ext – TLE 拡張機能の内容。この値には、関数などのオブジェクトが含まれます。

  • requires – この TLE 拡張機能の依存関係を指定するオプションパラメータ。pg_tle 拡張機能は、依存関係として自動的に追加されます。

これらの引数の多くは、PostgreSQL インスタンスのファイルシステムに PostgreSQL 拡張機能をインストールするための拡張制御ファイルに含まれている引数と同じです。詳細については、PostgreSQL ドキュメントの「拡張機能への関連オブジェクトのパッケージ化」にある「拡張ファイル」を参照してください。

出力

この関数は、正常時には OK を、エラー時には NULL を返します。

  • OK – TLE 拡張機能がデータベースに正常にインストールされました。

  • NULL – TLE 拡張機能がデータベースに正常にインストールされませんでした。

使用例

SELECT pgtle.install_extension(
 'pg_tle_test',
 '0.1',
 'My first pg_tle extension',
$_pgtle_$
  CREATE FUNCTION my_test()
  RETURNS INT
  AS $$
    SELECT 42;
  $$ LANGUAGE SQL IMMUTABLE;
$_pgtle_$
);

pgtle.install_update_path

この install_update_path 関数は、TLE 拡張機能の 2 つの異なるバージョン間の更新パスを提供します。この機能によって、TLE 拡張機能のユーザーは ALTER EXTENSION ... UPDATE 構文を使用してバージョンを更新できます。

関数プロトタイプ

pgtle.install_update_path(name text, fromvers text, tovers text, ext text)

ロール

pgtle_admin

引数

  • name – TLE 拡張機能の名前。この値は CREATE EXTENSION を呼び出すときに使用されます。

  • fromvers – アップグレードの TLE 拡張機能のソースバージョン。

  • tovers – アップグレードする TLE 拡張機能のデスティネーションバージョン。

  • ext – 更新の内容。この値には、関数などのオブジェクトが含まれます。

出力

なし。

使用例

SELECT pgtle.install_update_path('pg_tle_test', '0.1', '0.2',
  $_pgtle_$
    CREATE OR REPLACE FUNCTION my_test()
    RETURNS INT
    AS $$
      SELECT 21;
    $$ LANGUAGE SQL IMMUTABLE;
  $_pgtle_$
);

pgtle.register_feature

この register_feature 関数は、指定された内部 PostgreSQL 機能を pgtle.feature_info テーブルに追加します。PostgreSQL フックは、内部 PostgreSQL 機能の一例です。Trusted Language Extensions 開発キットは、PostgreSQL フックの使用をサポートしています。現在、この関数は次の機能をサポートしています。

  • passcheck – PostgreSQL のパスワードチェック動作をカスタマイズするプロシージャまたは関数にパスワードチェックフックを登録します。

関数プロトタイプ

pgtle.register_feature(proc regproc, feature pg_tle_feature)

ロール

pgtle_admin

引数

  • proc – その機能に使用するストアドプロシージャまた関数の名前。

  • feature – 関数に登録する pg_tle 機能 (passcheck など) の名前。

出力

なし。

使用例

SELECT pgtle.register_feature('pw_hook', 'passcheck');

pgtle.register_feature_if_not_exists

この pgtle.register_feature_if_not_exists 関数は、指定した PostgreSQL 機能を pgtle.feature_info テーブルに追加し、その機能を使用する TLE 拡張機能またはその他のプロシージャまたは関数を識別します。フックと Trusted Language Extensions の詳細については、「TLE 拡張機能で PostgreSQL フックを使用する」を参照してください。

関数プロトタイプ

pgtle.register_feature_if_not_exists(proc regproc, feature pg_tle_feature)

ロール

pgtle_admin

引数

  • proc – TLE 拡張機能として使用するロジック (コード) を含むストアドプロシージャまたは関数の名前。例えば、pw_hook コードです。

  • feature – TLE 関数に登録する PostgreSQL 機能の名前。現在、使用できる機能は passcheck フックだけです。詳しくは、「パスワードチェックフック (passcheck)」を参照してください。

出力

指定された拡張機能を登録した後、true を返します。機能が既に登録されていた場合は false を返します。

使用例

SELECT pgtle.register_feature_if_not_exists('pw_hook', 'passcheck');

pgtle.set_default_version

set_default_version 関数では、TLE 拡張機能に default_version を指定できます。この関数を使用してアップグレードパスを定義し、そのバージョンを TLE 拡張機能のデフォルトとして指定できます。データベースユーザーが CREATE EXTENSION および ALTER EXTENSION ... UPDATE コマンドで TLE 拡張機能を指定すると、そのユーザー用にそのバージョンの TLE 拡張機能がデータベースに作成されます。

この関数は成功すると true を返します。name 引数で指定された TLE 拡張機能が存在しない場合、関数はエラーを返します。同様に、TLE 拡張機能の version が存在しない場合、関数はエラーを返します。

関数プロトタイプ

pgtle.set_default_version(name text, version text)

ロール

pgtle_admin

引数

  • name – TLE 拡張機能の名前。この値は CREATE EXTENSION を呼び出すときに使用されます。

  • version – デフォルトに設定する TLE 拡張機能のバージョン。

出力

  • true — デフォルトバージョンの設定が成功すると、関数は true を返します。

  • ERROR – 指定された名前またはバージョンの TLE 拡張機能が存在しない場合は、エラーメッセージを返します。

使用例

SELECT * FROM pgtle.set_default_version('my-extension', '1.1');

pgtle.uninstall_extension(name)

uninstall_extension 関数は、TLE 拡張機能のすべてのバージョンをデータベースから削除します。この関数により、今後の CREATE EXTENSION の呼び出しで TLE 拡張機能がインストールされないようにします。TLE 拡張機能がデータベースに存在しない場合、エラーが発生します。

uninstall_extension 関数は、データベースで現在アクティブな TLE 拡張機能を削除しません。現在アクティブな TLE 拡張機能を削除するには、DROP EXTENSION を明示的に呼び出して削除する必要があります。

関数プロトタイプ

pgtle.uninstall_extension(extname text)

ロール

pgtle_admin

引数

  • extname – アンインストールする TLE 拡張機能の名前。この名前は、特定のデータベースで使用する TLE 拡張機能をロードするために CREATE EXTENSION で使用される名前と同じです。

出力

なし。

使用例

SELECT * FROM pgtle.uninstall_extension('pg_tle_test');

pgtle.uninstall_extension(name, version)

uninstall_extension(name, version) 関数は、指定されたバージョンの TLE 拡張機能をデータベースから削除します。この関数は、CREATE EXTENSION および ALTER EXTENSION が TLE 拡張機能を指定されたバージョンにインストールまたは更新するのを防ぎます。この関数は、TLE 拡張機能の指定されたバージョンのすべての更新パスも削除します。この関数は、データベースで現在アクティブになっている TLE 拡張機能をアンインストールしません。TLE 拡張機能を削除するには、明示的に DROP EXTENSION を呼び出す必要があります。TLE 拡張機能のすべてのバージョンをアンインストールするには、「pgtle.uninstall_extension(name)」を参照してください。

関数プロトタイプ

pgtle.uninstall_extension(extname text, version text)

ロール

pgtle_admin

引数

  • extname – TLE 拡張機能の名前。この値は CREATE EXTENSION を呼び出すときに使用されます。

  • version - データベースからアンインストールする TLE 拡張機能のバージョン。

出力

なし。

使用例

SELECT * FROM pgtle.uninstall_extension('pg_tle_test', '0.2');

pgtle.uninstall_extension_if_exists

uninstall_extension_if_exists 関数は、特定のデータベースから TLE 拡張機能のすべてのバージョンを削除します。TLE 拡張機能が存在しない場合、関数は何も返しません (エラーメッセージは発生しません)。指定された拡張機能がデータベース内で現在アクティブになっている場合、この関数はその拡張機能を削除しません。この関数を使用してアーティファクトをアンインストールする前に、DROP EXTENSION を明示的に呼び出して TLE 拡張機能を削除する必要があります。

関数プロトタイプ

pgtle.uninstall_extension_if_exists(extname text)

ロール

pgtle_admin

引数

  • extname – TLE 拡張機能の名前。この値は CREATE EXTENSION を呼び出すときに使用されます。

出力

uninstall_extension_if_exists 関数は、指定された拡張機能をアンインストールした後に、true を返します。指定した拡張機能が存在しない場合、この関数は false を返します。

  • true – TLE 拡張機能をアンインストールした後に true を返します。

  • false – TLE 拡張機能がデータベースに存在しない場合に false を返します。

使用例

SELECT * FROM pgtle.uninstall_extension_if_exists('pg_tle_test');

pgtle.uninstall_update_path

uninstall_update_path 関数は TLE 拡張機能から指定された更新パスを削除します。これにより、ALTER EXTENSION ... UPDATE TO では、これを更新パスとして使用できなくなります。

TLE 拡張機能が、この更新パス上のいずれかのバージョンで現在使用されている場合、その拡張機能はデータベースに残ります。

指定された更新パスが存在しない場合、この関数はエラーを発生させます。

関数プロトタイプ

pgtle.uninstall_update_path(extname text, fromvers text, tovers text)

ロール

pgtle_admin

引数

  • extname – TLE 拡張機能の名前。この値は CREATE EXTENSION を呼び出すときに使用されます。

  • fromvers – 更新パスで使用されている TLE 拡張機能のソースバージョン。

  • tovers – 更新パスで使用されている TLE 拡張機能の送信先バージョン。

出力

なし。

使用例

SELECT * FROM pgtle.uninstall_update_path('pg_tle_test', '0.1', '0.2');

pgtle.uninstall_update_path_if_exists

uninstall_update_path_if_exists 関数は、指定された更新パスを TLE 拡張機能から削除するという点で uninstall_update_path に似ています。ただし、更新パスが存在しない場合、この関数はエラーメッセージを表示しません。代わりに、関数は false を返します。

関数プロトタイプ

pgtle.uninstall_update_path_if_exists(extname text, fromvers text, tovers text)

ロール

pgtle_admin

引数

  • extname – TLE 拡張機能の名前。この値は CREATE EXTENSION を呼び出すときに使用されます。

  • fromvers – 更新パスで使用されている TLE 拡張機能のソースバージョン。

  • tovers – 更新パスで使用されている TLE 拡張機能の送信先バージョン。

出力

  • true – 関数は TLE 拡張機能のパスを正常に更新しました。

  • false – この関数は TLE 拡張機能のパスを更新できませんでした。

使用例

SELECT * FROM pgtle.uninstall_update_path_if_exists('pg_tle_test', '0.1', '0.2');

pgtle.unregister_feature

unregister_feature 関数は、フックなどの pg_tle 機能を使用するために登録された関数を削除する方法を提供します。機能の登録については、「pgtle.register_feature」を参照してください。

関数プロトタイプ

pgtle.unregister_feature(proc regproc, feature pg_tle_features)

ロール

pgtle_admin

引数

  • proc – pg_tle 機能に登録するストアド関数の名前。

  • feature – 関数に登録する pg_tle 機能の名前。例えば、passcheck は、お客様が開発した、信頼できる言語拡張機能で使用するために登録できる機能です。詳しくは、「パスワードチェックフック (passcheck)」を参照してください。

出力

なし。

使用例

SELECT * FROM pgtle.unregister_feature('pw_hook', 'passcheck');

pgtle.unregister_feature_if_exists

unregister_feature 関数は、フックなどの pg_tle 機能を使用するために登録された関数を削除する方法を提供します。詳しくは、「TLE 拡張機能で PostgreSQL フックを使用する」を参照してください。機能を正常に登録解除すると true を返します。機能が登録されていない場合は false を返します。

TLE 拡張機能の pg_tle 機能の登録の詳細については、「pgtle.register_feature」を参照してください。

関数プロトタイプ

pgtle.unregister_feature_if_exists('proc regproc', 'feature pg_tle_features')

ロール

pgtle_admin

引数

  • proc – pg_tle 機能を含めるように登録されたストアド関数の名前。

  • feature - 信頼できる言語拡張機能に登録された pg_tle 機能の名前。

出力

次のように false または true を返します。

  • true - 関数は拡張機能から機能を正常に登録解除しました。

  • false – 関数は TLE 拡張機能から機能を登録解除できませんでした。

使用例

SELECT * FROM pgtle.unregister_feature_if_exists('pw_hook', 'passcheck');