PG_RECVLOGICAL(1) PostgreSQL 18.6 Documentation PG_RECVLOGICAL(1)

pg_recvlogical - مدیریت جریان‌های رمزگشایی منطقی PostgreSQL

pg_recvlogical [گزینه...]

pg_recvlogical شکاف‌های رونوشت‌برداری رمزگشایی منطقی را کنترل کرده و داده‌ها را از این شکاف‌های رونوشت‌برداری به صورت جریانی دریافت می‌کند.

این ابزار اتصالی در حالت رونوشت‌برداری ایجاد می‌کند، بنابراین مشمول همان محدودیت‌های pg_receivewal(1) به‌علاوهٔ محدودیت‌های رونوشت‌برداری منطقی است (فصل 47 را ببینید).

pg_recvlogical هیچ معادلی برای حالت‌های peek و get در رابط SQL رمزگشایی منطقی ندارد. این دستور تأییدیه‌های بازپخش داده‌ها را به صورت تنبل (lazy) هنگام دریافت و در زمان خروج تمیز ارسال می‌کند. برای بررسی داده‌های در انتظار در یک شکاف بدون مصرف کردن آن‌ها، از pg_logical_slot_peek_changes استفاده کنید.

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

هنگامی که pg_recvlogical سیگنال SIGHUP را دریافت می‌کند، فایل خروجی فعلی را بسته و فایل جدیدی را با استفاده از نام فایل تعیین‌شده توسط گزینهٔ --file باز می‌کند. این ویژگی اجازه می‌دهد تا با تغییر نام فایل فعلی و سپس ارسال سیگنال SIGHUP به pg_recvlogical، فایل خروجی را چرخش (rotate) دهید.

حداقل یکی از گزینه‌های زیر باید برای انتخاب یک عملیات مشخص شود:

--create-slot

یک شکاف رونوشت‌برداری منطقی جدید با نام مشخص‌شده توسط --slot، با استفاده از افزونه خروجی تعیین‌شده توسط --plugin، برای پایگاه داده تعیین‌شده توسط --dbname ایجاد می‌کند.

گزینه‌های --slot و --dbname برای این عملیات الزامی هستند.

گزینه‌های --enable-two-phase و --enable-failover را می‌توان همراه با --create-slot مشخص کرد.

--drop-slot

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

گزینهٔ --slot برای این عملیات الزامی است.

--start

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

گزینه‌های --slot، --dbname و --file برای این عملیات الزامی هستند.

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

اتصال باید به همان پایگاه داده‌ای برقرار شود که برای ایجاد شکاف استفاده شده است.

می‌توان --create-slot و --start را با هم مشخص کرد. --drop-slot نمی‌تواند با عملیات دیگری ترکیب شود.

گزینه‌های خط فرمان زیر مکان و قالب خروجی و سایر رفتارهای رونوشت‌برداری را کنترل می‌کنند:

-E lsn
--endpos=lsn

در حالت --start، هنگامی که دریافت به LSN مشخص‌شده برسد، رونوشت‌برداری را به طور خودکار متوقف کرده و با وضعیت خروج عادی 0 خارج می‌شود. اگر در حالتی غیر از --start مشخص شود، یک خطا ایجاد خواهد شد.

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

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

--enable-failover

همگام‌سازی شکاف با سرورهای آماده‌باش (standbys) را فعال می‌کند. این گزینه فقط همراه با --create-slot قابل تعیین است.

-f filename
--file=filename

داده‌های تراکنش دریافت‌شده و رمزگشایی‌شده را در این فایل می‌نویسد. از - برای خروجی استاندارد (stdout) استفاده کنید.

این پارامتر برای --start الزامی است.

-F interval_seconds
--fsync-interval=interval_seconds

مشخص می‌کند که pg_recvlogical هر چند وقت یک‌بار باید فراخوانی‌های fsync() را صادر کند تا از تخلیهٔ امن فایل خروجی روی دیسک اطمینان حاصل شود.

سرور گاهی اوقات از کلاینت درخواست می‌کند که یک تخلیه انجام داده و موقعیت تخلیه را به سرور گزارش دهد. این تنظیم افزون بر آن است تا عمل تخلیه با بسامد بیشتری انجام شود.

مشخص کردن بازهٔ زمانی 0 فراخوانی‌های fsync() را به‌طور کامل غیرفعال می‌کند، در حالی که همچنان پیشرفت را به سرور گزارش می‌دهد. در این حالت، در صورت خرابی و توقف ناگهانی (crash)، ممکن است داده‌ها از دست بروند.

-I lsn
--startpos=lsn

در حالت --start، رونوشت‌برداری را از LSN داده‌شده آغاز می‌کند. برای جزئیات مربوط به اثر این تنظیم، به مستندات فصل 47 و بخش 54.4 مراجعه کنید. در سایر حالت‌ها نادیده گرفته می‌شود.

--if-not-exists

هنگامی که --create-slot مشخص شده و شکافی با نام تعیین‌شده از قبل وجود دارد، خطایی صادر نمی‌کند. -n
--no-loop
هنگامی که اتصال به سرور قطع می‌شود، در یک حلقه برای اتصال مجدد تلاش نکنید، فقط خارج شوید.

-o name[=value]
--option=name[=value]

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

-P plugin
--plugin=plugin

هنگام ایجاد یک اسلات، از افزونهٔ خروجی رمزگشایی منطقی مشخص‌شده استفاده کنید. فصل 47 را ببینید. اگر اسلات از قبل وجود داشته باشد، این گزینه هیچ اثری ندارد.

-s interval_seconds
--status-interval=interval_seconds

این گزینه همان اثر گزینه‌ای با همین نام در pg_receivewal(1) را دارد. توضیحات آن بخش را ببینید.

-S slot_name
--slot=slot_name

در حالت --start، از اسلات همانندسازی منطقی موجود با نام slot_name استفاده می‌کند. در حالت --create-slot، اسلاتی با این نام ایجاد می‌کند. در حالت --drop-slot، اسلات با این نام را حذف می‌کند.

این پارامتر برای هر یک از این عملیات‌ها الزامی است.

-t
--enable-two-phase
--two-phase (منسوخ‌شده)

رمزگشایی تراکنش‌های آماده‌شده را فعال می‌کند. این گزینه فقط همراه با --create-slot قابل تعیین است.

-v
--verbose

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

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

-d dbname
--dbname=dbname

پایگاه‌داده‌ای که باید به آن متصل شد. برای آگاهی از معنای دقیق این مورد، شرح عملیات‌ها را ببینید. dbname می‌تواند یک رشتهٔ اتصال (connection string) باشد. در این صورت، پارامترهای رشتهٔ اتصال بر هر گزینهٔ خط فرمان ناسازگار برتری خواهند داشت.

این پارامتر برای --create-slot و --start الزامی است.

-h hostname-or-ip
--host=hostname-or-ip

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

-p port
--port=port

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

-U user
--username=user

نام کاربری برای اتصال. پیش‌فرض، نام کاربر فعلی سیستم‌عامل است.

-w
--no-password

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

-W
--password

برنامهٔ pg_recvlogical را وادار می‌کند تا پیش از اتصال به پایگاه‌داده، درخواست گذرواژه کند.

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

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

-V
--version

نسخهٔ pg_recvlogical را چاپ کرده و خارج می‌شود.

-?
--help

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

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

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

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

چنانچه مجوزهای گروهی در کلاستر مبدأ فعال باشند، pg_recvlogical مجوزهای گروهی را روی فایل‌های خروجی حفظ خواهد کرد.

برای مشاهده یک مثال به بخش 47.1 مراجعه کنید.

pg_receivewal(1)

2026 PostgreSQL 18.6