'\" t
.\"     Title: pg_receivewal
.\"    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_RECEIVEWAL" "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_receivewal \- دریافت جریانی لاگ‌های پیش‌نویس (write\-ahead logs) از سرور PostgreSQL
.SH "خلاصه دستور (SYNOPSIS)"
.HP \w'\fBpg_receivewal\fR\ 'u
\fBpg_receivewal\fR [\fIگزینه\fR...]
.SH "توضیحات (DESCRIPTION)"
.PP
دستور
pg_receivewal
برای دریافت جریانی لاگ‌های پیش‌نویس (write\-ahead log) از یک کلاستر در حال اجرای
PostgreSQL
استفاده می‌شود\&. لاگ پیش‌نویس با استفاده از پروتکل رونوشت‌برداری جریانی (streaming replication) فرستاده شده و در یک دایرکتوری محلی از فایل‌ها ذخیره می‌شود\&. این دایرکتوری می‌تواند به عنوان مکان بایگانی برای انجام بازیابی نقطه‌ای در زمان (بخش\ \&25.3 را ببینید) به کار رود\&.
.PP
دستور
pg_receivewal
لاگ‌های پیش‌نویس را به‌صورت بلادرنگ و همگام با تولید شدن در سرور به‌طور جریانی دریافت می‌کند، و بر خلاف
archive_command
و
archive_library
منتظر کامل شدن سگمنت‌ها نمی‌ماند\&. به همین دلیل، هنگام استفاده از
pg_receivewal
نیازی به تنظیم
archive_timeout
نیست\&.
.PP
برخلاف دریافت‌کننده WAL در سرور آماده‌به‌کار (standby) در PostgreSQL، ابزار
pg_receivewal
به‌طور پیش‌فرض داده‌های WAL را تنها زمانی روی دیسک می‌نشاند (flush می‌کند) که یک فایل WAL بسته شود\&. برای نوشتن داده‌های WAL بر روی دیسک به‌صورت بلادرنگ، گزینه
\fB\-\-synchronous\fR
باید مشخص شود\&. از آنجا که
pg_receivewal
داده‌های WAL را اعمال (apply) نمی‌کند، نباید اجازه دهید در شرایطی که
synchronous_commit
برابر با
remote_apply
است، به یک سرور آماده‌به‌کار همگام (synchronous standby) تبدیل شود\&. اگر چنین شود، مانند یک سرور آماده‌به‌کار به نظر خواهد رسید که هرگز به پایگاه داده اصلی نمی‌رسد و باعث مسدود شدن تأیید تراکنش‌ها (commit) خواهد شد\&. برای اجتناب از این وضعیت، باید یا مقدار مناسبی را برای
synchronous_standby_names
پیکربندی کنید، یا یک
\fIapplication_name\fR
برای
pg_receivewal
مشخص کنید که با آن مطابقت نداشته باشد، یا مقدار
\fIsynchronous_commit\fR
را به چیزی غیر از
remote_apply
تغییر دهید\&.
.PP
لاگ‌های پیش‌نویس از طریق یک اتصال معمولی
PostgreSQL
و با استفاده از پروتکل رونوشت‌برداری (replication) به صورت جریانی منتقل می‌شوند\&. این اتصال باید توسط کاربری دارای مجوزهای
REPLICATION
(بخش\ \&21.2 را ببینید) یا مدیر سیستم (superuser) برقرار شود و فایل
pg_hba\&.conf
نیز باید اجازه اتصال رونوشت‌برداری را صادر کند\&. همچنین سرور باید طوری پیکربندی شده باشد که مقدار
max_wal_senders
به اندازه کافی بالا تنظیم شود تا حداقل یک نشست (session) برای این جریان در دسترس باقی بماند\&.
.PP
نقطه آغاز جریان لاگ‌های پیش‌نویس در زمان راه‌اندازی
pg_receivewal
محاسبه می‌شود:
.sp
.RS 4
.ie n \{\
\h'-04' 1.\h'+01'\c
.\}
.el \{\
.sp -1
.IP "  1." 4.2
.\}
ابتدا دایرکتوری محل ذخیره فایل‌های قطعه WAL بررسی شده و جدیدترین فایل قطعه تکمیل‌شده پیدا می‌شود؛ سپس ابتدای فایل قطعه بعدی WAL به عنوان نقطه آغاز در نظر گرفته می‌شود\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 2.\h'+01'\c
.\}
.el \{\
.sp -1
.IP "  2." 4.2
.\}
اگر محاسبه نقطه شروع با روش پیشین امکان‌پذیر نباشد و از یک replication slot استفاده شده باشد، یک دستور اضافی
\fBREAD_REPLICATION_SLOT\fR
صادر می‌شود تا
restart_lsn
مربوط به slot برای استفاده به عنوان نقطه شروع بازیابی گردد\&. این گزینه تنها هنگام دریافت جریانی لاگ‌های پیش‌نویس از
PostgreSQL
نسخه ۱۵ به بالا در دسترس است\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 3.\h'+01'\c
.\}
.el \{\
.sp -1
.IP "  3." 4.2
.\}
اگر با روش پیشین نیز محاسبه نقطه شروع ممکن نباشد، از آخرین مکان تخلیه (flush) لاگ WAL که توسط سرور از طریق دستور
IDENTIFY_SYSTEM
گزارش شده است استفاده می‌شود\&.
.RE
.PP
اگر اتصال با یک خطای غیرمرگبار قطع شود یا در ابتدا برقرار نگردد،
pg_receivewal
تلاش برای اتصال را تا بی‌نهایت تکرار می‌کند و جریان را در اسرع وقت مجدداً برقرار می‌سازد\&. برای جلوگیری از این رفتار، از پارامتر
\-n
استفاده کنید\&.
.PP
در صورت عدم وقوع خطاهای مرگبار،
pg_receivewal
تا زمانی که با سیگنال
SIGINT
(Control+C) یا
SIGTERM
متوقف نشود، به اجرای خود ادامه خواهد داد\&..SH "گزینه‌ها (OPTIONS)"
.PP
\fB\-D \fR\fB\fIdirectory\fR\fR
.br
\fB\-\-directory=\fR\fB\fIdirectory\fR\fR
.RS 4
دایرکتوری برای نوشتن خروجی در آن\&.
.sp
این پارامتر الزامی است\&.
.RE
.PP
\fB\-E \fR\fB\fIlsn\fR\fR
.br
\fB\-\-endpos=\fR\fB\fIlsn\fR\fR
.RS 4
توقف خودکار همانندسازی و خروج با وضعیت خروج عادی 0 هنگامی که دریافت به LSN مشخص‌شده برسد\&.
.sp
اگر رکوردی با LSN دقیقاً برابر با
\fIlsn\fR
وجود داشته باشد، آن رکورد پردازش خواهد شد\&.
.RE
.PP
\fB\-\-if\-not\-exists\fR
.RS 4
در صورتی که
\fB\-\-create\-slot\fR
مشخص شده باشد و اسلاتی با نام مشخص‌شده از قبل وجود داشته باشد، خطایی صادر نشود\&.
.RE
.PP
\fB\-n\fR
.br
\fB\-\-no\-loop\fR
.RS 4
در هنگام خطاهای اتصال در حلقه تکرار قرار نگیرد؛ در عوض، فوراً با یک خطا خارج شود\&.
.RE
.PP
\fB\-\-no\-sync\fR
.RS 4
این گزینه باعث می‌شود
\fBpg_receivewal\fR
داده‌های WAL را مجبور به تخلیه و همگام‌سازی با دیسک نکند\&. این کار سریع‌تر است، اما بدین معناست که از کار افتادن متعاقب سیستم‌عامل می‌تواند بخش‌های WAL را خراب کند\&. به‌طور کلی، این گزینه برای آزمایش مفید است اما نباید هنگام انجام بایگانی WAL در یک محیط عملیاتی استفاده شود\&.
.sp
این گزینه با
\-\-synchronous
ناسازگار است\&.
.RE
.PP
\fB\-s \fR\fB\fIinterval\fR\fR
.br
\fB\-\-status\-interval=\fR\fB\fIinterval\fR\fR
.RS 4
تعداد ثانیه‌های بین بسته‌های وضعیت ارسالی به سرور را تعیین می‌کند\&. این امر نظارت بر پیشرفت را از سمت سرور آسان‌تر می‌سازد\&. مقدار صفر، به‌روزرسانی‌های دوره‌ای وضعیت را کاملاً غیرفعال می‌کند، هرچند برای جلوگیری از قطع اتصال به دلیل اتمام زمان، هنگام درخواست سرور همچنان یک به‌روزرسانی ارسال خواهد شد\&. مقدار پیش‌فرض ۱۰ ثانیه است\&.
.RE
.PP
\fB\-S \fR\fB\fIslotname\fR\fR
.br
\fB\-\-slot=\fR\fB\fIslotname\fR\fR
.RS 4
لازم می‌دارد که
pg_receivewal
از یک اسلات همانندسازی موجود استفاده کند (بخش\ \&26.2.6 را ببینید)\&. هنگامی که از این گزینه استفاده می‌شود،
pg_receivewal
موقعیت تخلیه را به سرور گزارش می‌دهد، که نشان می‌دهد چه زمانی هر بخش با دیسک همگام شده است تا سرور بتواند آن بخش را در صورت عدم نیاز حذف کند\&.
.sp
هنگامی که کلاینت همانندسازی
pg_receivewal
روی سرور به عنوان یک standby همگام پیکربندی شده باشد، استفاده از یک اسلات همانندسازی موقعیت تخلیه را به سرور گزارش می‌دهد، اما تنها زمانی که یک فایل WAL بسته شود\&. بنابراین، آن پیکربندی باعث می‌شود که تراکنش‌ها روی سرور اصلی برای مدت طولانی منتظر بمانند و عملاً کارایی رضایت‌بخشی نداشته باشند\&. علاوه بر این، گزینه
\-\-synchronous
(زیر را ببینید) باید مشخص شود تا این سازوکار به درستی عمل کند\&.
.RE
.PP
\fB\-\-synchronous\fR
.RS 4
داده‌های WAL را بلافاصله پس از دریافت، روی دیسک تخلیه و همگام می‌کند\&. همچنین بلافاصله پس از تخلیه، صرف‌نظر از
\-\-status\-interval،
یک بسته وضعیت به سرور ارسال می‌کند\&.
.sp
اگر کلاینت همانندسازی
pg_receivewal
روی سرور به عنوان یک standby همگام پیکربندی شده باشد، این گزینه باید مشخص شود تا اطمینان حاصل گردد بازخورد به‌موقع به سرور فرستاده می‌شود\&.
.RE
.PP
\fB\-v\fR
.br
\fB\-\-verbose\fR
.RS 4
حالت پرگو (verbose) را فعال می‌کند\&.
.RE
.PP
\fB\-Z \fR\fB\fIlevel\fR\fR
.br
\fB\-Z \fR\fB\fImethod\fR\fR\fB[:\fR\fB\fIdetail\fR\fR\fB]\fR
.br
\fB\-\-compress=\fR\fB\fIlevel\fR\fR
.br
\fB\-\-compress=\fR\fB\fImethod\fR\fR\fB[:\fR\fB\fIdetail\fR\fR\fB]\fR
.RS 4
فشرده‌سازی گزارش‌های ثبت وقایع از پیش نوشته‌شده (write\-ahead logs) را فعال می‌کند\&.
.sp
روش فشرده‌سازی می‌تواند روی
gzip،
lz4
(اگر
PostgreSQL
با
\fB\-\-with\-lz4\fR
کامپایل شده باشد) یا
none
برای عدم فشرده‌سازی تنظیم شود\&. می‌توان به‌صورت اختیاری یک رشته جزئیات فشرده‌سازی را مشخص کرد\&. اگر رشته جزئیات یک عدد صحیح باشد، سطح فشرده‌سازی را مشخص می‌کند\&. در غیر این صورت، باید فهرستی از موارد جداشده با کاما به شکل
\fIkeyword\fR
یا
\fIkeyword=value\fR
باشد\&. در حال حاضر، تنها کلیدواژه پشتیبانی‌شده
level
است\&.
.sp
اگر هیچ سطح فشرده‌سازی مشخص نشود، از سطح فشرده‌سازی پیش‌فرض استفاده خواهد شد\&. اگر فقط یک سطح بدون ذکر الگوریتم مشخص شود، در صورتی که سطح بزرگ‌تر از 0 باشد از فشرده‌سازی
gzip
استفاده می‌شود، و در صورتی که سطح 0 باشد هیچ فشرده‌سازی اعمال نخواهد شد\&.
.sp
پسوند
\&.gz
به‌طور خودکار هنگام استفاده از
gzip
به تمام نام‌های فایل اضافه خواهد شد، و پسوند
\&.lz4
هنگام استفاده از
lz4
افزوده می‌شود\&.
.RE
.PP
گزینه‌های خط فرمان زیر پارامترهای اتصال به پایگاه‌داده را کنترل می‌کنند\&.
.PP
\fB\-d \fR\fB\fIconnstr\fR\fR
.br
\fB\-\-dbname=\fR\fB\fIconnstr\fR\fR
.RS 4
پارامترهای مورد استفاده برای اتصال به سرور را به عنوان یک رشته اتصال تعیین می‌کند؛ این مقادیر بر هر گزینه متناقض دیگری در خط فرمان اولویت خواهند داشت\&.
.sp
این گزینه برای سازگاری با سایر برنامه‌های کاربردی کلاینت
\-\-dbname
نامیده شده است، اما از آنجا که
pg_receivewal
به هیچ پایگاه‌داده خاصی در کلاستر متصل نمی‌شود، هر نام پایگاه‌داده‌ای که در رشته اتصال گنجانده شود توسط سرور نادیده گرفته خواهد شد\&. با این حال، نام پایگاه‌داده‌ای که از این طریق ارائه می‌شود، نام پایگاه‌داده پیش‌فرض (replication) را برای مقاصد جستجوی گذرواژه اتصال همانندسازی در
~/\&.pgpass
بازنویسی می‌کند\&. به همین ترتیب، میان‌افزارها یا پروکسی‌های مورد استفاده در اتصال به
PostgreSQL
ممکن است از این نام برای مقاصدی مانند مسیریابی اتصال استفاده کنند\&.
.RE
.PP
\fB\-h \fR\fB\fIhost\fR\fR
.br
\fB\-\-host=\fR\fB\fIhost\fR\fR
.RS 4
نام میزبان ماشینی را که سرور روی آن در حال اجرا است تعیین می‌کند\&. اگر مقدار با یک اسلش آغاز شود، به عنوان دایرکتوری برای سوکت دامنه یونیکس استفاده می‌شود\&. مقدار پیش‌فرض از متغیر محیطی
\fBPGHOST\fR
(در صورت تنظیم بودن) گرفته می‌شود، در غیر این صورت برای اتصال از طریق سوکت دامنه یونیکس تلاش خواهد شد\&.
.RE
.PP
\fB\-p \fR\fB\fIport\fR\fR
.br
\fB\-\-port=\fR\fB\fIport\fR\fR
.RS 4
پورت TCP یا پسوند فایل سوکت دامنه یونیکس محلی را که سرور روی آن به اتصالات گوش می‌دهد، تعیین می‌کند\&. پیش‌فرض آن در صورت تنظیم بودن متغیر محیطی
\fBPGPORT\fR
است، یا یک مقدار پیش‌فرض کامپایل‌شده داخلی\&.
.RE
.PP
\fB\-U \fR\fB\fIusername\fR\fR
.br
\fB\-\-username=\fR\fB\fIusername\fR\fR
.RS 4
نام کاربری برای اتصال\&.
.RE
.PP
\fB\-w\fR
.br
\fB\-\-no\-password\fR
.RS 4
هرگز درخواست وارد کردن گذرواژه را مطرح نکند\&. اگر سرور به احراز هویت با گذرواژه نیاز داشته باشد و گذرواژه از طریق راه‌های دیگر مانند فایل
\&.pgpass
در دسترس نباشد، تلاش برای اتصال با شکست مواجه خواهد شد\&. این گزینه می‌تواند در کارهای دسته‌ای و اسکریپت‌هایی که هیچ کاربری برای وارد کردن گذرواژه حضور ندارد، مفید باشد\&.
.RE
.PP
\fB\-W\fR
.br
\fB\-\-password\fR
.RS 4
اجبار می‌کند که
pg_receivewal
قبل از اتصال به پایگاه‌داده، گذرواژه را درخواست کند\&..sp
این گزینه هرگز ضروری نیست، چرا که اگر سرور نیازمند احراز هویت با گذرواژه باشد،
pg_receivewal
به‌طور خودکار گذرواژه را درخواست خواهد کرد\&. با این حال،
pg_receivewal
یک تلاش برای اتصال را جهت پی بردن به این که سرور گذرواژه می‌خواهد هدر می‌دهد\&. در برخی موارد برای جلوگیری از تلاش اتصال اضافی، وارد کردن
\fB\-W\fR
ارزشش را دارد\&.
.RE
.PP
دستور
pg_receivewal
می‌تواند یکی از دو اقدام زیر را برای کنترل replication slotهای فیزیکی انجام دهد:
.PP
\fB\-\-create\-slot\fR
.RS 4
یک replication slot فیزیکی جدید با نام مشخص‌شده در
\fB\-\-slot\fR
ایجاد کرده و سپس خارج شود\&.
.RE
.PP
\fB\-\-drop\-slot\fR
.RS 4
مورد replication slot با نام مشخص‌شده در
\fB\-\-slot\fR
را حذف کرده و سپس خارج شود\&.
.RE
.PP
گزینه‌های دیگری نیز در دسترس هستند:
.PP
\fB\-V\fR
.br
\fB\-\-version\fR
.RS 4
نسخهٔ
pg_receivewal
را چاپ کرده و خارج شود\&.
.RE
.PP
\fB\-?\fR
.br
\fB\-\-help\fR
.RS 4
راهنمایی دربارهٔ آرگومان‌های خط فرمان
pg_receivewal
را نمایش داده و خارج شود\&.
.RE
.SH "وضعیت خروج (EXIT STATUS)"
.PP
هنگامی که
pg_receivewal
توسط سیگنال
SIGINT
یا
SIGTERM
متوقف شود، با وضعیت 0 خارج خواهد شد\&. (این روش عادی برای پایان دادن به آن است؛ بنابراین خطا محسوب نمی‌شود\&.) برای خطاهای مهلک یا سایر سیگنال‌ها، وضعیت خروج غیرصفر خواهد بود\&.
.SH "محیط (ENVIRONMENT)"
.PP
این ابزار، مانند بیشتر ابزارهای دیگر
PostgreSQL،
از متغیرهای محیطی پشتیبانی‌شده توسط
libpq
استفاده می‌کند (بخش\ \&32.15 را ببینید)\&.
.PP
متغیر محیطی
\fBPG_COLOR\fR
مشخص می‌کند که آیا در پیام‌های عیب‌یابی از رنگ استفاده شود یا خیر\&. مقادیر ممکن عبارتند از
always،
auto
و
never\&.
.SH "نکات (NOTES)"
.PP
هنگام استفاده از
pg_receivewal
به‌جای
archive_command
یا
archive_library
به‌عنوان روش اصلی پشتیبان‌گیری WAL، اکیداً توصیه می‌شود از replication slotها استفاده کنید\&. در غیر این صورت، سرور مجاز است فایل‌های write\-ahead log را پیش از تهیهٔ نسخهٔ پشتیبان بازیافت (recycle) یا حذف کند، زیرا هیچ اطلاعاتی، چه از جانب
archive_command
یا
archive_library
و چه از سوی replication slotها، دربارهٔ این که جریان WAL تا کجا بایگانی شده است ندارد\&. با این حال توجه داشته باشید که اگر دریافت‌کننده نتواند همگام با دریافت داده‌های WAL پیش برود، یک replication slot فضای دیسک سرور را پر خواهد کرد\&.
.PP
در صورتی که مجوزهای دسترسی گروهی روی کلاستر مبدأ فعال باشد،
pg_receivewal
مجوزهای گروهی را روی فایل‌های WAL دریافتی حفظ خواهد کرد\&..SH "مثال‌ها (EXAMPLES)"
.PP
برای استریم کردن write\-ahead log از سرور
mydbserver
و ذخیره آن در دایرکتوری محلی
/usr/local/pgsql/archive:
.sp
.if n \{\
.RS 4
.\}
.nf
$ \fBpg_receivewal \-h mydbserver \-D /usr/local/pgsql/archive\fR
.fi
.if n \{\
.RE
.\}
.SH "همچنین ببینید (SEE ALSO)"
\fBpg_basebackup\fR(1)