# Trusted Language Extensions for PostgreSQL の関数リファレンス
<a name="PostgreSQL_trusted_language_extension-functions-reference"></a>

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

**Topics**
+ [pgtle.available\$1extensions](#pgtle.available_extensions)
+ [pgtle.available\$1extension\$1versions](#pgtle.available_extension_versions)
+ [pgtle.extension\$1update\$1paths](#pgtle.extension_update_paths)
+ [pgtle.install\$1extension](#pgtle.install_extension)
+ [pgtle.install\$1update\$1path](#pgtle.install_update_path)
+ [pgtle.register\$1feature](#pgtle.register_feature)
+ [pgtle.register\$1feature\$1if\$1not\$1exists](#pgtle.register_feature_if_not_exists)
+ [pgtle.set\$1default\$1version](#pgtle.set_default_version)
+ [pgtle.uninstall\$1extension(name)](#pgtle.uninstall_extension-name)
+ [pgtle.uninstall\$1extension(name, version)](#pgtle.uninstall_extension-name-version)
+ [pgtle.uninstall\$1extension\$1if\$1exists](#pgtle.uninstall_extension_if_exists)
+ [pgtle.uninstall\$1update\$1path](#pgtle.uninstall_update_path)
+ [pgtle.uninstall\$1update\$1path\$1if\$1exists](#pgtle.uninstall_update_path_if_exists)
+ [pgtle.unregister\$1feature](#pgtle.unregister_feature)
+ [pgtle.unregister\$1feature\$1if\$1exists](#pgtle.unregister_feature_if_exists)

## pgtle.available\$1extensions
<a name="pgtle.available_extensions"></a>

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

### 関数プロトタイプ
<a name="pgtle.available_extensions-prototype"></a>

```
pgtle.available_extensions()
```

### ロール
<a name="pgtle.available_extensions-role"></a>

なし。

### 引数
<a name="pgtle.available_extensions-arguments"></a>

なし。

### 出力
<a name="pgtle.available_extensions-output"></a>
+ `name` – TLE 拡張機能の名前。
+ `default_version` – バージョンを指定せずに `CREATE EXTENSION` が呼び出されたときに使用する TLE 拡張機能のバージョン。
+ `description` – TLE 拡張機能に関するさらに詳細な説明。

### 使用例
<a name="pgtle.available_extensions-usage-example"></a>

```
SELECT * FROM pgtle.available_extensions();
```

## pgtle.available\$1extension\$1versions
<a name="pgtle.available_extension_versions"></a>

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

### 関数プロトタイプ
<a name="pgtle.available_extension_versions-prototype"></a>

```
pgtle.available_extension_versions()
```

### ロール
<a name="pgtle.available_extension_versions-role"></a>

なし。

### 引数
<a name="pgtle.available_extension_versions-arguments"></a>

なし。

### 出力
<a name="pgtle.available_extension_versions-output"></a>
+ `name` – TLE 拡張機能の名前。
+ `version` – TLE 拡張機能のバージョン。
+ `superuser` – この値は、TLE 拡張機能では常に `false` です。TLE 拡張機能の作成または更新に必要なアクセス許可は、特定のデータベースに他のオブジェクトを作成する場合と同じです。
+ `trusted` – この値は、TLE 拡張機能では常に `false` です。
+ `relocatable` – この値は、TLE 拡張機能では常に `false` です。
+ `schema` – TLE 拡張機能がインストールされているスキーマの名前を指定します。
+ `requires` – この TLE 拡張機能に必要な他の拡張機能の名前を含む配列。
+ `description` – TLE 拡張機能の詳細な説明。

出力値の詳細については、PostgreSQL ドキュメントの [[Extension > Extension Files] (拡張機能 > 拡張機能ファイル) にある「関連オブジェクトのパッケージ化」](https://www.postgresql.org/docs/current/extend-extensions.html#id-1.8.3.20.11)を参照してください。

### 使用例
<a name="pgtle.available_extension_versions-example"></a>

```
SELECT * FROM pgtle.available_extension_versions();
```

## pgtle.extension\$1update\$1paths
<a name="pgtle.extension_update_paths"></a>

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

### 関数プロトタイプ
<a name="pgtle.extension_update_paths-prototype"></a>

```
pgtle.extension_update_paths(name)
```

### ロール
<a name="pgtle.extension_update_paths-role"></a>

なし。

### 引数
<a name="pgtle.extension_update_paths-arguments"></a>

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

### 出力
<a name="pgtle.extension_update_paths-output"></a>
+ `source` – 更新のソースバージョン。
+ `target` – 更新のターゲットバージョン。
+ `path` – TLE 拡張機能を `source` バージョンから `target` にアップグレードするために使用されるアップグレードパス (例えば `0.1--0.2`)。

### 使用例
<a name="pgtle.extension_update_paths-example"></a>

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

## pgtle.install\$1extension
<a name="pgtle.install_extension"></a>

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

### 関数プロトタイプ
<a name="pgtle.install_extension-prototype"></a>

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

### ロール
<a name="pgtle.install_extension-role"></a>

なし。

### 引数
<a name="pgtle.install_extension-arguments"></a>
+ `name` – TLE 拡張機能の名前。この値は `CREATE EXTENSION` を呼び出すときに使用されます。
+ `version` – TLE 拡張機能のバージョン。
+ `description` – TLE 拡張機能に関する詳細な説明。この説明は、`pgtle.available_extensions()` の `comment` フィールドに表示されます。
+ `ext` – TLE 拡張機能の内容。この値には、関数などのオブジェクトが含まれます。
+ `requires` – この TLE 拡張機能の依存関係を指定するオプションパラメータ。`pg_tle` 拡張機能は、依存関係として自動的に追加されます。

これらの引数の多くは、PostgreSQL インスタンスのファイルシステムに PostgreSQL 拡張機能をインストールするための拡張制御ファイルに含まれている引数と同じです。詳細については、PostgreSQL ドキュメントの「[拡張機能への関連オブジェクトのパッケージ化](https://www.postgresql.org/docs/current/extend-extensions.html)」にある「[拡張ファイル](http://www.postgresql.org/docs/current/extend-extensions.html#id-1.8.3.20.11)」を参照してください。

### 出力
<a name="pgtle.install_extension-output"></a>

この関数は、正常時には `OK` を、エラー時には `NULL` を返します。
+ `OK` – TLE 拡張機能がデータベースに正常にインストールされました。
+ `NULL` – TLE 拡張機能がデータベースに正常にインストールされませんでした。

### 使用例
<a name="pgtle.install_extension-example"></a>

```
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\$1update\$1path
<a name="pgtle.install_update_path"></a>

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

### 関数プロトタイプ
<a name="pgtle.install_update_path-prototype"></a>

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

### ロール
<a name="pgtle.install_update_path-role"></a>

`pgtle_admin`

### 引数
<a name="pgtle.install_update_path-arguments"></a>
+ `name` – TLE 拡張機能の名前。この値は `CREATE EXTENSION` を呼び出すときに使用されます。
+ `fromvers` – アップグレードの TLE 拡張機能のソースバージョン。
+ `tovers` – アップグレードする TLE 拡張機能のデスティネーションバージョン。
+ `ext` – 更新の内容。この値には、関数などのオブジェクトが含まれます。

### 出力
<a name="pgtle.install_update_path-output"></a>

なし。

### 使用例
<a name="pgtle.install_update_path-example"></a>

```
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\$1feature
<a name="pgtle.register_feature"></a>

この `register_feature` 関数は、指定された内部 PostgreSQL 機能を `pgtle.feature_info` テーブルに追加します。PostgreSQL フックは、内部 PostgreSQL 機能の一例です。Trusted Language Extensions 開発キットは、PostgreSQL フックの使用をサポートしています。現在、この関数は次の機能をサポートしています。
+ `passcheck` – PostgreSQL のパスワードチェック動作をカスタマイズするプロシージャまたは関数にパスワードチェックフックを登録します。

### 関数プロトタイプ
<a name="pgtle.register_feature-prototype"></a>

```
pgtle.register_feature(proc regproc, feature pg_tle_feature)
```

### ロール
<a name="pgtle.register_feature-role"></a>

`pgtle_admin` 

### 引数
<a name="pgtle.register_feature-arguments"></a>
+ `proc` – その機能に使用するストアドプロシージャまた関数の名前。
+ `feature` – 関数に登録する `pg_tle` 機能 (`passcheck` など) の名前。

### 出力
<a name="pgtle.register_feature-output"></a>

なし。

### 使用例
<a name="pgtle.register_feature-example"></a>

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

## pgtle.register\$1feature\$1if\$1not\$1exists
<a name="pgtle.register_feature_if_not_exists"></a>

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

### 関数プロトタイプ
<a name="pgtle.register_feature_if_not_exists-prototype"></a>

```
pgtle.register_feature_if_not_exists(proc regproc, feature pg_tle_feature)
```

### ロール
<a name="pgtle.register_feature_if_not_exists-role"></a>

`pgtle_admin` 

### 引数
<a name="pgtle.register_feature_if_not_exists-arguments"></a>
+ `proc` – TLE 拡張機能として使用するロジック (コード) を含むストアドプロシージャまたは関数の名前。例えば、`pw_hook` コードです。
+ `feature` – TLE 関数に登録する PostgreSQL 機能の名前。現在、使用できる機能は `passcheck` フックだけです。詳細については、「[パスワードチェックフック (passcheck)](PostgreSQL_trusted_language_extension-hooks-reference.md#passcheck_hook)」を参照してください。

### 出力
<a name="pgtle.register_feature_if_not_exists-output"></a>

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

### 使用例
<a name="pgtle.register_feature_if_not_exists-example"></a>

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

## pgtle.set\$1default\$1version
<a name="pgtle.set_default_version"></a>

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

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

### 関数プロトタイプ
<a name="pgtle.set_default_version-prototype"></a>

```
pgtle.set_default_version(name text, version text)
```

### ロール
<a name="pgtle.set_default_version-role"></a>

`pgtle_admin`

### 引数
<a name="pgtle.set_default_version-arguments"></a>
+ `name` – TLE 拡張機能の名前。この値は `CREATE EXTENSION` を呼び出すときに使用されます。
+ `version` – デフォルトに設定する TLE 拡張機能のバージョン。

### 出力
<a name="pgtle.set_default_version-output"></a>
+ `true` — デフォルトバージョンの設定が成功すると、関数は `true` を返します。
+ `ERROR` – 指定された名前またはバージョンの TLE 拡張機能が存在しない場合は、エラーメッセージを返します。

### 使用例
<a name="pgtle.set_default_version-example"></a>

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

## pgtle.uninstall\$1extension(name)
<a name="pgtle.uninstall_extension-name"></a>

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

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

### 関数プロトタイプ
<a name="pgtle.uninstall_extension-name-prototype"></a>

```
pgtle.uninstall_extension(extname text)
```

### ロール
<a name="pgtle.uninstall_extension-name-role"></a>

`pgtle_admin`

### 引数
<a name="pgtle.uninstall_extension-name-arguments"></a>
+ `extname` – アンインストールする TLE 拡張機能の名前。この名前は、特定のデータベースで使用する TLE 拡張機能をロードするために `CREATE EXTENSION` で使用される名前と同じです。

### 出力
<a name="pgtle.uninstall_extension-name-output"></a>

なし。

### 使用例
<a name="pgtle.uninstall_extension-name-example"></a>

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

## pgtle.uninstall\$1extension(name, version)
<a name="pgtle.uninstall_extension-name-version"></a>

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

### 関数プロトタイプ
<a name="pgtle.uninstall_extension-name-version-prototype"></a>

```
pgtle.uninstall_extension(extname text, version text)
```

### ロール
<a name="pgtle.uninstall_extension-name-version-role"></a>

`pgtle_admin`

### 引数
<a name="pgtle.uninstall_extension-name-version-arguments"></a>
+ `extname` – TLE 拡張機能の名前。この値は `CREATE EXTENSION` を呼び出すときに使用されます。
+ `version` - データベースからアンインストールする TLE 拡張機能のバージョン。

### 出力
<a name="pgtle.uninstall_extension-name-version-output"></a>

なし。

### 使用例
<a name="pgtle.uninstall_extension-name-version-example"></a>

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

## pgtle.uninstall\$1extension\$1if\$1exists
<a name="pgtle.uninstall_extension_if_exists"></a>

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

### 関数プロトタイプ
<a name="pgtle.uninstall_extension_if_exists-prototype"></a>

```
pgtle.uninstall_extension_if_exists(extname text)
```

### ロール
<a name="pgtle.uninstall_extension_if_exists-role"></a>

`pgtle_admin`

### 引数
<a name="pgtle.uninstall_extension_if_exists-arguments"></a>
+ `extname` – TLE 拡張機能の名前。この値は `CREATE EXTENSION` を呼び出すときに使用されます。

### 出力
<a name="pgtle.uninstall_extension_if_exists-output"></a>

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

### 使用例
<a name="pgtle.uninstall_extension_if_exists-example"></a>

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

## pgtle.uninstall\$1update\$1path
<a name="pgtle.uninstall_update_path"></a>

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

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

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

### 関数プロトタイプ
<a name="pgtle.uninstall_update_path-prototype"></a>

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

### ロール
<a name="pgtle.uninstall_update_path-role"></a>

`pgtle_admin`

### 引数
<a name="pgtle.uninstall_update_path-arguments"></a>
+ `extname` – TLE 拡張機能の名前。この値は `CREATE EXTENSION` を呼び出すときに使用されます。
+ `fromvers` – 更新パスで使用されている TLE 拡張機能のソースバージョン。
+  `tovers` – 更新パスで使用されている TLE 拡張機能の送信先バージョン。

### 出力
<a name="pgtle.uninstall_update_path-output"></a>

なし。

### 使用例
<a name="pgtle.uninstall_update_path-example"></a>

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

## pgtle.uninstall\$1update\$1path\$1if\$1exists
<a name="pgtle.uninstall_update_path_if_exists"></a>

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

### 関数プロトタイプ
<a name="pgtle.uninstall_update_path_if_exists-prototype"></a>

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

### ロール
<a name="pgtle.uninstall_update_path_if_exists-role"></a>

`pgtle_admin`

### 引数
<a name="pgtle.uninstall_update_path_if_exists-arguments"></a>
+ `extname` – TLE 拡張機能の名前。この値は `CREATE EXTENSION` を呼び出すときに使用されます。
+ `fromvers` – 更新パスで使用されている TLE 拡張機能のソースバージョン。
+ `tovers` – 更新パスで使用されている TLE 拡張機能の送信先バージョン。

### 出力
<a name="pgtle.uninstall_update_path_if_exists-output"></a>
+ `true` – 関数は TLE 拡張機能のパスを正常に更新しました。
+ `false` – この関数は TLE 拡張機能のパスを更新できませんでした。

### 使用例
<a name="pgtle.uninstall_update_path_if_exists-example"></a>

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

## pgtle.unregister\$1feature
<a name="pgtle.unregister_feature"></a>

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

### 関数プロトタイプ
<a name="pgtle.unregister_feature-prototype"></a>

```
pgtle.unregister_feature(proc regproc, feature pg_tle_features)
```

### ロール
<a name="pgtle.unregister_feature-role"></a>

`pgtle_admin`

### 引数
<a name="pgtle.unregister_feature-arguments"></a>
+ `proc` – `pg_tle` 機能に登録するストアド関数の名前。
+ `feature` – 関数に登録する `pg_tle` 機能の名前。例えば、`passcheck` は、お客様が開発した、信頼できる言語拡張機能で使用するために登録できる機能です。詳細については、「[パスワードチェックフック (passcheck)](PostgreSQL_trusted_language_extension-hooks-reference.md#passcheck_hook)」を参照してください。

### 出力
<a name="pgtle.unregister_feature-output"></a>

なし。

### 使用例
<a name="pgtle.unregister_feature-example"></a>

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

## pgtle.unregister\$1feature\$1if\$1exists
<a name="pgtle.unregister_feature_if_exists"></a>

`unregister_feature` 関数は、フックなどの `pg_tle` 機能を使用するために登録された関数を削除する方法を提供します。詳細については、「[TLE 拡張機能で PostgreSQL フックを使用する](PostgreSQL_trusted_language_extension.overview.tles-and-hooks.md)」を参照してください。機能を正常に登録解除すると `true` を返します。機能が登録されていない場合は `false` を返します。

TLE 拡張機能の `pg_tle` 機能の登録の詳細については、「[pgtle.register\$1feature](#pgtle.register_feature)」を参照してください。

### 関数プロトタイプ
<a name="pgtle.unregister_feature_if_exists-prototype"></a>

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

### ロール
<a name="pgtle.unregister_feature_if_exists-role"></a>

`pgtle_admin`

### 引数
<a name="pgtle.unregister_feature_if_exists-arguments"></a>
+ `proc` – `pg_tle` 機能を含めるように登録されたストアド関数の名前。
+ `feature` - 信頼できる言語拡張機能に登録された `pg_tle` 機能の名前。

### 出力
<a name="pgtle.unregister_feature_if_exists-output"></a>

次のように `false` または `true` を返します。
+ `true` - 関数は拡張機能から機能を正常に登録解除しました。
+ `false` – 関数は TLE 拡張機能から機能を登録解除できませんでした。

### 使用例
<a name="pgtle.unregister_feature_if_exists-example"></a>

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