PostgreSQL Kurulumu: initdb ile Küme Oluşturma ve pg_ctl ile Yönetim

Paketi kurmak: kılavuzun önerisi

Kılavuzun Installation from Binaries bölümü kısadır ve tek bir öneri verir: PostgreSQL yaygın işletim sistemlerinin çoğu için ikili paket olarak sunulur ve kullanıcılar için önerilen kurulum yolu budur. Kaynaktan derleme yalnızca PostgreSQL'in ya da eklentilerin kendisini geliştirenlere önerilir. Güncel platform listesi ve her platformun kurulum talimatı için https://www.postgresql.org/download/ adresine gidip kendi sisteminizi seçmeniz gerekir. Dağıtıma özel paket komutları resmî kılavuzda yer almadığı için bu yazıda da vermiyoruz.

Paketler genellikle sunucu için ayrı bir işletim sistemi kullanıcısı da oluşturur. Kılavuz, dışarıya açık her sunucu sürecinde olduğu gibi PostgreSQL'in de yalnızca kendi verisine sahip olan ayrı bir hesapla çalışmasını önerir; bu hesabın başka servislerle paylaşılmaması (örneğin nobody kullanıcısının kullanılmaması) ve hatta çalıştırılabilir dosyaların sahibi olmaması tavsiye edilir. Belgeler boyunca bu hesabın adı postgres olarak varsayılır. Paket, çoğu zaman bir veri dizini ve başlatma betiği de hazırlar; böyle bir düzen varsa kılavuz, initdb ve pg_ctl komutlarını doğrudan çalıştırmak yerine paketin kendi araçlarını kullanmanızı söyler. Aşağıdaki adımlar, dizini ve sunucuyu elle yönettiğiniz durumu anlatır.

Veritabanı kümesi nedir?

Kılavuzun terminolojisinde küme (database cluster), tek bir çalışan sunucu örneğinin yönettiği veritabanları topluluğudur. Dosya sistemi açısından küme tek bir dizindir; buna veri dizini (data directory) denir ve bütün veri bu dizinin altında durur. Varsayılan bir konum yoktur, yeri tamamen siz seçersiniz. initdb çalıştığında küme içinde üç veritabanı oluşturur: araçların ve uygulamaların varsayılan olarak bağlandığı postgres ile yeni veritabanlarına şablon olan template1 ve template0. Şablonların gerçek iş için kullanılmaması gerekir; ayrıntıları veritabanı ve şema oluşturma yazısında anlatıyoruz.

Bir makinede birden çok küme çalışabilir; her kümenin kendi veri dizini ve kendi portu olur. Bu yazıdaki denemeler de bu sayede kullanıcının asıl PostgreSQL servisine dokunmadan yapıldı. Aynı veri dizinini iki sunucunun kullanması ise engellenir: çalışan sunucu, süreç numarasını (PID) veri dizinindeki postmaster.pid dosyasına yazar ve bu dosya ikinci bir örneğin aynı dizinde açılmasını önler.

initdb ile kümeyi oluşturmak

initdb komutunun tek zorunlu bilgisi veri dizinidir; -D seçeneğiyle ya da PGDATA ortam değişkeniyle verilir. Komut sunucuyu çalıştıracak kullanıcıyla çalıştırılmalıdır; sunucu root olarak çalışamadığı için initdb de root ile çalışmayı reddeder. Linux'ta kılavuzun gösterdiği tipik akış, üst dizini root ile oluşturup sahipliğini postgres kullanıcısına vermek ve bu kullanıcıya geçip initdb çalıştırmaktır (aşağıdaki komutlar belgedeki Linux örneğidir, bu Windows makinesinde çalıştırılmadı):

root# mkdir /usr/local/pgsql
root# chown postgres /usr/local/pgsql
root# su postgres
postgres$ initdb -D /usr/local/pgsql/data

Varsayılan kimlik doğrulama ayarı yerel kullanıcıların parola sormadan bağlanabildiği trust yöntemidir; kılavuz bunun kolay kurulum için seçildiğini ve makinedeki bütün yerel kullanıcılara güvenmiyorsanız kullanılmaması gerektiğini açıkça yazar. Bu yüzden süper kullanıcıya parola atamak için -W (sorarak) ya da --pwfile (dosyadan, ilk satır) seçeneğini, ayrıca -A scram-sha-256 ile parola tabanlı yöntemi kullanmanızı öneririz. Denememizdeki komut ve tam çıktısı:

initdb -D pgveri -U postgres -A scram-sha-256 --pwfile=pw.txt -E UTF8 \
       --locale-provider=icu --icu-locale=tr-TR --locale=C

The files belonging to this database system will be owned by user "egeme".
This user must also own the server process.

Using language tag "tr-TR" for ICU locale "tr-TR".
The database cluster will be initialized with this locale configuration:
  locale provider:   icu
  default collation: tr-TR
  LC_COLLATE:  C
  LC_CTYPE:    C
  LC_MESSAGES: C
  LC_MONETARY: C
  LC_NUMERIC:  C
  LC_TIME:     C
The default text search configuration will be set to "english".

Data page checksums are enabled.

creating directory pgveri ... ok
creating subdirectories ... ok
selecting dynamic shared memory implementation ... windows
selecting default "max_connections" ... 100
selecting default "shared_buffers" ... 128MB
selecting default time zone ... Europe/Istanbul
creating configuration files ... ok
running bootstrap script ... ok
performing post-bootstrap initialization ... ok
syncing data to disk ... ok

Success. You can now start the database server using:

    ^"C^:^\Program^ Files^\PostgreSQL^\18^\bin^\pg^_ctl^" -D pgveri -l logfile start

Çıktıda dikkat edilecek birkaç satır var. İlk iki satır, oluşturulan dosyaların komutu çalıştıran işletim sistemi kullanıcısına ait olacağını ve sunucunun da aynı kullanıcıyla çalışması gerektiğini söylüyor. -U ile verdiğimiz postgres ise işletim sistemi kullanıcısı değil, kümenin ilk süper kullanıcısı olan veritabanı rolüdür; verilmezse initdb'yi çalıştıran kullanıcının adı kullanılır. Data page checksums are enabled. satırı PostgreSQL 18'deki bir değişikliğin sonucudur: sürüm notlarına göre initdb artık veri sayfası sağlama toplamlarını varsayılan olarak açar ve kapatmak isteyenler için yeni --no-data-checksums seçeneği eklenmiştir. Sürüm notları, pg_upgrade'in eski ve yeni kümede aynı checksum ayarını istediğini, bu seçeneğin checksum'sız eski kümeleri yükseltirken işe yarayacağını da belirtir.

Sonda yazdırılan başlatma komutu Windows komut satırına göre kaçışlanmıştır (^ işaretleri); bu satırı istemiyorsanız --no-instructions seçeneği onu kaldırır. Oluşan dizinde base, global, pg_wal gibi alt dizinlerin yanında yapılandırma dosyaları postgresql.conf, pg_hba.conf, pg_ident.conf ve postgresql.auto.conf bulunur. -A scram-sha-256 verdiğimiz için pg_hba.conf dosyasının bütün satırları bu yöntemle oluştu:

local   all             all                                     scram-sha-256
host    all             all             127.0.0.1/32            scram-sha-256
host    all             all             ::1/128                 scram-sha-256
local   replication     all                                     scram-sha-256
host    replication     all             127.0.0.1/32            scram-sha-256
host    replication     all             ::1/128                 scram-sha-256

Bu dosyanın satır biçimini ve uzaktan bağlantıya izin vermeyi pg_hba.conf ve uzak bağlantı yazısı anlatıyor.

Locale ve encoding seçimini ilk seferde doğru yapın

initdb kümenin varsayılan locale ve karakter kodlamasını belirler; şablon veritabanlarının sıralama düzeni sonradan bu veritabanları silinip yeniden oluşturulmadan değiştirilemez. Kılavuz bu nedenle seçimin ilk seferde doğru yapılmasını vurgular ve C ya da POSIX dışındaki locale'lerin performans maliyeti olduğunu, bunların indeks sıralamasını işletim sisteminin sıralama kütüphanesine bağladığını hatırlatır. Locale verilmezse ortamdaki ayarlar kullanılır. Türkçe Windows'ta bu ortam ayarı sorun çıkardı; locale seçeneği olmadan çalıştırdığımızda initdb şu hatayla durdu:

initdb: error: locale name "Turkish_T�rkiye.1254" contains non-ASCII characters

Çözüm, locale'i açıkça vermektir: yukarıdaki gibi ICU sağlayıcısıyla --locale-provider=icu --icu-locale=tr-TR ya da PostgreSQL'in kendi sağlayıcısıyla --locale-provider=builtin --builtin-locale=C.UTF-8. Hangi sağlayıcının Türkçe büyük/küçük harf ve sıralama kurallarını nasıl uyguladığı collation ve Türkçe sıralama yazısının konusu.

Sık kullanılan initdb seçenekleri

initdb ayrıca dolu bir dizinin üzerine yazmayı reddeder; bu, mevcut bir kurulumun yanlışlıkla silinmesine karşı bir korumadır. Aynı dizinde ikinci kez çalıştırdığımızda aldığımız çıktı:

initdb: error: directory "ana" exists but is not empty
initdb: hint: If you want to create a new database system, either remove or empty the directory "ana" or run initdb with an argument other than "ana".

Kümeyi initdb yerine pg_ctl -D dizin initdb ile de oluşturabilirsiniz; bu biçimde initdb seçenekleri -o ile tırnak içinde aktarılır. Sunucuyu zaten pg_ctl ile yönetiyorsanız tek bir araç kullanmak işinizi kolaylaştırır.

Sunucuyu başlatmak

Sunucu programının adı postgres'tir ve en çıplak hâliyle postgres -D veri_dizini komutuyla ön planda çalıştırılabilir. Pratikte bunun yerine pg_ctl start kullanılır: sunucuyu arka planda başlatır, terminalden ayırır ve -l ile verilen dosyaya günlük yazar. Kılavuz sunucu çıktısının mutlaka bir yere kaydedilmesini, sorun teşhisi için bunun önemli olduğunu belirtir. pg_ctl başlatma, durdurma ve yeniden başlatmada varsayılan olarak işlemin bitmesini bekler (-w); bekleme süresi -t ile ya da PGCTLTIMEOUT ortam değişkeniyle ayarlanır, ikisi de yoksa 60 saniyedir.

Denememizde port ve dinleme adresini postgresql.conf dosyasının sonuna ekledik; dosyada aynı parametre birden çok kez geçerse son değer geçerli olur. Ardından sunucuyu başlatıp durumunu sorduk:

printf "listen_addresses = '127.0.0.1'\nport = 46411\n" >> pgveri/postgresql.conf
pg_ctl -D pgveri -l pgveri.log start
pg_ctl -D pgveri status; echo "exit=$?"

waiting for server to start.... done
server started
pg_ctl: server is running (PID: 87744)
C:/Program Files/PostgreSQL/18/bin/postgres.exe "-D" "pgveri"
exit=0

status çıktısının ikinci satırı, restart kipinde yeniden kullanılacak komut satırıdır; aynı bilgi veri dizinindeki postmaster.opts dosyasında durur. status kipinin dönüş kodları betik yazarken işe yarar: sunucu çalışıyorsa 0, çalışmıyorsa 3, erişilebilir bir veri dizini verilmemişse 4 döner. Bağlantıyı doğrulamak için psql ile sürümü ve checksum ayarını sorduk; parolayı yalnızca bu deneme için PGPASSWORD ortam değişkeniyle verdik, gerçek kullanımda psql belgesinde anlatılan ~/.pgpass dosyası daha uygundur:

PGPASSWORD=... psql -h 127.0.0.1 -p 46411 -U postgres -d postgres -X \
    -c "SELECT version();" -c "SHOW data_checksums;"

 PostgreSQL 18.1 on x86_64-windows, compiled by msvc-19.44.35219, 64-bit
(1 row)

 data_checksums 
----------------
 on
(1 row)

Çıktının ilk satırını, yani version başlığını ve çizgisini kısalık için kestik. Parolayı yanlış verdiğimizde psql 2 dönüş koduyla şu hatayı verdi: FATAL: password authentication failed for user "postgres". Bu ve benzeri bağlantı hatalarını bağlantı hataları yazısında topluca ele alıyoruz.

Başlatma neden başarısız olur?

Kılavuz en sık başlatma hatası olarak portun başka bir sunucu tarafından kullanılmasını gösterir. Aynı portu kullanan ikinci bir kümeyi başlatmayı denediğimizde pg_ctl yalnızca genel bir hata verdi ve günlüğe bakmamızı istedi; asıl neden günlük dosyasındaydı:

waiting for server to start.... stopped waiting
pg_ctl: could not start server
Examine the log output.

LOG:  could not bind IPv4 address "127.0.0.1": Only one usage of each socket address (protocol/network address/port) is normally permitted.
HINT:  Is another postmaster already running on port 46411? If not, wait a few seconds and retry.
WARNING:  could not create listen socket for "127.0.0.1"
FATAL:  could not create any TCP/IP sockets
LOG:  database system is shut down

Günlük satırlarının başındaki tarih, saat ve süreç numarasını kısalık için çıkardık. Mesajın ilk kısmı Windows'un kendi soket hatasıdır; Linux'ta aynı durum belgede gösterildiği gibi Address already in use olarak görünür. Belge, ayrılmış bir port numarasında başlatma denemesinin Permission denied, paylaşılan bellek veya semafor sınırlarının ise could not create shared memory segment ve could not create semaphores mesajları verebileceğini de anlatır; ikincisinin disk dolmasıyla ilgisi yoktur, çekirdeğin semafor sınırıyla ilgilidir. İlk kural şudur: pg_ctl başlatamadığını söylediğinde önce -l ile verdiğiniz günlük dosyasının son satırlarını okuyun.

Sunucuyu kapatmak: smart, fast, immediate

Kılavuza göre bütün kapatma yöntemleri, sonuçta ana postgres sürecine bir sinyal göndermeye dayanır ve pg_ctl stop -m bunun kolay yoludur. Üç kip vardır ve farkları önemlidir:

smart kipini açık bir oturum varken denedik: bir psql oturumu 8 saniyelik pg_sleep çalıştırırken pg_ctl'e 3 saniyelik süre verdik. Sunucu yeni bağlantıları reddetmeye başladı ama mevcut oturum bitmeden kapanmadı:

pg_ctl -D pgveri -m smart -t 3 stop
psql -h 127.0.0.1 -p 46411 -U postgres -X -d postgres -c "SELECT 1"

waiting for server to shut down...... failed
pg_ctl: server does not shut down
HINT: The "-m fast" option immediately disconnects sessions rather than
waiting for session-initiated disconnection.
psql: error: connection to server at "127.0.0.1", port 46411 failed: FATAL:  the database system is shutting down

Burada önemli bir ayrıntı var: pg_ctl'in süre dolduğunda hata vermesi kapatma isteğinin iptal edildiği anlamına gelmez. Belge, işlemin arka planda devam edip sonunda başarılı olabileceğini söyler; nitekim uyku sorgusu bittikten birkaç saniye sonra pg_ctl status komutu pg_ctl: no server running yazdı ve 3 kodunu döndürdü. Bu, betiklerde şaşırtıcı sonuçlar doğurabilir; zaman aşımında ne yapılacağını betiğinizde açıkça tanımlayın.

immediate kipi ise süreçleri temiz kapatma işlemleri yapmadan sonlandırır; kılavuz bunu yalnızca acil durumlar için önerir. Bu kiple durdurup yeniden başlattığımızda günlükte kurtarma satırları göründü (tarih ve süreç numaraları kısaltıldı):

pg_ctl -D pgveri -m immediate stop
pg_ctl -D pgveri -l pgveri.log start

LOG:  database system was interrupted; last known up at 2026-11-07 12:31:31 +03
LOG:  database system was not properly shut down; automatic recovery in progress
LOG:  redo is not required
...
LOG:  database system is ready to accept connections

Boş bir deneme kümesinde yeniden oynatılacak kayıt olmadığı için redo is not required çıktı; yoğun bir sunucuda bu adım WAL kayıtlarını uygular ve daha uzun sürer. Kılavuz ayrıca SIGKILL ile kapatmanın paylaşılan belleğin ve semaforların serbest bırakılmasını engellediği için kullanılmaması gerektiğini vurgular. Tek bir oturumu kapatmak istiyorsanız sunucuyu değil yalnızca o oturumu sonlandırın; bunun için pg_terminate_backend() fonksiyonu vardır ve pg_stat_activity yazısında anlatılır.

reload ve restart farkı

pg_ctl reload sunucuya SIGHUP gönderir ve postgresql.conf ile pg_hba.conf gibi yapılandırma dosyalarının yeniden okunmasını sağlar; bağlantılar kesilmez. Yalnızca yeniden başlatmayla etkinleşen parametreler için restart gerekir; bu kip önce durdurur, sonra başlatır ve varsayılan olarak önceki komut satırı seçeneklerini yeniden kullanır. Hangi parametrenin hangi yöntemle değiştiğini postgresql.conf ve ALTER SYSTEM yazısı anlatıyor.

pg_ctl -D pgveri reload
pg_ctl -D pgveri restart

server signaled
waiting for server to shut down.... done
server stopped
waiting for server to start....2026-11-07 12:31:32.849 +03 [28048] LOG:  starting PostgreSQL 18.1 on x86_64-windows, compiled by msvc-19.44.35219, 64-bit
2026-11-07 12:31:32.850 +03 [28048] LOG:  listening on IPv4 address "127.0.0.1", port 46411
2026-11-07 12:31:32.879 +03 [79284] LOG:  database system was shut down at 2026-11-07 12:31:32 +03
2026-11-07 12:31:32.886 +03 [28048] LOG:  database system is ready to accept connections
 done
server started

Bu çıktıda bilerek bıraktığımız bir hata var: restart komutuna -l vermediğimiz için sunucu günlüğü terminale aktı. Belge, Windows'ta sunucunun standart çıktısının varsayılan olarak terminale gittiğini, Unix benzeri sistemlerde ise pg_ctl'in standart çıktısına yönlendirildiğini belirtir. restart kipi postgres seçeneklerini postmaster.opts'tan yeniden kullanır ama -l bir pg_ctl seçeneği olduğu için oraya yazılmaz; günlük dosyası istiyorsanız her start ve restart komutunda -l verin.

Açılışta otomatik başlatma

Bilgisayar açıldığında sunucunun başlaması işletim sistemine özeldir. Kılavuz Linux için şu systemd birim dosyasını örnek verir; dosya genellikle /etc/systemd/system/postgresql.service konumuna yazılır (Linux örneğidir, burada çalıştırılmadı):

[Unit]
Description=PostgreSQL database server
Documentation=man:postgres(1)
After=network-online.target
Wants=network-online.target

[Service]
Type=notify
User=postgres
ExecStart=/usr/local/pgsql/bin/postgres -D /usr/local/pgsql/data
ExecReload=/bin/kill -HUP $MAINPID
KillMode=mixed
KillSignal=SIGINT
TimeoutSec=infinity

[Install]
WantedBy=multi-user.target

Birkaç ayrıntı belgeden geliyor: Type=notify sunucunun systemd desteğiyle derlenmiş olmasını gerektirir; KillSignal=SIGINT systemd'nin durdururken fast kapatma sinyali göndermesini sağlar; TimeoutSec=infinity ise açılışta uzun sürebilecek bir kurtarmanın systemd'nin varsayılan zaman aşımı yüzünden yarıda kesilmesini engeller. Sunucu her durumda root değil postgres kullanıcısıyla çalışmalıdır. Birim dosyası yazma, etkinleştirme ve günlükleri okuma adımları için systemd servis yönetimi yazısına bakın. Windows'ta pg_ctl register kipi sunucuyu Windows hizmeti olarak kaydeder; bu deneme ortamında kullanıcının mevcut hizmetine dokunmamak için çalıştırmadık.

Sık yapılan hatalar

• Varsayılan trust ile kurmak: -A verilmezse yerel bağlantılar parolasız kabul edilir. -A scram-sha-256 ve -W veya --pwfile kullanın ya da sunucuyu ilk kez başlatmadan önce pg_hba.conf dosyasını düzeltin.
• initdb'yi root ile çalıştırmak: Komut bunu reddeder; sunucu hangi kullanıcıyla çalışacaksa küme de onunla oluşturulmalıdır.
• Locale seçimini sonraya bırakmak: Şablon veritabanlarının sıralama düzeni sonradan kolayca değişmez; Türkçe Windows'ta locale vermemek initdb'nin hiç çalışmamasına bile yol açabilir.
• Günlüğü kaydetmemek: -l olmadan başlatılan bir sunucunun neden açılmadığını anlamak zorlaşır; her başlatmada günlük dosyası verin.
• Paket sunucusunu elle başlatmak: Paketle gelen bir servis varsa onu paketin kendi araçlarıyla yönetin; aynı veri dizinini iki farklı yoldan başlatmaya çalışmak postmaster.pid çakışmasına yol açar.
• immediate kipini alışkanlık hâline getirmek: Her kullanımda bir sonraki açılış kurtarma ile başlar; normal bakımda varsayılan fast kipi yeterlidir.

Sık Sorulan Sorular

PGDATA ortam değişkenini kullanmak zorunlu mu?

Hayır. initdb, pg_ctl ve postgres veri dizinini -D ile alır; -D verilmezse PGDATA değişkenine bakarlar. Tek bir kümeyle çalışıyorsanız değişkeni tanımlamak yazmayı azaltır, birden çok kümeyle çalışıyorsanız her komutta -D vermek karışıklığı önler.

Data checksums açık olmalı mı?

PostgreSQL 18 ile initdb sayfa sağlama toplamlarını varsayılan olarak açar. Belge bunun G/Ç sistemindeki sessiz bozulmaları fark etmeye yaradığını, küçük bir performans maliyeti olabileceğini ve hataların pg_stat_database görünümünde raporlandığını belirtir. Eski ve checksum'sız bir kümeyi pg_upgrade ile taşıyacaksanız yeni kümeyi --no-data-checksums ile oluşturmanız gerekebilir; sürüm yükseltme yazısına bakın.

Sunucu çalışıyor mu, en hızlı nasıl anlarım?

Veri dizinine erişiminiz varsa pg_ctl -D dizin status en doğrudan yoldur ve dönüş kodu betiklerde kullanılabilir. Uzaktan bir sunucunun bağlantı kabul edip etmediğini anlamak için pg_isready aracı vardır; bağlantı hataları yazısında örnekleri var.

Aynı makinede iki PostgreSQL çalıştırabilir miyim?

Evet; her kümenin ayrı veri dizini ve ayrı portu olması yeterlidir. Bu yazıdaki denemeler de makinede çalışan servislerden bağımsız olarak 46411 portunda yapıldı. Aynı portu iki küme kullanmaya çalışırsa ikincisi yukarıda gösterilen soket hatasıyla açılmaz.

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 · psql komutları · Veritabanı ve şema oluşturma · pg_hba.conf ve uzak bağlantı · postgresql.conf yapılandırması · systemd servis yönetimi