PG_UPGRADE(1) PostgreSQL 18.6 Documentation PG_UPGRADE(1)

pg_upgrade - ارتقای یک نمونه سرور PostgreSQL

pg_upgrade -b oldbindir [-B newbindir] -d oldconfigdir -D newconfigdir [option...]

دستور pg_upgrade (که سابقاً pg_migrator نامیده می‌شد) این امکان را فراهم می‌کند که داده‌های ذخیره‌شده در فایل‌های دادهٔ PostgreSQL بدون نیاز به عملیات معمول تخلیه/بازیابی (dump/restore) برای ارتقای نسخه‌های اصلی (major)، به یک نسخهٔ اصلی بالاتر از PostgreSQL ارتقا یابند؛ برای مثال از 12.14 به 13.10 یا از 14.9 به 15.5. استفاده از این ابزار برای ارتقای نسخه‌های فرعی (minor) لازم نیست؛ مانند ارتقا از 12.7 به 12.8 یا از 14.1 به 14.5.

انتشارهای اصلی PostgreSQL مرتباً قابلیت‌های جدیدی اضافه می‌کنند که اغلب ساختار جدول‌های سیستمی را تغییر می‌دهد، اما قالب درونی ذخیره‌سازی داده‌ها به‌ندرت دستخوش تغییر می‌شود. pg_upgrade با بهره‌گیری از این ویژگی، از طریق ساخت جدول‌های سیستمی جدید و بازاستفادهٔ ساده از فایل‌های دادهٔ کاربر قدیمی، ارتقاهایی سریع را به انجام می‌رساند. اگر یک انتشار اصلی در آینده قالب ذخیره‌سازی داده‌ها را به‌گونه‌ای تغییر دهد که قالب دادهٔ قدیمی غیرقابل‌خواندن شود، pg_upgrade برای چنین ارتقاهایی قابل‌استفاده نخواهد بود. (جامعهٔ توسعه‌دهندگان تلاش خواهد کرد تا از بروز چنین وضعیتی جلوگیری کند.)

ابزار pg_upgrade تمام تلاش خود را به کار می‌بندد تا مطمئن شود کلاسترهای قدیمی و جدید از نظر باینری سازگار هستند؛ برای نمونه، با بررسی سازگاری تنظیمات زمان کامپایل، از جمله باینری‌های 32/64-bit. بسیار مهم است که هرگونه ماژول خارجی نیز سازگاری باینری داشته باشد، هرچند که این موضوع توسط pg_upgrade قابل بررسی نیست.

ابزار pg_upgrade از ارتقا از نسخهٔ 9.2.X و بالاتر به نسخهٔ اصلی کنونی PostgreSQL، شامل نسخه‌های snapshot و beta پشتیبانی می‌کند.


هشدار

ارتقای یک کلاستر باعث می‌شود که مقصد کدهای دلخواه به انتخاب مدیران سیستم (superusers) مبدأ را اجرا کند. پیش از ارتقا اطمینان حاصل کنید که مدیران سیستم مبدأ مورد اعتماد هستند.

pg_upgrade آرگومان‌های خط فرمان زیر را می‌پذیرد:

-b bindir
--old-bindir=bindir

دایرکتوری فایل‌های اجرایی قدیمی PostgreSQL؛ متغیر محیطی PGBINOLD

-B bindir
--new-bindir=bindir

دایرکتوری فایل‌های اجرایی جدید PostgreSQL؛ پیش‌فرض دایرکتوری‌ای است که pg_upgrade در آن قرار دارد؛ متغیر محیطی PGBINNEW

-c
--check

فقط کلاسترها را بررسی می‌کند و هیچ داده‌ای را تغییر نمی‌دهد

-d configdir
--old-datadir=configdir

دایرکتوری پیکربندی کلاستر پایگاه دادهٔ قدیمی؛ متغیر محیطی PGDATAOLD

-D configdir
--new-datadir=configdir

دایرکتوری پیکربندی کلاستر پایگاه دادهٔ جدید؛ متغیر محیطی PGDATANEW

-j njobs
--jobs=njobs

تعداد اتصالات و فرایندها/نخ‌های (threads) هم‌زمان مورد استفاده

-k
--link

استفاده از پیوندهای سخت (hard links) به جای کپی کردن فایل‌ها به کلاستر جدید

-N
--no-sync

به‌طور پیش‌فرض، pg_upgrade منتظر می‌ماند تا تمام فایل‌های کلاستر ارتقایافته با ایمنی روی دیسک نوشته شوند. این گزینه باعث می‌شود که pg_upgrade بدون انتظار بازگردد، که سریع‌تر است اما به این معنی است که فروپاشی (crash) بعدی سیستم‌عامل می‌تواند دایرکتوری داده‌ها را خراب کند. به‌طور کلی، این گزینه برای آزمودن مفید است اما نباید در یک محیط عملیاتی واقعی (production) استفاده شود.

-o options
--old-options options

گزینه‌هایی که باید مستقیماً به دستور قدیمی postgres ارسال شوند؛ فراخوانی‌های مکرر این گزینه به هم الحاق می‌شوند

-O options
--new-options options

گزینه‌هایی که باید مستقیماً به دستور جدید postgres ارسال شوند؛ فراخوانی‌های مکرر این گزینه به هم الحاق می‌شوند

-p port
--old-port=port

شماره درگاه (port) کلاستر قدیمی؛ متغیر محیطی PGPORTOLD

-P port
--new-port=port

شماره درگاه (port) کلاستر جدید؛ متغیر محیطی PGPORTNEW

-r
--retain

نگه‌داشتن فایل‌های SQL و فایل‌های گزارش (log) حتی پس از اتمام موفقیت‌آمیز -s dir
--socketdir=dir
دایرکتوری مورد استفاده برای سوکت‌های postmaster در طول ارتقا؛ پیش‌فرض دایرکتوری کاری فعلی است؛ متغیر محیطی PGSOCKETDIR

-U username
--username=username

نام کاربر نصب‌کننده کلاستر؛ متغیر محیطی PGUSER

-v
--verbose

فعال‌سازی ثبت تفصیلی گزارش‌های داخلی

-V
--version

نمایش اطلاعات نسخه و سپس خروج

--clone

استفاده از شبیه‌سازی کارآمد فایل (که در برخی سیستم‌ها به عنوان “reflinks” شناخته می‌شود) به‌جای کپی کردن فایل‌ها به کلاستر جدید. این کار می‌تواند منجر به کپی تقریباً آنی فایل‌های داده شود و مزایای سرعتِ -k/--link را فراهم کند در حالی که کلاستر قدیمی دست‌نخورده باقی می‌ماند.

شبیه‌سازی فایل فقط در برخی از سیستم‌های عامل و سیستم‌های فایل پشتیبانی می‌شود. اگر انتخاب شود اما پشتیبانی نشود، اجرای pg_upgrade با خطا مواجه خواهد شد. در حال حاضر، این قابلیت در Linux (هسته 4.5 یا جدیدتر) با Btrfs و XFS (در سیستم‌های فایلی که با پشتیبانی از reflink ایجاد شده‌اند)، و در macOS با APFS پشتیبانی می‌شود.

--copy

کپی کردن فایل‌ها به کلاستر جدید. این حالت پیش‌فرض است. (همچنین ببینید: --link، --clone، --copy-file-range و --swap.)

--copy-file-range

استفاده از فراخوان سیستمی copy_file_range برای کپی کارآمد. در برخی سیستم‌های فایل، این روش نتایجی مشابه با --clone با اشتراک‌گذاری بلوک‌های فیزیکی دیسک ارائه می‌دهد، در حالی که در برخی دیگر ممکن است همچنان بلوک‌ها را کپی کند، اما این کار را از طریق یک مسیر بهینه‌شده انجام دهد. در حال حاضر، این قابلیت در Linux و FreeBSD پشتیبانی می‌شود.

--no-statistics

عدم بازیابی آمارها از کلاستر قدیمی در کلاستر جدید.

--set-char-signedness=option

تنظیم دستی علامت‌دار بودن (signedness) پیش‌فرض char برای کلاسترهای جدید. مقادیر ممکن عبارتند از signed و unsigned.

در زبان C، علامت‌دار بودن پیش‌فرض نوع char (در صورتی که صراحتاً مشخص نشده باشد) در بسترهای مختلف متفاوت است. برای مثال، char در پردازنده‌های x86 به‌طور پیش‌فرض signed char است اما در پردازنده‌های ARM به‌طور پیش‌فرض unsigned char است.

از PostgreSQL 18 به بعد، کلاسترهای پایگاه داده تنظیمات علامت‌دار بودن پیش‌فرض char مختص به خود را نگه می‌دارند، که می‌تواند برای اطمینان از رفتار سازگار در بسترهایی با علامت‌دار بودن پیش‌فرض متفاوت char استفاده شود. به‌طور پیش‌فرض، pg_upgrade هنگام ارتقا از یک کلاستر موجود، تنظیمات علامت‌دار بودن char را حفظ می‌کند. با این حال، هنگام ارتقا از PostgreSQL 17 یا قبل‌تر، pg_upgrade علامت‌دار بودن char پلتفرمی را اعمال می‌کند که روی آن ساخته شده است.

این گزینه به شما اجازه می‌دهد تا علامت‌دار بودن پیش‌فرض char را به‌طور صریح برای کلاستر جدید تنظیم کنید و مقادیر موروثی را بازنویسی نمایید. دو سناریوی مشخص وجود دارد که این گزینه در آن‌ها کاربرد دارد:

•اگر قصد دارید پس از ارتقا به پلتفرم دیگری مهاجرت کنید، نباید از این گزینه استفاده کنید. رفتار پیش‌فرض در این حالت مناسب است. در عوض، ارتقا را روی پلتفرم اصلی بدون این پرچم انجام دهید و سپس کلاستر را منتقل کنید. این رویکرد توصیه‌شده و امن‌ترین روش است.
•اگر قبلاً کلاستر را به پلتفرمی با علامت‌دار بودن char متفاوت منتقل کرده‌اید (برای مثال، از یک سیستم مبتنی بر x86 به یک سیستم مبتنی بر ARM)، باید از این گزینه برای مشخص کردن علامت‌دار بودنی مطابق با علامت‌دار بودن پیش‌فرض char در پلتفرم اصلی استفاده کنید. علاوه بر این، ضروری است که هیچ‌یک از فایل‌های داده بین انتقال فایل‌های داده و اجرای pg_upgrade تغییر داده نشوند. pg_upgrade باید اولین عملیاتی باشد که کلاستر را روی پلتفرم جدید راه‌اندازی می‌کند.

--swap

انتقال دایرکتوری‌های داده از کلاستر قدیمی به کلاستر جدید. سپس، جایگزین کردن فایل‌های کاتالوگ با فایل‌های تولیدشده برای کلاستر جدید. این حالت می‌تواند عملکرد بهتری نسبت به --link، --clone، --copy و --copy-file-range ارائه دهد، به‌ویژه در کلاسترهایی با رابطه‌های (relations) زیاد.

با این حال، این حالت فایل‌های زائد زیادی را در کلاستر قدیمی ایجاد می‌کند، که در صورت استفاده از --sync-method=syncfs می‌تواند مرحله همگام‌سازی فایل را طولانی کند. بنابراین، توصیه می‌شود به همراه --swap از --sync-method=fsync استفاده شود.

علاوه بر این، به‌محض آغاز مرحله انتقال فایل، کلاستر قدیمی به‌طور برگشت‌ناپذیری تغییر خواهد کرد و بنابراین راه‌اندازی مجدد آن دیگر ایمن نخواهد بود. برای جزئیات به Step 17 مراجعه کنید.

--sync-method=method

هنگامی که روی fsync تنظیم شود (که پیش‌فرض است)، pg_upgrade تمام فایل‌های موجود در دایرکتوری داده کلاستر ارتقایافته را به‌صورت بازگشتی باز کرده و همگام‌سازی می‌کند. جستجوی فایل‌ها، پیوندهای نمادین دایرکتوری WAL و هر tablespace پیکربندی‌شده را دنبال خواهد کرد.

در Linux، می‌توان به‌جای آن از syncfs استفاده کرد تا از سیستم‌عامل خواسته شود کل سیستم‌های فایلی را که شامل دایرکتوری داده کلاستر ارتقایافته، فایل‌های WAL آن و هر tablespace هستند، همگام‌سازی کند. برای کسب اطلاعات درباره هشدارهایی که باید هنگام استفاده از syncfs در نظر داشته باشید، به recovery_init_sync_method مراجعه کنید.

در صورت استفاده از --no-sync این گزینه هیچ تأثیری ندارد.

-?
--help

نمایش راهنما و سپس خروج

مراحل انجام ارتقا با استفاده از pg_upgrade به شرح زیر است:


نکته

مراحل ارتقای خوشه‌های رونوشت‌برداری منطقی (logical replication clusters) در اینجا پوشش داده نشده است؛ برای جزئیات به Section 29.13 مراجعه کنید.

1.انتقال اختیاری خوشه قدیمی: اگر از دایرکتوری نصبی مختص به نسخه مانند /opt/PostgreSQL/18 استفاده می‌کنید، نیازی به جابه‌جایی خوشه قدیمی ندارید. نصاب‌های گرافیکی همگی از دایرکتوری‌های نصب مختص به نسخه استفاده می‌کنند.

اگر دایرکتوری نصب شما مختص به نسخه نیست، برای مثال /usr/local/pgsql، لازم است دایرکتوری نصب فعلی PostgreSQL را جابه‌جا کنید تا با نصب نسخه جدید PostgreSQL تداخلی نداشته باشد. به محض اینکه سرور فعلی PostgreSQL متوقف شد، تغییر نام دایرکتوری نصب PostgreSQL بلامانع است؛ با فرض اینکه دایرکتوری قدیمی /usr/local/pgsql است، می‌توانید:

mv /usr/local/pgsql /usr/local/pgsql.old

را برای تغییر نام دایرکتوری اجرا کنید.

2.برای نصب از سورس، کامپایل نسخه جدید: سورس جدید PostgreSQL را با گزینه‌های (flags) configure سازگار با خوشه قدیمی کامپایل کنید. ابزار pg_upgrade پیش از آغاز ارتقا، pg_controldata را بررسی خواهد کرد تا اطمینان یابد همه تنظیمات سازگار هستند.
3.نصب باینری‌های جدید PostgreSQL: فایل‌های باینری و فایل‌های پشتیبان سرور جدید را نصب کنید. pg_upgrade در یک نصب پیش‌فرض گنجانده شده است.

برای نصب از سورس، اگر می‌خواهید سرور جدید را در مکانی سفارشی نصب کنید، از متغیر prefix استفاده نمایید:

make prefix=/usr/local/pgsql.new install
4.راه‌اندازی اولیه خوشه جدید PostgreSQL: خوشه جدید را با استفاده از initdb راه‌اندازی اولیه کنید. مجدداً، از گزینه‌های سازگار initdb که با خوشه قدیمی همخوانی دارند استفاده کنید. بسیاری از نصاب‌های آماده این مرحله را به طور خودکار انجام می‌دهند. نیازی به راه‌اندازی خوشه جدید نیست.
5.نصب فایل‌های شیء اشتراکی (shared object) افزونه‌ها: بسیاری از افزونه‌ها و ماژول‌های سفارشی، چه از contrib و چه از منبعی دیگر، از فایل‌های شیء اشتراکی (یا DLLها) مانند pgcrypto.so استفاده می‌کنند. اگر خوشه قدیمی از این موارد استفاده می‌کرد، فایل‌های شیء اشتراکی مطابق با باینری سرور جدید باید در خوشه جدید نصب شوند، که معمولاً از طریق دستورات سیستم‌عامل انجام می‌شود. تعاریف شِما (schema definitions) را، مانند CREATE EXTENSION pgcrypto، بارگذاری نکنید؛ زیرا این تعاریف از خوشه قدیمی تکثیر خواهند شد. اگر به‌روزرسانی‌هایی برای افزونه‌ها در دسترس باشد، pg_upgrade این موضوع را گزارش داده و اسکریپتی می‌سازد که می‌توان آن را بعداً برای به‌روزرسانی آن‌ها اجرا کرد.
6.کپی کردن فایل‌های سفارشی جستجوی تمام‌متن: هرگونه فایل سفارشی جستجوی تمام‌متن (فرهنگ لغت، مترادف‌ها، اصطلاح‌نامه و کلمات توقف) را از خوشه قدیمی به خوشه جدید کپی کنید.
7.تنظیم احراز هویت: ابزار pg_upgrade چندین بار به سرورهای قدیمی و جدید متصل خواهد شد، بنابراین ممکن است بخواهید روش احراز هویت را در pg_hba.conf روی peer تنظیم کنید یا از فایل ~/.pgpass استفاده نمایید (به Section 32.16 مراجعه کنید).
8.متوقف کردن هر دو سرور: مطمئن شوید هر دو سرور پایگاه‌داده متوقف شده‌اند؛ برای نمونه در Unix با اجرای: 
pg_ctl -D /opt/PostgreSQL/12 stop
pg_ctl -D /opt/PostgreSQL/18 stop
یا در Windows، با استفاده از نام‌های مناسب سرویس: 
NET STOP postgresql-12
NET STOP postgresql-18

سرورهای standby مبتنی بر streaming replication و log-shipping در طول این خاموش‌سازی باید در حال اجرا باشند تا تمام تغییرات را دریافت کنند.

9.آماده‌سازی برای ارتقای سرورهای standby: اگر سرورهای standby را با استفاده از روش‌های شرح‌داده‌شده در بخش Step 11 ارتقا می‌دهید، با اجرای pg_controldata روی کلاسترهای primary و standby قدیمی، بررسی کنید که سرورهای standby قدیمی همگام باشند. بررسی کنید که مقادیر “Latest checkpoint location” در همهٔ کلاسترها مطابقت داشته باشند. همچنین، مطمئن شوید که wal_level در فایل postgresql.conf روی کلاستر primary جدید برابر با minimal تنظیم نشده باشد.
10.اجرای pg_upgrade: همیشه باینری pg_upgrade مربوط به سرور جدید را اجرا کنید، نه سرور قدیمی را. pg_upgrade نیازمند مشخص کردن دایرکتوری‌های داده و اجرایی (bin) کلاستر قدیمی و جدید است. همچنین می‌توانید مقادیر کاربر و پورت را مشخص کنید، و اینکه آیا می‌خواهید فایل‌های داده به جای رفتار پیش‌فرض کپی (copy)، پیوند (linked)، همتاسازی (cloned) یا جابه‌جا (swapped) شوند.

اگر از حالت link استفاده کنید، ارتقا بسیار سریع‌تر خواهد بود (بدون کپی فایل) و فضای دیسک کمتری استفاده خواهد شد، اما پس از اینکه سرور جدید را بعد از ارتقا راه‌اندازی کردید، دیگر به کلاستر قدیمی خود دسترسی نخواهید داشت. حالت link همچنین نیاز دارد که دایرکتوری‌های دادهٔ کلاستر قدیمی و جدید در یک فایل سیستم قرار داشته باشند. (Tablespaceها و pg_wal می‌توانند در فایل سیستم‌های متفاوتی باشند.) حالت clone همان مزایای سرعت و فضای دیسک را فراهم می‌کند اما باعث نمی‌شود که کلاستر قدیمی پس از راه‌اندازی کلاستر جدید غیرقابل‌استفاده شود. حالت clone نیز نیازمند آن است که دایرکتوری‌های دادهٔ قدیمی و جدید در یک فایل سیستم باشند. این حالت فقط روی سیستم‌عامل‌ها و فایل سیستم‌های خاصی در دسترس است. حالت swap در صورت وجود relationهای بسیار ممکن است سریع‌ترین باشد، اما به‌محض شروع مرحلهٔ انتقال فایل، دیگر به کلاستر قدیمی خود دسترسی نخواهید داشت. حالت swap نیز مستلزم آن است که دایرکتوری‌های دادهٔ کلاستر قدیمی و جدید در یک فایل سیستم باشند.

تنظیم --jobs روی ۲ یا بالاتر به pg_upgrade اجازه می‌دهد چندین پایگاه داده و tablespace را به‌صورت موازی پردازش کند. یک نقطه شروع مناسب، تعداد هسته‌های CPU در سیستم است. این گزینه می‌تواند زمان ارتقا را برای سرورهای دارای چند پایگاه داده و چند tablespace به‌میزان چشمگیری کاهش دهد.

برای کاربران Windows، باید با یک حساب دارای دسترسی مدیریتی (administrative) وارد شده باشید، و سپس pg_upgrade را با دایرکتوری‌های داخل کوتیشن اجرا کنید، مانند:

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"

پس از شروع، pg_upgrade سازگاری دو کلاستر را بررسی می‌کند و سپس ارتقا را انجام می‌دهد. می‌توانید از pg_upgrade --check برای انجام صرفاً بررسی‌ها استفاده کنید، حتی اگر سرور قدیمی هنوز در حال اجرا باشد. pg_upgrade --check همچنین هرگونه تنظیمات دستی که باید بعد از ارتقا انجام دهید را مشخص خواهد کرد. اگر قصد دارید از حالت link، clone، copy-file-range یا swap استفاده کنید، باید از گزینهٔ --link، --clone، --copy-file-range، یا --swap به همراه --check استفاده کنید تا بررسی‌های ویژهٔ آن حالت فعال شوند. pg_upgrade به مجوز نوشتن در دایرکتوری فعلی نیاز دارد.

بدیهی است که هیچ‌کس نباید در طول فرایند ارتقا به کلاسترها دسترسی داشته باشد. pg_upgrade به‌طور پیش‌فرض سرورها را روی پورت 50432 اجرا می‌کند تا از اتصالات ناخواسته کلاینت‌ها جلوگیری شود. هنگام ارتقا می‌توانید از یک شماره پورت یکسان برای هر دو کلاستر استفاده کنید، زیرا کلاسترهای قدیمی و جدید به‌طور هم‌زمان در حال اجرا نخواهند بود. با این حال، هنگام بررسی یک سرور قدیمی در حال اجرا، شماره پورت‌های قدیم و جدید باید متفاوت باشند.

اگر هنگام بازیابی شمای پایگاه داده خطایی رخ دهد، pg_upgrade خارج خواهد شد و شما باید مطابق با آنچه در Step 17 در زیر آمده است به کلاستر قدیمی بازگردید. برای امتحان مجدد pg_upgrade، باید کلاستر قدیمی را اصلاح کنید تا بازیابی شمای pg_upgrade با موفقیت انجام شود. اگر مشکل ناشی از یک ماژول contrib باشد، ممکن است لازم باشد ماژول contrib را از کلاستر قدیمی حذف نصب کنید و پس از ارتقا آن را در کلاستر جدید نصب کنید، به شرطی که از آن ماژول برای ذخیره داده‌های کاربر استفاده نشده باشد.

11.ارتقای سرورهای standby تکثیر جریانی (streaming replication) و انتقال گزارش (log-shipping): اگر از حالت link استفاده کرده‌اید و سرورهای standby با Streaming Replication (به Section 26.2.5 مراجعه کنید) یا Log-Shipping (به Section 26.2 مراجعه کنید) دارید، می‌توانید این مراحل را برای ارتقای سریع آن‌ها دنبال کنید. شما pg_upgrade را روی سرورهای standby اجرا نخواهید کرد، بلکه rsync را روی سرور اصلی (primary) اجرا می‌کنید. هنوز هیچ سروری را راه‌اندازی نکنید.

اگر از حالت link استفاده نکرده‌اید، ابزار rsync را ندارید یا نمی‌خواهید از آن استفاده کنید، یا راه‌حل ساده‌تری می‌خواهید، از دستورالعمل‌های این بخش صرف‌نظر کنید و صرفاً پس از اتمام pg_upgrade و راه‌اندازی primary جدید، سرورهای standby را از نو ایجاد کنید.

1.نصب باینری‌های جدید PostgreSQL روی سرورهای standby: مطمئن شوید که فایل‌های باینری و فایل‌های پشتیبانی جدید روی همه سرورهای standby نصب شده باشند.
2.اطمینان حاصل کنید که دایرکتوری‌های دادهٔ جدید standby وجود نداشته باشند: مطمئن شوید که دایرکتوری‌های دادهٔ جدید standby وجود ندارند یا خالی هستند. اگر initdb اجرا شده است، دایرکتوری‌های دادهٔ جدید سرورهای standby را حذف کنید.
3.نصب فایل‌های شیء اشتراکی (shared object) افزونه: همان فایل‌های شیء اشتراکی افزونه‌ای را روی standbyهای جدید نصب کنید که روی کلاستر primary جدید نصب کرده‌اید.
4.توقف سرورهای standby: اگر سرورهای standby هنوز در حال اجرا هستند، اکنون آن‌ها را با استفاده از دستورالعمل‌های بالا متوقف کنید.
5.ذخیره فایل‌های پیکربندی: هر فایل پیکربندی از دایرکتوری‌های پیکربندی standbyهای قدیمی را که به نگهداری آن‌ها نیاز دارید ذخیره کنید، مانند postgresql.conf (و هر فایلی که توسط آن گنجانده شده است)، postgresql.auto.conf، pg_hba.conf، زیرا این فایل‌ها در مرحله بعدی بازنویسی یا حذف خواهند شد.
6.اجرای rsync: هنگام استفاده از حالت link، سرورهای standby را می‌توان به سرعت با استفاده از rsync ارتقا داد. برای انجام این کار، از دایرکتوری‌ای در سرور primary که بالاتر از دایرکتوری‌های خوشه‌های پایگاه‌داده قدیمی و جدید قرار دارد، این دستور را روی primary برای هر سرور standby اجرا کنید: 
rsync --archive --delete --hard-links --size-only --no-inc-recursive old_cluster new_cluster remote_dir

که در آن old_cluster و new_cluster نسبت به دایرکتوری جاری در primary هستند، و remote_dir در سرور standby بالاتر از دایرکتوری‌های خوشه‌های قدیمی و جدید قرار دارد. ساختار دایرکتوری زیر دایرکتوری‌های مشخص‌شده در primary و standbyها باید یکسان باشد. برای جزئیات مربوط به تعیین دایرکتوری دوردست (remote)، صفحه راهنمای rsync را بررسی کنید، به عنوان مثال:

rsync --archive --delete --hard-links --size-only --no-inc-recursive /opt/PostgreSQL/12 \
      /opt/PostgreSQL/18 standby.example.com:/opt/PostgreSQL

می‌توانید با استفاده از گزینهٔ --dry-run در rsync بررسی کنید که این دستور چه کاری انجام خواهد داد. در حالی که rsync باید دست‌کم برای یک standby روی primary اجرا شود، اما تا زمانی که standby ارتقایافته راه‌اندازی نشده باشد، اجرای rsync روی یک standby ارتقایافته برای ارتقای سایر standbyها نیز امکان‌پذیر است.

کاری که این عمل انجام می‌دهد، ثبت پیوندهایی است که توسط حالت link در pg_upgrade ایجاد شده‌اند و فایل‌های موجود در خوشه‌های قدیمی و جدید را در سرور primary به یکدیگر پیوند می‌دهند. سپس فایل‌های متناظر را در خوشه قدیمی standby پیدا کرده و پیوندهایی برای آن‌ها در خوشه جدید standby ایجاد می‌کند. فایل‌هایی که در primary پیوند داده نشده بودند از primary به standby کپی می‌شوند. (این فایل‌ها معمولاً کوچک هستند.) این سازوکار ارتقای سریع standby را فراهم می‌کند. متأسفانه، rsync فایل‌های مرتبط با جدول‌های temporary و unlogged را به صورت غیرضروری کپی می‌کند زیرا این فایل‌ها معمولاً در سرورهای standby وجود ندارند.

اگر tablespace دارید، باید دستور rsync مشابهی را برای دایرکتوری هر tablespace اجرا کنید، به عنوان مثال:

rsync --archive --delete --hard-links --size-only --no-inc-recursive /vol1/pg_tblsp/PG_12_201909212 \
      /vol1/pg_tblsp/PG_18_202307071 standby.example.com:/vol1/pg_tblsp

اگر pg_wal را به خارج از دایرکتوری‌های داده منتقل کرده‌اید، rsync باید روی آن دایرکتوری‌ها نیز اجرا شود.

7.پیکربندی سرورهای standby برای streaming replication و log-shipping: سرورها را برای log shipping پیکربندی کنید. (نیازی به اجرای pg_backup_start() و pg_backup_stop() یا تهیه نسخه پشتیبان از فایل‌سیستم نیست، زیرا standbyها همچنان با primary همگام هستند.) اگر primary قدیمی قبل از نسخه 17.0 باشد، هیچ slotای از primary به standby جدید کپی نمی‌شود، بنابراین تمام slotها در standby قدیمی باید به صورت دستی بازسازی شوند. اگر primary قدیمی نسخه 17.0 یا بالاتر باشد، تنها slotهای منطقی (logical slots) روی primary به standby جدید کپی می‌شوند، اما سایر slotها در standby قدیمی کپی نمی‌شوند و بنابراین باید به صورت دستی دوباره ایجاد شوند.
12.بازیابی pg_hba.conf: اگر pg_hba.conf را تغییر داده‌اید، تنظیمات اصلی آن را بازیابی کنید. همچنین ممکن است لازم باشد سایر فایل‌های پیکربندی در خوشه جدید را طوری تنظیم کنید تا با خوشه قدیمی مطابقت داشته باشند، مانند postgresql.conf (و تمام فایل‌های گنجانده‌شده توسط آن)، postgresql.auto.conf.
13.راه‌اندازی سرور جدید: سرور جدید اکنون می‌تواند با اطمینان راه‌اندازی شود، و سپس هر سرور standby که با rsync همگام‌سازی شده است.
14.پردازش‌های پس از ارتقا: اگر به پردازش‌های پس از ارتقا نیاز باشد، pg_upgrade هنگام اتمام کار خود هشدارهایی صادر خواهد کرد. همچنین فایل‌های اسکریپتی تولید خواهد کرد که باید توسط مدیر سیستم اجرا شوند. این اسکریپت‌ها به هر پایگاه‌داده‌ای که نیاز به پردازش‌های پس از ارتقا دارد متصل می‌شوند. هر اسکریپت باید با استفاده از دستور زیر اجرا شود: 
psql --username=postgres --file=script.sql postgres

اسکریپت‌ها را می‌توان به هر ترتیبی اجرا کرد و پس از اجرا می‌توان آن‌ها را حذف نمود.


احتیاط
به‌طور کلی، دسترسی به جدول‌هایی که در اسکریپت‌های بازسازی (rebuild) به آن‌ها ارجاع داده شده است تا پیش از اتمام کامل اجرای آن اسکریپت‌ها ناامن است؛ انجام این کار می‌تواند منجر به نتایج نادرست یا افت کارایی شود. جدول‌هایی که در اسکریپت‌های بازسازی ارجاع داده نشده‌اند بلافاصله قابل دسترسی هستند.
15.آمارها: مگر اینکه گزینهٔ --no-statistics مشخص شده باشد، pg_upgrade بیشتر آمارهای بهینه‌ساز را از کلاستر قدیمی به کلاستر جدید انتقال خواهد داد. این کار همهٔ آمارها را منتقل نمی‌کند، مانند آن‌هایی که به صراحت با CREATE STATISTICS (CREATE_STATISTICS(7)) ایجاد شده‌اند، آمارهای سفارشی اضافه‌شده توسط یک افزونه، یا آمارهای جمع‌آوری‌شده توسط سیستم آمارهای تجمعی.

از آنجا که همهٔ آمارها توسط pg_upgrade منتقل نمی‌شوند، در پایان ارتقا از شما خواسته می‌شود تا دستوراتی را برای بازتولید آن اطلاعات اجرا کنید. ممکن است نیاز باشد پارامترهای اتصال را برای تطابق با کلاستر جدید خود تنظیم کنید.

ابتدا از vacuumdb --all --analyze-in-stages --missing-stats-only برای تولید سریع حداقل آمارهای بهینه‌ساز برای رابطه‌های فاقد آمار استفاده کنید. سپس از vacuumdb --all --analyze-only استفاده کنید تا مطمئن شوید همهٔ رابطه‌ها دارای آمارهای تجمعی به‌روز شده برای راه‌اندازی vacuum و analyze هستند. برای هر دو دستور، استفاده از --jobs می‌تواند سرعت کار را بالا ببرد. اگر vacuum_cost_delay روی یک مقدار غیرصفر تنظیم شده باشد، می‌توان آن را با استفاده از PGOPTIONS نادیده گرفت تا تولید آمار تسریع شود، به عنوان مثال: PGOPTIONS='-c vacuum_cost_delay=0' vacuumdb ....

16.حذف کلاستر قدیمی: پس از حصول اطمینان از صحت ارتقا، می‌توانید دایرکتوری‌های دادهٔ کلاستر قدیمی را با اجرای اسکریپتی که در زمان تکمیل pg_upgrade به آن اشاره می‌شود، حذف کنید. (اگر فضاهای جدول (tablespaces) تعریف‌شده توسط کاربر در داخل دایرکتوری داده‌های قدیمی داشته باشید، حذف خودکار امکان‌پذیر نیست.) همچنین می‌توانید دایرکتوری‌های نصب قدیمی (مانند bin و share) را حذف کنید.
17.بازگشت به کلاستر قدیمی: اگر پس از اجرای pg_upgrade، مایل به بازگشت به کلاستر قدیمی باشید، چندین گزینه وجود دارد:
•اگر از گزینهٔ --check استفاده شده باشد، کلاستر قدیمی دست‌نخورده باقی مانده است؛ می‌توان آن را مجدداً راه‌اندازی کرد.
•اگر نه از --link و نه از --swap استفاده نشده باشد، کلاستر قدیمی دست‌نخورده باقی مانده است؛ می‌توان آن را مجدداً راه‌اندازی کرد.
•اگر از گزینهٔ --link استفاده شده باشد، فایل‌های داده ممکن است بین کلاستر قدیمی و جدید مشترک باشند:
•اگر pg_upgrade پیش از آغاز پیوندزدن متوقف شده باشد، کلاستر قدیمی دست‌نخورده باقی مانده است؛ می‌توان آن را مجدداً راه‌اندازی کرد.
•اگر کلاستر جدید را راه‌اندازی نکرده باشید، کلاستر قدیمی دست‌نخورده باقی مانده است، مگر اینکه در زمان شروع پیوندزدن، پسوند .old به $PGDATA/global/pg_control اضافه شده باشد. برای استفادهٔ مجدد از کلاستر قدیمی، پسوند .old را از $PGDATA/global/pg_control حذف کنید؛ سپس می‌توانید کلاستر قدیمی را دوباره راه‌اندازی کنید.
•اگر کلاستر جدید را راه‌اندازی کرده باشید، روی فایل‌های مشترک نوشته است و استفاده از کلاستر قدیمی ناامن خواهد بود. در این حالت، کلاستر قدیمی باید از نسخهٔ پشتیبان بازیابی شود.
•اگر از گزینهٔ --swap استفاده شده باشد، ممکن است کلاستر قدیمی به صورت مخرب تغییر یافته باشد:
•اگر pg_upgrade پیش از گزارش اینکه کلاستر قدیمی دیگر برای راه‌اندازی امن نیست متوقف شود، کلاستر قدیمی دست‌نخورده باقی مانده است؛ می‌توان آن را مجدداً راه‌اندازی کرد.
•اگر pg_upgrade گزارش داده باشد که کلاستر قدیمی دیگر برای راه‌اندازی امن نیست، کلاستر قدیمی دچار تغییرات مخرب شده است. در این حالت، کلاستر قدیمی باید از نسخهٔ پشتیبان بازیابی شود.

برخی متغیرهای محیطی می‌توانند برای فراهم کردن مقادیر پیش‌فرض گزینه‌های خط فرمان استفاده شوند:

PGBINOLD

دایرکتوری فایل‌های اجرایی قدیمی PostgreSQL؛ گزینهٔ -b/--old-bindir.

PGBINNEW

دایرکتوری فایل‌های اجرایی جدید PostgreSQL؛ گزینهٔ -B/--new-bindir.

PGDATAOLD

دایرکتوری پیکربندی کلاستر پایگاه‌دادهٔ قدیمی؛ گزینهٔ -d/--old-datadir.

PGDATANEW

دایرکتوری پیکربندی کلاستر پایگاه‌دادهٔ جدید؛ گزینهٔ -D/--new-datadir.

PGPORTOLD

شماره پورت کلاستر قدیمی؛ گزینهٔ -p/--old-port.

PGPORTNEW

شماره پورت کلاستر جدید؛ گزینهٔ -P/--new-port.

PGSOCKETDIR

دایرکتوری مورد استفاده برای سوکت‌های postmaster در حین ارتقا؛ گزینهٔ -s/--socketdir.

PGUSER

نام کاربر نصب‌کنندهٔ کلاستر؛ گزینهٔ -U/--username.

دستور pg_upgrade فایل‌های کاری گوناگونی ایجاد می‌کند، مانند دامپ‌های اسکیما، که درون pg_upgrade_output.d در دایرکتوری کلاستر جدید ذخیره می‌شوند. هر بار اجرا یک زیردایرکتوری جدید ایجاد می‌کند که بر اساس برچسب زمانی با قالب استاندارد ISO 8601 (%Y%m%dT%H%M%S) نام‌گذاری شده است، جایی که تمام فایل‌های تولیدشدهٔ آن ذخیره می‌شوند. در صورتی که pg_upgrade با موفقیت به پایان برسد، pg_upgrade_output.d و فایل‌های موجود در آن به‌طور خودکار حذف خواهند شد؛ اما در صورت بروز مشکل، فایل‌های موجود در آنجا ممکن است اطلاعات مفیدی برای اشکال‌زدایی فراهم کنند.

دستور pg_upgrade فرایندهای postmaster کوتاه‌مدتی را در دایرکتوری‌های داده‌های قدیمی و جدید راه‌اندازی می‌کند. فایل‌های موقت سوکت یونیکس برای ارتباط با این postmasterها، به‌طور پیش‌فرض در دایرکتوری کاری فعلی ایجاد می‌شوند. در برخی شرایط ممکن است نام مسیر دایرکتوری فعلی طولانی‌تر از آن باشد که یک نام سوکت معتبر به‌شمار آید. در این حالت می‌توانید از گزینهٔ -s برای قرار دادن فایل‌های سوکت در دایرکتوری دیگری با نام مسیر کوتاه‌تر استفاده کنید. برای امنیت، مطمئن شوید که آن دایرکتوری برای هیچ کاربر دیگری قابل خواندن یا نوشتن نباشد. (این ویژگی در Windows پشتیبانی نمی‌شود.)

تمام موارد شکست، بازسازی و نمایه‌سازی مجدد (reindex) در صورتی که بر روی نصب شما تأثیر بگذارند، توسط pg_upgrade گزارش خواهند شد؛ اسکریپت‌های پس از ارتقا برای بازسازی جدول‌ها و ایندکس‌ها به‌طور خودکار تولید خواهند شد. اگر در حال خودکارسازی ارتقای کلاسترهای متعددی هستید، درمی‌یابید که کلاسترهایی با اسکیماهای پایگاه‌دادهٔ یکسان، به مراحل پس از ارتقای مشابهی برای همهٔ کلاسترها نیاز دارند؛ این به این دلیل است که مراحل پس از ارتقا مبتنی بر اسکیماهای پایگاه‌داده هستند، و نه داده‌های کاربر.

برای آزمایش استقرار، یک رونوشتِ فقط اسکیما از کلاستر قدیمی ایجاد کنید، داده‌های صوری درون آن درج نمایید، و آن را ارتقا دهید.

دستور pg_upgrade از ارتقای پایگاه‌های داده‌ای که ستون‌های جدول آن‌ها از این انواع داده‌های سیستمی reg* ارجاع‌دهنده به OID استفاده می‌کنند، پشتیبانی نمی‌کند:

regcollation
regconfig
regdictionary
regnamespace
regoper
regoperator
regproc
regprocedure
(انواع regclass، regrole و regtype می‌توانند ارتقا یابند.)

اگر می‌خواهید از حالت پیوند (link mode) استفاده کنید و مایل نیستید با راه‌اندازی کلاستر جدید، کلاستر قدیمی دستخوش تغییر شود، استفاده از حالت کلون (clone mode) را در نظر بگیرید. در صورتی که این قابلیت در دسترس نیست، یک رونوشت از کلاستر قدیمی بگیرید و آن را در حالت پیوند ارتقا دهید. برای ایجاد یک نسخهٔ معتبر از کلاستر قدیمی، در حالی که سرور در حال اجراست از rsync برای ایجاد یک نسخهٔ ناهمگام (dirty copy) از کلاستر قدیمی استفاده کنید، سپس سرور قدیمی را خاموش کرده و مجدداً دستور rsync --checksum را اجرا نمایید تا نسخهٔ رونوشت با اعمال تغییرات، یکدست و همگام شود. (استفاده از گزینهٔ --checksum ضروری است چرا که rsync تنها از دقت زمانی یک ثانیه‌ای برای زمان ویرایش فایل‌ها برخوردار است.) ممکن است بخواهید برخی فایل‌ها، مانند postmaster.pid، را همان‌طور که در Section 25.3.4 مستند شده است، مستثنی کنید. اگر فایل‌سیستم شما از اسنپ‌شات‌های فایل‌سیستم یا کپی فایل‌های copy-on-write پشتیبانی می‌کند، می‌توانید از آن برای پشتیبان‌گیری از کلاستر قدیمی و tablespaceها استفاده کنید، اگرچه اسنپ‌شات و کپی‌ها باید هم‌زمان یا در زمان متوقف بودن سرور پایگاه‌داده ایجاد شوند..SH "همچنین ببینید (SEE ALSO)" initdb(1), pg_ctl(1), pg_dump(1), postgres(1)

2026 PostgreSQL 18.6