From ce26f62ce443ae14a7c1f1750746a68b974e6c36 Mon Sep 17 00:00:00 2001 From: KOIZUMI Satoru Date: Tue, 5 Mar 2024 22:06:58 +0900 Subject: [PATCH] update extend for 16.0 --- doc/src/sgml/extend.sgml | 104 +++++++++++++++++---------------------- 1 file changed, 44 insertions(+), 60 deletions(-) diff --git a/doc/src/sgml/extend.sgml b/doc/src/sgml/extend.sgml index eb3868b6da1..a90002ed8f4 100644 --- a/doc/src/sgml/extend.sgml +++ b/doc/src/sgml/extend.sgml @@ -108,8 +108,8 @@ PostgreSQLと標準的なリレーショナルデータベースシステムの重要な違いは、PostgreSQLはカタログにより多くの情報を格納するということです。 テーブルと列に関する情報だけではなく、データ型、関数、アクセスメソッドなどの情報も格納されています。 これらのテーブルはユーザが変更できます。 -そして、PostgreSQLは操作をこれらのテーブルに基づいて行うので、PostgreSQLはユーザによって拡張することができるのです。 -これに対して、一般のデータベースシステムでは、ソースコード内にハードコーディングされたプロシージャを変えるか、DBMSベンダによって特別に書かれたモジュールをロードしなければ拡張することができません。 +そして、PostgreSQLは操作をこれらのテーブルに基づいて行うので、PostgreSQLはユーザによって拡張できるのです。 +これに対して、一般のデータベースシステムでは、ソースコード内にハードコーディングされたプロシージャを変えるか、DBMSベンダによって特別に書かれたモジュールをロードしなければ拡張できません。 @@ -126,7 +126,7 @@ structures. --> さらにPostgreSQLサーバは動的ローディングによってユーザの作成したコードを取り入れることができます。 -つまり、ユーザが新しい型か関数を実装するオブジェクトコードファイル（例えば共有ライブラリ）を指定することができ、PostgreSQLは要求された時にロードします。 +つまり、ユーザが新しい型か関数を実装するオブジェクトコードファイル（例えば共有ライブラリ）を指定でき、PostgreSQLは要求された時にロードします。 SQLで作成されたコードをサーバに追加するのはさらに簡単です。 このように演算をその場で変えることができるため、PostgreSQLは新しいアプリケーションや格納構造をラピッドプロトタイプする場合に適しています。 @@ -257,7 +257,7 @@ one-dimensional arrays. Refer to for more information. --> -配列は、全て同じ型の複数の値を保持することができます。 +配列は、全て同じ型の複数の値を保持できます。 配列型は各基本型、複合型、範囲型およびドメイン型に対して自動的に作られます。 しかし、配列の配列はありません。 この型システムにおいては多次元配列は一次元配列と同じです。 @@ -289,7 +289,7 @@ a few built-in ones exist. Refer to for more information. --> -範囲型は同じ型の二つの値を保持することができます。これらは範囲の下限と上限です。 +範囲型は同じ型の二つの値を保持できます。これらは範囲の下限と上限です。 範囲型はユーザによって作られますが、少数の組み込みの型もあります。 より詳細については、を参照してください。 @@ -335,7 +335,7 @@ --> 特殊な目的用に数個の疑似型があります。 疑似型はテーブルの列やコンテナ型の構成要素として現れることはありません。 -しかし、関数の引数や結果型を宣言する際に使用することができます。 +しかし、関数の引数や結果型を宣言する際に使用できます。 これは、型システム内で特殊な関数クラスを識別するための機構を提供します。 に既存の疑似型を列挙します。 @@ -571,7 +571,7 @@ positions declared as anyrange must all be the same range type. Likewise for anymultirange. --> -anyelementとして宣言された位置（引数もしくは戻り値）にはそれぞれ、任意の実データ型を指定することができますが、1つの呼び出しでは、これらはすべて同一の実データ型でなければなりません。 +anyelementとして宣言された位置（引数もしくは戻り値）にはそれぞれ、任意の実データ型を指定できますが、1つの呼び出しでは、これらはすべて同一の実データ型でなければなりません。 anyarrayとして宣言された位置にはそれぞれ、任意の配列データ型を持つことができますが、同様にこれらはすべて同じデータ型でなければなりません。 anyrangeと宣言された位置にはそれぞれ、同様にすべて同じ範囲型でなければなりません。 anymultirangeについても同様です。 @@ -643,7 +643,7 @@ 関数の戻り値を多様型として宣言する時、少なくとも1つの引数位置も多様でなければなりません。 そして多様の引数として与えられる実データ型がその呼び出しの実結果型を決定します。 例えば、配列添字機構がなかったとすると、subscript(anyarray, integer) returns anyelementとして添字機構を実装する関数を定義できます。 -この宣言には、最初の実引数は配列型になり、パーサはこの最初の実引数の型より正しい結果型を推論することができます。 +この宣言で最初の実引数は配列型に制約され、パーサはこの最初の実引数の型から正しい結果型を推論できます。 他にも例えば、f(anyarray) returns anyenumと宣言された関数は列挙型の配列のみを受け付けます。 @@ -846,7 +846,7 @@ RETURNS anycompatible AS ... other files available when loading such a dump into a new database. --> 拡張を使用する主な利点は、SQLスクリプトを実行するだけでデータベースに粗ななオブジェクトの群をロードできることではなく、PostgreSQLが拡張のオブジェクトをまとまったものと理解できることです。 -単一のDROP EXTENSIONコマンドでオブジェクトすべてを削除することができます（個々のアンインストールスクリプトを保守する必要はありません）。 +単一のDROP EXTENSIONコマンドでオブジェクトすべてを削除できます（個々のアンインストールスクリプトを保守する必要はありません）。 もっと有用なことは、pg_dumpが拡張の個々のメンバオブジェクトをダンプしてはならないことを把握していることです。 代わりにダンプ内にはCREATE EXTENSIONコマンドだけが含まれます。 これは、古いバージョンよりも多くのまたは異なるオブジェクトを含む可能性がある、拡張の新しいバージョンへの移行を大きく単純化します。 @@ -869,7 +869,7 @@ RETURNS anycompatible AS ... --> PostgreSQLはユーザに、拡張全体を削除させる以外に、拡張内に含まれる個々のオブジェクトを削除させません。 また、拡張のメンバオブジェクトの定義を変更する（例えば関数ではCREATE OR REPLACE FUNCTIONを介して変更する）ことはできますが、変更した定義はpg_dumpによりダンプされないことに留意してください。 -こうした変更は通常、同時に拡張のスクリプトファイルにも同じ変更を行った場合のみ認識することができます。 +こうした変更は通常、同時に拡張のスクリプトファイルにも同じ変更を行った場合のみ認識できます。 （しかし設定データを持つテーブルに対しては特殊な準備があります。を参照してください。） 本番環境では、拡張メンバオブジェクトへの変更を処理するために拡張更新スクリプトを作成するのが一般により良い方法です。 @@ -917,7 +917,7 @@ RETURNS anycompatible AS ... is actually installed in a given database. --> また拡張機構は、拡張に含まれるSQLオブジェクトの定義を調整するパッケージ調整スクリプトを準備しています。 -例えば、拡張のバージョン1.1でバージョン1.0と比べて１つの関数を追加し、他の関数本体を変更する場合、拡張の作成者はこれらの２つの変更のみを行う更新スクリプトを提供することができます。 +例えば、拡張のバージョン1.1でバージョン1.0と比べて１つの関数を追加し、他の関数本体を変更する場合、拡張の作成者はこれらの２つの変更のみを行う更新スクリプトを提供できます。 そしてALTER EXTENSION UPDATEコマンドを使用して、これらの変更を適用し、指定されたデータベース内に実際にインストールされた拡張のバージョンが何かを記録します。 @@ -993,7 +993,7 @@ RETURNS anycompatible AS ... CREATE EXTENSIONコマンドは各拡張に関して、拡張と同じ名前に.controlという拡張子を持つファイル名である必要がある、制御ファイルに依存します。 また、このファイルはインストレーションのSHAREDIR/extensionディレクトリ内に存在しなければなりません。 また少なくとも１つの、extension--version.sqlという命名規約（例えばfoo拡張のバージョン1.0ではfoo--1.0.sql）に従ったSQLスクリプトファイルが存在しなければなりません。 -デフォルトでは、このスクリプトファイルもSHAREDIR/extensionディレクトリに格納されますが、制御ファイルでスクリプトファイルを別のディレクトリに指定することができます。 +デフォルトでは、このスクリプトファイルもSHAREDIR/extensionディレクトリに格納されますが、制御ファイルでスクリプトファイルを別のディレクトリに指定できます。 @@ -1015,7 +1015,7 @@ RETURNS anycompatible AS ... -制御ファイルは以下のパラメータを設定することができます。 +制御ファイルは以下のパラメータを設定できます。 @@ -1049,7 +1049,7 @@ RETURNS anycompatible AS ... don't want to do that. --> 拡張のデフォルトのバージョン（CREATE EXTENSIONでバージョン指定がない場合にインストールされるバージョン）です。 -これは省略することができますが、その場合VERSIONオプションがないCREATE EXTENSIONは失敗します。 +これは省略できますが、その場合VERSIONオプションがないCREATE EXTENSIONは失敗します。 ですので通常省略しようとは思わないでしょう。 @@ -1068,7 +1068,7 @@ RETURNS anycompatible AS ... --> 拡張に関するコメント（任意の文字列）です。 最初に拡張が作成されるときにコメントは適用されますが、拡張が更新される間はされません（ユーザが追加したコメントを上書いてしまうため）。 -この他の方法として、スクリプトファイル内でコマンドを使用してコメントを設定することができます。 +この他の方法として、スクリプトファイル内でコマンドを使用してコメントを設定できます。 @@ -1138,8 +1138,8 @@ RETURNS anycompatible AS ... the @extschema:name@ syntax) in a way that cannot track renames. --> -《機械翻訳》このリストが依存する拡張名のextensionは、ALTER extension.SETスキーマを介してスキーマを変更することを禁止される必要があります。 -これは、このextensionのスクリプトが、名前変更を追跡できない方法で、必要なextensionのスキーマの名前を参照する場合に必要です(@extschema:名前@構文を使用)。 +この拡張が依存していて、ALTER EXTENSION ... SET SCHEMAでスキーマを変更することを禁止される拡張の名前の一覧です。 +この拡張のスクリプトが、名前変更を追跡できない方法で、(@extschema:name@構文を使って)必要な拡張のスキーマの名前を参照する場合に必要です。 @@ -1159,7 +1159,7 @@ RETURNS anycompatible AS ... script commands require superuser privileges. (Such commands would fail anyway, but it's more user-friendly to give the error up front.) --> -このパラメータがtrue（デフォルト）の場合、スーパーユーザのみが拡張を作成または新しいバージョンに更新することができます（ただし、後述するtrustedも参照してください）。 +このパラメータがtrue（デフォルト）の場合、スーパーユーザのみが拡張を作成または新しいバージョンに更新できます（ただし、後述するtrustedも参照してください）。 falseに設定されている場合は、インストール中のコマンド実行またはスクリプト更新のために必要な権限のみが必要とされます。 いずれかスクリプトコマンドがスーパーユーザ権限を必要とするなら、通常はtrueに設定されるべきです。 （このようなコマンドはいずれにせよ失敗するでしょうけれども、前もってエラーを出す方がよりユーザフレンドリです。） @@ -1211,7 +1211,7 @@ RETURNS anycompatible AS ... extension is not relocatable. See for more information. --> -拡張を最初に作成した後に拡張により含まれるオブジェクトを別のスキーマに移動することができる場合、拡張は再配置可能です。 +拡張を最初に作成した後に拡張により含まれるオブジェクトを別のスキーマに移動できる場合、拡張は再配置可能です。 デフォルトはfalse、つまり、拡張は再配置可能ではありません。 詳しくはを参照してください。 @@ -1230,7 +1230,7 @@ RETURNS anycompatible AS ... initially creating an extension, not during extension updates. See for more information. --> -このパラメータは再配置可能ではない拡張に対してのみ設定することができます。 +このパラメータは再配置可能ではない拡張に対してのみ設定できます。 拡張が指名したスキーマのみにロードされ、他にはロードされないことを強制します。 schemaパラメータは、拡張を最初に作成するときにのみ参照され、拡張が更新される間はされません。 詳しくはを参照してください。 @@ -1267,7 +1267,7 @@ RETURNS anycompatible AS ... transaction block (such as VACUUM). This is because the script files are implicitly executed within a transaction block. --> -拡張のSQLスクリプトファイルにはトランザクション制御コマンド（BEGIN、COMMITなど）およびトランザクションブロックの内側で実行することができないコマンド（VACUUMなど）を除く任意のSQLコマンドを含めることができます。 +拡張のSQLスクリプトファイルにはトランザクション制御コマンド（BEGIN、COMMITなど）およびトランザクションブロックの内側で実行できないコマンド（VACUUMなど）を除く任意のSQLコマンドを含めることができます。 スクリプトファイルが暗黙的にトランザクションブロック内で実行されるためです。 @@ -1379,20 +1379,11 @@ RETURNS anycompatible AS ... target schema using the SCHEMA option of CREATE EXTENSION. --> -《マッチ度[85.449358]》拡張はインストール処理の間再配置可能ですが、その後再配置することはできません。 +拡張はインストール処理の間再配置可能ですが、その後再配置することはできません。 通常これは、拡張のスクリプトファイルが、SQL関数用のsearch_path属性の設定など、対象のスキーマを明示的に参照する必要がある場合です。 こうした拡張では、制御ファイルでrelocatable = falseと設定し、スクリプトファイル内で対象のスキーマを参照するために@extschema@を設定してください。 -この文字列の出現箇所はすべて、スクリプトが実行される前に、実際の対象のスキーマ名に置換されます。 -ユーザはCREATE EXTENSIONのSCHEMAオプションを使用して対象のスキーマを設定することができます。 -《機械翻訳》extensionは、インストール中は再配置可能であっても、その後はケースではない場合があります。 -これは通常、extensionのスクリプトファイルニーズがターゲットスキーマを明示的にリファレンスする場合のです。 -例はSQL関数の検索_パスプロパティを設定します。 -このようなextensionの場合は、に再配置可能=偽を設定し、@extschema@を使用してスクリプト・ファイル内のを参照します。 -こののすべてのオカレンスは、実際ののに置き換えられます。 -(必要に応じて二重引用符で囲まれます。 -)スクリプトが実行されます。 -は、CREATEのオプションを使用してを設定できます。 -制御ファイルターゲットスキーマ文字列ターゲットスキーマ名前前ユーザターゲットスキーマスキーマextension +この文字列の出現箇所はすべて、スクリプトが実行される前に、(必要ならば二重引用符で括られて)実際の対象のスキーマ名に置換されます。 +ユーザはCREATE EXTENSIONのSCHEMAオプションを使用して対象のスキーマを設定できます。 @@ -1410,15 +1401,10 @@ RETURNS anycompatible AS ... substitution mechanism is available in this case too, although it is of limited use since the schema name is determined by the control file. --> -《マッチ度[88.998590]》拡張が再配置をまったくサポートしない場合、制御ファイルでrelocatable = falseを設定し、かつ、schemaを意図している対象スキーマの名前に設定してください。 +拡張が再配置をまったくサポートしない場合、制御ファイルでrelocatable = falseを設定し、かつ、schemaを意図している対象スキーマの名前に設定してください。 これは、制御ファイル内で指定されたスキーマと同じ名前が指定されていない限り、CREATE EXTENSIONのSCHEMAオプションの指定を阻止します。 この選択は通常、拡張が@extschema@を使用して置き換えることができないスキーマ名について内部的な仮定を持つ場合に必要です。 -@extschema@置換機構はこの場合でも使用することができますが、スキーマ名が制御ファイルによって決定されますので、用途は限定されます。 -《機械翻訳》extensionがサポートへの再配置をまったく行わない場合は、その制御ファイルに再配置可能=偽を設定し、目的のターゲットスキーマの名前にもスキーマを設定します。 -これにより、同じスキーマ記名的を制御ファイルで指定しない限り、CREATE extensionのスキーマオプションを使用できなくなります。 -通常、この選択が必要になるのは、extension包含のスキーマ名前に関する内部前提が@extschema@の使用で置き換えることができない場合です。 -@extschema@置換のメカニズムもこのケースで使用できますが、は回転によって決定されるため、使用には制限があります。 -スキーマ名前制御ファイル +@extschema@置換機構はこの場合でも使用できますが、スキーマ名が制御ファイルによって決定されますので、用途は限定されます。 @@ -1441,8 +1427,8 @@ SET LOCAL search_path TO @extschema@, pg_temp; but that is generally undesirable. search_path is restored to its previous setting upon completion of CREATE EXTENSION. --> -これによりスクリプトファイルで作成されるオブジェクトを対象のスキーマ内に格納することができます。 -スクリプトファイルは要望に応じてsearch_pathを変更することができますが、一般的には望まれません。 +これによりスクリプトファイルで作成されるオブジェクトを対象のスキーマ内に格納できます。 +スクリプトファイルは要望に応じてsearch_pathを変更できますが、一般的には望まれません。 CREATE EXTENSIONの実行後、search_pathは以前の設定に戻されます。 @@ -1518,15 +1504,13 @@ SET LOCAL search_path TO @extschema@, pg_temp; after yours is installed, by adding the name of the other extension to this one's no_relocate list. --> -《機械翻訳》extensionが別のextensionに属するオブジェクトを参照する場合は、それらの参照をスキーマ-修飾にすることをお勧めします。 -これを行うには、extensionのスクリプトファイルに@extschema:名前@と記述します。 -名前は他のextensionの名前です(このextensionのリストが必要にリストされている必要があります)。 -この文字列は、そのextensionのターゲットスキーマの名前(必要に応じて二重引用符で囲まれます)に置き換えられます。 -この表記では、の内の名に関するmakeハード-ワイアードの仮定の必要性は回避されますが、この表記を使用すると、他ののをこののインストールされたオブジェクトに埋め込むことができます。 -（通常、これは@extschema:@が本体や_alternations設定などのの内部で使用される場合に発生します。 -他の場合では、はの間に縮小され、その後のルックアップは必要ありません。） -他のがそれほどである場合は、インストール後に他のが再配置されないようにする必要があります。 -これを行うには、この1つのno_relocate参考文献に他のの参考文献を追加します。 +拡張が別の拡張に属するオブジェクトを参照する場合は、それらの参照をスキーマ修飾することをお勧めします。 +これを行うには、拡張のスクリプトファイルに@extschema:name@と記述します。ここで、nameは他の拡張の名前です(他の拡張はこの拡張のrequiresリストに記載されていることが必要です)。 +この文字列は、その拡張の対象スキーマの名前に(必要なら二重引用符で括られて)置き換えられます。 +この表記では、拡張のスクリプトファイルでスキーマ名が固定されているという仮定の必要性は回避されますが、この表記を使用すると、この拡張のインストールされたオブジェクトに他の拡張のスキーマ名を埋め込むことになります。 +（通常、これは@extschema:name@が関数本体やsearch_path設定などの文字列リテラルの内部で使用される場合に発生します。 +その他の場合では、オブジェクト参照は解析中にOIDへと縮小され、その後の検索は必要ありません。） +他の拡張のスキーマ名がそのように埋め込まれている場合は、インストール後に他の拡張が再配置されないようにすることが必要です。これを行うには、他の拡張の名前をこの拡張のno_relocateリストに追加します。 @@ -1637,7 +1621,7 @@ SELECT pg_catalog.pg_extension_config_dump('my_config', 'WHERE NOT standard_entr a table as no longer a configuration table is to dissociate it from the extension with ALTER EXTENSION ... DROP TABLE. --> -pg_extension_config_dumpを再度呼び出すことにより、設定テーブルに関連付いたフィルタ条件を変更することができます。 +pg_extension_config_dumpを再度呼び出すことにより、設定テーブルに関連付いたフィルタ条件を変更できます。 （通常これは拡張の更新スクリプト内で役に立つでしょう。） 設定ファイルからテーブルを取り除くように印付ける方法は、ALTER EXTENSION ... DROP TABLEを用いてテーブルを拡張から分離するしかありません。 @@ -1732,7 +1716,7 @@ SELECT pg_catalog.pg_extension_config_dump('my_config', 'WHERE NOT standard_entr update to version 2.0 is requested when 1.0 is currently installed. --> -ALTER EXTENSIONは、要求される更新を実現するために更新スクリプトを連続して実行することができます。 +ALTER EXTENSIONは、要求される更新を実現するために更新スクリプトを連続して実行できます。 例えばfoo--1.0--1.1.sqlとfoo--1.1--2.0.sqlのみが利用可能であるとすると、現在1.0がインストールされている時にバージョン2.0への更新が要求された場合、ALTER EXTENSIONはこれらを順番に適用します。 @@ -1791,7 +1775,7 @@ SELECT * FROM pg_extension_update_paths('extension_name これは指定した拡張の個々の既知のバージョン名の組み合わせをそれぞれ、元のバージョンから対象のバージョンへ進む時に取られる更新経路順、またはもし利用できる更新経路がなければNULLを付けて、表示します。 経路は--を区切り文字として使用したテキスト形式で表示されます。 -配列形式の方が良ければregexp_split_to_array(path,'--')を使用することができます。 +配列形式の方が良ければregexp_split_to_array(path,'--')を使用できます。 @@ -2085,7 +2069,7 @@ SELECT * FROM pg_extension_update_paths('extension_name ここでは、SQLのみの拡張の完全な例を示します。 -kとvという名称の２つの要素からなる複合型であり、そのスロットには任意の型の値を格納することができるものです。 +kとvという名称の２つの要素からなる複合型であり、そのスロットには任意の型の値を格納できるものです。 格納の際テキスト以外の値は自動的にテキストに変換されます。 @@ -2143,7 +2127,7 @@ relocatable = false While you hardly need a makefile to install these two files into the correct directory, you could use a Makefile containing this: --> -これらの２つのファイルを正しいディレクトリにインストールするためにmakefileを作成する必要はほとんどありませんが、以下を含むMakefileを使用することができます。 +これらの２つのファイルを正しいディレクトリにインストールするためにmakefileを作成する必要はほとんどありませんが、以下を含むMakefileを使用できます。 EXTENSION = pair @@ -2203,8 +2187,8 @@ include $(PGXS) own build system. --> PostgreSQL拡張モジュールの配布を考えているのであれば、移植可能な構築システムを準備することはかなり難しいものになるかもしれません。 -このためPostgreSQLインストレーションは単純な拡張モジュールをすでにインストールされているサーバに対して簡単に構築することができるように、PGXSと呼ばれる拡張向けの構築基盤を提供します。 -PGXSは主にCコードを含む拡張を意図していますが、SQLのみからなる拡張でも使用することができます。 +このためPostgreSQLインストレーションは単純な拡張モジュールをすでにインストールされているサーバに対して簡単に構築できるように、PGXSと呼ばれる拡張向けの構築基盤を提供します。 +PGXSは主にCコードを含む拡張を意図していますが、SQLのみからなる拡張でも使用できます。 PGXSがPostgreSQLと相互に作用する任意のソフトウェアを構築するために使用できるような万能な構築システムを意図したものではないことに注意してください。 これは単に、単純なサーバ拡張用の一般的な構築規則を自動化するものです。 より複雑なパッケージでは、独自の構築システムを作成する必要があるかもしれません。 @@ -2299,7 +2283,7 @@ include $(PGXS) -以下の変数も設定することができます。 +以下の変数も設定できます。 @@ -2682,7 +2666,7 @@ TAPテストを実行する必要があるかどうかを定義するオプシ このmakefileをMakefileとして拡張を保管するディレクトリ内に保管してください。 その後コンパイルするためにmakeを、モジュールをインストールするためにmake installを行うことができます。 デフォルトでは、PATHの中で最初に見つかるpg_configプログラムが対応するPostgreSQLインストレーション用に拡張はコンパイルされ、インストールされます。 -makefileまたはmakeのコマンドラインのいずれかでPG_CONFIGを別のpg_configプログラムを指し示すように設定することで、別のインストレーションを使用することができます。 +makefileまたはmakeのコマンドラインのいずれかでPG_CONFIGを別のpg_configプログラムを指し示すように設定することで、別のインストレーションを使用できます。