The <command>CREATE EXTENSION</command> command relies on a control file for each extension, which must be named the same as the extension with a suffix of <literal>.control</literal>, and must be placed in the installation's <literal>SHAREDIR/extension</literal> directory. There must also be at least one <acronym>SQL</acronym> script file, which follows the naming pattern <literal><replaceable>extension</replaceable>&#45;-<replaceable>version</replaceable>.sql</literal> (for example, <literal>foo&#45;-1.0.sql</literal> for version <literal>1.0</literal> of extension <literal>foo</literal>). By default, the script file(s) are also placed in the <literal>SHAREDIR/extension</literal> directory; but the control file can specify a different directory for the script file(s). CREATE EXTENSIONコマンドは各拡張に関して、拡張と同じ名前に.controlという拡張子を持つファイル名である必要がある、制御ファイルに依存します。 また、このファイルはインストレーションのSHAREDIR/extensionディレクトリ内に存在しなければなりません。 また少なくとも１つの、extension--version.sqlという命名規約（例えばfoo拡張のバージョン1.0ではfoo--1.0.sql）に従ったSQLスクリプトファイルが存在しなければなりません。 デフォルトでは、このスクリプトファイルもSHAREDIR/extensionディレクトリに格納されますが、制御ファイルでスクリプトファイルを別のディレクトリに指定できます。

The file format for an extension control file is the same as for the <filename>postgresql.conf</filename> file, namely a list of <replaceable>parameter_name</replaceable> <literal>=</literal> <replaceable>value</replaceable> assignments, one per line. Blank lines and comments introduced by <literal>#</literal> are allowed. Be sure to quote any value that is not a single word or number. 拡張の制御ファイルのファイル書式はpostgresql.confファイルと同じです。 すなわち、parameter_name = valueという代入を１行当たり１つ記述します。 空行および#から始まるコメントが許されます。 単一の単語または数字ではない値にはすべて引用符で確実にくくってください。

A control file can set the following parameters: 制御ファイルは以下のパラメータを設定できます。

In addition to the primary control file <literal><replaceable>extension</replaceable>.control</literal>, an extension can have secondary control files named in the style <literal><replaceable>extension</replaceable>&#45;-<replaceable>version</replaceable>.control</literal>. If supplied, these must be located in the script file directory. Secondary control files follow the same format as the primary control file. Any parameters set in a secondary control file override the primary control file when installing or updating to that version of the extension. However, the parameters <varname>directory</varname> and <varname>default_version</varname> cannot be set in a secondary control file. 主制御ファイルextension.controlに加え、拡張はextension--version.controlという形の名前の副制御ファイルを持つことができます。 これらを提供する場合は、スクリプトファイルディレクトリに格納しなければなりません。 副制御ファイルは主制御ファイルと同じ書式に従います。 拡張の対応するバージョンをインストールまたは更新する時、副制御ファイル内で設定されるパラメータはいずれも、主制御ファイルを上書きします。 しかしdirectoryおよびdefault_versionパラメータは副制御ファイルで設定することはできません。

An extension's <acronym>SQL</acronym> script files can contain any SQL commands, except for transaction control commands (<command>BEGIN</command>, <command>COMMIT</command>, etc.) and commands that cannot be executed inside a transaction block (such as <command>VACUUM</command>). This is because the script files are implicitly executed within a transaction block. 拡張のSQLスクリプトファイルにはトランザクション制御コマンド（BEGIN、COMMITなど）およびトランザクションブロックの内側で実行できないコマンド（VACUUMなど）を除く任意のSQLコマンドを含めることができます。 スクリプトファイルが暗黙的にトランザクションブロック内で実行されるためです。

An extension's <acronym>SQL</acronym> script files can also contain lines beginning with <literal>\echo</literal>, which will be ignored (treated as comments) by the extension mechanism. This provision is commonly used to throw an error if the script file is fed to <application>psql</application> rather than being loaded via <command>CREATE EXTENSION</command> (see example script in <xref linkend="extend-extensions-example"/>). Without that, users might accidentally load the extension's contents as <quote>loose</quote> objects rather than as an extension, a state of affairs that's a bit tedious to recover from. 拡張のSQLスクリプトファイルには、\echoから始まる行を含めることができます。 この行は拡張の機構では無視されます（コメントとして扱われます）。 これは、このスクリプトがCREATE EXTENSION（38.17.7のスクリプト例を参照）ではなくpsqlに渡された場合にエラーを発生するために一般的に使用するために用意されたものです。 これがないと、ユーザは間違って拡張としてではなく、「まとまっていない」オブジェクトとして拡張の内容をロードしてしまい、復旧が多少困難な状態になる可能性があります。

If the extension script contains the string <literal>@extowner@</literal>, that string is replaced with the (suitably quoted) name of the user calling <command>CREATE EXTENSION</command> or <command>ALTER EXTENSION</command>. Typically this feature is used by extensions that are marked trusted to assign ownership of selected objects to the calling user rather than the bootstrap superuser. (One should be careful about doing so, however. For example, assigning ownership of a C-language function to a non-superuser would create a privilege escalation path for that user.) 拡張のスクリプトに文字列@extowner@が含まれている場合、この文字列は、CREATE EXTENSIONやALTER EXTENSIONを実行した（適切にクォートされた）ユーザ名で置き換えられます。 典型的には、この機能はtrustedと印付けされた拡張が選択されたオブジェクトにサービス起動のスーパーユーザではなく実行したユーザを所有者として割り当てる際に使われます。 （とはいえ、このようにするには注意深くすべきです。例えば、C言語関数の所有者を非スーパーユーザに割り当てると、そのユーザに権限昇格の経路を作ることになるでしょう）

While the script files can contain any characters allowed by the specified encoding, control files should contain only plain ASCII, because there is no way for <productname>PostgreSQL</productname> to know what encoding a control file is in. In practice this is only an issue if you want to use non-ASCII characters in the extension's comment. Recommended practice in that case is to not use the control file <varname>comment</varname> parameter, but instead use <command>COMMENT ON EXTENSION</command> within a script file to set the comment. スクリプトファイルは指定した符号化方式で認められる任意の文字を含めることができますが、PostgreSQLが制御ファイルの符号化方式が何かを把握する方法がありませんので、制御ファイルにはASCII文字のみを含めなければなりません。 実際には、拡張のコメントに非ASCII文字を含めたい場合にのみ、これが問題になります。 このような場合には、制御ファイルのcommentを使用せず、代わりにコメントを設定するためにスクリプトファイル内でCOMMENT ON EXTENSIONを使用することを勧めます。

Users often wish to load the objects contained in an extension into a different schema than the extension's author had in mind. There are three supported levels of relocatability: ユーザは拡張に含まれるオブジェクトを拡張の作成者が考えていたスキーマとは別のスキーマにロードしたいとよく考えます。 再配置性に関して３つのレベルがサポートされます。

In all cases, the script file will be executed with <xref linkend="guc-search-path"/> initially set to point to the target schema; that is, <command>CREATE EXTENSION</command> does the equivalent of this: すべての場合において、スクリプトファイルは対象のスキーマを指し示すようにあらかじめ設定したsearch_pathを用いて実行されます。 つまりCREATE EXTENSIONは以下と同じことを行います。

SET LOCAL search_path TO @extschema@, pg_temp;

This allows the objects created by the script file to go into the target schema. The script file can change <varname>search_path</varname> if it wishes, but that is generally undesirable. <varname>search_path</varname> is restored to its previous setting upon completion of <command>CREATE EXTENSION</command>. これによりスクリプトファイルで作成されるオブジェクトを対象のスキーマ内に格納できます。 スクリプトファイルは要望に応じてsearch_pathを変更できますが、一般的には望まれません。 CREATE EXTENSIONの実行後、search_pathは以前の設定に戻されます。

The target schema is determined by the <varname>schema</varname> parameter in the control file if that is given, otherwise by the <literal>SCHEMA</literal> option of <command>CREATE EXTENSION</command> if that is given, otherwise the current default object creation schema (the first one in the caller's <varname>search_path</varname>). When the control file <varname>schema</varname> parameter is used, the target schema will be created if it doesn't already exist, but in the other two cases it must already exist. 対象のスキーマは制御ファイル内のschemaパラメータがあればこのパラメータにより決定されます。 このパラメータがなければ、CREATE EXTENSIONのSCHEMAがあればこの値で決まり、これ以外の場合は現在のデフォルトのオブジェクト生成用スキーマ（呼び出し元のsearch_pathの最初のもの）になります。 制御ファイルのschemaパラメータが使用される時、対象のスキーマが存在しない場合は作成されますが、これ以外の２つの場合ではすでに存在しなければなりません。

If any prerequisite extensions are listed in <varname>requires</varname> in the control file, their target schemas are added to the initial setting of <varname>search_path</varname>, following the new extension's target schema. This allows their objects to be visible to the new extension's script file. 何らかの事前に必要な拡張が制御ファイル内のrequiresに列挙されていた場合、それらのターゲットスキーマは新しい機能拡張のターゲットスキーマに続いてsearch_pathの初期設定に追加されます。 これにより新しい拡張のスクリプトファイルからそれらのオブジェクトが可視になります。

For security, <literal>pg_temp</literal> is automatically appended to the end of <varname>search_path</varname> in all cases. 安全のため、全てのケースにおいてpg_tempは自動的にsearch_pathの最後に追記されます。

Although a non-relocatable extension can contain objects spread across multiple schemas, it is usually desirable to place all the objects meant for external use into a single schema, which is considered the extension's target schema. Such an arrangement works conveniently with the default setting of <varname>search_path</varname> during creation of dependent extensions. 再配置不可能な拡張は複数スキーマにまたがるオブジェクトを含めることができますが、通常、外部使用を意図したオブジェクトはすべて単一スキーマに格納することが望まれます。 この単一スキーマが拡張の対象のスキーマとみなされます。 こうした調整は依存する拡張を作成する間、デフォルトのsearch_path設定を都合に合わせて扱います。

If an extension references objects belonging to another extension, it is recommended to schema-qualify those references. To do that, write <literal>@extschema:<replaceable>name</replaceable>@</literal> in the extension's script file, where <replaceable>name</replaceable> is the name of the other extension (which must be listed in this extension's <literal>requires</literal> list). This string will be replaced by the name (double-quoted if necessary) of that extension's target schema. Although this notation avoids the need to make hard-wired assumptions about schema names in the extension's script file, its use may embed the other extension's schema name into the installed objects of this extension. (Typically, that happens when <literal>@extschema:<replaceable>name</replaceable>@</literal> is used inside a string literal, such as a function body or a <varname>search_path</varname> setting. In other cases, the object reference is reduced to an OID during parsing and does not require subsequent lookups.) If the other extension's schema name is so embedded, you should prevent the other extension from being relocated after yours is installed, by adding the name of the other extension to this one's <literal>no_relocate</literal> list. 拡張が別の拡張に属するオブジェクトを参照する場合は、それらの参照をスキーマ修飾することをお勧めします。 これを行うには、拡張のスクリプトファイルに@extschema:name@と記述します。ここで、nameは他の拡張の名前です(他の拡張はこの拡張のrequiresリストに記載されていることが必要です)。 この文字列は、その拡張の対象スキーマの名前に(必要なら二重引用符で括られて)置き換えられます。 この表記では、拡張のスクリプトファイルでスキーマ名が固定されているという仮定の必要性は回避されますが、この表記を使用すると、この拡張のインストールされたオブジェクトに他の拡張のスキーマ名を埋め込むことになります。 （通常、これは@extschema:name@が関数本体やsearch_path設定などの文字列リテラルの内部で使用される場合に発生します。 その他の場合では、オブジェクト参照は解析中にOIDへと縮小され、その後の検索は必要ありません。） 他の拡張のスキーマ名がそのように埋め込まれている場合は、インストール後に他の拡張が再配置されないようにすることが必要です。これを行うには、他の拡張の名前をこの拡張のno_relocateリストに追加します。

Some extensions include configuration tables, which contain data that might be added or changed by the user after installation of the extension. Ordinarily, if a table is part of an extension, neither the table's definition nor its content will be dumped by <application>pg_dump</application>. But that behavior is undesirable for a configuration table; any data changes made by the user need to be included in dumps, or the extension will behave differently after a dump and restore. 一部の拡張は、拡張をインストールした後でユーザにより追加または変更される可能性があるデータを持つ設定テーブルを含みます。 通常、テーブルが拡張の一部である場合、テーブル定義もその内容もpg_dumpによりダンプされません。 しかしこの振舞いは設定テーブルの場合望まれません。 ユーザによってなされたデータ変更はダンプ内に含まれなければなりません。 さもないとダンプしリストアした後で拡張の動作が変わってしまいます。

To solve this problem, an extension's script file can mark a table or a sequence it has created as a configuration relation, which will cause <application>pg_dump</application> to include the table's or the sequence's contents (not its definition) in dumps. To do that, call the function <function>pg_extension_config_dump(regclass, text)</function> after creating the table or the sequence, for example この問題を解消するために、拡張のスクリプトファイルでは設定リレーションとして作成されるテーブル、またはシーケンスに印を付け、pg_dumpにテーブルの、またはシーケンスの内容をダンプに含める（定義は含まれません）ようにさせることができます。 このためには、以下の例のようにテーブル、またはシーケンスを作成した後にpg_extension_config_dump(regclass, text)関数を呼び出してください。

CREATE TABLE my_config (key text, value text);
CREATE SEQUENCE my_config_seq;

SELECT pg_catalog.pg_extension_config_dump('my_config', '');
SELECT pg_catalog.pg_extension_config_dump('my_config_seq', '');

Any number of tables or sequences can be marked this way. Sequences associated with <type>serial</type> or <type>bigserial</type> columns can be marked as well. 任意数のテーブル、またはシーケンスをこの方法で印付けることができます。 serial列またはbigserial列に関連したシーケンスが、同様に印付けることができます。

When the second argument of <function>pg_extension_config_dump</function> is an empty string, the entire contents of the table are dumped by <application>pg_dump</application>. This is usually only correct if the table is initially empty as created by the extension script. If there is a mixture of initial data and user-provided data in the table, the second argument of <function>pg_extension_config_dump</function> provides a <literal>WHERE</literal> condition that selects the data to be dumped. For example, you might do pg_extension_config_dumpの第２引数が空文字列である場合、テーブルのすべての内容がpg_dumpによりダンプされます。 これは、拡張のスクリプトによって作成された初期段階においてテーブルが空である場合のみ正しいものです。 テーブルの中で初期データとユーザが提供したデータが混在する場合、pg_extension_config_dumpの第２引数においてダンプすべきデータを選択するWHERE条件を提供します。 以下に例を示します。

CREATE TABLE my_config (key text, value text, standard_entry boolean);

SELECT pg_catalog.pg_extension_config_dump('my_config', 'WHERE NOT standard_entry');

and then make sure that <structfield>standard_entry</structfield> is true only in the rows created by the extension's script. このようにした後、拡張のスクリプトで作成される行のみでstandard_entryが確実に真になるようにします。

For sequences, the second argument of <function>pg_extension_config_dump</function> has no effect. シーケンスにおいて、pg_extension_config_dumpの第２引数は何も影響を及ぼしません。

More complicated situations, such as initially-provided rows that might be modified by users, can be handled by creating triggers on the configuration table to ensure that modified rows are marked correctly. 初期状態で提供される行がユーザによって変更されるようなもっと複雑な状況では、設定テーブルに対するトリガを作成して、変更された行が正しく印付けられることを確実にするように取り扱うことができます。

You can alter the filter condition associated with a configuration table by calling <function>pg_extension_config_dump</function> again. (This would typically be useful in an extension update script.) The only way to mark a table as no longer a configuration table is to dissociate it from the extension with <command>ALTER EXTENSION ... DROP TABLE</command>. pg_extension_config_dumpを再度呼び出すことにより、設定テーブルに関連付いたフィルタ条件を変更できます。 （通常これは拡張の更新スクリプト内で役に立つでしょう。） 設定ファイルからテーブルを取り除くように印付ける方法は、ALTER EXTENSION ... DROP TABLEを用いてテーブルを拡張から分離するしかありません。

Note that foreign key relationships between these tables will dictate the order in which the tables are dumped out by pg_dump. Specifically, pg_dump will attempt to dump the referenced-by table before the referencing table. As the foreign key relationships are set up at CREATE EXTENSION time (prior to data being loaded into the tables) circular dependencies are not supported. When circular dependencies exist, the data will still be dumped out but the dump will not be able to be restored directly and user intervention will be required. このテーブルとの外部キーの関係は、テーブルがpg_dumpによってダンプされる順序に影響します。 特に、pg_dumpは参照しているテーブルの前に参照されているテーブルをダンプしようとします。 外部キーの関係はCREATE EXTENSION時(データがテーブルにロードされる前)に設定されますので、循環依存はサポートされません。 循環依存が存在すれば、データはダンプされますが、そのダンプを直接はリストアできず、ユーザの介入が必要になります。

Sequences associated with <type>serial</type> or <type>bigserial</type> columns need to be directly marked to dump their state. Marking their parent relation is not enough for this purpose. serial列またはbigserial列に関連したシーケンスは、それらの状態をダンプするために直接印付けする必要があります。 親リレーションを印付けすることは、この目的に十分ではありません。

One advantage of the extension mechanism is that it provides convenient ways to manage updates to the SQL commands that define an extension's objects. This is done by associating a version name or number with each released version of the extension's installation script. In addition, if you want users to be able to update their databases dynamically from one version to the next, you should provide <firstterm>update scripts</firstterm> that make the necessary changes to go from one version to the next. Update scripts have names following the pattern <literal><replaceable>extension</replaceable>&#45;-<replaceable>old_version</replaceable>&#45;-<replaceable>target_version</replaceable>.sql</literal> (for example, <literal>foo&#45;-1.0&#45;-1.1.sql</literal> contains the commands to modify version <literal>1.0</literal> of extension <literal>foo</literal> into version <literal>1.1</literal>). 拡張機構の１つの利点は、拡張のオブジェクトを定義するSQLコマンドの更新を簡便に管理する方法を提供していることです。 これは、拡張のインストール用スクリプトのリリース版それぞれにバージョン名称またはバージョン番号を関連付けることで行われます。 さらに、ユーザにあるバージョンから次のバージョンへ動的にデータベースを更新させることができるようにしたい場合、あるバージョンから次のバージョンまでの間に行われる必要な変更を行う更新スクリプトを提供しなければなりません。 更新スクリプトはextension--old_version--target_version.sqlというパターンに従った名前（例えば、foo--1.0--1.1.sqlはfoo拡張のバージョン1.0からバージョン1.1に変更するコマンドを含みます。）を持たなければなりません。

Given that a suitable update script is available, the command <command>ALTER EXTENSION UPDATE</command> will update an installed extension to the specified new version. The update script is run in the same environment that <command>CREATE EXTENSION</command> provides for installation scripts: in particular, <varname>search_path</varname> is set up in the same way, and any new objects created by the script are automatically added to the extension. Also, if the script chooses to drop extension member objects, they are automatically dissociated from the extension. 適切な更新スクリプトが利用可能である場合、ALTER EXTENSION UPDATEコマンドはインストール済みの拡張を指定した新しいバージョンへ更新します。 更新スクリプトは、CREATE EXTENSIONがインストール用スクリプト向けに提供する環境と同じ環境で実行されます。 具体的にはsearch_pathは同じ方法で設定され、スクリプトにより作成される新しいオブジェクトはすべて自動的に拡張に追加されます。 また、スクリプトが拡張のメンバーオブジェクトを削除する場合には、それらのメンバーオブジェクトは拡張から自動的に分離されます。

If an extension has secondary control files, the control parameters that are used for an update script are those associated with the script's target (new) version. 拡張が副制御ファイルを持つ場合、更新スクリプトで使用される制御パラメータは、スクリプトの対象の（新しい）バージョンに関連付けされたものになります。

<command>ALTER EXTENSION</command> is able to execute sequences of update script files to achieve a requested update. For example, if only <literal>foo&#45;-1.0&#45;-1.1.sql</literal> and <literal>foo&#45;-1.1&#45;-2.0.sql</literal> are available, <command>ALTER EXTENSION</command> will apply them in sequence if an update to version <literal>2.0</literal> is requested when <literal>1.0</literal> is currently installed. ALTER EXTENSIONは、要求される更新を実現するために更新スクリプトを連続して実行できます。 例えばfoo--1.0--1.1.sqlとfoo--1.1--2.0.sqlのみが利用可能であるとすると、現在1.0がインストールされている時にバージョン2.0への更新が要求された場合、ALTER EXTENSIONはこれらを順番に適用します。

<productname>PostgreSQL</productname> doesn't assume anything about the properties of version names: for example, it does not know whether <literal>1.1</literal> follows <literal>1.0</literal>. It just matches up the available version names and follows the path that requires applying the fewest update scripts. (A version name can actually be any string that doesn't contain <literal>&#45;-</literal> or leading or trailing <literal>-</literal>.) PostgreSQLはバージョン名称の特性についてまったく仮定を行いません。 例えば1.0の次が1.1であるかどうかを把握しません。 これは利用可能なバージョン名をかみ合わせ、もっとも少ない数の更新スクリプトを適用するために必要な経路を続けるだけです。 （バージョン名には、--を含まず先頭または最後に-が付かなければ、任意の文字を取ることができます。）

Sometimes it is useful to provide <quote>downgrade</quote> scripts, for example <literal>foo&#45;-1.1&#45;-1.0.sql</literal> to allow reverting the changes associated with version <literal>1.1</literal>. If you do that, be careful of the possibility that a downgrade script might unexpectedly get applied because it yields a shorter path. The risky case is where there is a <quote>fast path</quote> update script that jumps ahead several versions as well as a downgrade script to the fast path's start point. It might take fewer steps to apply the downgrade and then the fast path than to move ahead one version at a time. If the downgrade script drops any irreplaceable objects, this will yield undesirable results. 「ダウングレード」スクリプトを提供することが便利な場合があります。 例えばfoo--1.1--1.0.sqlは、バージョン1.1に関連した変更を元に戻すことができます。 この場合、ダウングレードスクリプトがより短いパスを生成するために、予期せず適用されてしまう可能性に注意してください。 複数のバージョンをまたがって更新する「近道」更新スクリプトと近道の開始バージョンへのダウングレードスクリプトが存在する場合に危険性があります。 ダウングレードしてから近道となる更新スクリプトを実行する方が、バージョンを１つずつ進めるよりも少ない処理で済んでしまうかもしれません。 ダウングレードスクリプトが取り返しがつかないオブジェクトを何か削除してしまう場合、望まない結果になってしまいます。

To check for unexpected update paths, use this command: 想定外の更新経路かどうかを検査するためには、以下のコマンドを使用してください。

SELECT * FROM pg_extension_update_paths('extension_name');

This shows each pair of distinct known version names for the specified extension, together with the update path sequence that would be taken to get from the source version to the target version, or <literal>NULL</literal> if there is no available update path. The path is shown in textual form with <literal>&#45;-</literal> separators. You can use <literal>regexp_split_to_array(path,'&#45;-')</literal> if you prefer an array format. これは指定した拡張の個々の既知のバージョン名の組み合わせをそれぞれ、元のバージョンから対象のバージョンへ進む時に取られる更新経路順、またはもし利用できる更新経路がなければNULLを付けて、表示します。 経路は--を区切り文字として使用したテキスト形式で表示されます。 配列形式の方が良ければregexp_split_to_array(path,'--')を使用できます。

An extension that has been around for awhile will probably exist in several versions, for which the author will need to write update scripts. For example, if you have released a <literal>foo</literal> extension in versions <literal>1.0</literal>, <literal>1.1</literal>, and <literal>1.2</literal>, there should be update scripts <filename>foo&#45;-1.0&#45;-1.1.sql</filename> and <filename>foo&#45;-1.1&#45;-1.2.sql</filename>. Before <productname>PostgreSQL</productname> 10, it was necessary to also create new script files <filename>foo&#45;-1.1.sql</filename> and <filename>foo&#45;-1.2.sql</filename> that directly build the newer extension versions, or else the newer versions could not be installed directly, only by installing <literal>1.0</literal> and then updating. That was tedious and duplicative, but now it's unnecessary, because <command>CREATE EXTENSION</command> can follow update chains automatically. For example, if only the script files <filename>foo&#45;-1.0.sql</filename>, <filename>foo&#45;-1.0&#45;-1.1.sql</filename>, and <filename>foo&#45;-1.1&#45;-1.2.sql</filename> are available then a request to install version <literal>1.2</literal> is honored by running those three scripts in sequence. The processing is the same as if you'd first installed <literal>1.0</literal> and then updated to <literal>1.2</literal>. (As with <command>ALTER EXTENSION UPDATE</command>, if multiple pathways are available then the shortest is preferred.) Arranging an extension's script files in this style can reduce the amount of maintenance effort needed to produce small updates. 以前から存在している拡張は、おそらく複数のバージョンに渡って存在しているので、拡張の作者は更新スクリプトを開発する必要性が出てきます。 たとえば、拡張fooがバージョン1.0、1.1、1.2をリリースしていたとすると、更新スクリプトfoo--1.0--1.1.sqlとfoo--1.1--1.2.sqlが存在しなければなりません。 PostgreSQL 10より前では、新しい拡張のバージョンを直接作成するスクリプトファイルfoo--1.1.sqlとfoo--1.2.sqlも新規に作る必要がありました。 これらがないと、新しいバージョンの拡張を直接インストールすることはできず、1.0をインストールしてから更新するしかありませんでした。 それにはうんざりしますし、また冗長です。 しかし、今ではCREATE EXTENSIONが自動的に更新連鎖を追跡してくるので、それは不要になりました。 たとえば、foo--1.0.sql、foo--1.0--1.1.sql、foo--1.1--1.2.sqlだけしかない場合、バージョン1.2のインストールのリクエストは、これらのスクリプトを順に実行することによって達成されます。 この手順は、最初に1.0をインストールして、1.2にアップデートする場合でも同じです。 （ALTER EXTENSION UPDATEは、複数の手順がある場合には、最短の手順を選びます。） この方法で拡張のスクリプトを調整することにより、小さな更新を複数作成するための保守の手間を減らすことができます。

If you use secondary (version-specific) control files with an extension maintained in this style, keep in mind that each version needs a control file even if it has no stand-alone installation script, as that control file will determine how the implicit update to that version is performed. For example, if <filename>foo&#45;-1.0.control</filename> specifies <literal>requires = 'bar'</literal> but <literal>foo</literal>'s other control files do not, the extension's dependency on <literal>bar</literal> will be dropped when updating from <literal>1.0</literal> to another version. この方法で保守している拡張に二次的な（バージョン固有の）制御ファイルがある場合は、スタンドアローンのインストールスクリプトがない場合でも、各バージョンで制御ファイルが必要になることに注意してください。 そのバージョンへと更新する暗黙的な方法を、制御ファイルが決定するからです。 たとえば、foo--1.0.controlがrequires = 'bar'を指定しているのに、fooの他の制御ファイルが指定していないとすると、1.0から他のバージョンに更新した際にbarへの依存性が削除されてしまうでしょう。

Widely-distributed extensions should assume little about the database they occupy. Therefore, it's appropriate to write functions provided by an extension in a secure style that cannot be compromised by search-path-based attacks. 広く配布される拡張では、インストールされるデータベースについて想定していないはずです。 このため、拡張はサーチパスに基づく攻撃を受けないよう、安全なスタイルで拡張によって提供される関数記述するのが適切です。

An extension that has the <varname>superuser</varname> property set to true must also consider security hazards for the actions taken within its installation and update scripts. It is not terribly difficult for a malicious user to create trojan-horse objects that will compromise later execution of a carelessly-written extension script, allowing that user to acquire superuser privileges. superuserプロパティを真にしている拡張はインストールや更新スクリプトの中で行われるアクションのセキュリティ面での危険も考慮しなければなりません。 悪意あるユーザが不用意に書かれた拡張スクリプトを悪用してトロイの木馬を作成し、スーパーユーザ権限を獲得できるようにすることは、そう難しくありません。

If an extension is marked <varname>trusted</varname>, then its installation schema can be selected by the installing user, who might intentionally use an insecure schema in hopes of gaining superuser privileges. Therefore, a trusted extension is extremely exposed from a security standpoint, and all its script commands must be carefully examined to ensure that no compromise is possible. 拡張がtrustedと印付けされている場合、そのインストールスキーマはインストールするユーザにより選択できます。そのユーザはスーパーユーザ権限を獲得することを狙って意図的に安全でないスキーマを使用するかもしれません。 したがって、trustedの拡張はセキュリティ観点から極めて危険で、そのスクリプトのコマンドは危険性がないことを確実にするため注意深く検証されなければなりません。

Advice about writing functions securely is provided in <xref linkend="extend-extensions-security-funcs"/> below, and advice about writing installation scripts securely is provided in <xref linkend="extend-extensions-security-scripts"/>. 関数を安全に書くためのアドバイスは以下のリンクから提供されます。 38.17.6.1 また、インストールスクリプトを安全に書くためのアドバイスは以下のリンクから提供されます。 38.17.6.2

Here is a complete example of an <acronym>SQL</acronym>-only extension, a two-element composite type that can store any type of value in its slots, which are named <quote>k</quote> and <quote>v</quote>. Non-text values are automatically coerced to text for storage. ここでは、SQLのみの拡張の完全な例を示します。 「k」と「v」という名称の２つの要素からなる複合型であり、そのスロットには任意の型の値を格納できるものです。 格納の際テキスト以外の値は自動的にテキストに変換されます。

The script file <filename>pair&#45;-1.0.sql</filename> looks like this: pair--1.0.sqlスクリプトファイルは以下のようになります。

-- complain if script is sourced in psql, rather than via CREATE EXTENSION

-- スクリプトが、CREATE EXTENSION経由ではなく、psqlのソースとして使われた場合には文句を言う
\echo Use "CREATE EXTENSION pair" to load this file. \quit

CREATE TYPE pair AS ( k text, v text );

CREATE FUNCTION pair(text, text)
RETURNS pair LANGUAGE SQL AS 'SELECT ROW($1, $2)::@extschema@.pair;';

CREATE OPERATOR ~> (LEFTARG = text, RIGHTARG = text, FUNCTION = pair);

-- "SET search_path" is easy to get right, but qualified names perform better.
CREATE FUNCTION lower(pair)
RETURNS pair LANGUAGE SQL
AS 'SELECT ROW(lower($1.k), lower($1.v))::@extschema@.pair;'
SET search_path = pg_temp;

CREATE FUNCTION pair_concat(pair, pair)
RETURNS pair LANGUAGE SQL
AS 'SELECT ROW($1.k OPERATOR(pg_catalog.||) $2.k,
               $1.v OPERATOR(pg_catalog.||) $2.v)::@extschema@.pair;';

The control file <filename>pair.control</filename> looks like this: pair.control制御ファイルは以下のようになります。

# pair extension
comment = 'A key/value pair data type'
default_version = '1.0'
# cannot be relocatable because of use of @extschema@
relocatable = false

While you hardly need a makefile to install these two files into the correct directory, you could use a <filename>Makefile</filename> containing this: これらの２つのファイルを正しいディレクトリにインストールするためにmakefileを作成する必要はほとんどありませんが、以下を含むMakefileを使用できます。

EXTENSION = pair
DATA = pair--1.0.sql

PG_CONFIG = pg_config
PGXS := $(shell $(PG_CONFIG) --pgxs)
include $(PGXS)

This makefile relies on <acronym>PGXS</acronym>, which is described in <xref linkend="extend-pgxs"/>. The command <literal>make install</literal> will install the control and script files into the correct directory as reported by <application>pg_config</application>. このmakefileは38.18で説明するPGXSに依存します。 make installコマンドは制御ファイルとスクリプトファイルをpg_configで報告される正しいディレクトリにインストールします。

Once the files are installed, use the <command>CREATE EXTENSION</command> command to load the objects into any particular database. ファイルがインストールされた後、CREATE EXTENSIONコマンドを使用してオブジェクトを任意の特定のデータベースにロードしてください。