PG_RESETWAL(1) مستندات PostgreSQL 18.6 PG_RESETWAL(1)

pg_resetwal - بازنشانی گزارش پیش‌نویس (WAL) و سایر اطلاعات کنترلی کلاستر پایگاه‌داده PostgreSQL

pg_resetwal [-f | --force] [-n | --dry-run] [option...] [-D | --pgdata]datadir

دستور pg_resetwal گزارش‌های پیش‌نویس (WAL) را پاک کرده و به صورت اختیاری برخی دیگر از اطلاعات کنترلی ذخیره‌شده در فایل pg_control را بازنشانی می‌کند. این تابع در مواردی که این فایل‌ها خراب شده باشند لازم می‌شود. این ابزار تنها باید به عنوان آخرین چاره استفاده شود، زمانی که سرور به دلیل چنین خرابی‌هایی راه‌اندازی نمی‌شود.

برخی گزینه‌ها، مانند --wal-segsize (به زیر مراجعه کنید)، می‌توانند برای تغییر برخی تنظیمات سراسری یک کلاستر پایگاه‌داده بدون نیاز به اجرای مجدد initdb نیز استفاده شوند. در صورتی که هیچ‌یک از حالت‌های خطرناک ذکرشده در ادامه استفاده نشود، این کار می‌تواند با ایمنی روی یک کلاستر پایگاه‌داده سالم انجام شود.

اگر pg_resetwal روی دایرکتوری داده‌ای استفاده شود که سرور در آن به طور پاکیزه خاموش شده و فایل کنترل نیز سالم است، هیچ تاثیری بر محتوای سیستم پایگاه‌داده نخواهد داشت، به جز اینکه فایل‌های WAL بلااستفاده پاکسازی می‌شوند. هرگونه استفاده دیگر بالقوه خطرناک است و باید با احتیاط فراوان انجام گیرد. pg_resetwal پیش از کار بر روی دایرکتوری داده‌ای که در وضعیت خاموش شدن ناپاکیزه (unclean shutdown) است یا فایل کنترل آن خراب شده، نیازمند مشخص شدن گزینه -f (اجبار) خواهد بود.

پس از اجرای این دستور روی یک دایرکتوری داده با WAL خراب یا فایل کنترل آسیب‌دیده، باید بتوان سرور را راه‌اندازی کرد، اما به خاطر داشته باشید که ممکن است پایگاه‌داده به دلیل تراکنش‌های نیمه‌اعمال‌شده (partially-committed) حاوی داده‌های ناسازگار باشد. شما باید بلافاصله از داده‌های خود نسخه پشتیبان (dump) بگیرید، initdb را اجرا کرده و بازیابی (restore) نمایید. پس از بازیابی، ناسازگاری‌ها را بررسی کرده و در صورت نیاز تعمیر کنید.

اگر pg_resetwal پیام دهد که نمی‌تواند داده‌های معتبری برای pg_control تعیین کند، می‌توانید با تعیین گزینه -f (اجبار)، آن را مجبور به ادامه در هر صورت کنید. در این حالت مقادیر باورپذیر جایگزین داده‌های مفقود خواهند شد. می‌توان انتظار داشت بیشتر فیلدها مطابقت داشته باشند، اما ممکن است برای فیلدهای OID بعدی، شناسه و دوره (epoch) تراکنش بعدی، شناسه و آفست چندتراکنشی (multitransaction) بعدی، و فیلدهای مکان شروع WAL به مداخله دستی نیاز باشد. این فیلدها را می‌توان با گزینه‌هایی که در ادامه شرح داده شده تنظیم کرد. اگر قادر به تعیین مقادیر صحیح برای همه این فیلدها نیستید، همچنان می‌توان از -f استفاده کرد، اما باید به پایگاه‌داده بازیابی‌شده با سوءظن حتی بیشتری نسبت به حالت عادی نگریست: تهیه یک نسخه پشتیبان و بازیابی فوری ضروری است. هیچ عملیات تغییر داده‌ای را پیش از تهیه dump در پایگاه‌داده اجرا نکنید، زیرا هر اقدام این چنینی احتمالاً خرابی را بدتر خواهد کرد.

این ابزار تنها توسط کاربری که سرور را نصب کرده قابل اجرا است، زیرا به دسترسی خواندن/نوشتن در دایرکتوری داده نیاز دارد.

datadir
-D datadir
--pgdata=datadir

مکان دایرکتوری پایگاه‌داده را مشخص می‌کند. به دلایل امنیتی، باید دایرکتوری داده را در خط فرمان مشخص کنید. pg_resetwal از متغیر محیطی PGDATA استفاده نمی‌کند.

-f
--force

دستور pg_resetwal را مجبور می‌کند حتی در موقعیت‌هایی که طبق توضیحات بالا می‌تواند خطرناک باشد، به کار ادامه دهد. به طور مشخص، اگر سرور به صورت پاکیزه خاموش نشده باشد یا اگر pg_resetwal نتواند داده‌های معتبری را برای pg_control تعیین کند، این گزینه برای ادامه کار الزامی است.

-n
--dry-run

گزینه -n/--dry-run به pg_resetwal دستور می‌دهد مقادیر بازسازی‌شده از pg_control و مقادیری را که در آستانه تغییر هستند چاپ کند، و سپس بدون تغییر دادن هیچ چیزی خارج شود. این در درجه اول یک ابزار اشکال‌زدایی است، اما می‌تواند به عنوان یک بررسی سلامت اولیه پیش از اجازه دادن به pg_resetwal برای اجرای واقعی مفید باشد.

-V
--version

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

-?
--help

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

گزینه‌های زیر تنها زمانی مورد نیاز هستند که pg_resetwal قادر به تعیین مقادیر مناسب با خواندن pg_control نباشد. مقادیر ایمن را می‌توان طبق توضیحات زیر تعیین کرد. برای مقادیری که آرگومان عددی می‌گیرند، مقادیر شانزده‌شانزدهی (hexadecimal) را می‌توان با استفاده از پیشوند 0x مشخص کرد. توجه داشته باشید که این دستورالعمل‌ها تنها برای اندازه بلوک استاندارد 8 kB صدق می‌کنند.

-c xid,xid
--commit-timestamp-ids=xid,xid

قدیمی‌ترین و جدیدترین شناسه‌های تراکنش که زمان ثبت (commit time) آن‌ها قابل بازیابی است را به صورت دستی تنظیم می‌کند.

یک مقدار ایمن برای قدیمی‌ترین شناسه تراکنشی که زمان ثبت آن قابل بازیابی است (بخش اول) را می‌توان با یافتن کوچک‌ترین نام فایل از نظر عددی در دایرکتوری pg_commit_ts زیر دایرکتوری داده تعیین کرد. در مقابل، یک مقدار ایمن برای جدیدترین شناسه تراکنشی که زمان ثبت آن قابل بازیابی است (بخش دوم) را می‌توان با یافتن بزرگ‌ترین نام فایل از نظر عددی در همان دایرکتوری تعیین کرد. نام فایل‌ها به صورت شانزده‌شانزدهی هستند.

-e xid_epoch
--epoch=xid_epoch

دوره (epoch) شناسه تراکنش بعدی را به صورت دستی تنظیم می‌کند.

دوره شناسه تراکنش در واقع در هیچ کجای پایگاه‌داده ذخیره نمی‌شود مگر در فیلدی که توسط pg_resetwal تنظیم می‌شود، بنابراین تا جایی که به خود پایگاه‌داده مربوط است هر مقداری کار خواهد کرد. ممکن است برای اطمینان از عملکرد صحیح سیستم‌های تکثیر مانند Slony-I و Skytools نیاز به تنظیم این مقدار داشته باشید — اگر چنین است، باید بتوان مقدار مناسب را از وضعیت پایگاه‌داده تکثیرشده پایین‌دستی به دست آورد.

-l walfile
--next-wal-file=walfile

مکان شروع WAL را با تعیین نام فایل بخش بعدی WAL به صورت دستی تنظیم می‌کند.

نام فایل بخش بعدی WAL باید بزرگ‌تر از هر نام فایل بخش WAL دیگری باشد که در حال حاضر در دایرکتوری pg_wal زیر دایرکتوری داده وجود دارد. این نام‌ها نیز به صورت شانزده‌شانزدهی هستند و سه بخش دارند. بخش نخست “timeline ID” (شناسه خط زمانی) است و معمولاً باید دست‌نخورده باقی بماند. به عنوان مثال، اگر 00000001000000320000004A بزرگ‌ترین ورودی در pg_wal باشد، از -l 00000001000000320000004B یا بالاتر استفاده کنید.

توجه داشته باشید که هنگام استفاده از اندازه‌های غیرپیش‌فرض برای بخش‌های WAL، اعداد موجود در نام فایل‌های WAL با LSNهایی که توسط توابع و نماهای سیستمی گزارش می‌شوند متفاوت هستند. این گزینه یک نام فایل WAL دریافت می‌کند، نه یک LSN.


نکته
خود pg_resetwal فایل‌های موجود در pg_wal را بررسی کرده و یک مقدار پیش‌فرض فراتر از آخرین نام فایل موجود را برای تنظیم -l انتخاب می‌کند. بنابراین، تنظیم دستی -l تنها زمانی مورد نیاز خواهد بود که از فایل‌های بخش WAL که در حال حاضر در pg_wal موجود نیستند، مانند ورودی‌های یک آرشیو آفلاین، آگاه باشید؛ یا اینکه محتویات pg_wal به طور کامل از بین رفته باشد..sp .5v

-m mxid,mxid
--multixact-ids=mxid,mxid

تنظیم دستی شناسه چندتراکنشی (multitransaction ID) بعدی و قدیمی‌ترین.

یک مقدار امن برای شناسه چندتراکنشی بعدی (بخش اول) را می‌توان با جستجوی بزرگ‌ترین نام فایل از نظر عددی در دایرکتوری pg_multixact/offsets در زیر دایرکتوری داده، افزودن یک واحد به آن، و سپس ضرب در 65536 (0x10000) تعیین کرد. برعکس، یک مقدار امن برای قدیمی‌ترین شناسه چندتراکنشی (بخش دوم -m) را می‌توان با پیدا کردن کوچک‌ترین نام فایل از نظر عددی در همان دایرکتوری و ضرب آن در 65536 تعیین کرد. نام فایل‌ها به صورت هگزادسیمال هستند، بنابراین ساده‌ترین راه برای انجام این کار، مشخص کردن مقدار گزینه به صورت هگزادسیمال و افزودن چهار صفر به انتهای آن است.

-o oid
--next-oid=oid

تنظیم دستی OID بعدی.

هیچ راه به همان اندازه ساده‌ای برای تعیین OID بعدی که فراتر از بزرگ‌ترین مقدار در پایگاه‌داده باشد وجود ندارد، اما خوشبختانه دقیق بودن تنظیم next-OID حیاتی نیست.

-O mxoff
--multixact-offset=mxoff

تنظیم دستی multitransaction offset بعدی.

یک مقدار امن را می‌توان با جستجوی بزرگ‌ترین نام فایل از نظر عددی در دایرکتوری pg_multixact/members در زیر دایرکتوری داده، افزودن یک واحد به آن و سپس ضرب در 52352 (0xCC80) تعیین کرد. نام فایل‌ها به صورت هگزادسیمال هستند. بر خلاف گزینه‌های دیگر، دستورالعمل ساده‌ای مانند افزودن صفر به انتهای مقدار وجود ندارد.

-u xid
--oldest-transaction-id=xid

تنظیم دستی قدیمی‌ترین transaction ID منجمدنشده (unfrozen).

یک مقدار امن را می‌توان با پیدا کردن کوچک‌ترین نام فایل از نظر عددی در دایرکتوری pg_xact در زیر دایرکتوری داده و سپس ضرب آن در 1048576 (0x100000) تعیین کرد. توجه داشته باشید که نام فایل‌ها به صورت هگزادسیمال هستند. معمولاً ساده‌ترین کار این است که مقدار گزینه نیز به صورت هگزادسیمال مشخص شود. برای مثال، اگر 0007 کوچک‌ترین مدخل در pg_xact باشد، مقدار -u 0x700000 کار خواهد کرد (پنج صفر پایانی ضریب مناسب را فراهم می‌کنند).

-x xid
--next-transaction-id=xid

تنظیم دستی transaction ID بعدی.

یک مقدار امن را می‌توان با پیدا کردن بزرگ‌ترین نام فایل از نظر عددی در دایرکتوری pg_xact در زیر دایرکتوری داده، افزودن یک واحد به آن و سپس ضرب در 1048576 (0x100000) تعیین کرد. توجه داشته باشید که نام فایل‌ها به صورت هگزادسیمال هستند. معمولاً ساده‌ترین کار این است که مقدار گزینه نیز به صورت هگزادسیمال مشخص شود. برای مثال، اگر 0011 بزرگ‌ترین مدخل در pg_xact باشد، مقدار -x 0x1200000 کار خواهد کرد (پنج صفر پایانی ضریب مناسب را فراهم می‌کنند).

--char-signedness=option

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

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

--wal-segsize=wal_segment_size

تنظیم اندازه جدید سگمنت WAL، بر حسب مگابایت. این مقدار باید توانی از 2 بین 1 و 1024 (مگابایت) باشد. برای اطلاعات بیشتر، همین گزینه را در initdb(1) ببینید.

این گزینه می‌تواند همچنین برای تغییر اندازه سگمنت WAL یک کلاستر پایگاه‌داده موجود، به منظور جلوگیری از نیاز به اجرای مجدد initdb استفاده شود.


نکته
در حالی که pg_resetwal نشانی آغازین WAL را فراتر از آخرین فایل سگمنت موجود WAL تنظیم خواهد کرد، برخی تغییرات اندازه سگمنت می‌توانند باعث استفاده مجدد از نام‌های فایل‌های قبلی WAL شوند. توصیه می‌شود در صورتی که همپوشانی نام فایل‌های WAL باعث ایجاد مشکل در راهبرد بایگانی شما می‌شود، از -l همراه با این گزینه برای تنظیم دستی نشانی آغازین WAL استفاده کنید.

PG_COLOR

مشخص می‌کند که آیا در پیام‌های عیب‌یابی از رنگ استفاده شود یا خیر. مقادیر ممکن عبارتند از always، auto و never.

این دستور نباید هنگامی که سرور در حال اجرا است استفاده شود. pg_resetwal در صورتی که یک فایل قفل سرور را در دایرکتوری داده پیدا کند، از راه‌اندازی خودداری خواهد کرد. اگر سرور دچار فروپاشی (crash) شده باشد ممکن است یک فایل قفل بر جای مانده باشد؛ در این حالت می‌توانید فایل قفل را حذف کنید تا به pg_resetwal اجازهٔ اجرا داده شود. اما پیش از انجام این کار، کاملاً مطمئن شوید که هیچ فرایند سروری هنوز فعال نیست.

pg_resetwal تنها با سرورهایی از همان نسخهٔ اصلی (major version) کار می‌کند.

pg_controldata(1)

2026 PostgreSQL 18.6