PostgreSQL 打包相關(guān)對象到一個擴展中

CREATE EXTENSION命令依賴每一個擴展都有的控制文件，控制文件必須被命名為擴展的名稱加上一個后綴.control，并且必須被放在安裝的SHAREDIR/extension目錄中。還必須至少有一個 SQL腳本文件，它遵循命名模式extension --version.sql（例如，foo--1.0.sql表示擴展foo的1.0版本）。默認情況下，腳本文件也被放置在SHAREDIR/extension目錄中，但是控制文件中可以為腳本文件指定一個不同的目錄。

一個擴展控制文件的格式與postgresql.conf文件相同，即是一個parameter_name = value賦值的列表，每行一個。允許空行和#引入的注釋。注意對任何不是單一詞或數(shù)字的值加上引號。

一個控制文件可以設置下列參數(shù)：

除了主要控制文件extension .control，一個擴展還可以有二級控制文件，它們以extension --version.control的風格命名。如果提供了二級控制文件，它們必須被放置在腳本文件的目錄中。二級控制文件遵循主要控制文件相同的格式。在安裝或更新該擴展的版本時，一個二級控制文件中設置的任何參數(shù)將覆蓋主要控制文件中的設置。不過，參數(shù)directory以及default_version不能在二級控制文件中設置。

一個擴展的SQL腳本文件能夠包含任何 SQL 命令，除了事務控制命令（BEGIN、COMMIT等）以及不能在一個事務塊中執(zhí)行的命令（如VACUUM）。這是因為腳本文件會被隱式地在一個事務塊中被執(zhí)行。

一個擴展的SQL腳本文件也能包含以\echo開始的行，它將被擴展機制忽略（當作注釋）。如果腳本文件被送給psql而不是由CREATE EXTENSION載入（見第 37.17.7 節(jié)中的示例腳本），這種機制通常被用來拋出錯誤。如果沒有這種功能，用戶可能會意外地把該擴展的內(nèi)容作為 “松散的”對象而不是一整個擴展載入，這樣的狀態(tài)恢復起來比較麻煩。

如果擴展腳本包含字符串 @extowner@，該字符串將替換為調(diào)用 CREATE EXTENSION or ALTER EXTENSION 的用戶的名稱（適當引用）。 通常，此特性會被標記為受信任的擴展使用，將所選對象的所有權(quán)分配給調(diào)用用戶，而不是引導超級用戶。 （但是，在這樣做時應該小心謹慎。例如，將c語言函數(shù)的所有權(quán)分配給非超級用戶將為該用戶創(chuàng)建一個權(quán)限升級路徑。）

盡管腳本文件可以包含指定編碼允許的任何字符，但是控制文件應該只包含純 ASCII 字符，因為PostgreSQL沒有辦法知道一個控制文件是什么編碼。實際上，如果你想在擴展的注釋中使用非 ASCII 字符只有一個問題。推薦的方法是不使用控制文件的comment參數(shù)，而是使用腳本文件中的COMMENT ON EXTENSION來設置注釋。

用戶常常希望把擴展中包含的對象載入到一個與擴展的作者所設想的不一樣的模式中。對于這種可重定位性，有三種支持的級別：

在所有情況下，腳本文件將被用search_path執(zhí)行，它最初會被設置為指向目標模式，也就是說CREATE EXTENSION做的也是等效的工作：

SET LOCAL search_path TO @extschema@, pg_temp;

這允許由這個腳本文件創(chuàng)建的對象進入到目標模式中。如果腳本文件希望，它可以改變search_path，但這種用法通常是不受歡迎的。在CREATE EXTENSION結(jié)束后，search_path會被恢復到之前的設置。

如果控制文件中給出了schema參數(shù)，目標模式就由該參數(shù)決定，否則目標模式由CREATE EXTENSION的SCHEMA選項給出，如果以上兩者都沒有給出則會用當前默認的對象創(chuàng)建模式（在調(diào)用者search_path中的第一個）。當使用擴展文件的schema參數(shù)時，如果目標模式還不存在將創(chuàng)建它，但是在另外兩種情況下它必須已經(jīng)存在。

如果在控制文件中的requires中列舉了任何先導擴展，它們的目標模式會被追加到search_path的初始設置中，遵循新擴展的目標模式。 這允許新擴展的腳本文件能夠看到它們的對象。

為了安全，pg_temp 在所有情況下都會自動添加到 search_path 的末尾。

盡管一個不可重定位的擴展能夠包含散布在多個模式中的對象，通常還是值得將意圖用于外部使用的所有對象放置在一個模式中，這被認為是該擴展的目標模式。這樣一種安排可以在依賴的擴展創(chuàng)建過程中方便地與search_path的默認設置一起工作。

某些擴展包括配置表，其中包含可以由用戶在擴展安裝后增加或修改的數(shù)據(jù)。通常，如果一個表是一個擴展的一部分，該表的定義和內(nèi)容都不會被pg_dump轉(zhuǎn)儲。但是對于一個配置表來說并不希望是這樣的行為，任何用戶做出的數(shù)據(jù)修改都需要被包括在轉(zhuǎn)儲中，否則該擴展在重載之后的行為將和轉(zhuǎn)儲之前不同。

要解決這個問題，一個擴展的腳本文件可以把一個它創(chuàng)建的表或者序列標記為配置關(guān)系，這將導致pg_dump把該表或者序列的內(nèi)容（而不是它的定義）包括在轉(zhuǎn)儲中。要這樣做，在創(chuàng)建表或序列之后調(diào)用函數(shù)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', '');

可以用這種方法標記任意數(shù)量的表或者序列。與serial或者bigserial列相關(guān)聯(lián)的序列也可以被標記。

當pg_extension_config_dump的第二個參數(shù)是一個空字符串時，該表的全部內(nèi)容都會被pg_dump轉(zhuǎn)儲。這通常只有在表被擴展腳本創(chuàng)建為初始為空時才正確。如果在表中混合有初始數(shù)據(jù)和用戶提供的數(shù)據(jù)，pg_extension_config_dump的第二個參數(shù)提供了一種WHERE條件來選擇要被轉(zhuǎn)儲的數(shù)據(jù)。例如，你可能會做

CREATE TABLE my_config (key text, value text, standard_entry boolean); SELECT pg_catalog.pg_extension_config_dump('my_config', 'WHERE NOT standard_entry');
            

并且確保只有擴展腳本創(chuàng)建的行中standard_entry才為真。

對于序列，pg_extension_config_dump的第二個參數(shù)沒有影響。

更復雜的情況（例如用戶可能會修改初始提供的數(shù)據(jù)）可以通過在配置表上創(chuàng)建觸發(fā)器來處理，觸發(fā)器將負責保證被修改的行會被正確地標記。

你可通過再次調(diào)用pg_extension_config_dump來修改與一個配置表相關(guān)的過濾條件（這通常對于一個擴展更新腳本有用）。將一個表標記為不再是一個配置表的方法是用ALTER EXTENSION ... DROP TABLE將它與擴展脫離開。

注意這些表之間的外鍵關(guān)系將會指導這些表被 pg_dump 轉(zhuǎn)儲的順序。特別地，pg_dump 將嘗試 先轉(zhuǎn)儲被引用的表再轉(zhuǎn)儲引用表。由于外鍵關(guān)系是在 CREATE EXTENSION 時間（先于數(shù)據(jù)被載入 到表中）建立的，環(huán)狀依賴還沒有建立。當環(huán)狀依賴存在時，數(shù)據(jù)將仍然被轉(zhuǎn)儲，但是該轉(zhuǎn)儲無法被 直接恢復并且必須要用戶的介入。

與serial或者bigserial列相關(guān)聯(lián)的序列需要被直接標記以轉(zhuǎn)儲它們的狀態(tài)。只標記它們的父關(guān)系不足以轉(zhuǎn)儲它們的狀態(tài)。

擴展機制的一個優(yōu)點是它提供了方便的方法來管理那些定義擴展中對象的 SQL 命令的更新。 這是通過為擴展的安裝腳本的每一個發(fā)行版本關(guān)聯(lián)一個版本名稱或者版本號實現(xiàn)的。 此外，如果你希望用戶能夠動態(tài)地把他們的數(shù)據(jù)庫從一個版本更新到下一個版本，你應該提供更新腳本來做必要的更改。 更新腳本的名稱遵循extension --old_version--target_version.sql模式 （例如，foo--1.0--1.1.sql包含著把擴展foo的版本1.0修改成版本 1.1的命令）。

假定有一個合適的更新腳本可用，命令ALTER EXTENSION UPDATE將把一個已安裝的擴展更新到指定的新版本。更新腳本運行在與CREATE EXTENSION提供給安裝腳本相同的環(huán)境中：特別是search_path會按照相同的方式設置，并且該腳本創(chuàng)建的任何新對象會被自動地加入到擴展中。此外，如果腳本選擇刪除擴展的成員對象，它們會自動與擴展解除關(guān)聯(lián)。

如果一個擴展具有二級控制文件，用于更新腳本的控制參數(shù)是那些與新目標版本相關(guān)的參數(shù)。

ALTER EXTENSION能夠執(zhí)行更新腳本的序列來實現(xiàn)一個要求的更新。例如，如果只有foo--1.0--1.1.sql和foo--1.1--2.0.sql可用，當前安裝了1.0版本并且要求更新到版本2.0， ALTER EXTENSION將依次應用它們。

PostgreSQL并不假定任何有關(guān)版本名稱的性質(zhì)：例如，它不知道1.1是否跟在1.0后面。它只是匹配可用的版本名稱并且遵照要求應用最少更新腳本的路徑進行（一個版本名稱實際上可以是不含--或者前導或后綴-的字符串）。

有時提供“降級”腳本也有用，例如foo--1.1--1.0.sql允許把版本1.1相關(guān)的改變恢復原狀。如果你這樣做，要當心降級腳本被意外應用的可能性，因為它會得到一個較短的路徑。危險的情況是，有一個跳過幾個版本的“快速路徑”更新腳本還有一個降級到該快速路徑開始點的降級腳本。先應用降級然后再應用快速路徑可能比一次升級一個版本需要更少的步驟。如果降級版本刪除了任何不可替代的對象，這將會得到意想不到的結(jié)果。

要檢查意料之外的更新路徑，可使用這個命令：

SELECT * FROM pg_extension_update_paths('extension_name');

這會為指定的擴展顯示已知的每一個可區(qū)分的版本名對，每一個版本名對還帶有一個從源版本到目標版本的更新路徑序列，如果沒有可用的更新路徑則這部份信息為NULL。該路徑顯示為用--分隔符的文本形式。如果你更喜歡數(shù)組格式，可以使用regexp_split_to_array(path,'--')。

一個已經(jīng)存在一段時間的擴展可能存在多個版本，作者將需要為它們編寫更新腳本。例如，如果你已經(jīng)發(fā)布了擴展foo的版本1.0、1.1和1.2，就應該有更新腳本foo--1.0--1.1.sql和foo--1.1--1.2.sql。在 PostgreSQL10之前，還有必要創(chuàng)建新的腳本文件foo--1.1.sql和foo--1.2.sql，它們直接構(gòu)建比較新的擴展版本，或者新的版本無法被直接安裝，而是通過先安裝1.0然后更新。那種方式是無聊的重復性工作，但是現(xiàn)在它是不必要的了，因為CREATE EXTENSION能夠自動遵循更新鏈。例如，如果只有腳本文件 foo--1.0.sql、foo--1.0--1.1.sql和foo--1.1--1.2.sql可用，那么安裝版本1.2的請求會通過按順序運行上述三個腳本來實現(xiàn)。這種處理和先安裝1.0然后更新到1.2是一樣的（和 ALTER EXTENSION UPDATE一樣，如果有多條路徑可用則優(yōu)先選擇最短的）。按這種風格安排擴展 的腳本文件可以減少生產(chǎn)小更新所需的維護工作量。

如果以這種風格維護的擴展中使用了二級（版本相關(guān)的）控制文件，記住每個版本都需要一個控制文件，即使它沒有單獨的安裝腳本，因為該控制文件將決定如何執(zhí)行到這個版本的隱式更新。例如，如果foo--1.0.control指定有requires = 'bar'，但foo的其他控制文件沒有這樣做，在從1.0更新到另一個版本時，該擴展對bar的依賴將被刪除。

廣泛分布的擴展應該很少考慮它們所占用的數(shù)據(jù)庫。 因此，以一種不會被基于搜索路徑的攻擊所破壞的安全風格編寫擴展提供的函數(shù)是合適的.

將superuser設置為真的擴展還必須考慮在其安裝和更新腳本中執(zhí)行的操作的安全危害。 對于惡意用戶來說，創(chuàng)建特洛伊木馬對象并不非常困難，這些木馬對象會影響到后續(xù)粗心編寫的擴展腳本的執(zhí)行，從而允許該用戶獲得超級用戶特權(quán)。

如果擴展標記為 trusted，則安裝用戶可以選擇其安裝模式，安裝用戶可能會有意使用不安全的模式，希望獲得超級用戶權(quán)限。 因此，從安全角度來看，受信任的擴展是非常易受攻擊的，并且必須仔細檢查其所有腳本命令，以確保不會出現(xiàn)危害。

關(guān)于安全地編寫函數(shù)的建議在下面的第 37.17.6.1 節(jié) 中, 關(guān)于安全編寫安裝腳本的建議在 第 37.17.6.2 節(jié)中提供。

這里是一個只用SQL的擴展的完整例子，一個兩個元素的組合類型，它可以在它的槽（命名為“k”和“v”）中存儲任何類型的值。非文本值會被自動強制為文本進行存儲。

腳本文件pair--1.0.sql看起來像這樣：

-- 如果腳本是由 psql 而不是 CREATE EXTENSION 執(zhí)行，則報錯
\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" 容易操作，但限定名稱更好。
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;';

控制文件pair.control看起來像這樣：

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

雖然你幾乎不會需要一個 makefile 來安裝這兩個文件到正確的目錄，你還是可以使用一個Makefile：

EXTENSION = pair
DATA = pair--1.0.sql

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

這個 makefile 依賴于PGXS，它在第 37.18 節(jié)中描述。命令make install將把控制和腳本文件安裝到pg_config報告的正確的目錄中。

一旦文件被安裝，使用 命令就可以把對象載入到任何特定的數(shù)據(jù)庫中。