2025年9月25日: PostgreSQL 18 釋出!
支援的版本:當前18)/ 17 / 16 / 15 / 14 / 13
開發版本:devel
不支援的版本:12 / 11 / 10 / 9.6 / 9.5 / 9.4 / 9.3 / 9.2 / 9.1 / 9.0 / 8.4 / 8.3 / 8.2

19.1. 設定引數 #

19.1.1. 引數名稱和值 #

所有引數名稱均不區分大小寫。每個引數接受五種型別之一的值:布林值、字串、整數、浮點數或列舉值(enum)。型別決定了設定引數的語法。

  • 布林值: 值可以寫成 onofftruefalseyesno10(均不區分大小寫)或其中任何一個的不歧義字首。

  • 字串: 通常,將值放在單引號中,並將值內的任何單引號加倍。如果值是簡單的數字或識別符號,則通常可以省略引號。(在某些上下文中,匹配 SQL 關鍵字的值需要加引號。)

  • 數字(整數和浮點數): 數字引數可以用常規的整數和浮點數格式指定;如果引數是整數型別,則小數部分會四捨五入到最接近的整數。整數引數還接受十六進位制輸入(以 0x 開頭)和八進位制輸入(以 0 開頭),但這些格式不能包含小數。不要使用千位分隔符。除非是十六進位制輸入,否則不需要加引號。

  • 帶單位的數字: 某些數字引數具有隱式單位,因為它們描述的是記憶體或時間量。單位可能是位元組、千位元組、塊(通常是八千位元組)、毫秒、秒或分鐘。這些設定的無單位數值將使用該設定的預設單位,該單位可從 pg_settings.unit 中獲悉。為了方便起見,可以為設定指定顯式單位,例如時間值的 '120 ms',它們將被轉換為引數的實際單位。請注意,要使用此功能,該值必須以字串形式(帶引號)寫入。單位名稱區分大小寫,數字值和單位之間可以有空格。

    • 有效的記憶體單位是 B(位元組)、kB(千位元組)、MB(兆位元組)、GB(吉位元組)和 TB(太位元組)。記憶體單位的乘數是 1024,而不是 1000。

    • 有效的 time 單位是 us(微秒)、ms(毫秒)、s(秒)、min(分鐘)、h(小時)和 d(天)。

    如果指定了帶單位的小數值,它將被四捨五入到下一個更小單位的倍數(如果存在)。例如,30.1 GB 將被轉換為 30822 MB,而不是 32319628902 B。如果引數是整數型別,則在任何單位轉換後會進行最終的整數四捨五入。

  • 列舉值: 列舉型別引數的寫法與字串引數相同,但僅限於一組有限的值。此類引數允許的值可從 pg_settings.enumvals 中查詢。列舉引數值不區分大小寫。

19.1.2. 透過配置檔案互動引數 #

設定這些引數最根本的方法是編輯 postgresql.conf 檔案,該檔案通常儲存在資料目錄中。在初始化資料庫叢集目錄時,會安裝一個預設副本。該檔案可能看起來像這樣:

# This is a comment
log_connections = all
log_destination = 'syslog'
search_path = '"$user", public'
shared_buffers = 128MB

每行指定一個引數。名稱和值之間的等號是可選的。空格無關緊要(除了在帶引號的引數值內),並且忽略空行。井號(#)將該行剩餘部分視為註釋。非簡單識別符號或數字的引數值必須加單引號。要在引數值中嵌入單引號,請寫兩個引號(首選)或反斜槓引號。如果檔案包含同一引數的多個條目,則除最後一個外,其餘都將被忽略。

在此方式下設定的引數為叢集提供了預設值。活動會話看到的設定將是這些值,除非被覆蓋。以下各節將介紹管理員或使用者可以覆蓋這些預設值的方法。

在主伺服器程序收到 SIGHUP 訊號後,將重新讀取配置檔案;最容易傳送此訊號的方法是從命令列執行 pg_ctl reload 或呼叫 SQL 函式 pg_reload_conf()。主伺服器程序還會將此訊號傳播到所有當前正在執行的伺服器程序,以便現有會話也能採用新值(這將在它們完成任何當前執行的客戶端命令後發生)。或者,您可以直接將訊號傳送到單個伺服器程序。某些引數只能在伺服器啟動時設定;對配置檔案中其條目的任何更改都將被忽略,直到伺服器重新啟動為止。在 SIGHUP 處理期間,配置檔案中無效的引數設定同樣會被忽略(但會記錄)。

除了 postgresql.conf 之外,PostgreSQL 資料目錄還包含一個 postgresql.auto.conf 檔案,該檔案的格式與 postgresql.conf 相同,但旨在自動編輯,而非手動編輯。此檔案儲存透過 ALTER SYSTEM 命令提供的設定。此檔案在 postgresql.conf 重新讀取時也會被讀取,並且其設定會以相同方式生效。 postgresql.auto.conf 中的設定會覆蓋 postgresql.conf 中的設定。

外部工具也可以修改 postgresql.auto.conf。不建議在伺服器執行時這樣做,除非 allow_alter_system 設定為 off,因為併發的 ALTER SYSTEM 命令可能會覆蓋此類更改。這些工具可能只是在末尾追加新設定,或者它們可能選擇刪除重複設定和/或註釋(正如 ALTER SYSTEM 會做的那樣)。

系統檢視 pg_file_settings 有助於預先測試對配置檔案所做的更改,或者在 SIGHUP 訊號未達到預期效果時診斷問題。

19.1.3. 透過 SQL 互動引數 #

PostgreSQL 提供了三個 SQL 命令來建立配置預設值。已經提到的 ALTER SYSTEM 命令提供了可透過 SQL 訪問的修改全域性預設值的方法;它在功能上等同於編輯 postgresql.conf。此外,還有兩個命令允許按資料庫或按角色設定預設值。

  • ALTER DATABASE 命令允許按資料庫覆蓋全域性設定。

  • ALTER ROLE 命令允許使用使用者特定值覆蓋全域性設定和按資料庫的設定。

使用 ALTER DATABASEALTER ROLE 設定的值僅在啟動新的資料庫會話時應用。它們會覆蓋從配置檔案或伺服器命令列獲得的值,並構成該會話其餘部分Defaults。請注意,某些設定在伺服器啟動後無法更改,因此無法使用這些命令(或下面的命令)進行設定。

一旦客戶端連線到資料庫,PostgreSQL 就提供了另外兩個 SQL 命令(以及等效函式)來與會話本地的配置設定進行互動。

  • SHOW 命令允許檢查任何引數的當前值。對應的 SQL 函式是 current_setting(setting_name text)(參見 第 9.28.1 節)。

  • SET 命令允許修改那些可以設定為會話本地的引數的當前值;它對其他會話沒有影響。許多引數可以由任何使用者以這種方式設定,但某些引數只能由超級使用者和已授予該引數 SET 許可權的使用者設定。對應的 SQL 函式是 set_config(setting_name, new_value, is_local)(參見 第 9.28.1 節)。

此外,系統檢視 pg_settings 可用於檢視和更改會話本地值。

  • 查詢此檢視類似於使用 SHOW ALL,但提供了更多詳細資訊。它也更靈活,因為可以指定過濾條件或與其他關係進行連線。

  • 在此檢視上使用 UPDATE,特別是更新 setting 列,等同於發出 SET 命令。例如,等同於

    SET configuration_parameter TO DEFAULT;
    

    UPDATE pg_settings SET setting = reset_val WHERE name = 'configuration_parameter';
    

19.1.4. 透過 Shell 互動引數 #

除了設定全域性預設值或在資料庫或角色級別附加覆蓋項之外,您還可以透過 shell 工具將設定傳遞給 PostgreSQL。伺服器和 libpq 客戶端庫都接受透過 shell 傳遞的引數值。

  • 在伺服器啟動期間,可以透過 postgres 命令的 -c name=value 命令列引數,或其等效的 --name=value 變體來傳遞引數設定。例如:

    postgres -c log_connections=all --log-destination='syslog'
    

    以這種方式提供的設定會覆蓋透過 postgresql.confALTER SYSTEM 設定的設定,因此在不重新啟動伺服器的情況下無法全域性更改它們。

  • 透過 libpq 啟動客戶端會話時,可以使用 PGOPTIONS 環境變數指定引數設定。以這種方式建立的設定構成會話生命週期的預設值,但不會影響其他會話。出於歷史原因,PGOPTIONS 的格式類似於啟動 postgres 命令時使用的格式;具體來說,必須指定 -c,或者在名稱前加上 --。例如:

    env PGOPTIONS="-c geqo=off --statement-timeout=5min" psql
    

    其他客戶端和庫可能透過 shell 或其他方式提供自己的機制,允許使用者在不直接使用 SQL 命令的情況下修改會話設定。

19.1.5. 管理配置檔案內容 #

PostgreSQL 提供了多項功能,用於將複雜的 postgresql.conf 檔案分解為子檔案。當管理具有相關但又不完全相同的配置的多個伺服器時,這些功能尤其有用。

除了單個引數設定外,postgresql.conf 檔案還可以包含include 指令,這些指令指定要讀取並處理的另一個檔案,就好像它在此處插入到配置檔案中一樣。此功能允許將配置檔案物理上分成多個部分。Include 指令看起來很簡單:

include 'filename'

如果檔名不是絕對路徑,則它相對於包含引用配置檔案的目錄。包含可以巢狀。

還有一個 include_if_exists 指令,其作用與 include 指令相同,只是在引用的檔案不存在或無法讀取時除外。常規的 include 會將其視為錯誤條件,但 include_if_exists 僅記錄一條訊息並繼續處理引用配置檔案。

postgresql.conf 檔案還可以包含 include_dir 指令,這些指令指定要包含的整個配置檔案目錄。它們看起來像:

include_dir 'directory'

非絕對目錄名稱相對於包含引用配置檔案的目錄。在指定目錄中,只有以 .conf 字尾結尾的非目錄檔案才會被包含。以 . 字元開頭的檔名也會被忽略,以防出錯(因為在某些平臺上這些檔案是隱藏的)。包含目錄中的多個檔案按檔名順序處理(根據 C 語言 locale 規則,即數字在前,字母在後;大寫字母在前,小寫字母在後)。

包含檔案或目錄可用於邏輯上分隔資料庫配置的一部分,而不是使用單個大型 postgresql.conf 檔案。考慮一個公司有兩個資料庫伺服器,它們的記憶體量不同。配置中很可能有一些元素是它們共享的,例如用於日誌記錄。但伺服器上的記憶體相關引數在這兩者之間會有所不同。還可能存在伺服器特定的自定義設定。管理這種情況的一種方法是將您站點的自定義配置更改分解為三個檔案。您可以將以下內容新增到 postgresql.conf 檔案的末尾以包含它們:

include 'shared.conf'
include 'memory.conf'
include 'server.conf'

所有系統都將擁有相同的 shared.conf。每個具有特定記憶體量的伺服器可以共享相同的 memory.conf;您可能有一個用於所有具有 8GB RAM 的伺服器,另一個用於 16GB 的伺服器。最後,server.conf 可以包含真正伺服器特定的配置資訊。

另一種可能性是建立一個配置檔案目錄並將這些資訊放入該目錄的檔案中。例如,可以在 postgresql.conf 的末尾引用一個 conf.d 目錄:

include_dir 'conf.d'

然後,您可以為 conf.d 目錄中的檔案命名如下:

00shared.conf
01memory.conf
02server.conf

這種命名約定建立了一個載入這些檔案的清晰順序。這一點很重要,因為在伺服器讀取配置檔案時,特定引數的最後一個設定才會被使用。在此示例中,conf.d/02server.conf 中設定的內容將覆蓋 conf.d/01memory.conf 中設定的值。

您也可以使用此方法為檔案命名,使其更具描述性:

00shared.conf
01memory-8GB.conf
02server-foo.conf

這種安排為每個配置檔案變體提供了一個唯一的名稱。這可以幫助消除當多個伺服器的配置全部儲存在一個位置(例如版本控制儲存庫)時的歧義。(將資料庫配置檔案儲存在版本控制下是另一個值得考慮的良好實踐。)

提交更正

如果您在文件中發現任何不正確之處、與您對特定功能的實際體驗不符或需要進一步澄清的內容,請使用此表格報告文件問題。