PG_BASEBACKUP(1) PostgreSQL 18.6 Documentation PG_BASEBACKUP(1)

pg_basebackup - تهیه نسخه پشتیبان پایه از یک کلاستر PostgreSQL

pg_basebackup [گزینه...]

pg_basebackup برای تهیه یک نسخه پشتیبان پایه (base backup) از یک کلاستر پایگاه‌داده در حال اجرای PostgreSQL به کار می‌رود. پشتیبان‌گیری بدون تأثیر بر سایر کلاینت‌های پایگاه‌داده انجام می‌شود و می‌تواند هم برای بازیابی در نقطه زمانی مشخص (point-in-time recovery؛ به بخش 25.3 مراجعه کنید) و هم به عنوان نقطه شروعی برای سرور آماده‌به‌کار (standby) مبتنی بر log-shipping یا streaming-replication استفاده شود (به بخش 26.2 مراجعه کنید).

pg_basebackup می‌تواند یک نسخه پشتیبان پایه کامل (full) یا افزایشی (incremental) از پایگاه‌داده تهیه کند. هنگام استفاده برای تهیه پشتیبان کامل، یک کپی دقیق از فایل‌های کلاستر پایگاه‌داده ایجاد می‌کند. هنگام تهیه پشتیبان افزایشی، ممکن است برخی از فایل‌هایی که در نسخه کامل قرار می‌گرفتند با نسخه‌های افزایشی همان فایل‌ها جایگزین شوند، که تنها شامل بلوک‌هایی هستند که از زمان پشتیبان مرجع تغییر کرده‌اند. یک پشتیبان افزایشی را نمی‌توان مستقیماً استفاده کرد؛ بلکه ابتدا باید از pg_combinebackup(1) برای ترکیب آن با پشتیبان‌های قبلی که به آن‌ها وابسته است استفاده شود. برای اطلاعات بیشتر درباره پشتیبان‌های افزایشی به بخش 25.3.3 و برای مراحل بازیابی از یک نسخه پشتیبان به بخش 25.3.5 مراجعه کنید.

در هر حالتی، pg_basebackup اطمینان حاصل می‌کند که سرور به‌طور خودکار در حالت پشتیبان‌گیری قرار گرفته و از آن خارج می‌شود. پشتیبان‌گیری‌ها همواره از کل کلاستر پایگاه‌داده گرفته می‌شوند؛ امکان تهیه نسخه پشتیبان از پایگاه‌های داده یا اشیاء پایگاه‌داده به‌صورت مجزا وجود ندارد. برای پشتیبان‌گیری‌های انتخابی، باید از ابزار دیگری مانند pg_dump(1) استفاده شود.

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

امکان اجرای هم‌زمان چند نمونه از pg_basebackup وجود دارد، اما از نظر کارایی معمولاً بهتر است تنها یک پشتیبان تهیه شده و سپس نتیجه آن کپی شود.

pg_basebackup می‌تواند نه تنها از یک سرور اصلی (primary)، بلکه از یک سرور آماده‌به‌کار (standby) نیز نسخه پشتیبان پایه تهیه کند. برای تهیه پشتیبان از یک سرور standby، آن را به گونه‌ای پیکربندی کنید که بتواند اتصال‌های همانندسازی را بپذیرد (یعنی max_wal_senders و hot_standby را تنظیم کرده و فایل pg_hba.conf آن را به درستی پیکربندی کنید). همچنین نیاز است که full_page_writes را روی سرور primary فعال نمایید.

توجه داشته باشید که تهیه نسخه پشتیبان از یک سرور standby با محدودیت‌هایی همراه است:

•فایل تاریخچه پشتیبان‌گیری (backup history file) در کلاستر پایگاه‌داده‌ای که از آن پشتیبان گرفته شده ایجاد نمی‌شود.
•pg_basebackup نمی‌تواند سرور standby را مجبور کند که در پایان پشتیبان‌گیری به یک فایل WAL جدید سوییچ کند. هنگامی که از -X none استفاده می‌کنید، اگر فعالیت نوشتن در سرور primary کم باشد، ممکن است pg_basebackup مجبور شود مدت زمان زیادی منتظر بماند تا آخرین فایل WAL مورد نیاز برای پشتیبان‌گیری سوییچ و بایگانی شود. در این حالت، اجرای pg_switch_wal روی سرور primary به منظور ایجاد یک سوییچ فوری در فایل WAL می‌تواند مفید باشد.
•اگر سرور standby در حین پشتیبان‌گیری به سرور primary ارتقا یابد، عملیات پشتیبان‌گیری با شکست مواجه می‌شود.
•تمام رکوردهای WAL مورد نیاز برای پشتیبان‌گیری باید حاوی مقادیر کافی full-page writes باشند، که این امر نیازمند فعال بودن full_page_writes روی سرور primary است.

هر زمان که pg_basebackup در حال گرفتن یک پشتیبان پایه باشد، نمای pg_stat_progress_basebackup در سرور، پیشرفت پشتیبان‌گیری را گزارش خواهد داد. برای جزئیات به بخش 27.4.6 مراجعه کنید..SH "گزینه‌ها (OPTIONS)"

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

-D directory
--pgdata=directory

دایرکتوری مقصد را برای نوشتن خروجی مشخص می‌کند. اگر این دایرکتوری وجود نداشته باشد، pg_basebackup آن را (و هر دایرکتوری والد ناموجود را) ایجاد خواهد کرد. اگر از قبل وجود داشته باشد، باید خالی باشد.

هنگامی که پشتیبان در قالب tar است، دایرکتوری مقصد را می‌توان به عنوان - (خط تیره یا dash) مشخص کرد، که باعث می‌شود فایل tar در stdout نوشته شود.

این گزینه الزامی است.

-F format
--format=format

قالب خروجی را انتخاب می‌کند. format می‌تواند یکی از موارد زیر باشد:

p
plain

خروجی را به صورت فایل‌های معمولی (plain)، با ساختاری مشابه دایرکتوری داده و tablespaceهای سرور مبدا می‌نویسد. هنگامی که خوشه فاقد tablespaceهای اضافی است، کل پایگاه‌داده در دایرکتوری مقصد قرار می‌گیرد. اگر خوشه شامل tablespaceهای اضافی باشد، دایرکتوری دادهٔ اصلی در دایرکتوری مقصد قرار خواهد گرفت، اما تمام tablespaceهای دیگر در همان مسیر مطلقی قرار می‌گیرند که در سرور مبدا دارند. (برای تغییر این رفتار به --tablespace-mapping مراجعه کنید.)

این، قالب پیش‌فرض است.

t
tar

خروجی را به صورت فایل‌های tar در دایرکتوری مقصد می‌نویسد. محتویات دایرکتوری دادهٔ اصلی در فایلی به نام base.tar نوشته می‌شود، و هر tablespace دیگر در یک فایل tar جداگانه که بر اساس OID آن tablespace نام‌گذاری شده، نوشته خواهد شد.

اگر دایرکتوری مقصد به عنوان - (خط تیره) مشخص شود، محتویات tar در خروجی استاندارد نوشته می‌شود که برای هدایت (pipe) به عنوان مثال به gzip مناسب است. این حالت فقط در صورتی مجاز است که خوشه فاقد tablespaceهای اضافی بوده و از استریم WAL استفاده نشود.

-i old_manifest_file
--incremental=old_manifest_file

یک پشتیبان‌گیری افزایشی (incremental backup) انجام می‌دهد. مانیفست پشتیبان برای پشتیبان مرجع باید ارائه شود، و در سرور بارگذاری خواهد شد؛ سرور نیز با ارسال پشتیبان افزایشی درخواست‌شده پاسخ می‌دهد.

-R
--write-recovery-conf

یک فایل standby.signal

ایجاد کرده و تنظیمات اتصال را به فایل postgresql.auto.conf در دایرکتوری مقصد (یا درون فایل آرشیو پایه هنگام استفاده از قالب tar) اضافه می‌کند. این کار راه‌اندازی سرور standby را با استفاده از نتایج پشتیبان‌گیری آسان‌تر می‌کند.

فایل postgresql.auto.conf تنظیمات اتصال و، در صورت تعیین، اسلات رونوشت (replication slot) مورد استفاده توسط pg_basebackup را ثبت خواهد کرد تا رونوشت جریانی (streaming replication) و همگام‌سازی اسلات رونوشت منطقی (logical replication slot synchronization) بعداً از همان تنظیمات استفاده کنند. نام پایگاه داده (dbname) تنها در صورتی ثبت می‌شود که صراحتاً در رشته اتصال یا متغیر محیطی مشخص شده باشد.

-t target
--target=target

به سرور اعلام می‌کند که پشتیبان پایه را در کجا قرار دهد. مقصد پیش‌فرض، client است که مشخص می‌کند پشتیبان باید به ماشینی که pg_basebackup روی آن در حال اجراست فرستاده شود. اگر مقصد به جای آن روی server:/some/path تنظیم شود، پشتیبان روی ماشینی که سرور در حال اجراست در دایرکتوری /some/path ذخیره خواهد شد. ذخیره کردن پشتیبان روی سرور نیازمند امتیازات مدیر سیستم (superuser) یا داشتن امتیازات نقش pg_write_server_files است. اگر مقصد روی blackhole تنظیم شود، محتویات دور ریخته شده و در هیچ‌کجا ذخیره نمی‌شوند. این حالت فقط باید برای مقاصد آزمایشی استفاده شود، چرا که در پایان یک پشتیبان واقعی نخواهید داشت.

از آنجا که استریم WAL به جای سرور توسط pg_basebackup پیاده‌سازی می‌شود، این گزینه نمی‌تواند همراه با -Xstream استفاده شود. از آنجا که این مورد پیش‌فرض است، هنگام مشخص کردن این گزینه باید یکی از موارد -Xfetch یا -Xnone را نیز تعیین کنید.

-T olddir=newdir
--tablespace-mapping=olddir=newdir

در طول پشتیبان‌گیری، tablespace موجود در دایرکتوری olddir را به newdir منتقل می‌کند. برای کارآمد بودن، olddir باید دقیقاً با مسیر مشخص‌شدهٔ tablespace مطابق با تعریف آن در سرور مبدا مطابقت داشته باشد. (اما اگر در سرور مبدا هیچ tablespaceای در olddir وجود نداشته باشد، خطا نیست.) در عین حال، newdir دایرکتوری‌ای در فایل‌سیستم میزبان دریافت‌کننده است. همانند دایرکتوری مقصد اصلی، نیازی نیست newdir از قبل وجود داشته باشد، اما در صورت وجود باید خالی باشد. هر دو مسیر olddir و newdir باید مسیرهای مطلق باشند. اگر هر یک از مسیرها باید حاوی علامت مساوی (=) باشد، قبل از آن یک بک‌اسلش قرار دهید. این گزینه می‌تواند چندین بار برای چندین tablespace مشخص شود.

اگر یک tablespace به این شیوه جابه‌جا شود، پیوندهای نمادین درون دایرکتوری دادهٔ اصلی به‌روزرسانی می‌شوند تا به مکان جدید اشاره کنند. بنابراین، دایرکتوری دادهٔ جدید با تمام tablespaceها در مکان‌های به‌روزرسانی‌شده، آماده استفاده برای یک نمونهٔ سرور جدید است.

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

--waldir=waldir

دایرکتوری مقصد را برای نوشتن فایل‌های WAL (ثبت وقایع پیش از نوشتن یا write-ahead log) تعیین می‌کند. به طور پیش‌فرض، فایل‌های WAL در زیردایرکتوری pg_wal از دایرکتوری مقصد قرار می‌گیرند، اما از این گزینه می‌توان برای قرار دادن آنها در مکانی دیگر استفاده کرد. waldir باید یک مسیر مطلق باشد. مانند دایرکتوری مقصد اصلی، نیازی نیست waldir از قبل وجود داشته باشد، اما در صورت وجود باید خالی باشد. این گزینه فقط زمانی قابل تعیین است که پشتیبان در قالب plain باشد.

-X method
--wal-method=method

فایل‌های لازم WAL (ثبت وقایع پیش از نوشتن یا write-ahead log) را در پشتیبان می‌گنجاند. این شامل تمام لاگ‌های پیش از نوشتن تولید شده در حین پشتیبان‌گیری می‌شود. مگر اینکه روش none مشخص شده باشد، راه‌اندازی postmaster در دایرکتوری مقصد بدون نیاز به مراجعه به آرشیو WAL امکان‌پذیر خواهد بود و بدین ترتیب، خروجی به یک نسخه پشتیبان کاملاً مستقل تبدیل می‌شود.

روش‌های (method) زیر برای جمع‌آوری لاگ‌های پیش از نوشتن پشتیبانی می‌شوند:

n
none

لاگ‌های پیش از نوشتن را در پشتیبان قرار نمی‌دهد.

f
fetch

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

هنگام استفاده از قالب tar، فایل‌های لاگ پیش از نوشتن در فایل base.tar گنجانده خواهند شد.

s
stream

داده‌های لاگ پیش از نوشتن را هم‌زمان با تهیه نسخه پشتیبان، به صورت جریانی (stream) منتقل می‌کند. این روش یک اتصال دوم به سرور باز کرده و هم‌زمان با اجرای پشتیبان‌گیری، لاگ پیش از نوشتن را به طور موازی ارسال می‌کند. بنابراین، به دو اتصال رونوشت نیاز خواهد داشت و نه فقط یکی. تا زمانی که کلاینت بتواند همگام با داده‌های لاگ پیش از نوشتن پیش برود، استفاده از این روش نیازی به ذخیره لاگ‌های اضافی پیش از نوشتن در سرور مبدا ندارد..sp هنگامی که قالب tar استفاده می‌شود، فایل‌های write-ahead log در فایلی جداگانه به نام pg_wal.tar نوشته خواهند شد (اگر نگارش سرور قدیمی‌تر از 10 باشد، نام فایل pg_xlog.tar خواهد بود).

این مقدار پیش‌فرض است.

-z
--gzip

فشرده‌سازی gzip خروجی فایل tar را با سطح فشرده‌سازی پیش‌فرض فعال می‌کند. فشرده‌سازی تنها هنگام استفاده از قالب tar در دسترس است و پسوند .gz به‌طور خودکار به تمام نام‌های فایل tar اضافه خواهد شد.

-Z level
-Z [{client|server}-]method[:detail]
--compress=level
--compress=[{client|server}-]method[:detail]

فشرده‌سازی نسخه پشتیبان را درخواست می‌کند. اگر client یا server گنجانده شده باشد، مشخص می‌کند که فشرده‌سازی در کجا باید انجام شود. فشرده‌سازی روی سرور پهنای باند انتقال را کاهش می‌دهد، اما مصرف CPU سرور را افزایش خواهد داد. مقدار پیش‌فرض client است مگر زمانی که --target استفاده شود. در آن حالت، نسخه پشتیبان به کلاینت فرستاده نمی‌شود، بنابراین تنها فشرده‌سازی سرور معقول است. هنگامی که -Xstream، که حالت پیش‌فرض است، استفاده می‌شود، فشرده‌سازی سمت سرور بر روی WAL اعمال نخواهد شد. برای فشرده‌سازی WAL، از فشرده‌سازی سمت کلاینت استفاده کنید یا -Xfetch را مشخص نمایید.

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

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

هنگامی که قالب tar همراه با gzip، lz4 یا zstd استفاده شود، پسوند .gz، .lz4 یا .zst به‌ترتیب به‌طور خودکار به تمام نام‌های فایل tar افزوده خواهد شد. هنگامی که قالب plain استفاده می‌شود، فشرده‌سازی سمت کلاینت نمی‌تواند مشخص شود، اما همچنان امکان درخواست فشرده‌سازی سمت سرور وجود دارد. اگر این کار انجام شود، سرور نسخه پشتیبان را برای ارسال فشرده کرده و کلاینت آن را از فشردگی خارج و استخراج می‌کند.

هنگامی که این گزینه در ترکیب با -Xstream استفاده شود، در صورتی که فشرده‌سازی gzip سمت کلاینت انتخاب شده باشد، pg_wal.tar با استفاده از gzip فشرده خواهد شد، اما اگر هر الگوریتم فشرده‌سازی دیگری انتخاب شده باشد، یا فشرده‌سازی سمت سرور انتخاب گردد، فشرده نخواهد شد.

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

-c {fast|spread}
--checkpoint={fast|spread}

حالت checkpoint را روی fast (فوری) یا spread (پیش‌فرض) تنظیم می‌کند (بخش 25.3.4 را ببینید).

-C
--create-slot

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

-l label
--label=label

برچسب نسخه پشتیبان را تنظیم می‌کند. اگر مقداری مشخص نشود، مقدار پیش‌فرض “pg_basebackup base backup” استفاده خواهد شد.

-n
--no-clean

به‌طور پیش‌فرض، هنگامی که pg_basebackup با خطایی متوقف می‌شود، تمام دایرکتوری‌هایی را که ممکن است پیش از پی بردن به ناتوانی در اتمام کار ایجاد کرده باشد حذف می‌کند (برای نمونه، دایرکتوری مقصد و دایرکتوری write-ahead log). این گزینه مانع از پاک‌سازی می‌شود و بنابراین برای اشکال‌زدایی مفید است.

توجه داشته باشید که دایرکتوری‌های tablespace در هیچ‌یک از دو حالت پاک‌سازی نمی‌شوند.

-N
--no-sync

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

-P
--progress

گزارش پیشرفت را فعال می‌کند. روشن کردن این گزینه گزارش پیشرفتی تقریبی را در حین پشتیبان‌گیری ارائه می‌دهد. از آنجا که پایگاه‌داده ممکن است در حین پشتیبان‌گیری تغییر کند، این تنها یک تقریب است و ممکن است دقیقاً در 100% به پایان نرسد. به‌ویژه، هنگامی که لاگ WAL در نسخه پشتیبان گنجانده شده باشد، مقدار کل داده‌ها را نمی‌توان از قبل برآورد کرد، و در این حالت به محض اینکه داده‌ها از برآورد کل بدون WAL فراتر رود، اندازه تخمینی مقصد افزایش می‌یابد.

-r rate
--max-rate=rate

حداکثر نرخ انتقالی را تنظیم می‌کند که با آن داده‌ها از سرور مبدأ گردآوری می‌شوند. این کار می‌تواند برای محدود کردن تأثیر pg_basebackup بر روی سرور مفید باشد. مقادیر بر حسب کیلوبایت بر ثانیه هستند. از پسوند M برای نشان دادن مگابایت بر ثانیه استفاده کنید. پسوند k نیز پذیرفته می‌شود و هیچ تأثیری ندارد. مقادیر معتبر بین 32 کیلوبایت بر ثانیه و 1024 مگابایت بر ثانیه هستند.

این گزینه همیشه بر انتقال دایرکتوری داده تأثیر می‌گذارد. انتقال فایل‌های WAL تنها در صورتی تحت تأثیر قرار می‌گیرد که روش گردآوری fetch باشد.

-S slotname
--slot=slotname

این گزینه تنها همراه با -X stream می‌تواند استفاده شود. این گزینه باعث می‌شود که جریان‌سازی WAL از replication slot مشخص‌شده استفاده کند. اگر قرار است نسخه پشتیبان پایه به‌عنوان یک آماده‌به‌کار (standby) برای همانندسازی جریانی (streaming-replication) با استفاده از یک replication slot استفاده شود، آن standby باید از همان نام replication slot به‌عنوان primary_slot_name استفاده کند. این کار تضمین می‌کند که سرور اصلی هیچ‌کدام از داده‌های ضروری WAL را در فاصله زمانی میان پایان پشتیبان‌گیری پایه و آغاز streaming replication در standby جدید حذف نکند.

replication slot مشخص‌شده باید از قبل وجود داشته باشد مگر آنکه گزینه -C نیز استفاده شده باشد.

اگر این گزینه مشخص نشود و سرور از replication slotهای موقت پشتیبانی کند (نگارش 10 و جدیدتر)، آن‌گاه یک replication slot موقت به‌طور خودکار برای استریم WAL استفاده می‌شود.

--sync-method=method

هنگامی که روی fsync، که حالت پیش‌فرض است، تنظیم شود، pg_basebackup به‌طور بازگشتی تمام فایل‌های موجود در دایرکتوری پشتیبان را باز و همگام‌سازی خواهد کرد. هنگامی که قالب plain استفاده می‌شود، جستجو برای فایل‌ها از پیوندهای نمادین برای دایرکتوری WAL و هر tablespace پیکربندی‌شده پیروی خواهد کرد.

در لینوکس، می‌توان به‌جای آن از syncfs استفاده کرد تا از سیستم‌عامل خواسته شود کل سیستم‌فایلی را که شامل دایرکتوری پشتیبان است همگام‌سازی کند. زمانی که قالب plain استفاده شود، pg_basebackup همچنین سیستم‌فایل‌هایی را که حاوی فایل‌های WAL و هر tablespace هستند همگام‌سازی می‌کند. برای اطلاعات درباره نکاتی که هنگام استفاده از syncfs باید به آن‌ها توجه داشت، recovery_init_sync_method را ببینید.

این گزینه هنگامی که --no-sync استفاده شود، هیچ تأثیری ندارد. -v
--verbose

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

--manifest-checksums=algorithm

الگوریتم مجموع مقابله‌ای (checksum) را مشخص می‌کند که باید برای هر فایل موجود در مانیفست نسخهٔ پشتیبان اعمال شود. در حال حاضر، الگوریتم‌های موجود عبارتند از NONE، CRC32C، SHA224، SHA256، SHA384 و SHA512. مقدار پیش‌فرض CRC32C است.

اگر NONE انتخاب شود، مانیفست نسخهٔ پشتیبان شامل هیچ مجموع مقابله‌ای نخواهد بود. در غیر این صورت، با استفاده از الگوریتم مشخص‌شده شامل مجموع مقابله‌ای هر فایل در نسخهٔ پشتیبان خواهد بود. علاوه بر این، مانیفست همیشه شامل یک مجموع مقابله‌ای SHA256 از محتویات خود خواهد بود. الگوریتم‌های SHA به‌طور قابل توجهی نسبت به CRC32C بار پردازشی بیشتری روی CPU دارند، بنابراین انتخاب یکی از آن‌ها ممکن است زمان مورد نیاز برای تکمیل نسخهٔ پشتیبان را افزایش دهد.

استفاده از یک تابع درهم‌سازی SHA یک خلاصهٔ امن از نظر رمزنگاری از هر فایل برای کاربرانی فراهم می‌کند که مایلند اطمینان یابند نسخهٔ پشتیبان دستکاری نشده است، در حالی که الگوریتم CRC-32C یک مجموع مقابله‌ای فراهم می‌آورد که محاسبهٔ آن بسیار سریع‌تر است؛ این الگوریتم برای کشف خطاهای ناشی از تغییرات تصادفی مناسب است اما در برابر تغییرات مخرب مقاوم نیست. توجه داشته باشید که برای مفید بودن در برابر مهاجمی که به نسخهٔ پشتیبان دسترسی دارد، مانیفست نسخهٔ پشتیبان باید به‌طور امن در جای دیگری ذخیره شود یا به روش دیگری تأیید شود که از زمان تهیهٔ پشتیبان تغییر نیافته است.

از pg_verifybackup(1) می‌توان برای بررسی یکپارچگی نسخهٔ پشتیبان در برابر مانیفست نسخهٔ پشتیبان استفاده کرد.

--manifest-force-encode

کدگذاری همهٔ نام‌های فایل در مانیفست نسخهٔ پشتیبان را به صورت هگزادسیمال (hex-encoded) اجباری می‌کند. اگر این گزینه مشخص نشود، تنها نام فایل‌های غیر UTF8 به صورت هگز کدگذاری می‌شوند. این گزینه عمدتاً با هدف آزمایش این موضوع در نظر گرفته شده است که ابزارهای خوانندهٔ فایل مانیفست پشتیبان این حالت را به درستی مدیریت کنند.

--no-estimate-size

از تخمین حجم کل داده‌های پشتیبان که قرار است ارسال جریانی (stream) شوند توسط سرور جلوگیری می‌کند، که باعث می‌شود ستون backup_total در نمای pg_stat_progress_basebackup همیشه NULL باشد.

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

این گزینه هنگام استفاده از --progress مجاز نیست.

--no-manifest

تولید مانیفست نسخهٔ پشتیبان را غیرفعال می‌کند. اگر این گزینه مشخص نشود، سرور یک مانیفست پشتیبان تولید و ارسال می‌کند که می‌تواند با استفاده از pg_verifybackup(1) اعتبارسنجی شود. مانیفست فهرستی از تمامی فایل‌های موجود در نسخهٔ پشتیبان است، به استثنای فایل‌های WAL که ممکن است در آن گنجانده شده باشند. همچنین اندازه، زمان آخرین تغییر و یک مجموع مقابله‌ای اختیاری را برای هر فایل ذخیره می‌کند.

--no-slot

از ایجاد یک اسلات تکثیر (replication slot) موقت برای نسخهٔ پشتیبان جلوگیری می‌کند.

به‌طور پیش‌فرض، اگر ارسال جریانی لاگ انتخاب شده باشد اما هیچ نام اسلاتی با گزینهٔ -S داده نشده باشد، یک اسلات تکثیر موقت ایجاد می‌شود (اگر توسط سرور مبدأ پشتیبانی شود).

هدف اصلی این گزینه این است که اجازه دهد زمانی که سرور هیچ اسلات تکثیر آزادی ندارد، یک پشتیبان اولیه (base backup) تهیه شود. استفاده از یک اسلات تکثیر تقریباً همیشه ارجح است، زیرا از حذف WALهای مورد نیاز توسط سرور در طول پشتیبان‌گیری جلوگیری می‌کند.

--no-verify-checksums

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

به‌طور پیش‌فرض، مجموع‌های مقابله‌ای اعتبارسنجی می‌شوند و شکست در بررسی مجموع مقابله‌ای منجر به وضعیت خروج غیرصفر خواهد شد. با این حال، در چنین حالتی پشتیبان اولیه حذف نخواهد شد، درست مثل اینکه گزینهٔ --no-clean استفاده شده باشد. خطاهای اعتبارسنجی مجموع مقابله‌ای همچنین در نمای pg_stat_database گزارش خواهند شد.

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

-d connstr
--dbname=connstr

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

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

-h host
--host=host

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

-p port
--port=port

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

-s interval
--status-interval=interval

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

-U username
--username=username

نام کاربری را برای اتصال مشخص می‌کند.

-w
--no-password

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

-W
--password

دستور pg_basebackup را وادار می‌کند تا قبل از اتصال به سرور مبدأ، گذرواژه را درخواست کند.

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

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

-V
--version

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

-?
--help

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

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

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

در ابتدای پشتیبان‌گیری، باید یک نقطه بازرسی (checkpoint) روی سرور مبدأ اجرا شود. این کار ممکن است مدتی طول بکشد (به‌ویژه اگر از گزینهٔ --checkpoint=fast استفاده نشود)، که در طول آن pg_basebackup به‌نظر بیکار خواهد رسید.

پشتیبان‌گیری شامل تمام فایل‌های موجود در دایرکتوری داده و tablespaceها خواهد بود، از جمله فایل‌های پیکربندی و هر فایل اضافی دیگری که توسط اشخاص ثالث در دایرکتوری قرار گرفته باشد، به‌جز برخی فایل‌های موقت مدیریت‌شده توسط PostgreSQL و فایل‌های سیستم‌عامل. اما فقط فایل‌ها و دایرکتوری‌های معمولی کپی می‌شوند، به این استثنا که پیوندهای نمادین مورد استفاده برای tablespaceها حفظ می‌شوند. پیوندهای نمادینی که به دایرکتوری‌های خاص شناخته‌شده برای PostgreSQL اشاره می‌کنند، به‌صورت دایرکتوری‌های خالی کپی می‌شوند. سایر پیوندهای نمادین و فایل‌های ویژهٔ دستگاه نادیده گرفته می‌شوند. برای جزئیات دقیق بخش 54.4 را ببینید.

در قالب plain، از tablespaceها در همان مسیری که روی سرور مبدأ دارند پشتیبان گرفته می‌شود، مگر اینکه از گزینهٔ --tablespace-mapping استفاده شود. بدون این گزینه، اگر tablespaceها در حال استفاده باشند، اجرای پشتیبان‌گیری پایه با قالب plain روی همان میزبان سرور کار نخواهد کرد، زیرا نسخه پشتیبان باید در همان مکان‌های دایرکتوری tablespaceهای اصلی نوشته شود.

هنگامی که قالب tar استفاده می‌شود، این مسئولیت کاربر است که قبل از راه‌اندازی یک سرور PostgreSQL که از داده‌ها استفاده می‌کند، هر فایل tar را از حالت فشرده خارج کند. اگر tablespaceهای اضافی وجود داشته باشند، فایل‌های tar مربوط به آن‌ها باید در مکان‌های صحیح باز شوند. در این حالت، پیوندهای نمادین برای آن tablespaceها توسط سرور با توجه به محتویات فایل tablespace_map که در فایل base.tar گنجانده شده است، ایجاد خواهند شد.

دستور pg_basebackup با سرورهای دارای نسخهٔ اصلی یکسان یا قدیمی‌تر، تا نسخهٔ 9.1 کار می‌کند. با این حال، حالت استریم WAL‏ (-X stream) فقط با سرور نسخهٔ 9.3 و جدیدتر، قالب tar‏ (--format=tar) فقط با سرور نسخهٔ 9.5 و جدیدتر، و پشتیبان‌گیری افزایشی (--incremental) فقط با سرور نسخهٔ 17 و جدیدتر کار می‌کند.

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

برای ایجاد یک پشتیبان پایه از سرور در mydbserver و ذخیرهٔ آن در دایرکتوری محلی /usr/local/pgsql/data:

$ pg_basebackup -h mydbserver -D /usr/local/pgsql/data

برای ایجاد یک نسخه پشتیبان از سرور محلی با یک فایل tar فشرده‌شده برای هر tablespace، و ذخیرهٔ آن در دایرکتوری backup، همراه با نمایش گزارش پیشرفت در حین اجرا:

$ pg_basebackup -D backup -Ft -z -P

برای ایجاد یک نسخه پشتیبان از یک پایگاه داده محلی تک-tablespace و فشرده‌سازی آن با bzip2:

$ pg_basebackup -D - -Ft -X fetch | bzip2 > backup.tar.bz2

(در صورت وجود چندین tablespace در پایگاه داده، این دستور ناموفق خواهد بود.)

برای ایجاد یک نسخه پشتیبان از یک پایگاه داده محلی که در آن tablespace موجود در /opt/ts به ./backup/ts منتقل شده است:

$ pg_basebackup -D backup/data -T /opt/ts=$(pwd)/backup/ts

برای ایجاد یک نسخه پشتیبان از سرور محلی با یک فایل tar برای هر tablespace که با gzip در سطح 9 فشرده شده و در دایرکتوری backup ذخیره می‌شود:

$ pg_basebackup -D backup -Ft --compress=gzip:9
pg_dump(1)، بخش 27.4.6
2026 PostgreSQL 18.6