PG_RECEIVEWAL(1) PostgreSQL 18.6 Documentation PG_RECEIVEWAL(1)

pg_receivewal - دریافت جریانی لاگ‌های پیش‌نویس (write-ahead logs) از سرور PostgreSQL

pg_receivewal [گزینه...]

دستور pg_receivewal برای دریافت جریانی لاگ‌های پیش‌نویس (write-ahead log) از یک کلاستر در حال اجرای PostgreSQL استفاده می‌شود. لاگ پیش‌نویس با استفاده از پروتکل رونوشت‌برداری جریانی (streaming replication) فرستاده شده و در یک دایرکتوری محلی از فایل‌ها ذخیره می‌شود. این دایرکتوری می‌تواند به عنوان مکان بایگانی برای انجام بازیابی نقطه‌ای در زمان (بخش 25.3 را ببینید) به کار رود.

دستور pg_receivewal لاگ‌های پیش‌نویس را به‌صورت بلادرنگ و همگام با تولید شدن در سرور به‌طور جریانی دریافت می‌کند، و بر خلاف archive_command و archive_library منتظر کامل شدن سگمنت‌ها نمی‌ماند. به همین دلیل، هنگام استفاده از pg_receivewal نیازی به تنظیم archive_timeout نیست.

برخلاف دریافت‌کننده WAL در سرور آماده‌به‌کار (standby) در PostgreSQL، ابزار pg_receivewal به‌طور پیش‌فرض داده‌های WAL را تنها زمانی روی دیسک می‌نشاند (flush می‌کند) که یک فایل WAL بسته شود. برای نوشتن داده‌های WAL بر روی دیسک به‌صورت بلادرنگ، گزینه --synchronous باید مشخص شود. از آنجا که pg_receivewal داده‌های WAL را اعمال (apply) نمی‌کند، نباید اجازه دهید در شرایطی که synchronous_commit برابر با remote_apply است، به یک سرور آماده‌به‌کار همگام (synchronous standby) تبدیل شود. اگر چنین شود، مانند یک سرور آماده‌به‌کار به نظر خواهد رسید که هرگز به پایگاه داده اصلی نمی‌رسد و باعث مسدود شدن تأیید تراکنش‌ها (commit) خواهد شد. برای اجتناب از این وضعیت، باید یا مقدار مناسبی را برای synchronous_standby_names پیکربندی کنید، یا یک application_name برای pg_receivewal مشخص کنید که با آن مطابقت نداشته باشد، یا مقدار synchronous_commit را به چیزی غیر از remote_apply تغییر دهید.

لاگ‌های پیش‌نویس از طریق یک اتصال معمولی PostgreSQL و با استفاده از پروتکل رونوشت‌برداری (replication) به صورت جریانی منتقل می‌شوند. این اتصال باید توسط کاربری دارای مجوزهای REPLICATION (بخش 21.2 را ببینید) یا مدیر سیستم (superuser) برقرار شود و فایل pg_hba.conf نیز باید اجازه اتصال رونوشت‌برداری را صادر کند. همچنین سرور باید طوری پیکربندی شده باشد که مقدار max_wal_senders به اندازه کافی بالا تنظیم شود تا حداقل یک نشست (session) برای این جریان در دسترس باقی بماند.

نقطه آغاز جریان لاگ‌های پیش‌نویس در زمان راه‌اندازی pg_receivewal محاسبه می‌شود:

1.ابتدا دایرکتوری محل ذخیره فایل‌های قطعه WAL بررسی شده و جدیدترین فایل قطعه تکمیل‌شده پیدا می‌شود؛ سپس ابتدای فایل قطعه بعدی WAL به عنوان نقطه آغاز در نظر گرفته می‌شود.
2.اگر محاسبه نقطه شروع با روش پیشین امکان‌پذیر نباشد و از یک replication slot استفاده شده باشد، یک دستور اضافی READ_REPLICATION_SLOT صادر می‌شود تا restart_lsn مربوط به slot برای استفاده به عنوان نقطه شروع بازیابی گردد. این گزینه تنها هنگام دریافت جریانی لاگ‌های پیش‌نویس از PostgreSQL نسخه ۱۵ به بالا در دسترس است.
3.اگر با روش پیشین نیز محاسبه نقطه شروع ممکن نباشد، از آخرین مکان تخلیه (flush) لاگ WAL که توسط سرور از طریق دستور IDENTIFY_SYSTEM گزارش شده است استفاده می‌شود.

اگر اتصال با یک خطای غیرمرگبار قطع شود یا در ابتدا برقرار نگردد، pg_receivewal تلاش برای اتصال را تا بی‌نهایت تکرار می‌کند و جریان را در اسرع وقت مجدداً برقرار می‌سازد. برای جلوگیری از این رفتار، از پارامتر -n استفاده کنید.

در صورت عدم وقوع خطاهای مرگبار، pg_receivewal تا زمانی که با سیگنال SIGINT (Control+C) یا SIGTERM متوقف نشود، به اجرای خود ادامه خواهد داد..SH "گزینه‌ها (OPTIONS)"

-D directory
--directory=directory

دایرکتوری برای نوشتن خروجی در آن.

این پارامتر الزامی است.

-E lsn
--endpos=lsn

توقف خودکار همانندسازی و خروج با وضعیت خروج عادی 0 هنگامی که دریافت به LSN مشخص‌شده برسد.

اگر رکوردی با LSN دقیقاً برابر با lsn وجود داشته باشد، آن رکورد پردازش خواهد شد.

--if-not-exists

در صورتی که --create-slot مشخص شده باشد و اسلاتی با نام مشخص‌شده از قبل وجود داشته باشد، خطایی صادر نشود.

-n
--no-loop

در هنگام خطاهای اتصال در حلقه تکرار قرار نگیرد؛ در عوض، فوراً با یک خطا خارج شود.

--no-sync

این گزینه باعث می‌شود pg_receivewal داده‌های WAL را مجبور به تخلیه و همگام‌سازی با دیسک نکند. این کار سریع‌تر است، اما بدین معناست که از کار افتادن متعاقب سیستم‌عامل می‌تواند بخش‌های WAL را خراب کند. به‌طور کلی، این گزینه برای آزمایش مفید است اما نباید هنگام انجام بایگانی WAL در یک محیط عملیاتی استفاده شود.

این گزینه با --synchronous ناسازگار است.

-s interval
--status-interval=interval

تعداد ثانیه‌های بین بسته‌های وضعیت ارسالی به سرور را تعیین می‌کند. این امر نظارت بر پیشرفت را از سمت سرور آسان‌تر می‌سازد. مقدار صفر، به‌روزرسانی‌های دوره‌ای وضعیت را کاملاً غیرفعال می‌کند، هرچند برای جلوگیری از قطع اتصال به دلیل اتمام زمان، هنگام درخواست سرور همچنان یک به‌روزرسانی ارسال خواهد شد. مقدار پیش‌فرض ۱۰ ثانیه است.

-S slotname
--slot=slotname

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

هنگامی که کلاینت همانندسازی pg_receivewal روی سرور به عنوان یک standby همگام پیکربندی شده باشد، استفاده از یک اسلات همانندسازی موقعیت تخلیه را به سرور گزارش می‌دهد، اما تنها زمانی که یک فایل WAL بسته شود. بنابراین، آن پیکربندی باعث می‌شود که تراکنش‌ها روی سرور اصلی برای مدت طولانی منتظر بمانند و عملاً کارایی رضایت‌بخشی نداشته باشند. علاوه بر این، گزینه --synchronous (زیر را ببینید) باید مشخص شود تا این سازوکار به درستی عمل کند.

--synchronous

داده‌های WAL را بلافاصله پس از دریافت، روی دیسک تخلیه و همگام می‌کند. همچنین بلافاصله پس از تخلیه، صرف‌نظر از --status-interval، یک بسته وضعیت به سرور ارسال می‌کند.

اگر کلاینت همانندسازی pg_receivewal روی سرور به عنوان یک standby همگام پیکربندی شده باشد، این گزینه باید مشخص شود تا اطمینان حاصل گردد بازخورد به‌موقع به سرور فرستاده می‌شود.

-v
--verbose

حالت پرگو (verbose) را فعال می‌کند.

-Z level
-Z method[:detail]
--compress=level
--compress=method[:detail]

فشرده‌سازی گزارش‌های ثبت وقایع از پیش نوشته‌شده (write-ahead logs) را فعال می‌کند.

روش فشرده‌سازی می‌تواند روی gzip، lz4 (اگر PostgreSQL با --with-lz4 کامپایل شده باشد) یا none برای عدم فشرده‌سازی تنظیم شود. می‌توان به‌صورت اختیاری یک رشته جزئیات فشرده‌سازی را مشخص کرد. اگر رشته جزئیات یک عدد صحیح باشد، سطح فشرده‌سازی را مشخص می‌کند. در غیر این صورت، باید فهرستی از موارد جداشده با کاما به شکل keyword یا keyword=value باشد. در حال حاضر، تنها کلیدواژه پشتیبانی‌شده level است.

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

پسوند .gz به‌طور خودکار هنگام استفاده از gzip به تمام نام‌های فایل اضافه خواهد شد، و پسوند .lz4 هنگام استفاده از lz4 افزوده می‌شود.

گزینه‌های خط فرمان زیر پارامترهای اتصال به پایگاه‌داده را کنترل می‌کنند.

-d connstr
--dbname=connstr

پارامترهای مورد استفاده برای اتصال به سرور را به عنوان یک رشته اتصال تعیین می‌کند؛ این مقادیر بر هر گزینه متناقض دیگری در خط فرمان اولویت خواهند داشت.

این گزینه برای سازگاری با سایر برنامه‌های کاربردی کلاینت --dbname نامیده شده است، اما از آنجا که pg_receivewal به هیچ پایگاه‌داده خاصی در کلاستر متصل نمی‌شود، هر نام پایگاه‌داده‌ای که در رشته اتصال گنجانده شود توسط سرور نادیده گرفته خواهد شد. با این حال، نام پایگاه‌داده‌ای که از این طریق ارائه می‌شود، نام پایگاه‌داده پیش‌فرض (replication) را برای مقاصد جستجوی گذرواژه اتصال همانندسازی در ~/.pgpass بازنویسی می‌کند. به همین ترتیب، میان‌افزارها یا پروکسی‌های مورد استفاده در اتصال به PostgreSQL ممکن است از این نام برای مقاصدی مانند مسیریابی اتصال استفاده کنند.

-h host
--host=host

نام میزبان ماشینی را که سرور روی آن در حال اجرا است تعیین می‌کند. اگر مقدار با یک اسلش آغاز شود، به عنوان دایرکتوری برای سوکت دامنه یونیکس استفاده می‌شود. مقدار پیش‌فرض از متغیر محیطی PGHOST (در صورت تنظیم بودن) گرفته می‌شود، در غیر این صورت برای اتصال از طریق سوکت دامنه یونیکس تلاش خواهد شد.

-p port
--port=port

پورت TCP یا پسوند فایل سوکت دامنه یونیکس محلی را که سرور روی آن به اتصالات گوش می‌دهد، تعیین می‌کند. پیش‌فرض آن در صورت تنظیم بودن متغیر محیطی PGPORT است، یا یک مقدار پیش‌فرض کامپایل‌شده داخلی.

-U username
--username=username

نام کاربری برای اتصال.

-w
--no-password

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

-W
--password

اجبار می‌کند که pg_receivewal قبل از اتصال به پایگاه‌داده، گذرواژه را درخواست کند..sp این گزینه هرگز ضروری نیست، چرا که اگر سرور نیازمند احراز هویت با گذرواژه باشد، pg_receivewal به‌طور خودکار گذرواژه را درخواست خواهد کرد. با این حال، pg_receivewal یک تلاش برای اتصال را جهت پی بردن به این که سرور گذرواژه می‌خواهد هدر می‌دهد. در برخی موارد برای جلوگیری از تلاش اتصال اضافی، وارد کردن -W ارزشش را دارد.

دستور pg_receivewal می‌تواند یکی از دو اقدام زیر را برای کنترل replication slotهای فیزیکی انجام دهد:

--create-slot

یک replication slot فیزیکی جدید با نام مشخص‌شده در --slot ایجاد کرده و سپس خارج شود.

--drop-slot

مورد replication slot با نام مشخص‌شده در --slot را حذف کرده و سپس خارج شود.

گزینه‌های دیگری نیز در دسترس هستند:

-V
--version

نسخهٔ pg_receivewal را چاپ کرده و خارج شود.

-?
--help

راهنمایی دربارهٔ آرگومان‌های خط فرمان pg_receivewal را نمایش داده و خارج شود.

هنگامی که pg_receivewal توسط سیگنال SIGINT یا SIGTERM متوقف شود، با وضعیت 0 خارج خواهد شد. (این روش عادی برای پایان دادن به آن است؛ بنابراین خطا محسوب نمی‌شود.) برای خطاهای مهلک یا سایر سیگنال‌ها، وضعیت خروج غیرصفر خواهد بود.

این ابزار، مانند بیشتر ابزارهای دیگر PostgreSQL، از متغیرهای محیطی پشتیبانی‌شده توسط libpq استفاده می‌کند (بخش 32.15 را ببینید).

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

هنگام استفاده از pg_receivewal به‌جای archive_command یا archive_library به‌عنوان روش اصلی پشتیبان‌گیری WAL، اکیداً توصیه می‌شود از replication slotها استفاده کنید. در غیر این صورت، سرور مجاز است فایل‌های write-ahead log را پیش از تهیهٔ نسخهٔ پشتیبان بازیافت (recycle) یا حذف کند، زیرا هیچ اطلاعاتی، چه از جانب archive_command یا archive_library و چه از سوی replication slotها، دربارهٔ این که جریان WAL تا کجا بایگانی شده است ندارد. با این حال توجه داشته باشید که اگر دریافت‌کننده نتواند همگام با دریافت داده‌های WAL پیش برود، یک replication slot فضای دیسک سرور را پر خواهد کرد.

در صورتی که مجوزهای دسترسی گروهی روی کلاستر مبدأ فعال باشد، pg_receivewal مجوزهای گروهی را روی فایل‌های WAL دریافتی حفظ خواهد کرد..SH "مثال‌ها (EXAMPLES)"

برای استریم کردن write-ahead log از سرور mydbserver و ذخیره آن در دایرکتوری محلی /usr/local/pgsql/archive:

$ pg_receivewal -h mydbserver -D /usr/local/pgsql/archive

pg_basebackup(1)

2026 PostgreSQL 18.6