PG_CREATESUBSCRIBER(1) PostgreSQL 18.6 Documentation PG_CREATESUBSCRIBER(1)

pg_createsubscriber - تبدیل یک رپلیکای فیزیکی به یک رپلیکای منطقی جدید

pg_createsubscriber [گزینه‌ها...] {-d | --database}dbname {-D | --pgdata}datadir {-P | --publisher-server}connstr

دستور pg_createsubscriber یک رپلیکای منطقی جدید از روی یک سرور استندبای فیزیکی ایجاد می‌کند. تمامی جدول‌های موجود در پایگاه‌داده مشخص‌شده در پیکربندی رپلیکیشن منطقی گنجانده می‌شوند. برای هر پایگاه‌داده یک جفت شیء انتشار (publication) و اشتراک (subscription) ایجاد می‌شود. این ابزار باید روی سرور مقصد اجرا شود.

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

ابزار pg_createsubscriber سیستم‌های پایگاه‌داده بزرگ را هدف قرار می‌دهد، زیرا در راه‌اندازی رپلیکیشن منطقی، بخش عمده زمان صرف رونوشت اولیه داده‌ها می‌شود. علاوه بر این، پیامد این زمان طولانی صرف‌شده برای همگام‌سازی داده‌ها، معمولاً حجم بالایی از تغییرات است که باید اعمال شوند (تغییراتی که در طول رونوشت اولیه داده‌ها ایجاد شده‌اند)؛ این موضوع زمان در دسترس قرار گرفتن رپلیکای منطقی را باز هم افزایش می‌دهد. برای پایگاه‌های داده کوچک‌تر، توصیه می‌شود رپلیکیشن منطقی با همگام‌سازی اولیه داده‌ها راه‌اندازی شود. برای جزئیات بیشتر، گزینه copy_data در CREATE SUBSCRIPTION را ببینید.

دستور pg_createsubscriber آرگومان‌های خط فرمان زیر را می‌پذیرد:

-a
--all

به ازای هر پایگاه‌داده روی سرور مقصد یک اشتراک ایجاد می‌کند. پایگاه‌های داده الگو (template) و پایگاه‌های داده‌ای که اتصال را مجاز نمی‌دانند مستثنی هستند. برای پیدا کردن فهرست تمامی پایگاه‌های داده، با استفاده از نام پایگاه‌داده مشخص‌شده در رشته اتصال --publisher-server به سرور مبدأ متصل می‌شود؛ در صورت عدم تعیین، از پایگاه‌داده postgres استفاده خواهد شد، و اگر وجود نداشته باشد، از template1 استفاده می‌شود. در صورت تعیین این گزینه، نام‌های تولیدشده خودکار برای اشتراک‌ها، انتشارات و اسلات‌های رپلیکیشن استفاده می‌شوند. این گزینه را نمی‌توان همراه با گزینه‌های --database، --publication، --replication-slot یا --subscription به کار برد.

-d dbname
--database=dbname

نام پایگاه‌داده‌ای که باید در آن اشتراک ایجاد شود. با نوشتن چندین سوئیچ -d می‌توان چندین پایگاه‌داده را انتخاب کرد. این گزینه را نمی‌توان همراه با -a به کار برد. اگر گزینه -d ارائه نشود، نام پایگاه‌داده از گزینه -P گرفته خواهد شد. اگر نام پایگاه‌داده نه در گزینه -d و نه در گزینه -P مشخص نشده باشد، و گزینه -a نیز تعیین نشده باشد، خطا گزارش خواهد شد.

-D directory
--pgdata=directory

دایرکتوری مقصد که حاوی یک دایرکتوری کلاستر از رپلیکای فیزیکی است.

-n
--dry-run

تمام مراحل را به جز تغییر دادن واقعی دایرکتوری مقصد انجام می‌دهد.

-p port
--subscriber-port=port

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

-P connstr
--publisher-server=connstr

رشته اتصال به ناشر (publisher). برای جزئیات به بخش 32.1.1 مراجعه کنید.

-s dir
--socketdir=dir

دایرکتوری مورد استفاده برای سوکت‌های postmaster در سرور مقصد. پیش‌فرض، دایرکتوری جاری است.

-t seconds
--recovery-timeout=seconds

حداکثر زمان به ثانیه برای انتظار جهت پایان بازیابی (recovery). مقدار 0 آن را غیرفعال می‌کند. مقدار پیش‌فرض 0 است.

-T
--enable-two-phase

قابلیت تایید دوفازی (two_phase commit) را برای اشتراک فعال می‌کند. هنگامی که چندین پایگاه‌داده مشخص شده باشند، این گزینه به صورت یکنواخت برای تمام اشتراک‌های ایجادشده روی آن پایگاه‌های داده اعمال می‌شود. مقدار پیش‌فرض false است.

-U username
--subscriber-username=username

نام کاربری برای اتصال به عنوان آن در سرور مقصد. پیش‌فرض، نام کاربری فعلی سیستم‌عامل است.

-v
--verbose

حالت پرگویی را فعال می‌کند. این امر موجب می‌شود pg_createsubscriber پیام‌های پیشرفت و اطلاعات دقیق مربوط به هر مرحله را در خروجی خطای استاندارد بنویسد. تکرار این گزینه باعث نمایش پیام‌های بیشتر در سطح اشکال‌زدایی (debug) در خروجی خطای استاندارد می‌شود.

--clean=objtype

تمامی اشیاء از نوع مشخص‌شده را از پایگاه‌های داده معین در سرور مقصد حذف (drop) می‌کند.
•publications: انتشارات FOR ALL TABLES ایجادشده برای این مشترک همواره حذف می‌شوند؛ مشخص کردن این نوع شیء باعث می‌شود تمامی انتشارات دیگری نیز که از سرور مبدأ بازتکرار شده‌اند حذف شوند.

اشیاء انتخاب‌شده برای حذف به صورت جداگانه ثبت لاگ می‌شوند، از جمله در حین اجرای --dry-run. هیچ امکانی برای جلوگیری یا متوقف کردن حذف اشیاء انتخاب‌شده وجود ندارد، بنابراین تهیه نسخه پشتیبان از آن‌ها با استفاده از pg_dump را در نظر داشته باشید.

--config-file=filename

از فایل پیکربندی اصلی سرور مشخص‌شده برای دایرکتوری داده مقصد استفاده می‌کند. pg_createsubscriber در درون خود از دستور pg_ctl برای راه‌اندازی و توقف سرور مقصد استفاده می‌کند. این گزینه به شما اجازه می‌دهد در صورتی که فایل پیکربندی واقعی postgresql.conf در خارج از دایرکتوری داده قرار دارد، آن را مشخص کنید.

--publication=name

نام انتشار برای راه‌اندازی رپلیکیشن منطقی. با نوشتن چندین سوئیچ --publication می‌توان چندین انتشار را مشخص کرد. تعداد نام‌های انتشار باید با تعداد پایگاه‌های داده مشخص‌شده مطابقت داشته باشد، در غیر این صورت خطا گزارش می‌شود. ترتیب چندین سوئیچ نام انتشار باید با ترتیب سوئیچ‌های پایگاه‌داده مطابقت داشته باشد. اگر این گزینه مشخص نشود، نامی تولیدشده به انتشار اختصاص می‌یابد. این گزینه را نمی‌توان همراه با --all استفاده کرد.

--replication-slot=name

نام اسلات رپلیکیشن برای راه‌اندازی رپلیکیشن منطقی. با نوشتن چندین سوئیچ --replication-slot می‌توان چندین اسلات رپلیکیشن را تعیین کرد. تعداد نام‌های اسلات رپلیکیشن باید با تعداد پایگاه‌های داده تعیین‌شده مطابقت داشته باشد، در غیر این صورت خطا گزارش خواهد شد. ترتیب چندین سوئیچ نام اسلات رپلیکیشن باید با ترتیب سوئیچ‌های پایگاه‌داده همخوانی داشته باشد. اگر این گزینه مشخص نشود، نام اشتراک به نام اسلات رپلیکیشن اختصاص داده می‌شود. این گزینه را نمی‌توان همراه با --all به کار برد.

--subscription=name

نام اشتراک برای راه‌اندازی رپلیکیشن منطقی. با نوشتن چندین سوئیچ --subscription می‌توان چندین اشتراک را تعیین نمود. تعداد نام‌های اشتراک باید با تعداد پایگاه‌های داده مشخص‌شده مطابقت داشته باشد، در غیر این صورت خطا گزارش می‌شود. ترتیب چندین سوئیچ نام اشتراک باید با ترتیب سوئیچ‌های پایگاه‌داده مطابقت داشته باشد. اگر این گزینه مشخص نشود، یک نام تولیدشده به نام اشتراک اختصاص می‌یابد. این گزینه را نمی‌توان همراه با --all به کار برد.

-V
--version

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

-?
--help

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

برای اینکه pg_createsubscriber سرور مقصد را به یک رپلیکای منطقی تبدیل کند، پیش‌نیازهایی وجود دارد. اگر این پیش‌نیازها برآورده نشوند، خطا گزارش خواهد شد. سرورهای مبدأ و مقصد باید دارای نسخه اصلی یکسانی با pg_createsubscriber باشند. دایرکتوری داده مقصد داده‌شده باید دارای شناسه سیستم یکسانی با دایرکتوری داده مبدأ باشد. کاربر پایگاه‌داده مشخص‌شده برای دایرکتوری داده مقصد باید دسترسی‌های لازم برای ایجاد اشتراک‌ها و استفاده از pg_replication_origin_advance() را داشته باشد.

سرور مقصد باید به عنوان یک استندبای فیزیکی مورد استفاده قرار گیرد. در سرور مقصد باید max_active_replication_origins و max_logical_replication_workers روی مقداری بزرگ‌تر یا مساوی با تعداد پایگاه‌های داده مشخص‌شده پیکربندی شده باشند. در سرور مقصد باید max_worker_processes روی مقداری بزرگ‌تر از تعداد پایگاه‌های داده مشخص‌شده پیکربندی شده باشد. سرور مقصد باید اتصالات محلی را بپذیرد. اگر قصد استفاده از سوئیچ --enable-two-phase را دارید، باید max_prepared_transactions را نیز به شکل مناسب تنظیم کنید.

سرور مبدأ باید اتصالات از جانب سرور مقصد را بپذیرد. سرور مبدأ نباید در وضعیت بازیابی باشد. در سرور مبدأ باید wal_level روی logical تنظیم شده باشد. سرور مبدأ باید max_replication_slots را روی مقداری بزرگ‌تر یا مساوی با تعداد پایگاه‌های داده مشخص‌شده به‌علاوه اسلات‌های رپلیکیشن موجود پیکربندی کرده باشد. سرور مبدأ باید max_wal_senders را روی مقداری بزرگ‌تر یا مساوی با تعداد پایگاه‌های داده مشخص‌شده و فرآیندهای فرستنده WAL موجود تنظیم کرده باشد.

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

دستور pg_createsubscriber معمولاً در طول تغییر و تبدیل، سرور مقصد را با تنظیمات اتصال متفاوتی راه‌اندازی می‌کند. بنابراین، اتصالات به سرور مقصد باید ناموفق باشند.

از آنجا که دستورات DDL توسط رپلیکیشن منطقی بازتکرار نمی‌شوند، در حین اجرای pg_createsubscriber از اجرای دستورات DDL که شمای پایگاه‌داده را تغییر می‌دهند خودداری کنید. اگر سرور مقصد قبلاً به رپلیکای منطقی تبدیل شده باشد، دستورات DDL ممکن است بازتکرار نشوند که می‌تواند موجب بروز خطا شود.

اگر pg_createsubscriber در حین پردازش با شکست مواجه شود، اشیاء (انتشارات، اسلات‌های رپلیکیشن) ایجادشده روی سرور مبدأ حذف می‌شوند. اگر سرور مقصد نتواند به سرور مبدأ متصل شود، ممکن است این حذف با شکست مواجه گردد. در چنین شرایطی، یک پیام هشدار اشیاء باقی‌مانده را اطلاع خواهد داد. اگر سرور مقصد در حال اجرا باشد، متوقف خواهد شد.

اگر رپلیکیشن از primary_slot_name استفاده می‌کند، پس از راه‌اندازی رپلیکیشن منطقی از روی سرور مبدأ حذف خواهد شد.

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

مگر اینکه سوئیچ --enable-two-phase مشخص شده باشد، pg_createsubscriber رپلیکیشن منطقی را با غیرفعال بودن تایید دوفازی راه‌اندازی می‌کند. این بدان معناست که هر تراکنش آماده‌شده (prepared transaction) در زمان COMMIT PREPARED و بدون آماده‌سازی قبلی بازتکرار خواهد شد. پس از اتمام راه‌اندازی، می‌توانید به صورت دستی اشتراک(ها) را حذف کرده و با فعال بودن گزینه two_phase دوباره ایجاد کنید.

دستور pg_createsubscriber شناسه سیستم را با استفاده از pg_resetwal تغییر می‌دهد. این کار از شرایطی که در آن سرور مقصد ممکن است از فایل‌های WAL سرور مبدأ استفاده کند جلوگیری می‌نماید. اگر سرور مقصد خود دارای استندبای باشد، رپلیکیشن آن مختل خواهد شد و باید یک استندبای تازه ایجاد شود.

در صورتی که فایل‌های WAL مورد نیاز وجود نداشته باشند، ممکن است شکست در رپلیکیشن رخ دهد. برای جلوگیری از این موضوع، سرور مبدأ باید max_slot_wal_keep_size را روی -1 تنظیم کند تا اطمینان حاصل شود که فایل‌های WAL مورد نیاز پیش از موعد حذف نمی‌شوند.

ایده اصلی داشتن یک نقطه شروع رپلیکیشن از سرور مبدأ و راه‌اندازی رپلیکیشن منطقی برای شروع از این نقطه است:

1.راه‌اندازی سرور مقصد با گزینه‌های خط فرمان مشخص‌شده. اگر سرور مقصد در حال حاضر در حال اجرا باشد، pg_createsubscriber با یک خطا متوقف خواهد شد.
2.بررسی اینکه آیا سرور مقصد می‌تواند تبدیل شود یا خیر. همچنین چند بررسی روی سرور مبدأ انجام می‌شود. اگر هر یک از پیش‌نیازها برآورده نشوند، pg_createsubscriber با یک خطا متوقف خواهد شد.
3.ایجاد یک انتشار و یک اسلات رپلیکیشن برای هر پایگاه‌داده مشخص‌شده روی سرور مبدأ. هر انتشار با استفاده از FOR ALL TABLES ایجاد می‌شود. اگر گزینه --publication مشخص نشده باشد، انتشار دارای الگوی نام‌گذاری زیر خواهد بود: “pg_createsubscriber_%u_%x” (پارامترها: شناسه پایگاه‌داده oid، عدد تصادفی int). اگر گزینه --replication-slot مشخص نشده باشد، اسلات رپلیکیشن دارای الگوی نام‌گذاری زیر خواهد بود: “pg_createsubscriber_%u_%x” (پارامترها: شناسه پایگاه‌داده oid، عدد تصادفی int). این اسلات‌های رپلیکیشن در مرحله بعدی توسط اشتراک‌ها مورد استفاده قرار خواهند گرفت. آخرین LSN اسلات رپلیکیشن به عنوان نقطه توقف در پارامتر recovery_target_lsn و توسط اشتراک‌ها به عنوان نقطه شروع رپلیکیشن استفاده می‌شود. این کار تضمین می‌کند که هیچ تراکنشی از دست نخواهد رفت.
4.نوشتن پارامترهای بازیابی در دایرکتوری داده مقصد و راه‌اندازی مجدد سرور مقصد. این عمل، یک LSN (در recovery_target_lsn) از موقعیت گزارش ثبت وقایع قبل از نوشتن (WAL) را مشخص می‌کند که بازیابی تا آن نقطه پیش خواهد رفت. همچنین promote را به عنوان اقدامی که سرور پس از رسیدن به هدف بازیابی باید انجام دهد مشخص می‌کند. پارامترهای بازیابی دیگری نیز اضافه می‌شوند تا از رفتارهای غیرمنتظره در حین فرآیند بازیابی جلوگیری شود، مانند پایان بازیابی به محض رسیدن به وضعیتی پایدار (WAL باید تا موقعیت شروع رپلیکیشن اعمال شود) و اهداف بازیابی چندگانه که می‌توانند باعث شکست شوند. این مرحله به محض اینکه سرور از حالت استندبای خارج شده و تراکنش‌های خواندن/نوشتن را بپذیرد پایان می‌یابد. اگر گزینه --recovery-timeout تنظیم شده باشد، در صورتی که بازیابی تا مدت زمان تعیین‌شده به ثانیه به پایان نرسد، pg_createsubscriber متوقف می‌شود.
5.ایجاد یک اشتراک برای هر پایگاه‌داده مشخص‌شده روی سرور مقصد. اگر گزینه --subscription مشخص نشده باشد، اشتراک دارای الگوی نام‌گذاری زیر خواهد بود: “pg_createsubscriber_%u_%x” (پارامترها: شناسه پایگاه‌داده oid، عدد تصادفی int). این عمل داده‌های موجود را از سرور مبدأ رونوشت نمی‌کند. اسلات رپلیکیشن نیز ایجاد نمی‌کند. در عوض، از اسلات رپلیکیشنی که در مرحله قبلی ایجاد شده بود استفاده می‌کند. اشتراک ایجاد می‌شود اما هنوز فعال نیست. دلیل آن این است که پیشرفت رپلیکیشن باید قبل از شروع رپلیکیشن، روی نقطه شروع رپلیکیشن تنظیم شود.
6.حذف انتشارات روی سرور مقصد که به دلیل ایجاد شدن قبل از موقعیت شروع رپلیکیشن، بازتکرار شده بودند. این انتشارات روی مشترک هیچ کاربردی ندارند.
7.تنظیم پیشرفت رپلیکیشن روی نقطه شروع رپلیکیشن برای هر اشتراک. هنگامی که سرور مقصد فرآیند بازیابی را آغاز می‌کند، خود را به نقطه شروع رپلیکیشن می‌رساند. این دقیقاً همان LSN است که باید به عنوان موقعیت رپلیکیشن اولیه برای هر اشتراک استفاده شود. نام مبدأ رپلیکیشن با توجه به ایجاد اشتراک به دست می‌آید. نام مبدأ رپلیکیشن و نقطه شروع رپلیکیشن در pg_replication_origin_advance() برای تنظیم موقعیت اولیه رپلیکیشن استفاده می‌شوند.
8.فعال کردن اشتراک برای هر پایگاه‌داده مشخص‌شده روی سرور مقصد. اشتراک اعمال تراکنش‌ها را از نقطه شروع رپلیکیشن آغاز می‌کند.
9.اگر سرور استندبای از primary_slot_name استفاده می‌کرد، از این پس کاربردی ندارد، بنابراین حذف می‌شود.
10.اگر سرور استندبای حاوی اسلات‌های رپلیکیشن failover باشد، دیگر امکان همگام‌سازی آن‌ها وجود ندارد، بنابراین حذف می‌شوند.
11.به‌روزرسانی شناسه سیستم در سرور مقصد. دستور pg_resetwal(1) برای تغییر دادن شناسه سیستم اجرا می‌شود. سرور مقصد به عنوان یکی از الزامات pg_resetwal متوقف می‌گردد.

برای ایجاد یک رپلیکای منطقی برای پایگاه‌های داده hr و finance از روی یک رپلیکای فیزیکی در foo:

$ pg_createsubscriber -D /usr/local/pgsql/data -P "host=foo" -d hr -d finance

pg_basebackup(1)

2026 PostgreSQL 18.6