Skip to content
TalosBilişim
DatabaseJanuary 6, 2026· 4 min read

What to watch for when setting up automatic failover for PostgreSQL with Patroni

How the leader lock, ttl and loop_wait decide failover time, plus the settings around replication, backups and routing that matter.

T

Talos Mühendislik

Veritabanı Ekibi

English translation of this article is in progress — content shown below is in Turkish.

PostgreSQL'in streaming replication'ı size bir standby verir ama primary gittiğinde o standby'ı kimin, neye bakarak promote edeceğini söylemez. Bu kararı gece üçte bir insana bırakmak istemiyorsanız araya bir karar verici koymanız gerekir. Patroni bu işi yapan araçların en yaygını: her veritabanı sunucusunda çalışan bir agent PostgreSQL'i kendisi başlatıp durdurur ve kimin leader olduğu bilgisini etcd gibi bir dağıtık anahtar-değer deposunda tutar.

Tipik kurulum üç PostgreSQL node'u, üç üyeli bir etcd cluster'ı ve önde bir HAProxy'den oluşur. etcd'yi veritabanı sunucularına da kurabilirsiniz, ama disk gecikmesine duyarlı olduğu için ben olsam ayrı makinelere koyarım.

Failover sırasında olanlar

Leader olan Patroni, etcd'deki leader anahtarını her loop_wait saniyede bir yeniler; anahtarın ömrü ttl kadardır. Leader'ın makinesi tümden giderse anahtar yenilenmez, ttl dolunca silinir ve replica'lar yarışa girer. Her aday diğer üyelerin REST API'sine sorarak WAL konumunu karşılaştırır, geride olan çekilir, en güncel olan lock'u alıp kendi PostgreSQL'ini promote eder.

Yani makine kaybında kesintinin alt sınırını ttl belirler. Varsayılanı 30 saniyedir, üstüne promote ve istemcilerin yeniden bağlanma süresi eklenir. Değeri düşürüp daha hızlı failover alabilirsiniz, bedeli kısa bir ağ takılmasında gereksiz yere leader değiştirmektir. Patroni belgeleri loop_wait + 2 * retry_timeout toplamının ttl değerini aşmamasını ister; varsayılan 30/10/10 bu kuralın tam sınırındadır ve bence çoğu kurulumda dokunmaya gerek yoktur.

Yapılandırma

Aşağıdaki dosya ilk node için asgari bir başlangıç. Parolaları bilerek yazmadım; Patroni bunları PATRONI_SUPERUSER_PASSWORD ve PATRONI_REPLICATION_PASSWORD ortam değişkenlerinden de okur.

scope: prod-cluster
name: patroni-1

restapi:
  listen: 0.0.0.0:8008
  connect_address: 10.0.0.11:8008

etcd3:
  hosts:
    - 10.0.0.21:2379
    - 10.0.0.22:2379
    - 10.0.0.23:2379

bootstrap:
  dcs:
    ttl: 30
    loop_wait: 10
    retry_timeout: 10
    maximum_lag_on_failover: 1048576
    postgresql:
      use_pg_rewind: true
      parameters:
        wal_log_hints: "on"
        archive_mode: "on"
        archive_command: "pgbackrest --stanza=main archive-push %p"

postgresql:
  listen: 0.0.0.0:5432
  connect_address: 10.0.0.11:5432
  data_dir: /var/lib/postgresql/16/main
  bin_dir: /usr/lib/postgresql/16/bin
  authentication:
    superuser:
      username: postgres
    replication:
      username: replicator

watchdog:
  mode: automatic
  device: /dev/watchdog
  safety_margin: 5

İki ayrıntı sık atlanıyor. etcd'nin güncel sürümleri v2 API'yi varsayılan olarak kapalı tutar, bu yüzden bölüm adı etcd3 olmalı. Ayrıca bootstrap.dcs altındaki her şey yalnız cluster ilk kez oluşturulurken etcd'ye yazılır. Sonradan dosyada ttl değerini değiştirip Patroni'yi yeniden başlatmanın hiçbir etkisi olmaz; çalışan cluster'da bu ayarlar patronictl edit-config ile değişir.

HAProxy sağlık kontrolünü 5432 yerine Patroni'nin REST API'sine yapar. /primary yalnız leader'da 200 döner; okuma trafiği için aynı bloğu /replica ile ikinci bir portta tekrarlayabilirsiniz.

listen postgres_rw
    bind *:5000
    mode tcp
    option httpchk GET /primary
    http-check expect status 200
    default-server inter 3s fall 3 rise 2 on-marked-down shutdown-sessions
    server patroni-1 10.0.0.11:5432 check port 8008
    server patroni-2 10.0.0.12:5432 check port 8008
    server patroni-3 10.0.0.13:5432 check port 8008

on-marked-down shutdown-sessions eski leader'a açık kalmış bağlantıları keser; bu olmadan uygulama artık read-only olan bir node'a yazmayı denemeye devam edebilir.

Split-brain ve veri kaybı

Patroni'nin split-brain koruması etcd'nin çoğunluk kuralına dayanır. Leader, etcd'ye ulaşıp lock'unu yenileyemezse kendini read-only'ye düşürür, ağın azınlıkta kalan tarafında kimse leader olamaz. Bunun hoş olmayan yan etkisi, etcd çoğunluğunu kaybettiğinde PostgreSQL'ler sapasağlam olsa bile yazmanın durmasıdır. Patroni 3.0 ile gelen failsafe_mode bunu yumuşatır: leader diğer bütün üyelere REST API üzerinden ulaşabiliyorsa görevde kalır. İki üyeli etcd tek üyeliden daha kötüdür, çünkü biri gidince çoğunluk da gider. Üç ya da beş üye kullanın.

Zincirin zayıf halkası Patroni sürecinin donmasıdır. Lock düşer, başka bir node promote olur, ama donmuş node'daki PostgreSQL hâlâ yazma kabul ediyordur. Yukarıdaki watchdog bölümü bunun için var: Patroni kernel'in watchdog cihazını düzenli besler, besleyemezse makine yeniden başlar.

Varsayılan kurulumda replikasyon asenkrondur, yani failover anında replica'ya henüz ulaşmamış commit'ler kaybolur. maximum_lag_on_failover bu kaybın üst sınırını bayt cinsinden koyar; daha fazla geride kalan replica aday olamaz. Sıfır kayıp istiyorsanız synchronous_mode: true açarsınız, karşılığında her commit bir replica'nın onayını bekler ve yazma gecikmesi artar.

Yedek ve günlük işletim

Replica yedek sayılmaz; yanlışlıkla çalıştırılan bir DELETE saniyeler içinde bütün node'lara ulaşır. Yapılandırmadaki archive_command bu yüzden pgBackRest'e bağlı. Tam yedek ve belirli bir ana dönüş şöyle görünür:

pgbackrest --stanza=main --type=full backup
pgbackrest --stanza=main --delta --type=time --target="2026-04-01 14:30:00+03" restore

Restore PostgreSQL kapalıyken çalışır. Patroni'yi durdurmadan denerseniz veritabanını sizin yerinize yeniden başlatmaya çalışır; prosedürü sakin bir günde prova edin.

Günlük hayatta en çok patronictl -c /etc/patroni/patroni.yml list komutunu kullanırsınız; üyeleri, rollerini, timeline'ı ve replication lag'i gösterir. Planlı bakımda leader'ı patronictl switchover ile değiştirirsiniz, ttl beklenmediği için failover'dan çok daha kısa sürer. İzleme tarafında ilk kuracağım uyarılar replication lag, leader'sız geçen süre ve etcd üyelerinin sağlığı olurdu.

Kurulum bitince leader'ın fişini gerçekten çekin, sonra etcd üyelerinden ikisini kapatın ve ne olduğunu izleyin. Failover'ın çalıştığını ilk kez gerçek bir kesintide öğrenmek istemezsiniz.

#PostgreSQL#Patroni#HA#Database