# 35.15\. 包裝相關對象到一個擴展 PostgreSQL的一個有用擴展通常包括 多個SQL對象；例如，一個新的數據類型將需要新的函數，新的操作符，以及可能的新的索引操作類。 為了簡化數據庫管理有助于收集所有這些對象到一個單一的包。 PostgreSQL調用這樣的包如_extension_。為了定義一個擴展， 你至少需要一個_腳本文件_包含SQL命令以創建擴展的對象，并且 _控制文件_指定擴展本身的幾個基本性質。如果擴展包括C代碼， 通常也是一個共享庫文件的已經編譯的C代碼。 一旦你有了這些文件，一個簡單的[CREATE EXTENSION](#calibre_link-572)命令加載對象到你的數據庫。 使用一個擴展的主要優點，不是運行 SQL腳本加載一組"loose"對象到 你的數據庫，而是PostgreSQL將一起了解擴展的對象。 你可以刪除使用單獨[DROP EXTENSION](#calibre_link-46)命令的 所有的對象（不需要維護一個單獨的"卸載"腳本）。 更有用的，pg_dump知道 它不應該轉儲擴展的單個成員對象—； 它會只包括`CREATE EXTENSION`命令創建擴展。 這大大簡化了遷移到一個新的擴展版本， 可能含有比舊版本更多的或不同的對象。 但是請注意，當裝載轉儲到一個新的數據庫的時候，你必須有擴展的控制，腳本，以及 其他可用的文件。 PostgreSQL不會讓你刪除 包含在擴展中的單獨的對象，除了減少整個擴展。 同時，雖然你可以改變擴展成員對象的定義 （例如，通過`CREATE OR REPLACE FUNCTION`函數），記住修改后的定義將不會 通過pg_dump被轉儲。這種變化通常是唯一明智的，如果 你同時在擴展的腳本文件中有相同的變化。 （但對包含配置數據的表有特殊規定；見下文。） 擴展機制也為包裝修改腳本制定規定，它調整包含擴展的SQL對象的定義。 例如，如果擴展的版本1.1增加了一個功能并且 改變相比較于1.0的另一個函數的主體，擴展可以提供一個_更新腳本_，只是那兩個改變。 `ALTER EXTENSION UPDATE`命令可以用于應用這些變化，并且 跟蹤擴展的版本，實際上是安裝在一個給定的數據庫中。 一些SQL對象是顯示在[ALTER EXTENSION](#calibre_link-573)的描述中的擴展對象。 值得注意的是，對象是數據庫集群范圍，如數據庫，角色，和表空間， 無法擴展成員，因為擴展在一個數據庫中是唯一已知的。 （雖然并不禁止擴展腳本創建這樣的對象，如果它這樣做， 他們將不會作為跟蹤擴展。）也注意到，當一個表可以是擴展成員時， 其子對象如索引不直接考慮擴展成員。 另外重要的一點是，模式可以屬于擴展，但非 反之亦然：擴展這樣有一個不合格的名稱并且不 存在任何模式"內部"。 擴展的成員對象，然而，將屬于模式， 只要適合他們的對象類型。它可能或可能不適合擁有模式成員對象的一個擴展。 ## 35.15.1\. 擴展文件 [CREATE EXTENSION](#calibre_link-572)命令依賴于每個擴展的控制文件， 它必須被命名為和帶有`.control`后綴的擴展相同。并且被放置在安裝的 `SHAREDIR/extension`目錄中。必須至少有一個SQL腳本文件， 遵循命名模式`_extension_`--`_version_`.sql （比如，擴展`foo`的版本`1.0`是`foo--1.0.sql`）。 缺省，腳本文件也被放置在`SHAREDIR/extension`目錄中； 但是控制文件可以為腳本文件聲明不同的目錄。 擴展控制文件的文件格式與`postgresql.conf`文件相同， `_parameter_name_` `=` `_value_` 任務列表，每行一個。通過允許`#`引進空行和注釋。 確保引用任何值，不是單詞或者數字。 控制文件可以設置以下參數： `directory` (`string`) 該目錄包含擴展的SQL腳本文件。 除非給定絕對路徑名，名字是相對于安裝的`SHAREDIR`目錄。 默認操作相當于指定`directory = 'extension'`。 `default_version` (`string`) 擴展的默認版本（如果在`CREATE EXTENSION`中沒有聲明版本，則一個將被安裝）。 雖然這可以被省略，如果沒有`VERSION`選項，這將導致`CREATE EXTENSION` 失敗，所以你通常不想這樣做。 `comment` (`string`) 關于擴展的注釋（任何字符串）。另外，注釋可以通過腳本文件中的[COMMENT](#calibre_link-690) 命令進行設置。 `encoding` (`string`) 通過腳本文件使用字符集編碼。如果腳本文件包含任何非-ASCII字符，則被聲明。 否則這些文件被認為數據庫編碼。 `module_pathname` (`string`) 這個參數的值將 為了每個發生在腳本文件中的`MODULE_PATHNAME`被替換。如果它不被設置， 則沒有替代。通常情況下，這是設置為 `$libdir/``_shared_library_name_`并且 `MODULE_PATHNAME`在`CREATE FUNCTION`命令中為C語言函數被使用， 因此腳本文件不需要硬線共享庫的名字。 `requires` (`string`) 這個擴展取決于擴展名列表，比如`requires = 'foo, bar'`。 這些擴展必須在可以被安裝前被安裝。 `superuser` (`boolean`) 如果這個參數是`true`（缺省），只有超級用戶可以創建擴展或者更新它到一個新版本。 如果它被設置為`false`，僅僅需要安裝過程中執行命令所需的權限或者更新腳本。 `relocatable` (`boolean`) 如果擴展初始化創建之后可能移動所包含的對象到不同的模式中， 則擴展是_浮動的_。缺省是`false`等，這個擴展是不浮動的。 參見下文獲取更多信息。 `schema` (`string`) 這個參數只能設置為非-浮動的擴展。它強制擴展被加載到精確的命名模式中，并且 沒有任何其他的。參見下文獲取更多信息。 除了初步控制文件`_extension_`.control， 擴展有在形式`_extension_`--`_version_`.control 中命名的二級控制文件。如果被提供，這些必須位于腳本文件目錄中。 二級控制文件遵循同樣格式作為初步控制文件。 當安裝或者更新擴展版本的時候，在二級控制文件中設置的任何參數覆蓋初步控制文件， 然而，不能在二級控制文件中設置參數`directory`和 `default_version`。 擴展的SQL腳本文件可以包含任何SQL命令，除了事務控制命令 (`BEGIN`，`COMMIT`等)以及不能在一個事務塊中執行的命令（比如`VACUUM`）。 這是因為腳本文件在事務塊中是隱式執行的。 擴展的SQL腳本文件也可以包含以`\echo`開頭的行， 這被擴展機制忽略（作為注釋）。如果腳本文件給psql而不是通過`CREATE EXTENSION` （參見下文例子腳本）被加載，則這個規定往往拋出錯誤。 沒有那些，用戶可能無意中加載擴展內容作為"loose"對象而不是作為擴展， 從中恢復的事態有點繁瑣。 當腳本文件可以包含指定編碼允許的任何字符時，則控制文件應該包含純ASCII， 因為PostgreSQL不知道控制文件中的編碼方式。 實踐中如果你想在擴展注釋中使用非-ASCII字符，這個是一個問題。 在這種情況下推薦做法是不使用控制文件`comment`參數，但是代替使用 腳本文件中的`COMMENT ON EXTENSION`設置comment。 ## 35.15.2\. 擴展浮動 用戶通常希望加載包含在擴展中的對象到一個擴展者考慮到的不同的模式中。 有浮動的三種支持級別。 * 一個完全可浮動擴展可移動到任何時間下的另一個模式， 即使它被加載到數據庫之后。 這是執行了`ALTER EXTENSION SET SCHEMA`命令， 它可以自動重命名所有成員對象到新模式中， 通常情況下，這是唯一可能的擴展，如果擴展包含關于任何對象在什么模式中的非內部假設。 同時，擴展的對象都必須在一個模式中（忽略不屬于任何模式的對象，如程序語言）。 通過設置控制文件中`relocatable = true`標記完全的浮動擴展。 * 一個擴展可能會在安裝過程中被重定位，但不是之后。 這是通常的情況，如果擴展的腳本文件需要參考明確的目標模式，例如 在為SQL函數設置`search_path`屬性時。對于這種擴展， 在控制文件中設置`relocatable = false`， 并且使用`@extschema@`指向腳本文件中的目標模式。 在執行腳本前該字符串的所有出現將被實際的目標模式的名字取代。 用戶可以使用`CREATE EXTENSION` 的`SCHEMA`選項設置目標模式。 * 如果擴展不支持重定位，則在控制文件中設置 `relocatable = false`，并且設置 `schema`到目標模式名。 這將防止使用`CREATE EXTENSION`的`SCHEMA`選項， 除非指定了控制文件命名的相同模式。 如果擴展包含關于模式名不能被`@extschema@`替代的內部假設， 這種選擇通常是必要的。在這種情況下`@extschema@`替代機制可用，盡管 它是有限的使用，因為模式名稱是由控制文件確定的。 在所有情況下，腳本文件與[search_path](#calibre_link-738)初始設置指向 目標模式一起被執行；也就是說，`CREATE EXTENSION`相當于： ``` SET LOCAL search_path TO @extschema@; ``` 這允許通過腳本文件創建的對象到目標模式。如果它希望，則腳本文件可以改變`search_path`。 但是這通常是不可取的，`search_path`被存儲到`CREATE EXTENSION`的 先前設置完成。 如果它被給定，目標模式是由控制文件中的`schema`參數決定的。 否則由`CREATE EXTENSION`的`SCHEMA`選項決定。 否則當前的默認對象創建模式（調用者`search_path`的第一個）。 當使用控制文件`schema`，如果它不存在，則創建目標模式， 但是在其他兩種情況下，它必須已經存在。 如果任何先決條件擴展列在控制文件的`requires`中，目標模式附加到 `search_path`的初始設置中。這允許對象對于新的擴展腳本文件時可見的。 盡管非可重定位擴展可以通過多個模式包含對象，為了外部使用把所有的對象放到一個單獨模式中是可取的， 這被認為是擴展的目標模式。在相關擴展創建過程中，這樣的安排方便`search_path`的缺省設置。 ## 35.15.3\. 擴展配置表 一些擴展包含配置表， 其中包含的數據可能安裝擴展之后被用戶添加或更改。 通常，如果一個表是擴展部分，既不是表的定義， 也不是被pg_dump備份的內容， 但這樣的行為對配置表是不需要的； 用戶修改的任何數據需要包含到備份中， 或備份和重載之后擴展會有不同的表現。 為了解決這個問題，擴展的腳本文件可以標記表，它已經作為配置表被創建，其中 將導致pg_dump包含轉儲中表的內容（不是定義）。要做到這一點， 在創建表之后調用`pg_extension_config_dump(regclass, text)`，比如： ``` CREATE TABLE my_config (key text, value text); SELECT pg_catalog.pg_extension_config_dump('my_config', ''); ``` 這種方式可以標記任何數量表。 當`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'); ``` 并且確保通過擴展腳本創建的行`standard_entry`為真。 更加復雜的情況，比如初始化提供的行可能通過用戶被修改，通過在配置表上創建觸發器被處理 以確保正確標記修改的行。 你可以通過再次調用`pg_extension_config_dump`修改與配置表相關的過濾條件。 這在擴展更新腳本中通常是有用的。 標記表不再為配置表的唯一方法是從帶有`ALTER EXTENSION ... DROP TABLE` 的擴展中分離出來。 ## 35.15.4\. 擴展更新 擴展機制的一個優點是，它提供了方便管理更新定義一個擴展對象的SQL命令的方式。 這是通過將版本的名稱或號鏈接擴展的安裝腳本的每個發布版本做到的。 此外，如果您希望用戶可以動態的從一個版本到下一個更新他們的數據庫 ，你應該提供_update scripts_執行一個版本到下一個做出必要的改變。 以下模式`_extension_`--`_oldversion_`--`_newversion_`.sql 更新腳本的名字。（比如，`foo--1.0--1.1.sql`使用命令修改擴展`foo` 的版本`1.0`到版本`1.1`）。 給定一個可用的合適更新腳本， 命令`ALTER EXTENSION UPDATE`將更新已安裝擴展到指定的新版本。 運行在相同環境中的更新腳本，`CREATE EXTENSION` 提供了安裝環境腳本：特別是，`search_path`以相同 方式進行設置，并通過腳本創建任何新的對象被自動添加到擴展中。 如果擴展有二次控制文件，控制參數用于與腳本目標（新）版本聯系的更新腳本。 更新機制可以用來解決一個重要的特殊情況： 將轉變"松散"對象的集合到一個擴展。 在擴展機制被添加到PostgreSQL(9.1中)之前， 許多人寫的擴展模塊簡化了已創建的各式各樣的未包裝的對象。 給定包含這樣對象的現有數據庫，我們怎么能轉換 對象到適當成套擴展？刪除它們然后執行純`CREATE EXTENSION`是一種方式， 但它不是可取的，如果對象有依賴關系（例如，如果有擴展創建的數據類型的表列）。 修復這種情況的方式是創建一個空的擴展，然后使用`ALTER EXTENSION ADD` 把每個預先存在的對象附屬在擴展中， 最后在當前擴展版本中創建任何新的對象， 但不在未包裝發布中。`CREATE EXTENSION` 支持帶有`FROM` `_old_version_`選項的情況。 這導致它不運行目標版本的正常安裝腳本，而是更新腳本命名 `_extension_`--`_old_version_`--`_target_version_`.sql。 虛擬版本名稱選擇使用`_old_version_`勝任擴展發起者， 盡管`未包裝`是一種常見的公約。如果你有多個以前的版本，你需要能夠更新擴展風格， 使用多個虛擬版本名稱來識別它們。 `ALTER EXTENSION`能夠執行更新 腳本文件序列以實現請求更新。例如，如果只有 `foo--1.0--1.1.sql`和`foo--1.1--2.0.sql`可用， 當目前安裝的是`1.0`時， 如果需要更新到版本`2.0`， `ALTER EXTENSION`將在序列中應用它們。 PostgreSQL不假定任何有關版本名稱的屬性： 例如，它不知道`1.1`遵循`1.0`。 它只匹配可用的版本名稱并且 遵循路徑要求應用最新的更新腳本。 （一個版本的名稱可以是不包含 `--`或前導或尾隨`-`的任意字符串。） 有時提供"downgrade"腳本是非常有用的， 例如`foo--1.1--1.0.sql`允許恢復與版本`1.1`相關的變化。 如果你這樣做了，小心downgrade腳本可能會意外地 因它產生一個較短的路徑而得以應用的可能性。 風險情況下有一個"快速路徑"更新腳本，向前跳幾個版本 以及降級腳本到快速路徑的起點。 這可能需要較少的步驟應用降級，然后快速路徑向前一次移動一個版本。 如果降級腳本刪除任何不可替代的對象，這將產生不良的結果。 為了檢查意外的更新路徑，使用這個命令： ``` SELECT * FROM pg_extension_update_paths('_extension_name_'); ``` 這顯示了已指定擴展的每對不同已知的版本名稱， 以及更新路徑序列將采取從源版本到目標版本， 或者如果沒有可用的更新路徑，則為`NULL`。 路徑以帶有`--`分隔符的文本形式顯示。 如果你喜歡數組形式，則可以使用`regexp_split_to_array(path,'--')`。 ## 35.15.5\. 擴展實例 這是一個SQL擴展的完整實例，二元復合類型可以存儲插槽中的任何類型的值， 被命名為"k"和"v"。非-文本值自動強制轉換為文本存儲。 腳本文件`pair--1.0.sql`看起來像： ``` -- complain if script is sourced in psql, rather than via CREATE EXTENSION \echo Use "CREATE EXTENSION pair" to load this file. \quit CREATE TYPE pair AS ( k text, v text ); CREATE OR REPLACE FUNCTION pair(anyelement, text) RETURNS pair LANGUAGE SQL AS 'SELECT ROW($1, $2)::pair'; CREATE OR REPLACE FUNCTION pair(text, anyelement) RETURNS pair LANGUAGE SQL AS 'SELECT ROW($1, $2)::pair'; CREATE OR REPLACE FUNCTION pair(anyelement, anyelement) RETURNS pair LANGUAGE SQL AS 'SELECT ROW($1, $2)::pair'; CREATE OR REPLACE FUNCTION pair(text, text) RETURNS pair LANGUAGE SQL AS 'SELECT ROW($1, $2)::pair;'; CREATE OPERATOR ~> (LEFTARG = text, RIGHTARG = anyelement, PROCEDURE = pair); CREATE OPERATOR ~> (LEFTARG = anyelement, RIGHTARG = text, PROCEDURE = pair); CREATE OPERATOR ~> (LEFTARG = anyelement, RIGHTARG = anyelement, PROCEDURE = pair); CREATE OPERATOR ~> (LEFTARG = text, RIGHTARG = text, PROCEDURE = pair); ``` 控制文件`pair.control`看起來像： ``` # pair extension comment = 'A key/value pair data type' default_version = '1.0' relocatable = true ``` 當你幾乎不需要makefile安裝這兩個文件到正確目錄時，你可以使用 包含下面內容的`Makefile`： ``` EXTENSION = pair DATA = pair--1.0.sql PG_CONFIG = pg_config PGXS := $(shell $(PG_CONFIG) --pgxs) include $(PGXS) ``` 這個makefile依賴于PGXS，在[Section 35.16](#calibre_link-841)中描述。 命令`make install`將安裝控制和腳本文件到正確目錄，通過pg_config 報告。 一旦安裝了這些文件，使用[CREATE EXTENSION](#calibre_link-572)命令加載對象到 任何特定數據庫。