'\" t
.\"     Title: pg_upgrade
.\"    Author: The PostgreSQL Global Development Group
.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net>
.\"      Date: 2026
.\"    Manual: PostgreSQL 18.6 Documentation
.\"    Source: PostgreSQL 18.6
.\"  Language: English
.\"
.TH "PG_UPGRADE" "1" "2026" "PostgreSQL 18.6" "PostgreSQL 18.6 Documentation"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "نام (NAME)"
pg_upgrade \- ارتقای یک نمونه سرور PostgreSQL
.SH "خلاصه دستور (SYNOPSIS)"
.HP \w'\fBpg_upgrade\fR\ 'u
\fBpg_upgrade\fR \fB\-b\fR \fIoldbindir\fR [\fB\-B\fR\ \fInewbindir\fR] \fB\-d\fR \fIoldconfigdir\fR \fB\-D\fR \fInewconfigdir\fR [\fIoption\fR...]
.SH "توضیحات (DESCRIPTION)"
.PP
دستور
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\&.
.PP
انتشارهای اصلی PostgreSQL مرتباً قابلیت‌های جدیدی اضافه می‌کنند که اغلب ساختار جدول‌های سیستمی را تغییر می‌دهد، اما قالب درونی ذخیره‌سازی داده‌ها به‌ندرت دستخوش تغییر می‌شود\&.
pg_upgrade
با بهره‌گیری از این ویژگی، از طریق ساخت جدول‌های سیستمی جدید و بازاستفادهٔ ساده از فایل‌های دادهٔ کاربر قدیمی، ارتقاهایی سریع را به انجام می‌رساند\&. اگر یک انتشار اصلی در آینده قالب ذخیره‌سازی داده‌ها را به‌گونه‌ای تغییر دهد که قالب دادهٔ قدیمی غیرقابل‌خواندن شود،
pg_upgrade
برای چنین ارتقاهایی قابل‌استفاده نخواهد بود\&. (جامعهٔ توسعه‌دهندگان تلاش خواهد کرد تا از بروز چنین وضعیتی جلوگیری کند\&.)
.PP
ابزار
pg_upgrade
تمام تلاش خود را به کار می‌بندد تا مطمئن شود کلاسترهای قدیمی و جدید از نظر باینری سازگار هستند؛ برای نمونه، با بررسی سازگاری تنظیمات زمان کامپایل، از جمله باینری‌های 32/64\-bit\&. بسیار مهم است که هرگونه ماژول خارجی نیز سازگاری باینری داشته باشد، هرچند که این موضوع توسط
pg_upgrade
قابل بررسی نیست\&.
.PP
ابزار
pg_upgrade
از ارتقا از نسخهٔ 9\&.2\&.X و بالاتر به نسخهٔ اصلی کنونی
PostgreSQL،
شامل نسخه‌های snapshot و beta پشتیبانی می‌کند\&.
.if n \{\
.sp
.\}
.RS 4
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBهشدار\fR
.ps -1
.br
.PP
ارتقای یک کلاستر باعث می‌شود که مقصد کدهای دلخواه به انتخاب مدیران سیستم (superusers) مبدأ را اجرا کند\&. پیش از ارتقا اطمینان حاصل کنید که مدیران سیستم مبدأ مورد اعتماد هستند\&.
.sp .5v
.RE
.SH "گزینه‌ها (OPTIONS)"
.PP
pg_upgrade
آرگومان‌های خط فرمان زیر را می‌پذیرد:
.PP
\fB\-b\fR \fIbindir\fR
.br
\fB\-\-old\-bindir=\fR\fIbindir\fR
.RS 4
دایرکتوری فایل‌های اجرایی قدیمی PostgreSQL؛ متغیر محیطی
\fBPGBINOLD\fR
.RE
.PP
\fB\-B\fR \fIbindir\fR
.br
\fB\-\-new\-bindir=\fR\fIbindir\fR
.RS 4
دایرکتوری فایل‌های اجرایی جدید PostgreSQL؛ پیش‌فرض دایرکتوری‌ای است که
pg_upgrade
در آن قرار دارد؛ متغیر محیطی
\fBPGBINNEW\fR
.RE
.PP
\fB\-c\fR
.br
\fB\-\-check\fR
.RS 4
فقط کلاسترها را بررسی می‌کند و هیچ داده‌ای را تغییر نمی‌دهد
.RE
.PP
\fB\-d\fR \fIconfigdir\fR
.br
\fB\-\-old\-datadir=\fR\fIconfigdir\fR
.RS 4
دایرکتوری پیکربندی کلاستر پایگاه دادهٔ قدیمی؛ متغیر محیطی
\fBPGDATAOLD\fR
.RE
.PP
\fB\-D\fR \fIconfigdir\fR
.br
\fB\-\-new\-datadir=\fR\fIconfigdir\fR
.RS 4
دایرکتوری پیکربندی کلاستر پایگاه دادهٔ جدید؛ متغیر محیطی
\fBPGDATANEW\fR
.RE
.PP
\fB\-j \fR\fB\fInjobs\fR\fR
.br
\fB\-\-jobs=\fR\fB\fInjobs\fR\fR
.RS 4
تعداد اتصالات و فرایندها/نخ‌های (threads) هم‌زمان مورد استفاده
.RE
.PP
\fB\-k\fR
.br
\fB\-\-link\fR
.RS 4
استفاده از پیوندهای سخت (hard links) به جای کپی کردن فایل‌ها به کلاستر جدید
.RE
.PP
\fB\-N\fR
.br
\fB\-\-no\-sync\fR
.RS 4
به‌طور پیش‌فرض،
\fBpg_upgrade\fR
منتظر می‌ماند تا تمام فایل‌های کلاستر ارتقایافته با ایمنی روی دیسک نوشته شوند\&. این گزینه باعث می‌شود که
\fBpg_upgrade\fR
بدون انتظار بازگردد، که سریع‌تر است اما به این معنی است که فروپاشی (crash) بعدی سیستم‌عامل می‌تواند دایرکتوری داده‌ها را خراب کند\&. به‌طور کلی، این گزینه برای آزمودن مفید است اما نباید در یک محیط عملیاتی واقعی (production) استفاده شود\&.
.RE
.PP
\fB\-o\fR \fIoptions\fR
.br
\fB\-\-old\-options\fR \fIoptions\fR
.RS 4
گزینه‌هایی که باید مستقیماً به دستور قدیمی
\fBpostgres\fR
ارسال شوند؛ فراخوانی‌های مکرر این گزینه به هم الحاق می‌شوند
.RE
.PP
\fB\-O\fR \fIoptions\fR
.br
\fB\-\-new\-options\fR \fIoptions\fR
.RS 4
گزینه‌هایی که باید مستقیماً به دستور جدید
\fBpostgres\fR
ارسال شوند؛ فراخوانی‌های مکرر این گزینه به هم الحاق می‌شوند
.RE
.PP
\fB\-p\fR \fIport\fR
.br
\fB\-\-old\-port=\fR\fIport\fR
.RS 4
شماره درگاه (port) کلاستر قدیمی؛ متغیر محیطی
\fBPGPORTOLD\fR
.RE
.PP
\fB\-P\fR \fIport\fR
.br
\fB\-\-new\-port=\fR\fIport\fR
.RS 4
شماره درگاه (port) کلاستر جدید؛ متغیر محیطی
\fBPGPORTNEW\fR
.RE
.PP
\fB\-r\fR
.br
\fB\-\-retain\fR
.RS 4
نگه‌داشتن فایل‌های SQL و فایل‌های گزارش (log) حتی پس از اتمام موفقیت‌آمیز
.RE.PP
\fB\-s\fR \fIdir\fR
.br
\fB\-\-socketdir=\fR\fIdir\fR
.RS 4
دایرکتوری مورد استفاده برای سوکت‌های postmaster در طول ارتقا؛ پیش‌فرض دایرکتوری کاری فعلی است؛ متغیر محیطی
\fBPGSOCKETDIR\fR
.RE
.PP
\fB\-U\fR \fIusername\fR
.br
\fB\-\-username=\fR\fIusername\fR
.RS 4
نام کاربر نصب‌کننده کلاستر؛ متغیر محیطی
\fBPGUSER\fR
.RE
.PP
\fB\-v\fR
.br
\fB\-\-verbose\fR
.RS 4
فعال‌سازی ثبت تفصیلی گزارش‌های داخلی
.RE
.PP
\fB\-V\fR
.br
\fB\-\-version\fR
.RS 4
نمایش اطلاعات نسخه و سپس خروج
.RE
.PP
\fB\-\-clone\fR
.RS 4
استفاده از شبیه‌سازی کارآمد فایل (که در برخی سیستم‌ها به عنوان
\(lqreflinks\(rq
شناخته می‌شود) به‌جای کپی کردن فایل‌ها به کلاستر جدید\&. این کار می‌تواند منجر به کپی تقریباً آنی فایل‌های داده شود و مزایای سرعتِ
\fB\-k\fR/\fB\-\-link\fR
را فراهم کند در حالی که کلاستر قدیمی دست‌نخورده باقی می‌ماند\&.
.sp
شبیه‌سازی فایل فقط در برخی از سیستم‌های عامل و سیستم‌های فایل پشتیبانی می‌شود\&. اگر انتخاب شود اما پشتیبانی نشود، اجرای
pg_upgrade
با خطا مواجه خواهد شد\&. در حال حاضر، این قابلیت در Linux (هسته 4\&.5 یا جدیدتر) با Btrfs و XFS (در سیستم‌های فایلی که با پشتیبانی از reflink ایجاد شده‌اند)، و در macOS با APFS پشتیبانی می‌شود\&.
.RE
.PP
\fB\-\-copy\fR
.RS 4
کپی کردن فایل‌ها به کلاستر جدید\&. این حالت پیش‌فرض است\&. (همچنین ببینید:
\fB\-\-link\fR،
\fB\-\-clone\fR،
\fB\-\-copy\-file\-range\fR
و
\fB\-\-swap\fR\&.)
.RE
.PP
\fB\-\-copy\-file\-range\fR
.RS 4
استفاده از فراخوان سیستمی
\fBcopy_file_range\fR
برای کپی کارآمد\&. در برخی سیستم‌های فایل، این روش نتایجی مشابه با
\fB\-\-clone\fR
با اشتراک‌گذاری بلوک‌های فیزیکی دیسک ارائه می‌دهد، در حالی که در برخی دیگر ممکن است همچنان بلوک‌ها را کپی کند، اما این کار را از طریق یک مسیر بهینه‌شده انجام دهد\&. در حال حاضر، این قابلیت در Linux و FreeBSD پشتیبانی می‌شود\&.
.RE
.PP
\fB\-\-no\-statistics\fR
.RS 4
عدم بازیابی آمارها از کلاستر قدیمی در کلاستر جدید\&.
.RE
.PP
\fB\-\-set\-char\-signedness=\fR\fIoption\fR
.RS 4
تنظیم دستی علامت‌دار بودن (signedness) پیش‌فرض char برای کلاسترهای جدید\&. مقادیر ممکن عبارتند از
signed
و
unsigned\&.
.sp
در زبان C، علامت‌دار بودن پیش‌فرض نوع
char
(در صورتی که صراحتاً مشخص نشده باشد) در بسترهای مختلف متفاوت است\&. برای مثال،
char
در پردازنده‌های x86 به‌طور پیش‌فرض
signed char
است اما در پردازنده‌های ARM به‌طور پیش‌فرض
unsigned char
است\&.
.sp
از
PostgreSQL
18 به بعد، کلاسترهای پایگاه داده تنظیمات علامت‌دار بودن پیش‌فرض char مختص به خود را نگه می‌دارند، که می‌تواند برای اطمینان از رفتار سازگار در بسترهایی با علامت‌دار بودن پیش‌فرض متفاوت char استفاده شود\&. به‌طور پیش‌فرض،
pg_upgrade
هنگام ارتقا از یک کلاستر موجود، تنظیمات علامت‌دار بودن char را حفظ می‌کند\&. با این حال، هنگام ارتقا از
PostgreSQL
17 یا قبل‌تر،
pg_upgrade
علامت‌دار بودن char پلتفرمی را اعمال می‌کند که روی آن ساخته شده است\&.
.sp
این گزینه به شما اجازه می‌دهد تا علامت‌دار بودن پیش‌فرض char را به‌طور صریح برای کلاستر جدید تنظیم کنید و مقادیر موروثی را بازنویسی نمایید\&. دو سناریوی مشخص وجود دارد که این گزینه در آن‌ها کاربرد دارد:
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
اگر قصد دارید پس از ارتقا به پلتفرم دیگری مهاجرت کنید، نباید از این گزینه استفاده کنید\&. رفتار پیش‌فرض در این حالت مناسب است\&. در عوض، ارتقا را روی پلتفرم اصلی بدون این پرچم انجام دهید و سپس کلاستر را منتقل کنید\&. این رویکرد توصیه‌شده و امن‌ترین روش است\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
اگر قبلاً کلاستر را به پلتفرمی با علامت‌دار بودن char متفاوت منتقل کرده‌اید (برای مثال، از یک سیستم مبتنی بر x86 به یک سیستم مبتنی بر ARM)، باید از این گزینه برای مشخص کردن علامت‌دار بودنی مطابق با علامت‌دار بودن پیش‌فرض char در پلتفرم اصلی استفاده کنید\&. علاوه بر این، ضروری است که هیچ‌یک از فایل‌های داده بین انتقال فایل‌های داده و اجرای
\fBpg_upgrade\fR
تغییر داده نشوند\&.
\fBpg_upgrade\fR
باید اولین عملیاتی باشد که کلاستر را روی پلتفرم جدید راه‌اندازی می‌کند\&.
.RE
.sp
.RE
.PP
\fB\-\-swap\fR
.RS 4
انتقال دایرکتوری‌های داده از کلاستر قدیمی به کلاستر جدید\&. سپس، جایگزین کردن فایل‌های کاتالوگ با فایل‌های تولیدشده برای کلاستر جدید\&. این حالت می‌تواند عملکرد بهتری نسبت به
\fB\-\-link\fR،
\fB\-\-clone\fR،
\fB\-\-copy\fR
و
\fB\-\-copy\-file\-range\fR
ارائه دهد، به‌ویژه در کلاسترهایی با رابطه‌های (relations) زیاد\&.
.sp
با این حال، این حالت فایل‌های زائد زیادی را در کلاستر قدیمی ایجاد می‌کند، که در صورت استفاده از
\fB\-\-sync\-method=syncfs\fR
می‌تواند مرحله همگام‌سازی فایل را طولانی کند\&. بنابراین، توصیه می‌شود به همراه
\fB\-\-swap\fR
از
\fB\-\-sync\-method=fsync\fR
استفاده شود\&.
.sp
علاوه بر این، به‌محض آغاز مرحله انتقال فایل، کلاستر قدیمی به‌طور برگشت‌ناپذیری تغییر خواهد کرد و بنابراین راه‌اندازی مجدد آن دیگر ایمن نخواهد بود\&. برای جزئیات به
Step 17
مراجعه کنید\&.
.RE
.PP
\fB\-\-sync\-method=\fR\fImethod\fR
.RS 4
هنگامی که روی
fsync
تنظیم شود (که پیش‌فرض است)،
\fBpg_upgrade\fR
تمام فایل‌های موجود در دایرکتوری داده کلاستر ارتقایافته را به‌صورت بازگشتی باز کرده و همگام‌سازی می‌کند\&. جستجوی فایل‌ها، پیوندهای نمادین دایرکتوری WAL و هر tablespace پیکربندی‌شده را دنبال خواهد کرد\&.
.sp
در Linux، می‌توان به‌جای آن از
syncfs
استفاده کرد تا از سیستم‌عامل خواسته شود کل سیستم‌های فایلی را که شامل دایرکتوری داده کلاستر ارتقایافته، فایل‌های WAL آن و هر tablespace هستند، همگام‌سازی کند\&. برای کسب اطلاعات درباره هشدارهایی که باید هنگام استفاده از
syncfs
در نظر داشته باشید، به
recovery_init_sync_method
مراجعه کنید\&.
.sp
در صورت استفاده از
\fB\-\-no\-sync\fR
این گزینه هیچ تأثیری ندارد\&.
.RE
.PP
\fB\-?\fR
.br
\fB\-\-help\fR
.RS 4
نمایش راهنما و سپس خروج
.RE.SH "نحوه استفاده (USAGE)"
.PP
مراحل انجام ارتقا با استفاده از
pg_upgrade
به شرح زیر است:
.if n \{\
.sp
.\}
.RS 4
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBنکته\fR
.ps -1
.br
.PP
مراحل ارتقای خوشه‌های رونوشت‌برداری منطقی (logical replication clusters) در اینجا پوشش داده نشده است؛ برای جزئیات به
Section\ \&29.13
مراجعه کنید\&.
.sp .5v
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 1.\h'+01'\c
.\}
.el \{\
.sp -1
.IP "  1." 4.2
.\}
انتقال اختیاری خوشه قدیمی: اگر از دایرکتوری نصبی مختص به نسخه مانند
/opt/PostgreSQL/18
استفاده می‌کنید، نیازی به جابه‌جایی خوشه قدیمی ندارید\&. نصاب‌های گرافیکی همگی از دایرکتوری‌های نصب مختص به نسخه استفاده می‌کنند\&.
.sp
اگر دایرکتوری نصب شما مختص به نسخه نیست، برای مثال
/usr/local/pgsql، لازم است دایرکتوری نصب فعلی PostgreSQL را جابه‌جا کنید تا با نصب نسخه جدید
PostgreSQL
تداخلی نداشته باشد\&. به محض اینکه سرور فعلی
PostgreSQL
متوقف شد، تغییر نام دایرکتوری نصب PostgreSQL بلامانع است؛ با فرض اینکه دایرکتوری قدیمی
/usr/local/pgsql
است، می‌توانید:
.sp
.if n \{\
.RS 4
.\}
.nf
mv /usr/local/pgsql /usr/local/pgsql\&.old
.fi
.if n \{\
.RE
.\}
.sp
را برای تغییر نام دایرکتوری اجرا کنید\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 2.\h'+01'\c
.\}
.el \{\
.sp -1
.IP "  2." 4.2
.\}
برای نصب از سورس، کامپایل نسخه جدید: سورس جدید PostgreSQL را با گزینه‌های (flags)
\fBconfigure\fR
سازگار با خوشه قدیمی کامپایل کنید\&.
ابزار
pg_upgrade
پیش از آغاز ارتقا،
\fBpg_controldata\fR
را بررسی خواهد کرد تا اطمینان یابد همه تنظیمات سازگار هستند\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 3.\h'+01'\c
.\}
.el \{\
.sp -1
.IP "  3." 4.2
.\}
نصب باینری‌های جدید PostgreSQL: فایل‌های باینری و فایل‌های پشتیبان سرور جدید را نصب کنید\&.
pg_upgrade
در یک نصب پیش‌فرض گنجانده شده است\&.
.sp
برای نصب از سورس، اگر می‌خواهید سرور جدید را در مکانی سفارشی نصب کنید، از متغیر
prefix
استفاده نمایید:
.sp
.if n \{\
.RS 4
.\}
.nf
make prefix=/usr/local/pgsql\&.new install
.fi
.if n \{\
.RE
.\}
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 4.\h'+01'\c
.\}
.el \{\
.sp -1
.IP "  4." 4.2
.\}
راه‌اندازی اولیه خوشه جدید PostgreSQL: خوشه جدید را با استفاده از
\fBinitdb\fR
راه‌اندازی اولیه کنید\&. مجدداً، از گزینه‌های سازگار
\fBinitdb\fR
که با خوشه قدیمی همخوانی دارند استفاده کنید\&. بسیاری از نصاب‌های آماده این مرحله را به طور خودکار انجام می‌دهند\&. نیازی به راه‌اندازی خوشه جدید نیست\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 5.\h'+01'\c
.\}
.el \{\
.sp -1
.IP "  5." 4.2
.\}
نصب فایل‌های شیء اشتراکی (shared object) افزونه‌ها: بسیاری از افزونه‌ها و ماژول‌های سفارشی، چه از
contrib
و چه از منبعی دیگر، از فایل‌های شیء اشتراکی (یا DLLها) مانند
pgcrypto\&.so
استفاده می‌کنند\&. اگر خوشه قدیمی از این موارد استفاده می‌کرد، فایل‌های شیء اشتراکی مطابق با باینری سرور جدید باید در خوشه جدید نصب شوند، که معمولاً از طریق دستورات سیستم‌عامل انجام می‌شود\&. تعاریف شِما (schema definitions) را، مانند
\fBCREATE EXTENSION pgcrypto\fR،
بارگذاری نکنید؛ زیرا این تعاریف از خوشه قدیمی تکثیر خواهند شد\&. اگر به‌روزرسانی‌هایی برای افزونه‌ها در دسترس باشد،
pg_upgrade
این موضوع را گزارش داده و اسکریپتی می‌سازد که می‌توان آن را بعداً برای به‌روزرسانی آن‌ها اجرا کرد\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 6.\h'+01'\c
.\}
.el \{\
.sp -1
.IP "  6." 4.2
.\}
کپی کردن فایل‌های سفارشی جستجوی تمام‌متن: هرگونه فایل سفارشی جستجوی تمام‌متن (فرهنگ لغت، مترادف‌ها، اصطلاح‌نامه و کلمات توقف) را از خوشه قدیمی به خوشه جدید کپی کنید\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 7.\h'+01'\c
.\}
.el \{\
.sp -1
.IP "  7." 4.2
.\}
تنظیم احراز هویت: ابزار
\fBpg_upgrade\fR
چندین بار به سرورهای قدیمی و جدید متصل خواهد شد، بنابراین ممکن است بخواهید روش احراز هویت را در
pg_hba\&.conf
روی
peer
تنظیم کنید یا از فایل
~/\&.pgpass
استفاده نمایید (به
Section\ \&32.16
مراجعه کنید)\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 8.\h'+01'\c
.\}
.el \{\
.sp -1
.IP "  8." 4.2
.\}
متوقف کردن هر دو سرور: مطمئن شوید هر دو سرور پایگاه‌داده متوقف شده‌اند؛ برای نمونه در Unix با اجرای:
.sp
.if n \{\
.RS 4
.\}
.nf
pg_ctl \-D /opt/PostgreSQL/12 stop
pg_ctl \-D /opt/PostgreSQL/18 stop
.fi
.if n \{\
.RE
.\}.sp
یا در Windows، با استفاده از نام‌های مناسب سرویس:
.sp
.if n \{\
.RS 4
.\}
.nf
NET STOP postgresql\-12
NET STOP postgresql\-18
.fi
.if n \{\
.RE
.\}
.sp
سرورهای standby مبتنی بر streaming replication و log\-shipping در طول این خاموش‌سازی باید در حال اجرا باشند تا تمام تغییرات را دریافت کنند\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 9.\h'+01'\c
.\}
.el \{\
.sp -1
.IP "  9." 4.2
.\}
آماده‌سازی برای ارتقای سرورهای standby: اگر سرورهای standby را با استفاده از روش‌های شرح‌داده‌شده در بخش
Step 11 ارتقا می‌دهید، با اجرای
pg_controldata
روی کلاسترهای primary و standby قدیمی، بررسی کنید که سرورهای standby قدیمی همگام باشند\&. بررسی کنید که مقادیر
\(lqLatest checkpoint location\(rq
در همهٔ کلاسترها مطابقت داشته باشند\&. همچنین، مطمئن شوید که
\fIwal_level\fR
در فایل
postgresql\&.conf
روی کلاستر primary جدید برابر با
minimal
تنظیم نشده باشد\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 10.\h'+01'\c
.\}
.el \{\
.sp -1
.IP "  10." 4.2
.\}
اجرای pg_upgrade: همیشه باینری
pg_upgrade
مربوط به سرور جدید را اجرا کنید، نه سرور قدیمی را\&.
pg_upgrade
نیازمند مشخص کردن دایرکتوری‌های داده و اجرایی (bin) کلاستر قدیمی و جدید است\&. همچنین می‌توانید مقادیر کاربر و پورت را مشخص کنید، و اینکه آیا می‌خواهید فایل‌های داده به جای رفتار پیش‌فرض کپی (copy)، پیوند (linked)، همتاسازی (cloned) یا جابه‌جا (swapped) شوند\&.
.sp
اگر از حالت link استفاده کنید، ارتقا بسیار سریع‌تر خواهد بود (بدون کپی فایل) و فضای دیسک کمتری استفاده خواهد شد، اما پس از اینکه سرور جدید را بعد از ارتقا راه‌اندازی کردید، دیگر به کلاستر قدیمی خود دسترسی نخواهید داشت\&. حالت link همچنین نیاز دارد که دایرکتوری‌های دادهٔ کلاستر قدیمی و جدید در یک فایل سیستم قرار داشته باشند\&. (Tablespaceها و
pg_wal
می‌توانند در فایل سیستم‌های متفاوتی باشند\&.) حالت clone همان مزایای سرعت و فضای دیسک را فراهم می‌کند اما باعث نمی‌شود که کلاستر قدیمی پس از راه‌اندازی کلاستر جدید غیرقابل‌استفاده شود\&. حالت clone نیز نیازمند آن است که دایرکتوری‌های دادهٔ قدیمی و جدید در یک فایل سیستم باشند\&. این حالت فقط روی سیستم‌عامل‌ها و فایل سیستم‌های خاصی در دسترس است\&. حالت swap در صورت وجود relationهای بسیار ممکن است سریع‌ترین باشد، اما به‌محض شروع مرحلهٔ انتقال فایل، دیگر به کلاستر قدیمی خود دسترسی نخواهید داشت\&. حالت swap نیز مستلزم آن است که دایرکتوری‌های دادهٔ کلاستر قدیمی و جدید در یک فایل سیستم باشند\&.
.sp
تنظیم
\fB\-\-jobs\fR
روی ۲ یا بالاتر به pg_upgrade اجازه می‌دهد چندین پایگاه داده و tablespace را به‌صورت موازی پردازش کند\&. یک نقطه شروع مناسب، تعداد هسته‌های CPU در سیستم است\&. این گزینه می‌تواند زمان ارتقا را برای سرورهای دارای چند پایگاه داده و چند tablespace به‌میزان چشمگیری کاهش دهد\&.
.sp
برای کاربران Windows، باید با یک حساب دارای دسترسی مدیریتی (administrative) وارد شده باشید، و سپس
pg_upgrade
را با دایرکتوری‌های داخل کوتیشن اجرا کنید، مانند:
.sp
.if n \{\
.RS 4
.\}
.nf
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"
.fi
.if n \{\
.RE
.\}
.sp
پس از شروع،
\fBpg_upgrade\fR
سازگاری دو کلاستر را بررسی می‌کند و سپس ارتقا را انجام می‌دهد\&. می‌توانید از
\fBpg_upgrade \-\-check\fR
برای انجام صرفاً بررسی‌ها استفاده کنید، حتی اگر سرور قدیمی هنوز در حال اجرا باشد\&.
\fBpg_upgrade \-\-check\fR
همچنین هرگونه تنظیمات دستی که باید بعد از ارتقا انجام دهید را مشخص خواهد کرد\&. اگر قصد دارید از حالت link، clone، copy\-file\-range یا swap استفاده کنید، باید از گزینهٔ
\fB\-\-link\fR،
\fB\-\-clone\fR،
\fB\-\-copy\-file\-range\fR، یا
\fB\-\-swap\fR
به همراه
\fB\-\-check\fR
استفاده کنید تا بررسی‌های ویژهٔ آن حالت فعال شوند\&.
\fBpg_upgrade\fR
به مجوز نوشتن در دایرکتوری فعلی نیاز دارد\&.
.sp
بدیهی است که هیچ‌کس نباید در طول فرایند ارتقا به کلاسترها دسترسی داشته باشد\&.
pg_upgrade
به‌طور پیش‌فرض سرورها را روی پورت 50432 اجرا می‌کند تا از اتصالات ناخواسته کلاینت‌ها جلوگیری شود\&. هنگام ارتقا می‌توانید از یک شماره پورت یکسان برای هر دو کلاستر استفاده کنید، زیرا کلاسترهای قدیمی و جدید به‌طور هم‌زمان در حال اجرا نخواهند بود\&. با این حال، هنگام بررسی یک سرور قدیمی در حال اجرا، شماره پورت‌های قدیم و جدید باید متفاوت باشند\&.
.sp
اگر هنگام بازیابی شمای پایگاه داده خطایی رخ دهد،
\fBpg_upgrade\fR
خارج خواهد شد و شما باید مطابق با آنچه در
Step 17
در زیر آمده است به کلاستر قدیمی بازگردید\&. برای امتحان مجدد
\fBpg_upgrade\fR،
باید کلاستر قدیمی را اصلاح کنید تا بازیابی شمای pg_upgrade با موفقیت انجام شود\&. اگر مشکل ناشی از یک ماژول
contrib
باشد، ممکن است لازم باشد ماژول
contrib
را از کلاستر قدیمی حذف نصب کنید و پس از ارتقا آن را در کلاستر جدید نصب کنید، به شرطی که از آن ماژول برای ذخیره داده‌های کاربر استفاده نشده باشد\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 11.\h'+01'\c
.\}
.el \{\
.sp -1
.IP "  11." 4.2
.\}
ارتقای سرورهای standby تکثیر جریانی (streaming replication) و انتقال گزارش (log\-shipping): اگر از حالت link استفاده کرده‌اید و سرورهای standby با Streaming Replication (به
Section\ \&26.2.5
مراجعه کنید) یا Log\-Shipping (به
Section\ \&26.2
مراجعه کنید) دارید، می‌توانید این مراحل را برای ارتقای سریع آن‌ها دنبال کنید\&. شما
pg_upgrade
را روی سرورهای standby اجرا نخواهید کرد، بلکه
rsync
را روی سرور اصلی (primary) اجرا می‌کنید\&. هنوز هیچ سروری را راه‌اندازی نکنید\&.
.sp
اگر از حالت link استفاده
\fIنکرده‌اید\fR،
ابزار
rsync
را ندارید یا نمی‌خواهید از آن استفاده کنید، یا راه‌حل ساده‌تری می‌خواهید، از دستورالعمل‌های این بخش صرف‌نظر کنید و صرفاً پس از اتمام
pg_upgrade
و راه‌اندازی primary جدید، سرورهای standby را از نو ایجاد کنید\&.
.sp
.RS 4
.ie n \{\
\h'-04' 1.\h'+01'\c
.\}
.el \{\
.sp -1
.IP "  1." 4.2
.\}
نصب باینری‌های جدید PostgreSQL روی سرورهای standby: مطمئن شوید که فایل‌های باینری و فایل‌های پشتیبانی جدید روی همه سرورهای standby نصب شده باشند\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 2.\h'+01'\c
.\}
.el \{\
.sp -1
.IP "  2." 4.2
.\}
اطمینان حاصل کنید که دایرکتوری‌های دادهٔ جدید standby وجود \fIنداشته باشند\fR: مطمئن شوید که دایرکتوری‌های دادهٔ جدید standby وجود
\fIندارند\fR
یا خالی هستند\&. اگر
initdb
اجرا شده است، دایرکتوری‌های دادهٔ جدید سرورهای standby را حذف کنید\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 3.\h'+01'\c
.\}
.el \{\
.sp -1
.IP "  3." 4.2
.\}
نصب فایل‌های شیء اشتراکی (shared object) افزونه: همان فایل‌های شیء اشتراکی افزونه‌ای را روی standbyهای جدید نصب کنید که روی کلاستر primary جدید نصب کرده‌اید\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 4.\h'+01'\c
.\}
.el \{\
.sp -1
.IP "  4." 4.2
.\}
توقف سرورهای standby: اگر سرورهای standby هنوز در حال اجرا هستند، اکنون آن‌ها را با استفاده از دستورالعمل‌های بالا متوقف کنید\&.
.RE.sp
.RS 4
.ie n \{\
\h'-04' 5.\h'+01'\c
.\}
.el \{\
.sp -1
.IP "  5." 4.2
.\}
ذخیره فایل‌های پیکربندی: هر فایل پیکربندی از دایرکتوری‌های پیکربندی standbyهای قدیمی را که به نگهداری آن‌ها نیاز دارید ذخیره کنید، مانند
postgresql\&.conf
(و هر فایلی که توسط آن گنجانده شده است)،
postgresql\&.auto\&.conf،
pg_hba\&.conf، زیرا این فایل‌ها در مرحله بعدی بازنویسی یا حذف خواهند شد\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 6.\h'+01'\c
.\}
.el \{\
.sp -1
.IP "  6." 4.2
.\}
اجرای rsync: هنگام استفاده از حالت link، سرورهای standby را می‌توان به سرعت با استفاده از
rsync
ارتقا داد\&. برای انجام این کار، از دایرکتوری‌ای در سرور primary که بالاتر از دایرکتوری‌های خوشه‌های پایگاه‌داده قدیمی و جدید قرار دارد، این دستور را روی
\fIprimary\fR
برای هر سرور standby اجرا کنید:
.sp
.if n \{\
.RS 4
.\}
.nf
rsync \-\-archive \-\-delete \-\-hard\-links \-\-size\-only \-\-no\-inc\-recursive old_cluster new_cluster remote_dir
.fi
.if n \{\
.RE
.\}
.sp
که در آن
\fBold_cluster\fR
و
\fBnew_cluster\fR
نسبت به دایرکتوری جاری در primary هستند، و
\fBremote_dir\fR
در سرور standby
\fIبالاتر\fR
از دایرکتوری‌های خوشه‌های قدیمی و جدید قرار دارد\&. ساختار دایرکتوری زیر دایرکتوری‌های مشخص‌شده در primary و standbyها باید یکسان باشد\&. برای جزئیات مربوط به تعیین دایرکتوری دوردست (remote)، صفحه راهنمای
rsync
را بررسی کنید، به عنوان مثال:
.sp
.if n \{\
.RS 4
.\}
.nf
rsync \-\-archive \-\-delete \-\-hard\-links \-\-size\-only \-\-no\-inc\-recursive /opt/PostgreSQL/12 \e
      /opt/PostgreSQL/18 standby\&.example\&.com:/opt/PostgreSQL
.fi
.if n \{\
.RE
.\}
.sp
می‌توانید با استفاده از گزینهٔ
\fB\-\-dry\-run\fR
در
rsync
بررسی کنید که این دستور چه کاری انجام خواهد داد\&. در حالی که
rsync
باید دست‌کم برای یک standby روی primary اجرا شود، اما تا زمانی که standby ارتقایافته راه‌اندازی نشده باشد، اجرای
rsync
روی یک standby ارتقایافته برای ارتقای سایر standbyها نیز امکان‌پذیر است\&.
.sp
کاری که این عمل انجام می‌دهد، ثبت پیوندهایی است که توسط حالت link در
pg_upgrade
ایجاد شده‌اند و فایل‌های موجود در خوشه‌های قدیمی و جدید را در سرور primary به یکدیگر پیوند می‌دهند\&. سپس فایل‌های متناظر را در خوشه قدیمی standby پیدا کرده و پیوندهایی برای آن‌ها در خوشه جدید standby ایجاد می‌کند\&. فایل‌هایی که در primary پیوند داده نشده بودند از primary به standby کپی می‌شوند\&. (این فایل‌ها معمولاً کوچک هستند\&.) این سازوکار ارتقای سریع standby را فراهم می‌کند\&. متأسفانه،
rsync
فایل‌های مرتبط با جدول‌های temporary و unlogged را به صورت غیرضروری کپی می‌کند زیرا این فایل‌ها معمولاً در سرورهای standby وجود ندارند\&.
.sp
اگر tablespace دارید، باید دستور
rsync
مشابهی را برای دایرکتوری هر tablespace اجرا کنید، به عنوان مثال:
.sp
.if n \{\
.RS 4
.\}
.nf
rsync \-\-archive \-\-delete \-\-hard\-links \-\-size\-only \-\-no\-inc\-recursive /vol1/pg_tblsp/PG_12_201909212 \e
      /vol1/pg_tblsp/PG_18_202307071 standby\&.example\&.com:/vol1/pg_tblsp
.fi
.if n \{\
.RE
.\}
.sp
اگر
pg_wal
را به خارج از دایرکتوری‌های داده منتقل کرده‌اید،
rsync
باید روی آن دایرکتوری‌ها نیز اجرا شود\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 7.\h'+01'\c
.\}
.el \{\
.sp -1
.IP "  7." 4.2
.\}
پیکربندی سرورهای standby برای streaming replication و log\-shipping: سرورها را برای log shipping پیکربندی کنید\&. (نیازی به اجرای
\fBpg_backup_start()\fR
و
\fBpg_backup_stop()\fR
یا تهیه نسخه پشتیبان از فایل‌سیستم نیست، زیرا standbyها همچنان با primary همگام هستند\&.) اگر primary قدیمی قبل از نسخه 17\&.0 باشد، هیچ slotای از primary به standby جدید کپی نمی‌شود، بنابراین تمام slotها در standby قدیمی باید به صورت دستی بازسازی شوند\&. اگر primary قدیمی نسخه 17\&.0 یا بالاتر باشد، تنها slotهای منطقی (logical slots) روی primary به standby جدید کپی می‌شوند، اما سایر slotها در standby قدیمی کپی نمی‌شوند و بنابراین باید به صورت دستی دوباره ایجاد شوند\&.
.RE
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 12.\h'+01'\c
.\}
.el \{\
.sp -1
.IP "  12." 4.2
.\}
بازیابی pg_hba\&.conf: اگر
pg_hba\&.conf
را تغییر داده‌اید، تنظیمات اصلی آن را بازیابی کنید\&. همچنین ممکن است لازم باشد سایر فایل‌های پیکربندی در خوشه جدید را طوری تنظیم کنید تا با خوشه قدیمی مطابقت داشته باشند، مانند
postgresql\&.conf
(و تمام فایل‌های گنجانده‌شده توسط آن)،
postgresql\&.auto\&.conf\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 13.\h'+01'\c
.\}
.el \{\
.sp -1
.IP "  13." 4.2
.\}
راه‌اندازی سرور جدید: سرور جدید اکنون می‌تواند با اطمینان راه‌اندازی شود، و سپس هر سرور standby که با
rsync
همگام‌سازی شده است\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 14.\h'+01'\c
.\}
.el \{\
.sp -1
.IP "  14." 4.2
.\}
پردازش‌های پس از ارتقا: اگر به پردازش‌های پس از ارتقا نیاز باشد، pg_upgrade هنگام اتمام کار خود هشدارهایی صادر خواهد کرد\&. همچنین فایل‌های اسکریپتی تولید خواهد کرد که باید توسط مدیر سیستم اجرا شوند\&. این اسکریپت‌ها به هر پایگاه‌داده‌ای که نیاز به پردازش‌های پس از ارتقا دارد متصل می‌شوند\&. هر اسکریپت باید با استفاده از دستور زیر اجرا شود:
.sp
.if n \{\
.RS 4
.\}
.nf
psql \-\-username=postgres \-\-file=script\&.sql postgres
.fi
.if n \{\
.RE
.\}
.sp
اسکریپت‌ها را می‌توان به هر ترتیبی اجرا کرد و پس از اجرا می‌توان آن‌ها را حذف نمود\&.
.if n \{\
.sp
.\}
.RS 4
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBاحتیاط\fR
.ps -1
.br
به‌طور کلی، دسترسی به جدول‌هایی که در اسکریپت‌های بازسازی (rebuild) به آن‌ها ارجاع داده شده است تا پیش از اتمام کامل اجرای آن اسکریپت‌ها ناامن است؛ انجام این کار می‌تواند منجر به نتایج نادرست یا افت کارایی شود\&. جدول‌هایی که در اسکریپت‌های بازسازی ارجاع داده نشده‌اند بلافاصله قابل دسترسی هستند\&.
.sp .5v
.RE
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 15.\h'+01'\c
.\}
.el \{\.sp -1
.IP "  15." 4.2
.\}
آمارها: مگر اینکه گزینهٔ
\fB\-\-no\-statistics\fR
مشخص شده باشد،
\fBpg_upgrade\fR
بیشتر آمارهای بهینه‌ساز را از کلاستر قدیمی به کلاستر جدید انتقال خواهد داد\&. این کار همهٔ آمارها را منتقل نمی‌کند، مانند آن‌هایی که به صراحت با
CREATE STATISTICS (\fBCREATE_STATISTICS\fR(7))
ایجاد شده‌اند، آمارهای سفارشی اضافه‌شده توسط یک افزونه، یا آمارهای جمع‌آوری‌شده توسط سیستم آمارهای تجمعی\&.
.sp
از آنجا که همهٔ آمارها توسط
\fBpg_upgrade\fR
منتقل نمی‌شوند، در پایان ارتقا از شما خواسته می‌شود تا دستوراتی را برای بازتولید آن اطلاعات اجرا کنید\&. ممکن است نیاز باشد پارامترهای اتصال را برای تطابق با کلاستر جدید خود تنظیم کنید\&.
.sp
ابتدا از
\fBvacuumdb \-\-all \-\-analyze\-in\-stages \-\-missing\-stats\-only\fR
برای تولید سریع حداقل آمارهای بهینه‌ساز برای رابطه‌های فاقد آمار استفاده کنید\&. سپس از
\fBvacuumdb \-\-all \-\-analyze\-only\fR
استفاده کنید تا مطمئن شوید همهٔ رابطه‌ها دارای آمارهای تجمعی به‌روز شده برای راه‌اندازی vacuum و analyze هستند\&. برای هر دو دستور، استفاده از
\fB\-\-jobs\fR
می‌تواند سرعت کار را بالا ببرد\&. اگر
\fIvacuum_cost_delay\fR
روی یک مقدار غیرصفر تنظیم شده باشد، می‌توان آن را با استفاده از
\fBPGOPTIONS\fR
نادیده گرفت تا تولید آمار تسریع شود، به عنوان مثال:
PGOPTIONS=\*(Aq\-c vacuum_cost_delay=0\*(Aq vacuumdb \&.\&.\&.\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 16.\h'+01'\c
.\}
.el \{\
.sp -1
.IP "  16." 4.2
.\}
حذف کلاستر قدیمی: پس از حصول اطمینان از صحت ارتقا، می‌توانید دایرکتوری‌های دادهٔ کلاستر قدیمی را با اجرای اسکریپتی که در زمان تکمیل
\fBpg_upgrade\fR
به آن اشاره می‌شود، حذف کنید\&. (اگر فضاهای جدول (tablespaces) تعریف‌شده توسط کاربر در داخل دایرکتوری داده‌های قدیمی داشته باشید، حذف خودکار امکان‌پذیر نیست\&.) همچنین می‌توانید دایرکتوری‌های نصب قدیمی (مانند
bin
و
share)
را حذف کنید\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 17.\h'+01'\c
.\}
.el \{\
.sp -1
.IP "  17." 4.2
.\}
بازگشت به کلاستر قدیمی: اگر پس از اجرای
\fBpg_upgrade\fR،
مایل به بازگشت به کلاستر قدیمی باشید، چندین گزینه وجود دارد:
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
اگر از گزینهٔ
\fB\-\-check\fR
استفاده شده باشد، کلاستر قدیمی دست‌نخورده باقی مانده است؛ می‌توان آن را مجدداً راه‌اندازی کرد\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
اگر نه از
\fB\-\-link\fR
و نه از
\fB\-\-swap\fR
استفاده نشده باشد، کلاستر قدیمی دست‌نخورده باقی مانده است؛ می‌توان آن را مجدداً راه‌اندازی کرد\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
اگر از گزینهٔ
\fB\-\-link\fR
استفاده شده باشد، فایل‌های داده ممکن است بین کلاستر قدیمی و جدید مشترک باشند:
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
اگر
\fBpg_upgrade\fR
پیش از آغاز پیوندزدن متوقف شده باشد، کلاستر قدیمی دست‌نخورده باقی مانده است؛ می‌توان آن را مجدداً راه‌اندازی کرد\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
اگر کلاستر جدید را راه‌اندازی
\fIنکرده\fR
باشید، کلاستر قدیمی دست‌نخورده باقی مانده است، مگر اینکه در زمان شروع پیوندزدن، پسوند
\&.old
به
$PGDATA/global/pg_control
اضافه شده باشد\&. برای استفادهٔ مجدد از کلاستر قدیمی، پسوند
\&.old
را از
$PGDATA/global/pg_control
حذف کنید؛ سپس می‌توانید کلاستر قدیمی را دوباره راه‌اندازی کنید\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
اگر کلاستر جدید را راه‌اندازی کرده باشید، روی فایل‌های مشترک نوشته است و استفاده از کلاستر قدیمی ناامن خواهد بود\&. در این حالت، کلاستر قدیمی باید از نسخهٔ پشتیبان بازیابی شود\&.
.RE
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
اگر از گزینهٔ
\fB\-\-swap\fR
استفاده شده باشد، ممکن است کلاستر قدیمی به صورت مخرب تغییر یافته باشد:
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
اگر
\fBpg_upgrade\fR
پیش از گزارش اینکه کلاستر قدیمی دیگر برای راه‌اندازی امن نیست متوقف شود، کلاستر قدیمی دست‌نخورده باقی مانده است؛ می‌توان آن را مجدداً راه‌اندازی کرد\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
اگر
\fBpg_upgrade\fR
گزارش داده باشد که کلاستر قدیمی دیگر برای راه‌اندازی امن نیست، کلاستر قدیمی دچار تغییرات مخرب شده است\&. در این حالت، کلاستر قدیمی باید از نسخهٔ پشتیبان بازیابی شود\&.
.RE
.sp
.RE
.RE.SH "محیط (ENVIRONMENT)"
.PP
برخی متغیرهای محیطی می‌توانند برای فراهم کردن مقادیر پیش‌فرض گزینه‌های خط فرمان استفاده شوند:
.PP
\fBPGBINOLD\fR
.RS 4
دایرکتوری فایل‌های اجرایی قدیمی PostgreSQL؛ گزینهٔ
\fB\-b\fR/\fB\-\-old\-bindir\fR\&.
.RE
.PP
\fBPGBINNEW\fR
.RS 4
دایرکتوری فایل‌های اجرایی جدید PostgreSQL؛ گزینهٔ
\fB\-B\fR/\fB\-\-new\-bindir\fR\&.
.RE
.PP
\fBPGDATAOLD\fR
.RS 4
دایرکتوری پیکربندی کلاستر پایگاه‌دادهٔ قدیمی؛ گزینهٔ
\fB\-d\fR/\fB\-\-old\-datadir\fR\&.
.RE
.PP
\fBPGDATANEW\fR
.RS 4
دایرکتوری پیکربندی کلاستر پایگاه‌دادهٔ جدید؛ گزینهٔ
\fB\-D\fR/\fB\-\-new\-datadir\fR\&.
.RE
.PP
\fBPGPORTOLD\fR
.RS 4
شماره پورت کلاستر قدیمی؛ گزینهٔ
\fB\-p\fR/\fB\-\-old\-port\fR\&.
.RE
.PP
\fBPGPORTNEW\fR
.RS 4
شماره پورت کلاستر جدید؛ گزینهٔ
\fB\-P\fR/\fB\-\-new\-port\fR\&.
.RE
.PP
\fBPGSOCKETDIR\fR
.RS 4
دایرکتوری مورد استفاده برای سوکت‌های postmaster در حین ارتقا؛ گزینهٔ
\fB\-s\fR/\fB\-\-socketdir\fR\&.
.RE
.PP
\fBPGUSER\fR
.RS 4
نام کاربر نصب‌کنندهٔ کلاستر؛ گزینهٔ
\fB\-U\fR/\fB\-\-username\fR\&.
.RE
.SH "نکات (NOTES)"
.PP
دستور
pg_upgrade
فایل‌های کاری گوناگونی ایجاد می‌کند، مانند دامپ‌های اسکیما، که درون
pg_upgrade_output\&.d
در دایرکتوری کلاستر جدید ذخیره می‌شوند\&. هر بار اجرا یک زیردایرکتوری جدید ایجاد می‌کند که بر اساس برچسب زمانی با قالب استاندارد ISO 8601 (%Y%m%dT%H%M%S) نام‌گذاری شده است، جایی که تمام فایل‌های تولیدشدهٔ آن ذخیره می‌شوند\&. در صورتی که
pg_upgrade
با موفقیت به پایان برسد،
pg_upgrade_output\&.d
و فایل‌های موجود در آن به‌طور خودکار حذف خواهند شد؛ اما در صورت بروز مشکل، فایل‌های موجود در آنجا ممکن است اطلاعات مفیدی برای اشکال‌زدایی فراهم کنند\&.
.PP
دستور
pg_upgrade
فرایندهای postmaster کوتاه‌مدتی را در دایرکتوری‌های داده‌های قدیمی و جدید راه‌اندازی می‌کند\&. فایل‌های موقت سوکت یونیکس برای ارتباط با این postmasterها، به‌طور پیش‌فرض در دایرکتوری کاری فعلی ایجاد می‌شوند\&. در برخی شرایط ممکن است نام مسیر دایرکتوری فعلی طولانی‌تر از آن باشد که یک نام سوکت معتبر به‌شمار آید\&. در این حالت می‌توانید از گزینهٔ
\fB\-s\fR
برای قرار دادن فایل‌های سوکت در دایرکتوری دیگری با نام مسیر کوتاه‌تر استفاده کنید\&. برای امنیت، مطمئن شوید که آن دایرکتوری برای هیچ کاربر دیگری قابل خواندن یا نوشتن نباشد\&. (این ویژگی در Windows پشتیبانی نمی‌شود\&.)
.PP
تمام موارد شکست، بازسازی و نمایه‌سازی مجدد (reindex) در صورتی که بر روی نصب شما تأثیر بگذارند، توسط
pg_upgrade
گزارش خواهند شد؛ اسکریپت‌های پس از ارتقا برای بازسازی جدول‌ها و ایندکس‌ها به‌طور خودکار تولید خواهند شد\&. اگر در حال خودکارسازی ارتقای کلاسترهای متعددی هستید، درمی‌یابید که کلاسترهایی با اسکیماهای پایگاه‌دادهٔ یکسان، به مراحل پس از ارتقای مشابهی برای همهٔ کلاسترها نیاز دارند؛ این به این دلیل است که مراحل پس از ارتقا مبتنی بر اسکیماهای پایگاه‌داده هستند، و نه داده‌های کاربر\&.
.PP
برای آزمایش استقرار، یک رونوشتِ فقط اسکیما از کلاستر قدیمی ایجاد کنید، داده‌های صوری درون آن درج نمایید، و آن را ارتقا دهید\&.
.PP
دستور
pg_upgrade
از ارتقای پایگاه‌های داده‌ای که ستون‌های جدول آن‌ها از این انواع داده‌های سیستمی
reg*
ارجاع‌دهنده به OID استفاده می‌کنند، پشتیبانی نمی‌کند:
.RS 4
regcollation
.RE
.RS 4
regconfig
.RE
.RS 4
regdictionary
.RE
.RS 4
regnamespace
.RE
.RS 4
regoper
.RE
.RS 4
regoperator
.RE
.RS 4
regproc
.RE
.RS 4
regprocedure
.RE
(انواع
regclass،
regrole
و
regtype
می‌توانند ارتقا یابند\&.)
.PP
اگر می‌خواهید از حالت پیوند (link mode) استفاده کنید و مایل نیستید با راه‌اندازی کلاستر جدید، کلاستر قدیمی دستخوش تغییر شود، استفاده از حالت کلون (clone mode) را در نظر بگیرید\&. در صورتی که این قابلیت در دسترس نیست، یک رونوشت از کلاستر قدیمی بگیرید و آن را در حالت پیوند ارتقا دهید\&. برای ایجاد یک نسخهٔ معتبر از کلاستر قدیمی، در حالی که سرور در حال اجراست از
\fBrsync\fR
برای ایجاد یک نسخهٔ ناهمگام (dirty copy) از کلاستر قدیمی استفاده کنید، سپس سرور قدیمی را خاموش کرده و مجدداً دستور
\fBrsync \-\-checksum\fR
را اجرا نمایید تا نسخهٔ رونوشت با اعمال تغییرات، یکدست و همگام شود\&. (استفاده از گزینهٔ
\fB\-\-checksum\fR
ضروری است چرا که
\fBrsync\fR
تنها از دقت زمانی یک ثانیه‌ای برای زمان ویرایش فایل‌ها برخوردار است\&.) ممکن است بخواهید برخی فایل‌ها، مانند
postmaster\&.pid،
را همان‌طور که در
Section\ \&25.3.4\&
مستند شده است، مستثنی کنید\&. اگر فایل‌سیستم شما از اسنپ‌شات‌های فایل‌سیستم یا کپی فایل‌های copy\-on\-write پشتیبانی می‌کند، می‌توانید از آن برای پشتیبان‌گیری از کلاستر قدیمی و tablespaceها استفاده کنید، اگرچه اسنپ‌شات و کپی‌ها باید هم‌زمان یا در زمان متوقف بودن سرور پایگاه‌داده ایجاد شوند\&..SH "همچنین ببینید (SEE ALSO)"
\fBinitdb\fR(1), \fBpg_ctl\fR(1), \fBpg_dump\fR(1), \fBpostgres\fR(1)