PostgreSQL Yapılandırması: postgresql.conf, ALTER SYSTEM, pg_settings ve Parametre Bağlamları

postgresql.conf sözdizimi

Dosyada her satırda bir parametre bulunur. Ad ile değer arasındaki eşittir işareti isteğe bağlıdır, boşluklar (tırnak içi hariç) önemsizdir ve # satırın geri kalanını yoruma çevirir. Basit bir sayı ya da tanımlayıcı olmayan değerler tek tırnak içine alınır; değerin içinde tek tırnak gerekiyorsa iki tırnak yazılması önerilir. Parametre adları büyük ve küçük harfe duyarsızdır. Aynı parametre dosyada birden fazla kez geçerse son satır geçerli olur, öncekiler yok sayılır.

# Bu bir yorum
log_connections = all
search_path = '"$user", public'
shared_buffers = 128MB
statement_timeout = '30s'      # tırnaklı birim de olur

Dosyanın tam yolu SHOW config_file ile, veri dizini SHOW data_directory ile görülür. Belgelere göre dosyaların yeri config_file, hba_file ve ident_file parametreleriyle veri dizininden ayrı olarak da belirlenebilir; bu yüzden yolu tahmin etmek yerine bu komutları kullanın. Kümenin kurulumu ve dosyaların ilk oluşturulması initdb ve pg_ctl yazısında anlatılıyor.

Parametre türleri ve birimler

Her parametre beş türden birine sahiptir: boolean, string, integer, floating point ya da enum. Boolean değerler on, off, true, false, yes, no, 1, 0 ya da bunların belirsiz olmayan bir önekiyle yazılabilir. Enum parametrelerin alabileceği değerler pg_settings.enumvals sütununda listelenir; örneğin wal_level için sonuç {minimal,replica,logical} oldu.

Bellek ve zaman parametrelerinin örtük bir birimi vardır. Birim yazmazsanız parametrenin kendi birimi kullanılır; bunu pg_settings.unit sütunu söyler. Birim yazarsanız değer tırnak içinde olmalıdır. Bellek birimleri B, kB, MB, GB, TB (çarpan 1024), zaman birimleri us, ms, s, min, h, d'dir ve büyük küçük harfe duyarlıdır. Aşağıdaki denemelerde birimin nasıl çevrildiğini ve sık yapılan iki hatayı görebilirsiniz:

SET work_mem = '64MB';
SHOW work_mem;                                              -- sonuç: 64MB
SELECT setting, unit FROM pg_settings WHERE name = 'work_mem';   -- 65536 | kB
SET statement_timeout = '1.5min';
SHOW statement_timeout;                                     -- sonuç: 90s
SET work_mem = '64mb';
SET work_mem = 1000000000000;

ERROR:  invalid value for parameter "work_mem": "64mb"
HINT:  Valid units for this parameter are "B", "kB", "MB", "GB", and "TB".
ERROR:  invalid value for parameter "work_mem": "1000000000000"
HINT:  Value exceeds integer range.

64MB, kB biriminde saklanan work_mem için 65536 olarak kaydedildi. Kesirli 1.5min değeri bir alt birime yuvarlanarak 90 saniyeye çevrildi; belgelerdeki kural da budur. Küçük harfli mb ise reddedildi ve ipucu satırı geçerli birimleri saydı. Binlik ayırıcı kullanılmaz; tam sayı parametreleri ayrıca 0x ile başlayan onaltılık değerleri de kabul eder.

pg_settings ve parametre bağlamları

SHOW ALL bütün parametreleri listeler, ama pg_settings görünümü filtrelenebildiği ve çok daha fazla sütun içerdiği için genellikle daha kullanışlıdır. Altı farklı parametreye baktık:

SELECT name, setting, unit, vartype, context, source
FROM pg_settings
WHERE name IN ('work_mem', 'shared_buffers', 'statement_timeout',
               'log_min_duration_statement', 'wal_level', 'search_path')
ORDER BY name;

            name            |     setting     | unit | vartype |  context   |       source       
----------------------------+-----------------+------+---------+------------+--------------------
 log_min_duration_statement | -1              | ms   | integer | superuser  | default
 search_path                | "$user", public |      | string  | user       | default
 shared_buffers             | 16384           | 8kB  | integer | postmaster | configuration file
 statement_timeout          | 0               | ms   | integer | user       | default
 wal_level                  | replica         |      | enum    | postmaster | default
 work_mem                   | 4096            | kB   | integer | user       | default
(6 rows)

shared_buffers satırındaki 16384 değeri 8 kB'lık blok sayısıdır, yani dosyadaki 128MB ile aynı şeydir. source sütunu değerin nereden geldiğini söyler: default yerleşik varsayılan, configuration file ayar dosyası demektir. context sütunu ise bir parametrenin nasıl ve kim tarafından değiştirilebileceğini belirleyen en önemli bilgidir. Belgelerdeki sırayla, değiştirmesi en zordan en kolaya:

Bağlamı postmaster olan bir parametreyi oturumda değiştirmeye çalışırsanız hata alırsınız: SET shared_buffers = '256MB' denediğimizde sunucu ERROR: parameter "shared_buffers" cannot be changed without restarting the server yanıtını verdi. Bağlamı superuser olan log_min_duration_statement ise sıradan bir kullanıcıya permission denied to set parameter hatası verdirdi; bunun çözümünü aşağıda göreceksiniz.

SET, SET LOCAL ve set_config

SET yalnızca o oturumu etkiler, diğer bağlantılar değişikliği görmez. SET LOCAL ise değeri yalnızca içinde bulunulan transaction boyunca geçerli kılar; transaction bitince önceki değer geri gelir. RESET oturum değerini oturum başlangıcındaki varsayılana döndürür, RESET ALL bunu bütün parametreler için yapar. SQL fonksiyonu olarak karşılıkları current_setting() ve set_config(ad, deger, is_local)'dır:

-- oturumda statement_timeout = 90s iken
BEGIN;
SET LOCAL statement_timeout = '5s';
SHOW statement_timeout;      -- sonuç: 5s
COMMIT;
SHOW statement_timeout;      -- sonuç: 90s
RESET statement_timeout;
SHOW statement_timeout;      -- sonuç: 0
SELECT current_setting('work_mem'), set_config('work_mem', '8MB', false);   -- 64MB | 8MB

SET LOCAL, bağlantı havuzu kullanan uygulamalarda bir ayarın sonraki isteklere sızmaması için iyi bir alışkanlıktır. Satır güvenliği politikalarında oturum değişkeni kullanan bir örnek ve bu kullanımın bir tuzağı row level security yazısında var. SET içinde çalıştırılan ve sonra geri alınan (ROLLBACK) bir transaction'daki değişiklik de geri alınır; SET transaction'a duyarlıdır.

ALTER SYSTEM ve postgresql.auto.conf

ALTER SYSTEM, postgresql.conf dosyasını elle düzenlemenin SQL karşılığıdır. Değeri postgresql.auto.conf dosyasına yazar; bu dosya postgresql.conf her okunduğunda onunla birlikte okunur ve içindeki ayarlar ana dosyadakilerin önüne geçer. Komutu yalnızca süper kullanıcılar ve ilgili parametre üzerinde ALTER SYSTEM yetkisi verilmiş roller çalıştırabilir.

ALTER SYSTEM SET log_min_duration_statement = '250ms';
SHOW log_min_duration_statement;     -- sonuç: -1 (henüz yüklenmedi)
SELECT pg_reload_conf();
-- yeni bir bağlantıda:
SHOW log_min_duration_statement;     -- sonuç: 250ms

# postgresql.auto.conf içeriği
# Do not edit this file manually!
# It will be overwritten by the ALTER SYSTEM command.
log_min_duration_statement = '250ms'

Komut değeri hemen uygulamaz; bir sonraki yeniden yüklemeden ya da (postmaster bağlamındaki parametreler için) yeniden başlatmadan sonra etkinleşir. Bir ayarı geri almak için ALTER SYSTEM RESET parametre, hepsini temizlemek için ALTER SYSTEM RESET ALL yazılır; bunlar satırı postgresql.auto.conf'tan siler ve postgresql.conf'taki değer yeniden geçerli olur. Komut doğrudan dosya sistemine yazdığı ve geri alınamadığı için transaction içinde çalışmaz:

BEGIN;
ALTER SYSTEM SET work_mem = '16MB';

ERROR:  ALTER SYSTEM cannot run inside a transaction block

data_directory ve allow_alter_system gibi bazı parametreler ALTER SYSTEM ile ayarlanamaz. allow_alter_system = off yapmak komutu devre dışı bırakır, ancak belgeler bunun bir güvenlik önlemi olmadığını açıkça vurgular: süper kullanıcının dosyayı başka yollarla değiştirmesine engel olmaz. Sunucu çalışırken postgresql.auto.conf dosyasını dış araçlarla düzenlemek de, eşzamanlı bir ALTER SYSTEM değişikliği ezebileceği için önerilmez.

Yeniden başlatma gerektiren ayarlar ve pending_restart

shared_buffers gibi postmaster bağlamındaki bir parametre için ALTER SYSTEM çalıştırıp yapılandırmayı yeniden yüklediğimizde yeni değer dosyaya yazıldı ama uygulanmadı:

ALTER SYSTEM SET shared_buffers = '256MB';
SELECT pg_reload_conf();
SELECT name, setting, pending_restart FROM pg_settings WHERE name = 'shared_buffers';
SELECT name, setting, applied, error FROM pg_file_settings WHERE name = 'shared_buffers';

      name      | setting | pending_restart 
----------------+---------+-----------------
 shared_buffers | 16384   | t
(1 row)

      name      | setting | applied |            error             
----------------+---------+---------+------------------------------
 shared_buffers | 128MB   | f       | 
 shared_buffers | 256MB   | f       | setting could not be applied
(2 rows)

pending_restart = t, dosyadaki değerin yeniden başlatma beklediğini gösterir. Windows'taki testimizde ilginç bir ayrıntı gördük: aynı sorguyu yeniden yüklemeden sonra açılan yeni bir bağlantıda çalıştırdığımızda pending_restart f döndü; t değerini yalnızca yeniden yükleme sinyalini işlemiş oturum gösterdi. pg_file_settings görünümü ise iki bağlantıda da aynı bilgiyi verdi: 256MB satırında setting could not be applied yazıyordu. Bu yüzden bekleyen değişiklikleri kontrol ederken pg_file_settings görünümüne bakmak daha güvenilirdir. Testten sonra ALTER SYSTEM RESET shared_buffers ile değeri geri aldık; sunucuyu durdurup başlatma komutları pg_ctl yazısında.

Veritabanı ve role özel varsayılanlar

Bir ayarı bütün sunucu yerine yalnızca bir veritabanı ya da bir rol için değiştirmek istiyorsanız ALTER DATABASE ... SET ve ALTER ROLE ... SET kullanırsınız. Bu değerler yalnızca yeni bir oturum başlarken uygulanır, ayar dosyalarındaki ve sunucu komut satırındaki değerleri geçersiz kılar ve oturumun geri kalanı için varsayılan olur:

CREATE ROLE ayar_kullanici LOGIN;
ALTER DATABASE ornek_ayar SET statement_timeout = '30s';
ALTER ROLE ayar_kullanici IN DATABASE ornek_ayar SET statement_timeout = '10s';
\drds

                  List of settings
      Role      |  Database  |       Settings        
----------------+------------+-----------------------
 ayar_kullanici | ornek_ayar | statement_timeout=10s
                | ornek_ayar | statement_timeout=30s
(2 rows)

Ardından iki farklı kullanıcıyla bağlanıp SELECT name, setting, source FROM pg_settings WHERE name = 'statement_timeout' çalıştırdık. postgres kullanıcısı 30000 | database, ayar_kullanici ise 10000 | database user gördü. Belgelere göre çakışma durumunda veritabanı ve rol birlikte tanımlanmış ayar, yalnızca role ait ayarı; o da yalnızca veritabanına ait ayarı geçersiz kılar. Bir de istemci tarafı vardır: libpq'nun PGOPTIONS ortam değişkeniyle bağlantı isteğinde gönderilen değer. PGOPTIONS="-c statement_timeout=5min" ile bağlandığımızda ayar_kullanici için sonuç 300000 | client oldu.

Tablo yaklaşık bir öncelik sırasıdır: alt satırlar, aynı parametre için üst satırlardaki değeri geçersiz kılar. Ayar dosyaları kendi içinde de sıralıdır; postgresql.auto.conf, postgresql.conf ve onun içerdiği dosyaların önüne geçer. Role bağlı ayarların bir kullanım örneği rol yönetimi yazısında var.

SET yetkisi: süper kullanıcı olmadan ayar değiştirmek

Bağlamı superuser olan parametreleri normalde yalnızca süper kullanıcılar değiştirebilir. PostgreSQL bunun için parametre düzeyinde iki yetki tanır: oturumda değiştirmek için SET, kalıcı değiştirmek için ALTER SYSTEM. Sıradan kullanıcının SET log_min_duration_statement = 0 denemesi ERROR: permission denied to set parameter "log_min_duration_statement" ile reddedildi; yetkiyi verince çalıştı:

GRANT SET ON PARAMETER log_min_duration_statement TO ayar_kullanici;
\dconfig+ log_min_duration_statement

                           List of configuration parameters
         Parameter          | Value |  Type   |  Context  |     Access privileges     
----------------------------+-------+---------+-----------+---------------------------
 log_min_duration_statement | 250ms | integer | superuser | postgres=sA/postgres     +
                            |       |         |           | ayar_kullanici=s/postgres
(1 row)

s harfi SET, A harfi ALTER SYSTEM yetkisidir; yetki harflerinin tamamı GRANT ve REVOKE yazısında açıklanıyor. psql'in \dconfig komutu desen verilmezse yalnızca varsayılandan farklı değerdeki parametreleri listeler; hepsini görmek için \dconfig * yazılır.

include_dir ile dosyayı bölmek ve pg_file_settings ile kontrol

postgresql.conf içine include 'dosya', include_if_exists 'dosya' ve include_dir 'dizin' yönergeleri yazılabilir. Dizin içindeki yalnızca .conf ile biten ve noktayla başlamayan dosyalar, C yerel ayarına göre ad sırasıyla okunur; bu yüzden 00-ortak.conf, 01-bellek.conf gibi numaralı adlar yaygındır. Yönerge dosyanın neresindeyse içerik oraya eklenmiş gibi işlenir ve aynı parametre için son okunan değer kazandığından, yönergenin yeri önemlidir. Test kümemizde postgresql.conf sonuna include_dir 'conf.d' ekleyip içine bilerek yazım hatalı bir parametre koyduk:

# conf.d/01-kayit.conf
# kayit ayarlari
log_line_prefix = '%m [%p] %u@%d '
log_min_duraton_statement = '1s'

pg_reload_conf() sonrasında pg_file_settings görünümü dosyadaki her geçerli satırı, dosya adı ve satır numarasıyla gösterdi. Hatalı satırın error sütunu doluydu, ama dikkat çekici olan diğer satırlardı:

SELECT regexp_replace(sourcefile, '^.*/', '') AS dosya, sourceline, name, setting, applied, error
FROM pg_file_settings ORDER BY seqno;

        dosya         | sourceline |            name            |      setting       | applied |                error                 
----------------------+------------+----------------------------+--------------------+---------+--------------------------------------
 postgresql.conf      |         65 | max_connections            | 100                | f       | 
 ...
 01-kayit.conf        |          2 | log_line_prefix            | %m [%p] %u@%d      | f       | 
 01-kayit.conf        |          3 | log_min_duraton_statement  | 1s                 | f       | unrecognized configuration parameter
 postgresql.auto.conf |          3 | log_min_duration_statement | 250ms              | f       | 
(20 rows)

(Çıktının ortasındaki 16 satırı kısaltmak için ... ile atladık.) Bütün satırlarda applied değeri f idi ve SHOW log_line_prefix eski değeri göstermeye devam etti. Sunucu günlüğü nedenini açıkça yazdı: configuration file ".../conf.d/01-kayit.conf" contains errors; no changes were applied. Yani testimizde tek bir yazım hatası, aynı yeniden yüklemedeki bütün değişikliklerin uygulanmamasına yol açtı. Belgeler pg_file_settings görünümünü tam da bu amaçla, değişiklikleri önceden denemek ya da beklenen etkiyi göstermeyen bir yeniden yüklemeyi teşhis etmek için önerir.

Yazım hatasını düzeltip tekrar yüklediğimizde log_line_prefix satırı applied = t oldu ve yeni değer etkinleşti. 01-kayit.conf içindeki log_min_duration_statement = '1s' satırı ise applied = f kaldı, çünkü aynı parametre postgresql.auto.conf içinde de vardı ve o dosya sonra okunduğu için 250ms kazandı. ALTER SYSTEM ile bir kez ayarlanmış bir parametreyi dosyada değiştirip etkisini göremiyorsanız ilk bakacağınız yer burasıdır.

Sık yapılan hatalar

• Dosyayı değiştirip yeniden yüklemeyi unutmak: değişiklik ancak pg_reload_conf(), pg_ctl reload ya da yeniden başlatmayla okunur.
• postmaster parametresi için yalnızca reload yapmak: shared_buffers, listen_addresses, port, wal_level gibi parametreler yeniden başlatma ister.
• Birim harflerini yanlış yazmak: 64mb geçersizdir, 64MB yazılmalıdır; birim kullanırken değer tırnak içinde olmalıdır.
• ALTER SYSTEM değerini unutmak: postgresql.auto.conf her zaman postgresql.conf'un önüne geçer; dosyadaki değişiklik etkisiz görünüyorsa pg_settings.sourcefile sütununa bakın.
• Tek yazım hatasının etkisini küçümsemek: testimizde hatalı bir satır, aynı dosyadaki bütün değişikliklerin uygulanmamasına neden oldu; pg_file_settings ile kontrol edin.
• postgresql.auto.conf'u elle düzenlemek: dosyanın başındaki uyarı da bunu söyler; ALTER SYSTEM kullanın.

Sık Sorulan Sorular

Bir ayarın hangi dosyadan geldiğini nasıl bulurum?

Süper kullanıcı ya da pg_read_all_settings üyesi olarak SELECT name, setting, source, sourcefile, sourceline FROM pg_settings WHERE name = '...' çalıştırın. Testimizde log_min_duration_statement için source configuration file, dosya postgresql.auto.conf, satır 3 göründü.

ALTER SYSTEM ile postgresql.conf düzenlemek arasında fark var mı?

İşlev olarak aynıdır; belgeler ikisini eşdeğer sayar. Fark, ALTER SYSTEM değerinin ayrı bir dosyada tutulması ve ana dosyanın önüne geçmesidir. Bir parametreyi her iki yerde de ayarladıysanız geçerli olan postgresql.auto.conf'taki değerdir.

Hangi değerleri vermeliyim?

Bu yazı yalnızca ayarların nasıl değiştirildiğini anlatıyor. Bellek, WAL ve bağlantı parametreleri için değer seçimi performans optimizasyonu yazısında, yavaş sorgu günlüğü ve istatistikler izleme yazısında, vacuum ayarları autovacuum yazısında ele alınıyor.

PostgreSQL 18 ayar sisteminde ne değişti?

Sürüm notlarına göre log_connections artık receipt, authentication, authorization, setup_durations gibi seçeneklerden oluşan bir liste alıyor; autovacuum_worker_slots ile autovacuum_max_workers yeniden başlatmadan bu sınıra kadar değiştirilebiliyor; MD5 parola uyarıları için md5_password_warnings eklendi. Tam liste PostgreSQL 18 yenilikleri yazısında.

Marka adları sahiplerine aittir. Bu yazı bağımsız bir teknik rehberdir; adı geçen kuruluşlarla bayilik veya ortaklık ilişkisi bulunduğu anlamına gelmez.

İlgili içerikler: PostgreSQL öğrenme rehberi · PostgreSQL performans optimizasyonu · pg_hba.conf ve uzak bağlantı · SSL/TLS şifreli bağlantı · Kurulum, initdb ve pg_ctl · pg_stat_activity ve pg_stat_statements