PostgreSQL'de ara sürüm (minor) yükseltmesi, örneğin 18.1'den 18.6'ya geçiş, yalnızca sunucu kapalıyken ikili dosyaları değiştirip yeniden başlatmaktır; veri dizinine dokunulmaz. Ana sürüm (major) yükseltmesinde ise iç depolama biçimi değişebileceği için üç yoldan biri gerekir: pg_dumpall ile mantıksal döküm alıp yeni kümeye yüklemek, pg_upgrade ile veri dosyalarını yeniden kullanarak yerinde yükseltmek ya da logical replication ile yeni sürümdeki bir kopyaya geçmek. Her durumda önce aradaki tüm ana sürümlerin sürüm notlarındaki "Migration" bölümünü okursunuz.
Bu yazı kılavuzun "Upgrading a PostgreSQL Cluster" bölümünü, pg_upgrade başvuru sayfasını ve PostgreSQL 18 sürüm notlarını temel alır. Test ortamımızda yalnızca PostgreSQL 18.1 kurulu olduğu için iki ayrı ana sürüm arasında gerçek bir pg_upgrade çalıştırılmadı; pg_upgrade komutları kılavuzdaki biçimiyle gösteriliyor ve bu açıkça belirtiliyor. pg_dumpall ile bir kümeden ikinci bir 18.1 kümesine taşıma ise gerçekten çalıştırıldı. Serinin geri kalanı için PostgreSQL öğrenme rehberine bakabilirsiniz.
Sürüm numarası: ana sürüm ve ara sürüm
PostgreSQL 10'dan bu yana sürüm numarası iki parçalıdır: 18.1'de 18 ana sürüm, 1 ise o ana sürümün birinci ara sürümüdür. 10 öncesinde ana sürüm ilk iki sayıydı (9.5.3'te 9.5 ana, 3 ara sürüm). Çalışan sunucunun sürümünü SQL ile öğrenebilirsiniz:
SELECT version();
SHOW server_version; -- sonuç: 18.1
SHOW server_version_num; -- sonuç: 180001 version
-------------------------------------------------------------------------
PostgreSQL 18.1 on x86_64-windows, compiled by msvc-19.44.35219, 64-bit
(1 row)Kılavuzun temel kuralı şudur: ara sürümler iç depolama biçimini hiçbir zaman değiştirmez ve aynı ana sürümün önceki ve sonraki ara sürümleriyle her zaman uyumludur. Bu yüzden 18.x ara sürümleri arasında geçişte döküm/geri yükleme gerekmez. Ana sürümlerde ise biçim değişebilir, ayrıca kullanıcıya görünen uyumsuzluklar gelebilir; uygulama kodunda değişiklik gerekebilir.
| Ara sürüm (18.1 ile 18.6) | Ana sürüm (17 ile 18) | |
|---|---|---|
| Veri biçimi | Değişmez | Değişebilir |
| Yöntem | Sunucuyu durdur, ikili dosyaları değiştir, başlat | pg_dumpall, pg_upgrade veya logical replication |
| Okunacak not | İlgili ara sürüm notlarının Migration bölümü | Aradaki tüm ana sürümlerin Migration bölümleri |
| Kesinti | Yeniden başlatma süresi | Yönteme göre dakikalardan saatlere |
Ara sürüm yükseltmesi ve notları okumak
Ara sürüm yükseltmesi teknik olarak basittir, ama "notlara bakmadan değiştir" demek değildir. 18 serisinin her ara sürüm notu "18.X kullananlar için döküm/geri yükleme gerekmez" diye başlar, ardından bazı durumlarda ek işlem ister. Örneğin 18.2 notları ltree sütunlarında indeks varsa güncellemeden sonra yeniden indekslemenin gerekebileceğini söyler. 18.6 notları ise üç güvenlik maddesinin yapılandırma ayarı ve veri temizliği gerektirebileceğini, GIN indeksi olan tablolarda reltuples değerleriyle ilgili bir maddeye bakılması gerektiğini ve btree_gist ya da ltree kullanılıyorsa yeniden indekslemenin gerekebileceğini belirtir. 18.5 hiç yayımlanmamıştır; notlara göre paketleme sonrası bulunan bir gerileme nedeniyle atlanmıştır.
Bir sürümü atlıyorsanız atladığınız her sürümün notunu okuyun. 18.3, 18.4 ve 18.6 notlarının hepsi "18.2'den eski bir sürümden geliyorsanız 18.2 bölümüne bakın" der. Yani 18.1'den 18.6'ya geçen biri 18.2'nin ltree uyarısını da dikkate almalıdır. Sunucuyu durdurup başlatmanın ayrıntıları initdb ve pg_ctl yazısında, paketlerin nereden alınacağı ise kılavuzun gösterdiği tek yer olan https://www.postgresql.org/download/ adresindedir.
Yöntem 1: pg_dumpall ile döküm ve geri yükleme
Mantıksal döküm her ana sürüm geçişinde çalışan geleneksel yöntemdir. Kılavuz dosya sistemi düzeyindeki yedeklerin bu iş için kullanılamayacağını, mantıksal bir araç gerektiğini vurgular. İki önemli tavsiyesi vardır: döküm araçlarının yeni sürüme ait olanını kullanın, çünkü iyileştirmeler ve hata düzeltmeleri oradadır (güncel döküm araçları 9.2'ye kadar eski sunuculardan okuyabilir); ve döküm sırasında veritabanının güncellenmediğinden emin olun, gerekirse pg_hba.conf ile erişimi kısın. Değişen veri dökümün bütünlüğünü bozmaz ama dökümde yer almaz.
En kısa kesinti için kılavuz, yeni sunucuyu ayrı bir dizine kurup eski ve yeni sunucuyu farklı portlarda paralel çalıştırmayı ve veriyi doğrudan aktarmayı önerir: pg_dumpall -p 5432 | psql -d postgres -p 5433. Biz aynı işlemi iki ayrı 18.1 kümesi arasında, ara dosya kullanarak çalıştırdık; kaynak 46480, hedef 46481 portunda dinliyordu:
pg_dumpall -h 127.0.0.1 -p 46480 -U postgres -f tum.sql
psql -h 127.0.0.1 -p 46481 -U postgres -X -q -d postgres -f tum.sqlpsql:tum.sql:16: ERROR: role "postgres" already exists(psql hata satırının başına dosyanın tam yolunu yazar; burada yol kısaltıldı.) Bu hata beklenendir. pg_dumpall sayfası, betiğin kaynaktaki her rol için CREATE ROLE çalıştırdığını, bu yüzden hedef küme aynı adlı önyükleme süper kullanıcısıyla oluşturulduysa "role already exists" hatasının kesin olarak çıkacağını ve zararsız olduğunu söyler. Betiğin hatasız tamamlanması beklenmemelidir; önemli olan başka hata olmamasıdır. Aktarımdan sonra hedef kümede tabloyu sorguladık:
psql -h 127.0.0.1 -p 46481 -U postgres -X -d ornek_upg -c "SELECT * FROM siparis" id | musteri | tutar
----+---------------+---------
1 | Ayşe Yılmaz | 250.00
2 | Mehmet Öztürk | 1200.50
(2 rows)Döküm dosyasındaki CREATE DATABASE satırları her veritabanının kodlamasını ve yerel ayar sağlayıcısını da taşır; örneğin dosyamızda CREATE DATABASE ornek_upg WITH TEMPLATE = template0 ENCODING = 'UTF8' LOCALE_PROVIDER = builtin LOCALE = 'C' BUILTIN_LOCALE = 'C.UTF-8'; satırı vardı. Kılavuz, postgres ve template1 veritabanlarının da kaynaktaki özellikleri koruması isteniyorsa --clean seçeneğini önerir; bu durumda başlangıçta postgres veritabanına bağlanmak gerekir. Yeni kümede pg_hba.conf ve postgresql.conf değişikliklerinizi de geri yüklemeyi unutmayın; döküm bunları içermez. Döküm biçimleri ve seçici geri yükleme için pg_dump ve pg_restore yazısına, yedek stratejisi için veritabanı yedekleme stratejileri yazısına bakın.
Bu yöntemin artısı, yeni kümeyi farklı yerel ayar, kodlama veya initdb seçenekleriyle kurma serbestliğidir; örneğin geçişi veritabanlarını ICU Türkçe collation ile yeniden oluşturmak için de kullanabilirsiniz (ayrıntı collation ve Türkçe sıralama yazısında). Eksisi, büyük veritabanlarında dökümün ve indekslerin yeniden kurulmasının uzun sürmesidir.
Yöntem 2: pg_upgrade ile yerinde yükseltme
pg_upgrade, ana sürümlerin çoğunlukla sistem tablolarının düzenini değiştirdiğini ama kullanıcı verisinin iç biçimini nadiren değiştirdiğini kullanır: yeni sistem tablolarını oluşturur ve eski kullanıcı veri dosyalarını yeniden kullanır. 9.2.X ve sonrasından güncel ana sürüme yükseltmeyi destekler; ara sürüm yükseltmesinde gerekmez. Sözdizimi şöyledir:
pg_upgrade -b eski_bin -B yeni_bin -d eski_veri -D yeni_veri [secenek...]Dosyaların yeni kümeye nasıl aktarılacağı en önemli seçimdir. Varsayılan kopyalamadır ve eski kümeyi olduğu gibi bırakır. Diğer modlar daha hızlıdır ama koşulları vardır:
| Seçenek | Ne yapar | Eski küme sonra kullanılabilir mi | Koşul |
|---|---|---|---|
| --copy (varsayılan) | Dosyaları kopyalar | Evet | İki kat disk alanı |
| -k, --link | Kopya yerine sabit bağlantı (hard link) | Yeni küme başlatıldıktan sonra hayır | Aynı dosya sistemi |
| --clone | Dosya klonlama (reflink) | Evet | Linux Btrfs/XFS (reflink), macOS APFS; aynı dosya sistemi |
| --copy-file-range | copy_file_range sistem çağrısı | Evet | Linux ve FreeBSD |
| --swap | Veri dizinlerini taşır, katalogları değiştirir | Dosya aktarımı başladıktan sonra hayır | Aynı dosya sistemi; PostgreSQL 18 ile geldi |
Diğer önemli seçenekler: -c veya --check yalnızca uyumluluk denetimi yapar, hiçbir veriyi değiştirmez ve eski sunucu çalışırken de kullanılabilir. -j ile birden çok veritabanı ve tablespace paralel işlenir; kılavuz başlangıç değeri olarak makinedeki CPU çekirdeği sayısını önerir. -p ve -P eski ve yeni küme portlarıdır; pg_upgrade istenmeyen istemci bağlantılarını önlemek için varsayılan olarak 50432 portunu kullanır. Canlı bir eski sunucuyu denetlerken iki port farklı olmalıdır. -N (--no-sync) dosyaların diske yazılmasını beklemez; kılavuz bunun yalnızca test için uygun olduğunu, üretimde kullanılmaması gerektiğini söyler.
pg_upgrade adımları
Kılavuz 17 adımlık bir yol izler. Özetle, sıra şöyledir (komutlar kılavuzdaki örneklerdir ve bu ortamda iki farklı ana sürüm bulunmadığı için çalıştırılmadı):
- Yeni sürümün ikili dosyalarını ayrı bir dizine kurun. Sürüme özel dizin kullanan kurulumlarda (ör.
/opt/PostgreSQL/18) eski kümeyi taşımanız gerekmez. - Yeni kümeyi
initdbile, eski kümeyle uyumlu seçeneklerle oluşturun; başlatmanız gerekmez. - Eklentilerin paylaşılan kitaplık dosyalarını yeni kümeye kurun, ama
CREATE EXTENSIONçalıştırmayın; şema tanımları eski kümeden gelir. Özel full text search dosyalarını (sözlük, eşanlamlı, thesaurus, stop word) kopyalayın. - Kimlik doğrulamayı ayarlayın;
pg_upgradeiki sunucuya birkaç kez bağlanır. Kılavuzpg_hba.confiçindepeerya da bir~/.pgpassdosyası önerir. - İki sunucuyu da durdurun, sonra yeni sürümün
pg_upgradeprogramını önce--checkile, ardından gerçek olarak çalıştırın. Kılavuz eski sürümün programını değil her zaman yeni sürümünkini çalıştırmayı söyler. pg_hba.confve diğer yapılandırma dosyalarını eski kümeye uyacak şekilde düzenleyin, yeni sunucuyu başlatın,pg_upgrade'in ürettiği betikleri ve istatistik komutlarını çalıştırın.- Memnun kaldığınızda,
pg_upgrade'in sonunda verdiği betikle eski kümeyi silin.
Unix üzerinde sunucuları durdurma örneği ve Windows'ta yönetici hesabıyla, dizinleri tırnak içinde vererek çalıştırma örneği kılavuzda şöyle geçer. Windows örneğindeki NET STOP servis adları kendi kurulumunuza göre değişir:
# Unix (kılavuzdaki örnek)
pg_ctl -D /opt/PostgreSQL/12 stop
pg_ctl -D /opt/PostgreSQL/18 stop
# Windows (kılavuzdaki örnek, yönetici hesabıyla)
NET STOP postgresql-12
NET STOP postgresql-18
pg_upgrade.exe
--old-datadir "C:/Program Files/PostgreSQL/12/data"
--new-datadir "C:/Program Files/PostgreSQL/18/data"
--old-bindir "C:/Program Files/PostgreSQL/12/bin"
--new-bindir "C:/Program Files/PostgreSQL/18/bin"--check çalıştırması yükseltmeden sonra elle yapmanız gereken ayarları da listeler. Link, clone, copy-file-range veya swap modunu kullanacaksanız kılavuz, moda özgü denetimlerin de yapılması için aynı seçeneği --check ile birlikte vermenizi ister. 18.6 notlarına göre 17 ve sonrasından yükseltirken, eski kümedeki logical replication slotlarının çıktı eklentilerine yeni kümedeki output_plugin_libraries parametresi izin vermiyorsa pg_upgrade --check başarısız olur.
# kılavuzdaki seçeneklerle bir denetim komutu (bu ortamda çalıştırılmadı)
pg_upgrade --check --link -j 4 \
-b /opt/PostgreSQL/17/bin -B /opt/PostgreSQL/18/bin \
-d /opt/PostgreSQL/17/data -D /opt/PostgreSQL/18/dataYükseltme sonrası: istatistikler ve betikler
PostgreSQL 18 ile pg_upgrade planlayıcı istatistiklerinin çoğunu eski kümeden yeni kümeye taşır; sürüm notları bunu öne çıkan yenilikler arasında sayar ve devre dışı bırakmak için --no-statistics seçeneğini ekler. Ancak her şey taşınmaz: CREATE STATISTICS ile oluşturulan genişletilmiş istatistikler, eklentilerin özel istatistikleri ve kümülatif istatistik sistemi verileri aktarılmaz. Bu yüzden kılavuz yükseltmenin sonunda iki komut önerir: önce hiç istatistiği olmayan ilişkiler için hızlıca asgari istatistik üretmek, sonra tüm ilişkilerin istatistiklerini güncellemek.
vacuumdb --all --analyze-in-stages --missing-stats-only
vacuumdb --all --analyze-onlyİki komut da --jobs ile hızlandırılabilir. vacuum_cost_delay sıfırdan farklıysa kılavuz PGOPTIONS='-c vacuum_cost_delay=0' vacuumdb ... biçimiyle bu gecikmenin geçici olarak kaldırılabileceğini belirtir. --missing-stats-only seçeneği de PostgreSQL 18 ile gelmiştir. ANALYZE ve istatistiklerin işleyişi VACUUM, autovacuum ve bloat yazısında anlatılıyor.
pg_upgrade yeniden oluşturma gerektiren tablo veya indeks bulursa bitişte uyarı verir ve yöneticinin psql --username=postgres --file=script.sql postgres biçimiyle çalıştırması gereken betikler üretir. Betikler herhangi bir sırayla çalıştırılabilir. Kılavuz, yeniden oluşturma betiklerinde adı geçen tablolara betikler bitmeden erişmenin yanlış sonuç veya kötü performans verebileceği konusunda uyarır.
Geri dönüş planı
Kılavuz geri dönüşü moda göre ayırır. --check kullanıldıysa ya da ne --link ne --swap kullanıldıysa eski küme değişmemiştir ve yeniden başlatılabilir. Link modunda, bağlama başlamadan önce durulduysa eski küme sağlamdır; bağlama başladıysa ama yeni küme hiç başlatılmadıysa $PGDATA/global/pg_control dosyasına eklenen .old sonekini kaldırmak yeterlidir; yeni küme başlatıldıysa paylaşılan dosyalara yazılmıştır ve eski küme yedekten geri yüklenmelidir. Swap modunda pg_upgrade eski kümenin artık güvenle başlatılamayacağını bildirdiyse yine yedekten dönmek gerekir. Sonuç: link veya swap kullanacaksanız önce güncel bir yedek alın; WAL arşivleme ve PITR ya da pg_dump bu iş için uygundur. Kılavuz, eski kümenin değişmemesini istiyorsanız clone modunu, o yoksa kümenin bir kopyasını link moduyla yükseltmeyi önerir.
Yöntem 3: logical replication ile geçiş
Logical replication farklı ana sürümler arasında çalıştığı için yeni sürümde bir kopya kurup eski sunucuyla senkronize edebilir, ardından rolleri değiştirip eski sunucuyu kapatabilirsiniz. Kılavuz bu geçişin yalnızca birkaç saniyelik kesintiyle yapılabileceğini belirtir. Kurulumu logical replication yazısında bulabilirsiniz. Fiziksel streaming replication ise aynı ana sürüm gerektirir; pg_upgrade sayfası link moduyla yükseltilen kümelerde standby sunucularının rsync ile hızlıca güncellenmesini ayrıca anlatır. Standby yapısı için streaming replication yazısına bakın.
Sık yapılan hatalar
- Eski sürümün
pg_upgradeveyapg_dumpallprogramını kullanmak: kılavuz ikisinde de yeni sürümün araçlarını önerir. - Yalnızca hedef sürümün notunu okumak: aradaki her ana sürümün Migration bölümü ve atlanan ara sürüm notları okunmalıdır.
- Eklenti paylaşılan dosyalarını yeni kümeye kurmamak ya da yeni kümede
CREATE EXTENSIONçalıştırıp şemayı çiftlemek. - Link modunda yeni kümeyi başlattıktan sonra eski kümeye dönebileceğini sanmak.
regconfig,regcollation,regprocgibi OID'ye başvuranreg*tiplerinde sütun bulunan veritabanlarınıpg_upgradeile yükseltmeye çalışmak: kılavuza göre bunlar desteklenmez (regclass,regroleveregtypehariç).- Yükseltmeden sonra istatistik komutlarını atlamak: genişletilmiş istatistikler taşınmaz, planlar ilk günlerde beklenenden kötü olabilir.
Sık Sorulan Sorular
17'den 18'e geçerken arada bir sürüme uğramam gerekir mi?
Hayır. Kılavuz ara ana sürümlere yükseltmeden doğrudan geçilebileceğini, ama aradaki tüm ana sürümlerin notlarının okunması gerektiğini söyler. pg_upgrade 9.2.X ve sonrasını doğrudan destekler.
pg_dumpall mı pg_upgrade mı?
Veritabanı küçükse veya yeni kümede yerel ayar, kodlama gibi temel seçimleri değiştirmek istiyorsanız pg_dumpall sade ve öngörülebilirdir. Büyük kümelerde kesintiyi kısaltmak için pg_upgrade, özellikle link veya clone modu, dakikalar düzeyinde yükseltme sağlar. Kesintinin neredeyse sıfır olması gerekiyorsa logical replication düşünülür.
pg_upgrade --check eski sunucuyu durdurmamı gerektirir mi?
Hayır. Kılavuza göre --check eski sunucu çalışırken de kullanılabilir; bu durumda eski ve yeni port numaraları farklı olmalıdır. Gerçek yükseltme için iki sunucu da durdurulmalıdır.
Yükseltmeden sonra collation uyarısı alırsam ne yapmalıyım?
İşletim sistemi veya ICU sürümü değiştiyse collation sürüm uyuşmazlığı uyarısı görülebilir. İlgili indeksleri REINDEX ile yeniden kurup sonra ALTER COLLATION ... REFRESH VERSION çalıştırın; ayrıntı collation 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 18 yenilikleri · pg_dump ve pg_restore · Logical replication · Kurulum, initdb ve pg_ctl · Yedekleme stratejileri