PG_DUMP(1) PostgreSQL 18.6 Documentation PG_DUMP(1)

pg_dump - برون‌بری یک پایگاه داده PostgreSQL در قالب اسکریپت SQL یا فرمت‌های دیگر

pg_dump [connection-option...] [option...] [dbname]

pg_dump ابزاری برای برون‌بری یک پایگاه داده PostgreSQL است. این ابزار حتی در صورت استفاده هم‌زمان از پایگاه داده، خروجی‌های سازگار و یکدستی ایجاد می‌کند. pg_dump مانع دسترسی سایر کاربران به پایگاه داده نمی‌شود (نه خوانندگان و نه نویسندگان). با این حال، توجه داشته باشید که به جز در موارد ساده، pg_dump عموماً انتخاب مناسبی برای تهیه منظم نسخه‌های پشتیبان از پایگاه‌های داده عملیاتی (production) نیست. برای توضیحات بیشتر به Chapter 25 مراجعه کنید.

pg_dump تنها از یک پایگاه داده نسخه پشتیبان تهیه می‌کند. برای برون‌بری کل یک کلاستر، یا برون‌بری اشیاء سراسری (global) که میان تمام پایگاه‌های داده یک کلاستر مشترک هستند (مانند نقش‌ها و tablespaceها)، از pg_dumpall(1) استفاده کنید.

خروجی‌ها را می‌توان در قالب فایل اسکریپت یا فایل‌های بایگانی (archive) ذخیره کرد. نسخه‌های اسکریپتی، فایل‌های متنی ساده‌ای (plain-text) هستند که شامل دستورات SQL لازم برای بازسازی پایگاه داده به وضعیتی که در زمان ذخیره‌سازی داشته است می‌باشند. برای بازیابی از چنین اسکریپتی، آن را به psql(1) ارسال کنید. فایل‌های اسکریپت را می‌توان برای بازسازی پایگاه داده حتی روی ماشین‌های دیگر و با معماری‌های متفاوت به کار گرفت؛ و با اعمال برخی تغییرات، حتی روی سایر سیستم‌های پایگاه داده مبتنی بر SQL قابل استفاده هستند.

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

هنگام استفاده با یکی از فرمت‌های فایل بایگانی و ترکیب با pg_restore، ابزار pg_dump یک سازوکار بایگانی و انتقال منعطف را فراهم می‌آورد. pg_dump می‌تواند برای برون‌بری یک پایگاه داده کامل استفاده شود، سپس pg_restore می‌تواند برای بررسی بایگانی و/یا انتخاب این‌که کدام بخش‌های پایگاه داده باید بازیابی شوند مورد استفاده قرار گیرد. منعطف‌ترین فرمت‌های فایل خروجی، فرمت “custom” (-Fc) و فرمت “directory” (-Fd) هستند. آن‌ها امکان انتخاب و تغییر ترتیب تمام آیتم‌های بایگانی‌شده را فراهم می‌سازند، از بازیابی موازی پشتیبانی می‌کنند و به‌طور پیش‌فرض فشرده هستند. فرمت “directory” تنها فرمتی است که از برون‌بری موازی (parallel dumps) پشتیبانی می‌کند.

هنگام اجرای pg_dump، باید خروجی را برای هرگونه هشدار (چاپ‌شده در خطای استاندارد) بررسی کرد، به‌ویژه با در نظر گرفتن محدودیت‌های ذکر شده در زیر.


هشدار

بازیابی یک نسخه پشتیبان باعث می‌شود مقصد، کدهای دلخواه انتخابی مدیران سیستم (superusers) مبدأ را اجرا کند. برون‌بری‌های جزئی و بازیابی‌های جزئی این موضوع را محدود نمی‌کنند. اگر مدیران سیستم (superusers) مبدأ مورد اعتماد نباشند، دستورات SQL استخراج‌شده باید پیش از بازیابی بازبینی شوند. نسخه‌های پشتیبان غیرمتنی را می‌توان با استفاده از گزینه --file در pg_restore بررسی کرد. توجه داشته باشید کلاینتی که dump و restore را اجرا می‌کند نیازی به اعتماد به مدیران سیستم (superusers) مبدأ یا مقصد ندارد.

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

dbname

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

-a
--data-only

تنها از داده‌ها رونوشت می‌گیرد، نه از طرح‌واره (تعاریف داده) یا آمارها. داده‌های جدول، اشیاء بزرگ (large objects)، و مقادیر دنباله (sequence) استخراج می‌شوند.

این گزینه مشابه، اما به دلایل تاریخی نه دقیقاً یکسان با، مشخص کردن --section=data است.

-b
--large-objects
--blobs (منسوخ‌شده)

اشیاء بزرگ را در رونوشت می‌گنجاند. این رفتار پیش‌فرض است مگر هنگامی که --schema، --table، --schema-only، --statistics-only، یا --no-data مشخص شده باشد. بنابراین سوییچ -b تنها زمانی مفید است که بخواهید اشیاء بزرگ را به رونوشت‌هایی بیفزایید که یک طرح‌واره یا جدول خاص درخواست شده است. توجه داشته باشید که اشیاء بزرگ جزو داده‌ها محسوب می‌شوند و در نتیجه هنگامی که --data-only به کار می‌رود گنجانده می‌شوند، اما هنگامی که --schema-only یا --statistics-only استفاده شود، خیر.

-B
--no-large-objects
--no-blobs (منسوخ‌شده)

اشیاء بزرگ را از خروجی رونوشت مستثنی می‌کند.

هنگامی که هر دو گزینهٔ -b و -B داده شوند، رفتار برنامه خروجی دادن اشیاء بزرگ است، در صورتی که داده‌ها در حال رونوشت‌گیری باشند؛ به مستندات -b مراجعه کنید.

-c
--clean

دستوراتی صادر می‌کند تا قبل از دستورات ساخت، تمام اشیاء پایگاه دادهٔ استخراج‌شده با DROP حذف شوند. این گزینه زمانی مفید است که بازیابی قرار باشد روی یک پایگاه دادهٔ موجود بازنویسی شود. اگر هر یک از اشیاء در پایگاه دادهٔ مقصد وجود نداشته باشند، در طول بازیابی پیام‌های خطای قابل چشم‌پوشی گزارش می‌شوند، مگر آن‌که --if-exists نیز مشخص شده باشد.

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

-C
--create

خروجی را با دستوری برای ایجاد خود پایگاه داده و اتصال مجدد به پایگاه دادهٔ ایجادشده آغاز می‌کند. (با اسکریپتی به این شکل، تفاوتی نمی‌کند قبل از اجرای اسکریپت به کدام پایگاه داده در سامانهٔ مقصد متصل شوید.) اگر --clean نیز مشخص شده باشد، اسکریپت پیش از اتصال مجدد به پایگاه دادهٔ هدف، آن را حذف و دوباره ایجاد می‌کند.

با --create، خروجی همچنین شامل یادداشت (comment) پایگاه داده در صورت وجود، و هرگونه تنظیمات متغیرهای پیکربندی مختص به این پایگاه داده خواهد بود؛ یعنی تمام دستورهای ALTER DATABASE ... SET ... و ALTER ROLE ... IN DATABASE ... SET ... که به این پایگاه داده اشاره دارند. مجوزهای دسترسی برای خود پایگاه داده نیز استخراج می‌شوند، مگر اینکه --no-acl مشخص شده باشد.

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

-e pattern
--extension=pattern

تنها افزونه‌های منطبق با pattern را در خروجی رونوشت می‌آورد. هنگامی که این گزینه مشخص نشده باشد، تمام افزونه‌های غیرسیستمی در پایگاه دادهٔ هدف استخراج می‌شوند. با نوشتن چندین سوییچ -e می‌توان چندین افزونه را انتخاب کرد. پارامتر pattern مطابق با همان قواعدی که دستورات \d در psql به کار می‌برند (بخش الگوها / Patterns را ببینید) به عنوان الگو تفسیر می‌شود، بنابراین می‌توان با نوشتن نویسه‌های عام (wildcard) در الگو، چندین افزونه را نیز انتخاب کرد. هنگام استفاده از نویسه‌های عام، دقت کنید که در صورت نیاز الگو را درون نقل‌قول قرار دهید تا پوسته نویسه‌های عام را بسط ندهد.

هر رابطهٔ پیکربندی ثبت‌شده توسط pg_extension_config_dump، اگر افزونهٔ آن توسط --extension مشخص شده باشد، در رونوشت گنجانده می‌شود.


نکته
هنگامی که -e مشخص می‌شود، pg_dump هیچ تلاشی برای استخراج سایر اشیاء پایگاه داده که افزونه(های) انتخاب‌شده ممکن است به آن‌ها وابسته باشند نمی‌کند. از این رو، هیچ تضمینی وجود ندارد که نتایج یک رونوشتِ افزونه-خاص بتواند به تنهایی با موفقیت در یک پایگاه دادهٔ پاک بازیابی شود.

-E encoding
--encoding=encoding

رونوشت را با کدگذاری مجموعه نویسهٔ (character set encoding) مشخص‌شده ایجاد می‌کند. به طور پیش‌فرض، رونوشت در کدگذاری پایگاه داده ایجاد می‌شود. (راه دیگر برای دستیابی به همین نتیجه، تنظیم متغیر محیطی PGCLIENTENCODING روی کدگذاری مورد نظر برای رونوشت است.) کدگذاری‌های پشتیبانی‌شده در بخش 23.3.1 شرح داده شده‌اند.

-f file
--file=file

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

-F format
--format=format

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

p
plain

یک فایل اسکریپت SQL متن ساده (پیش‌فرض) خروجی می‌دهد.

c
custom

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

d
directory

یک آرشیو با قالب دایرکتوری مناسب برای ورودی به pg_restore خروجی می‌دهد. این گزینه دایرکتوری‌ای ایجاد می‌کند که شامل یک فایل برای هر جدول و شیء بزرگ استخراج‌شده است، به علاوه فایلی موسوم به فهرست مطالب (Table of Contents) که اشیاء استخراج‌شده را در قالبی ماشین‌خوان که pg_restore بتواند بخواند شرح می‌دهد. یک آرشیو با قالب دایرکتوری را می‌توان با ابزارهای استاندارد یونیکس دستکاری کرد؛ به عنوان مثال، فایل‌ها در یک آرشیو غیرفشرده را می‌توان با ابزارهای gzip، lz4، یا zstd فشرده کرد. این قالب به طور پیش‌فرض با استفاده از gzip فشرده‌سازی می‌شود و همچنین از رونوشت‌گیری موازی پشتیبانی می‌کند. t
tar
یک بایگانی در قالب tar تولید می‌کند که برای ورودی به pg_restore مناسب است. قالب tar با قالب دایرکتوری سازگار است: استخراج یک بایگانی با قالب tar یک بایگانی معتبر در قالب دایرکتوری تولید می‌کند. با این حال، قالب tar از فشرده‌سازی پشتیبانی نمی‌کند. همچنین، هنگام استفاده از قالب tar، ترتیب نسبی داده‌های جداول را نمی‌توان در طول بازیابی تغییر داد.

-j njobs
--jobs=njobs

اجرای موازی dump با پشتیبان‌گیری هم‌زمان از njobs جدول. این گزینه ممکن است زمان مورد نیاز برای انجام dump را کاهش دهد، اما بار کاری روی سرور پایگاه داده را نیز افزایش می‌دهد. شما فقط می‌توانید از این گزینه با قالب خروجی دایرکتوری استفاده کنید، زیرا این تنها قالب خروجی است که چند فرآیند می‌توانند به طور هم‌زمان داده‌های خود را در آن بنویسند.

دستور pg_dump به تعداد njobs + 1 اتصال به پایگاه داده باز خواهد کرد، بنابراین اطمینان حاصل کنید که تنظیم max_connections شما به اندازه کافی بالا باشد تا بتواند پاسخگوی تمام اتصالات باشد.

درخواست قفل‌های انحصاری بر روی اشیاء پایگاه داده هنگام اجرای یک dump موازی می‌تواند باعث شکست dump شود. دلیل آن این است که فرآیند راهبر (leader) در pg_dump قفل‌های اشتراکی (ACCESS SHARE) را بر روی اشیایی که فرآیندهای کارگر (worker) قرار است بعداً از آن‌ها dump بگیرند درخواست می‌کند تا مطمئن شود هیچ‌کس آن‌ها را در حین اجرای dump حذف نکرده یا از بین نمی‌برد. اگر سپس یک کلاینت دیگر درخواست قفل انحصاری روی یک جدول داشته باشد، آن قفل اعطا نخواهد شد اما در صف انتظار برای آزادسازی قفل اشتراکی فرآیند راهبر منتظر خواهد ماند. در نتیجه، به هیچ دسترسی دیگری به جدول نیز اجازه داده نخواهد شد و پس از درخواست قفل انحصاری در صف قرار می‌گیرد. این شامل فرآیند کارگری که تلاش می‌کند از جدول dump بگیرد نیز می‌شود. بدون هیچ تدبیری، این یک وضعیت کلاسیک بن‌بست (deadlock) خواهد بود. برای تشخیص این تداخل، فرآیند کارگر pg_dump با استفاده از گزینه NOWAIT درخواست یک قفل اشتراکی دیگر می‌دهد. اگر به فرآیند کارگر این قفل اشتراکی داده نشود، شخص دیگری باید در این میان قفل انحصاری درخواست کرده باشد و هیچ راهی برای ادامه dump وجود ندارد، بنابراین pg_dump چاره‌ای جز لغو عملیات dump ندارد.

برای انجام یک dump موازی، سرور پایگاه داده باید از نماهای لحظه‌ای همگام‌سازی‌شده (synchronized snapshots) پشتیبانی کند؛ قابلیتی که در PostgreSQL نسخه 9.2 برای سرورهای اصلی (primary) و نسخه 10 برای سرورهای آماده‌باش (standby) معرفی شد. با این ویژگی، کلاینت‌های پایگاه داده می‌توانند اطمینان حاصل کنند که مجموعه داده‌های یکسانی را می‌بینند، حتی اگر از اتصالات متفاوتی استفاده کنند. pg_dump -j از چندین اتصال پایگاه داده استفاده می‌کند؛ یک بار با فرآیند راهبر و یک بار دیگر برای هر کارگر (worker job) به پایگاه داده متصل می‌شود. بدون ویژگی نماهای لحظه‌ای همگام‌سازی‌شده، تضمین نمی‌شود که کارهای کارگر مختلف داده‌های یکسانی را در هر اتصال مشاهده کنند، که می‌تواند منجر به یک پشتیبان‌گیری ناسازگار شود.

-n pattern
--schema=pattern

تنها از اسکیمای منطبق با pattern dump می‌گیرد؛ این گزینه هم خود اسکیما و هم تمام اشیاء درون آن را انتخاب می‌کند. در صورتی که این گزینه مشخص نشده باشد، از تمام اسکیمای غیرسیستمی در پایگاه داده هدف پشتیبان‌گیری خواهد شد. با نوشتن چندین سوئیچ -n می‌توان چندین اسکیما را انتخاب کرد. پارامتر pattern مطابق با همان قواعدی که توسط دستورات \d در psql استفاده می‌شود (به بخش Patterns مراجعه کنید) به عنوان الگو تفسیر می‌شود؛ بنابراین می‌توان با نوشتن نویسه‌های عام (wildcard) در الگو، چندین اسکیما را نیز انتخاب کرد. هنگام استفاده از نویسه‌های عام، دقت کنید که در صورت نیاز الگو را درون نقل‌قول قرار دهید تا از بسط نویسه‌های عام توسط شل جلوگیری شود؛ به بخش Examples در زیر مراجعه کنید.

نکته
هنگامی که -n مشخص می‌شود، pg_dump هیچ تلاشی برای گرفتن dump از سایر اشیاء پایگاه داده که اسکیما(های) انتخاب‌شده ممکن است به آن‌ها وابسته باشند انجام نمی‌دهد. بنابراین، تضمینی وجود ندارد که نتایج یک dump مربوط به اسکیمایی خاص بتواند به تنهایی در یک پایگاه داده تمیز با موفقیت بازیابی شود.

نکته
اشیای غیر اسکیما مانند large objects هنگامی که -n مشخص شده باشد dump نمی‌شوند. با استفاده از سوئیچ --large-objects می‌توانید large objects را دوباره به dump اضافه کنید.

-N pattern
--exclude-schema=pattern

از هیچ اسکیمایی که با pattern مطابقت داشته باشد dump نمی‌گیرد. الگو طبق همان قواعد مربوط به -n تفسیر می‌شود. سوئیچ -N می‌تواند بیش از یک بار مشخص شود تا اسکیمای منطبق با هر یک از الگوهای مشخص‌شده مستثنی گردند.

هنگامی که هر دوی -n و -N داده شوند، رفتار بدین صورت است که فقط از اسکیمایی dump گرفته می‌شود که حداقل با یکی از سوئیچ‌های -n مطابقت داشته باشد و با هیچ‌یک از سوئیچ‌های -N مطابقت نداشته باشد. اگر -N بدون -n بیاید، در آن صورت اسکیمای منطبق بر -N از آنچه که در حالت عادی یک dump معمولی است، مستثنی می‌شوند.

-O
--no-owner

دستورات مربوط به تنظیم مالکیت اشیاء مطابق با پایگاه داده اصلی را در خروجی نمی‌آورد. به طور پیش‌فرض، pg_dump دستورات ALTER OWNER یا SET SESSION AUTHORIZATION را برای تخصیص مالکیت اشیاء ایجادشده در پایگاه داده صادر می‌کند. این دستورات هنگام اجرای اسکریپت با شکست مواجه خواهند شد مگر اینکه توسط یک کاربر ریشه/مدیر سیستم (یا همان کاربری که مالک تمامی اشیاء در اسکریپت است) اجرا شود. برای ایجاد اسکریپتی که توسط هر کاربری قابل بازیابی باشد، اما مالکیت تمام اشیاء را به همان کاربر بدهد، -O را مشخص کنید.

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

-R
--no-reconnect

این گزینه منسوخ شده است اما هنوز به منظور سازگاری رو به عقب پذیرفته می‌شود.

-s
--schema-only

تنها تعاریف اشیاء (اسکیما) را dump می‌کند، نه داده‌ها یا آمارها را.

این گزینه نمی‌تواند همراه با --data-only یا --statistics-only استفاده شود. این گزینه مشابه تعیین --section=pre-data --section=post-data است، هرچند بنا به دلایل تاریخی دقیقاً با آن یکسان نیست.

(این گزینه را با گزینه --schema که از واژه “schema” به معنایی متفاوت استفاده می‌کند اشتباه نگیرید.)

برای مستثنی کردن داده‌های جدول تنها برای زیرمجموعه‌ای از جداول در پایگاه داده، به --exclude-table-data مراجعه کنید.

-S username
--superuser=username

نام کاربری مدیر سیستم (superuser) را برای استفاده هنگام غیرفعال‌سازی تریگرها مشخص می‌کند. این گزینه فقط در صورتی کاربرد دارد که از --disable-triggers استفاده شده باشد. (معمولاً بهتر است این گزینه نادیده گرفته شود و در عوض اسکریپت حاصل به عنوان مدیر سیستم اجرا گردد.)

-t pattern
--table=pattern

تنها از جدول‌هایی با نام‌های منطبق بر pattern dump می‌گیرد. با نوشتن چندین سوئیچ -t می‌توان چندین جدول را انتخاب کرد. پارامتر pattern مطابق با همان قوانینی که توسط دستورات \d در psql استفاده می‌شود (به بخش Patterns مراجعه کنید) به عنوان یک الگو تفسیر می‌گردد؛ بنابراین می‌توان با درج نویسه‌های عام در الگو نیز چندین جدول را انتخاب کرد. هنگام استفاده از نویسه‌های عام، دقت کنید که در صورت نیاز الگو را درون نقل‌قول قرار دهید تا از بسط نویسه‌های عام توسط شل جلوگیری شود؛ به بخش Examples در زیر مراجعه کنید..sp علاوه بر جدول‌ها، این گزینه می‌تواند برای استخراج تعریف نماها، نماهای مادی‌شده، جدول‌های خارجی و توالی‌های منطبق به کار رود. این گزینه محتوای نماها یا نماهای مادی‌شده را استخراج نمی‌کند و محتوای جدول‌های خارجی تنها در صورتی استخراج می‌شود که سرور خارجی متناظر با --include-foreign-data مشخص شده باشد.

سوئیچ‌های -n و -N هنگام استفاده از -t هیچ تاثیری ندارند، زیرا جدول‌های انتخاب‌شده با -t صرف‌نظر از آن سوئیچ‌ها استخراج خواهند شد و اشیاء غیرجدولی استخراج نخواهند شد.


نکته
هنگامی که -t مشخص می‌شود، pg_dump هیچ تلاشی برای استخراج اشیاء پایگاه داده دیگری که جدول(های) انتخاب‌شده ممکن است به آن‌ها وابسته باشند نمی‌کند. بنابراین، هیچ تضمینی وجود ندارد که نتایج یک استخراج مختص به جدول بتواند به تنهایی در یک پایگاه داده تمیز با موفقیت بازیابی شود.

-T pattern
--exclude-table=pattern

هیچ جدولی را که با pattern منطبق باشد استخراج نکن. الگو مطابق با همان قواعد -t تفسیر می‌شود. -T می‌تواند بیش از یک بار مشخص شود تا جدول‌های منطبق با هر یک از چندین الگو مستثنی شوند.

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

-v
--verbose

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

-V
--version

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

-x
--no-privileges
--no-acl

از استخراج امتیازات دسترسی (دستورهای grant/revoke) جلوگیری کن.

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

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

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

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

قالب آرشیو tar در حال حاضر به‌هیچ‌وجه از فشرده‌سازی پشتیبانی نمی‌کند.

--binary-upgrade

این گزینه برای استفاده ابزارهای ارتقاء درجا (in-place upgrade) است. استفاده از آن برای مقاصد دیگر توصیه یا پشتیبانی نمی‌شود. رفتار این گزینه ممکن است در نسخه‌های بعدی بدون اطلاع قبلی تغییر کند.

--column-inserts
--attribute-inserts

داده‌ها را به عنوان دستورهای INSERT با نام‌های صریح ستون‌ها (INSERT INTO table (column, ...) VALUES ...) استخراج کن. این کار بازیابی را بسیار کند خواهد کرد؛ کاربرد اصلی آن برای ایجاد استخراج‌هایی است که بتوان آن‌ها را در پایگاه‌های داده غیر PostgreSQL بارگذاری کرد. هرگونه خطا در طول بازیابی تنها باعث از دست رفتن سطرهایی می‌شود که بخشی از دستور INSERT مشکل‌دار هستند، نه کل محتویات جدول.

--disable-dollar-quoting

این گزینه استفاده از نقل‌قول دلاری (dollar quoting) را برای بدنه توابع غیرفعال کرده و آن‌ها را ملزم به نقل‌قول با استفاده از نحو رشته‌ای استاندارد SQL می‌کند.

--disable-triggers

این گزینه تنها هنگام ایجاد استخراجی که شامل داده‌ها است اما شامل طرحواره (schema) نیست کاربرد دارد. این گزینه به pg_dump دستور می‌دهد تا دستورهایی را برای غیرفعال کردن موقت تریگرها در جدول‌های هدف در حین بازیابی داده‌ها بگنجاند. اگر بررسی‌های جامعیت ارجاعی یا تریگرهای دیگری روی جدول‌ها دارید که نمی‌خواهید در طول بازیابی داده‌ها فراخوانی شوند، از این گزینه استفاده کنید.

در حال حاضر، دستورهای ایجادشده برای --disable-triggers باید توسط مدیر سیستم (superuser) اجرا شوند. بنابراین، باید نام یک مدیر سیستم را با -S مشخص کنید، یا ترجیحاً دقت کنید که اسکریپت حاصل به عنوان مدیر سیستم (superuser) اجرا شود.

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

--enable-row-security

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

توجه داشته باشید در صورتی که هم‌اکنون از این گزینه استفاده می‌کنید، احتمالاً می‌خواهید استخراج در قالب INSERT باشد، زیرا دستور COPY FROM در زمان بازیابی از امنیت در سطح سطر پشتیبانی نمی‌کند. --exclude-extension=pattern

هیچ افزونه‌ای منطبق با pattern تخلیه نشود. این الگو طبق همان قواعد مربوط به -e تفسیر می‌شود. گزینهٔ --exclude-extension می‌تواند بیش از یک بار مشخص شود تا افزونه‌های منطبق با هر یک از چندین الگو را مستثنی کند.

هنگامی که هر دو گزینهٔ -e و --exclude-extension داده شده باشند، رفتار به این صورت است که تنها افزونه‌هایی تخلیه می‌شوند که حداقل با یکی از سوییچ‌های -e تطابق داشته و با هیچ‌یک از سوییچ‌های --exclude-extension تطابقی نداشته باشند. اگر --exclude-extension بدون -e ارائه شود، افزونه‌های منطبق با --exclude-extension از آنچه در غیر این صورت یک تخلیهٔ عادی می‌بود، مستثنی می‌شوند.

--exclude-table-and-children=pattern

این گزینه مشابه گزینهٔ -T/--exclude-table است، با این تفاوت که هرگونه پارتیشن یا جدول‌های فرزند موروثی از جدول(های) منطبق با pattern را نیز مستثنی می‌کند.

--exclude-table-data=pattern

داده‌های هیچ‌یک از جدول‌های منطبق با pattern را تخلیه نکنید. این الگو بر اساس همان قواعد مربوط به -t تفسیر می‌شود. گزینهٔ --exclude-table-data می‌تواند بیش از یک بار برای مستثنی کردن جدول‌های منطبق با هر یک از چندین الگو مشخص شود. این گزینه زمانی مفید است که به تعریف یک جدول خاص نیاز دارید، حتی اگر نیازی به داده‌های درون آن نداشته باشید.

برای مستثنی کردن داده‌های تمام جدول‌های پایگاه داده، به --schema-only یا --statistics-only مراجعه کنید.

--exclude-table-data-and-children=pattern

این گزینه مشابه گزینهٔ --exclude-table-data است، به جز اینکه داده‌های تمامی پارتیشن‌ها یا جدول‌های فرزند موروثی از جدول(های) منطبق با pattern را نیز مستثنی می‌کند.

--extra-float-digits=ndigits

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

--filter=filename

نام فایلی را مشخص کنید که الگوهای اشیاء جهت گنجاندن یا مستثنی کردن از تخلیه از آن خوانده شود. الگوها طبق همان قواعد مربوط به گزینه‌های متناظر تفسیر می‌شوند: -t/--table، --table-and-children، -T/--exclude-table و --exclude-table-and-children برای جدول‌ها، -n/--schema و -N/--exclude-schema برای طرح‌واره‌ها، --include-foreign-data برای داده‌های روی سرورهای خارجی، --exclude-table-data و --exclude-table-data-and-children برای داده‌های جدول، و -e/--extension و --exclude-extension برای افزونه‌ها. برای خواندن از STDIN، از - به عنوان نام فایل استفاده کنید. گزینهٔ --filter می‌تواند همگام با گزینه‌های ذکرشده در بالا برای گنجاندن یا مستثنی کردن اشیاء مشخص شود، و همچنین می‌تواند بیش از یک بار برای چندین فایل پالایه تعیین گردد.

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

{ include | exclude } { extension | foreign_data | table | table_and_children | table_data | table_data_and_children | schema } PATTERN

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

•extension: افزونه‌ها. این مورد مانند گزینهٔ -e/--extension یا --exclude-extension عمل می‌کند.
•foreign_data: داده‌های روی سرورهای خارجی. این مورد مانند گزینهٔ --include-foreign-data عمل می‌کند. این کلمهٔ کلیدی تنها می‌تواند به همراه کلمهٔ کلیدی include استفاده شود.
•table: جدول‌ها. این مورد مانند گزینهٔ -t/--table یا -T/--exclude-table عمل می‌کند.
•table_and_children: جدول‌ها شامل تمامی پارتیشن‌ها یا جدول‌های فرزند موروثی. این مورد مانند گزینهٔ --table-and-children یا --exclude-table-and-children عمل می‌کند.
•table_data: داده‌های جدول برای هر جدولی که با pattern تطابق دارد. این مورد مانند گزینهٔ --exclude-table-data عمل می‌کند. این کلمهٔ کلیدی تنها می‌تواند به همراه کلمهٔ کلیدی exclude استفاده شود.
•table_data_and_children: داده‌های جدول برای هر جدولی که با pattern مطابقت داشته باشد، و همچنین تمامی پارتیشن‌ها یا فرزندان وراثتی آن جدول(ها). این مانند گزینهٔ --exclude-table-data-and-children عمل می‌کند. این کلیدواژه فقط می‌تواند همراه با کلیدواژهٔ exclude استفاده شود.
•schema: طرحواره‌ها. این مانند گزینهٔ -n/--schema یا -N/--exclude-schema عمل می‌کند.

سطرهایی که با # شروع می‌شوند توضیح (کامنت) در نظر گرفته شده و نادیده گرفته می‌شوند. توضیحات می‌توانند پس از یک سطر الگوی شیء نیز قرار گیرند. سطرهای خالی نیز نادیده گرفته می‌شوند. برای نحوهٔ نقل‌قول‌گذاری در الگوها بخش Patterns را ببینید.

فایل‌های نمونه در زیر در بخش Examples فهرست شده‌اند.

--if-exists

استفاده از دستورهای DROP ... IF EXISTS برای حذف اشیاء در حالت --clean. این کار خطاهای “does not exist” (وجود ندارد) را که در غیر این صورت ممکن است گزارش شوند نادیده می‌گیرد. این گزینه معتبر نیست مگر اینکه --clean نیز مشخص شده باشد.

--include-foreign-data=foreignserver

استخراج داده‌ها برای هر جدول خارجی با یک سرور خارجی منطبق بر الگوی foreignserver. با نوشتن چندین سوئیچ --include-foreign-data می‌توان چندین سرور خارجی را انتخاب کرد. همچنین، پارامتر foreignserver بر اساس همان قواعد به کار رفته در دستورهای \d برنامهٔ psql (بخش Patterns را ببینید) به عنوان یک الگو تفسیر می‌شود، بنابراین می‌توان با نوشتن نویسه‌های عام (wildcard) در الگو، چندین سرور خارجی را نیز انتخاب کرد. هنگام استفاده از نویسه‌های عام، دقت کنید که در صورت نیاز الگو را درون نقل‌قول قرار دهید تا از بسط نویسه‌های عام توسط شل جلوگیری شود؛ بخش Examples را در زیر ببینید. تنها استثنا این است که الگوی خالی مجاز نیست.

نکته
استفاده از نویسه‌های عام در --include-foreign-data ممکن است منجر به دسترسی به سرورهای خارجی غیرمنتظره شود. همچنین، برای استفادهٔ امن از این گزینه، مطمئن شوید که سرور نام‌برده مالک قابل اعتمادی داشته باشد.

نکته
هنگامی که --include-foreign-data مشخص شده باشد، pg_dump بررسی نمی‌کند که آیا جدول خارجی قابل نوشتن است یا خیر. بنابراین، هیچ تضمینی وجود ندارد که نتایج استخراج یک جدول خارجی با موفقیت بازیابی شود.

--inserts

استخراج داده‌ها به صورت دستورهای INSERT (به جای COPY). این کار بازیابی را بسیار کُند می‌کند؛ این گزینه عمدتاً برای ایجاد فایل‌های خروجی مفیدی است که بتوان آن‌ها را در پایگاه‌های دادهٔ غیر PostgreSQL بارگذاری کرد. هرگونه خطا در حین بازیابی فقط باعث از دست رفتن ردیف‌هایی می‌شود که بخشی از دستور INSERT مشکل‌دار هستند، نه تمام محتویات جدول. توجه داشته باشید اگر ترتیب ستون‌ها را تغییر داده باشید، ممکن است بازیابی به طور کلی با شکست مواجه شود. گزینهٔ --column-inserts در برابر تغییرات ترتیب ستون‌ها ایمن است، اگرچه حتی کُندتر عمل می‌کند.

--load-via-partition-root

هنگام استخراج داده‌ها برای یک پارتیشن جدول، دستورهای COPY یا INSERT به جای خود پارتیشن، ریشهٔ سلسله‌مراتب پارتیشن‌بندی شامل آن را هدف قرار می‌دهند. این کار باعث می‌شود تا هنگام بارگذاری داده‌ها، پارتیشن مناسب برای هر ردیف دوباره تعیین شود. این ویژگی ممکن است زمانی مفید باشد که داده‌ها روی سروری بازیابی می‌شوند که ردیف‌ها لزوماً در همان پارتیشن‌هایی که در سرور اصلی بودند قرار نمی‌گیرند. برای مثال، این وضعیت ممکن است زمانی رخ دهد که ستون پارتیشن‌بندی از نوع text باشد و دو سیستم تعاریف متفاوتی از ترتیب تطبیق (collation) مورد استفاده برای مرتب‌سازی ستون پارتیشن‌بندی داشته باشند.

--lock-wait-timeout=timeout

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

--no-comments

دستورهای COMMENT استخراج نشوند.

--no-data

داده‌ها استخراج نشوند.

--no-policies

سیاست‌های امنیت سطری (row security policies) استخراج نشوند.

--no-publications

انتشارها (publications) استخراج نشوند.

--no-schema

طرحواره (تعاریف داده‌ها) استخراج نشود.

--no-security-labels

برچسب‌های امنیتی استخراج نشوند.

--no-statistics

آمارها استخراج نشوند. این حالت پیش‌فرض است.

--no-subscriptions

اشتراک‌ها (subscriptions) استخراج نشوند.

--no-sync

به‌طور پیش‌فرض، pg_dump منتظر می‌ماند تا تمامی فایل‌ها به طور ایمن روی دیسک نوشته شوند. این گزینه باعث می‌شود pg_dump بدون انتظار به کار خود پایان دهد، که سریع‌تر است اما بدین معناست که از کار افتادن (crash) بعدی سیستم‌عامل می‌تواند فایل استخراج‌شده را آسیب‌دیده باقی بگذارد. به‌طور کلی، این گزینه برای آزمودن مفید است اما نباید هنگام استخراج داده‌ها از محیط‌های عملیاتی استفاده شود. --no-table-access-method
دستورهایی را برای انتخاب متدهای دسترسی به جدول در خروجی قرار نده. با این گزینه، تمام اشیاء با هر متد دسترسی جدولی که هنگام بازیابی پیش‌فرض باشد ایجاد خواهند شد.

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

--no-tablespaces

دستورهایی را برای انتخاب tablespaceها در خروجی قرار نده. با این گزینه، تمام اشیاء در هر tablespaceای که هنگام بازیابی پیش‌فرض باشد ایجاد خواهند شد.

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

--no-toast-compression

دستورهایی را برای تنظیم روش‌های فشرده‌سازی TOAST در خروجی قرار نده. با این گزینه، همه ستون‌ها با تنظیمات فشرده‌سازی پیش‌فرض بازیابی خواهند شد.

--no-unlogged-table-data

محتوای جدول‌ها و دنباله‌ها (sequences) ثبت‌نشده (unlogged) را در خروجی dump قرار نده. این گزینه هیچ تأثیری بر تخلیه شدن یا نشدن تعاریف جدول و دنباله (طرح‌واره یا schema) ندارد؛ فقط از تخلیه داده‌های جدول و دنباله جلوگیری می‌کند. داده‌های جدول‌ها و دنباله‌های unlogged هنگام گرفتن dump از یک سرور standby همیشه مستثنی می‌شوند.

--on-conflict-do-nothing

عبارت ON CONFLICT DO NOTHING را به دستورهای INSERT اضافه کن. این گزینه معتبر نیست مگر اینکه --inserts، --column-inserts یا --rows-per-insert نیز مشخص شده باشد.

--quote-all-identifiers

کوتیشن‌گذاری اجباری برای همه شناسه‌ها. این گزینه زمانی توصیه می‌شود که از یک پایگاه‌داده در سروری dump گرفته می‌شود که نسخه اصلی (major version) PostgreSQL آن با نسخه pg_dump متفاوت است، یا زمانی که قرار است خروجی در سروری با نسخه اصلی متفاوتی بارگذاری شود. به‌طور پیش‌فرض، pg_dump تنها شناسه‌هایی را داخل کوتیشن قرار می‌دهد که در نسخه اصلی خودش جزو کلمات رزروشده باشند. این امر گاهی اوقات هنگام تعامل با سرورهایی از نسخه‌های دیگر که ممکن است مجموعه‌ای کمی متفاوت از کلمات رزروشده داشته باشند، به مشکلات سازگاری می‌انجامد. استفاده از --quote-all-identifiers از چنین مشکلاتی جلوگیری می‌کند، به بهای اینکه خوانایی اسکریپت خروجی کمتر خواهد شد.

--restrict-key=restrict_key

از رشته ارائه‌شده به عنوان کلید \restrict در psql در خروجی dump استفاده کن. این گزینه فقط برای dumpهای متنی ساده (plain-text) قابل تعیین است؛ یعنی زمانی که --format روی plain تنظیم شده باشد یا گزینه --format حذف شده باشد. اگر هیچ کلید محدودیتی مشخص نشود، pg_dump در صورت نیاز یک کلید تصادفی ایجاد خواهد کرد. کلیدها فقط می‌توانند شامل نویسه‌های الفبایی-عددی (alphanumeric) باشند.

این گزینه عمدتاً برای اهداف آزمایشی و سایر سناریوهایی که نیاز به خروجی تکرارپذیر دارند (مانند مقایسه فایل‌های dump) در نظر گرفته شده است. برای استفاده عمومی توصیه نمی‌شود، زیرا یک سرور مخرب با آگاهی قبلی از کلید ممکن است بتواند کدهای دلخواهی را تزریق کند که روی ماشینی که psql را با خروجی dump اجرا می‌کند، اجرا شوند.

--rows-per-insert=nrows

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

--section=sectionname

تنها از بخش نام‌برده خروجی بگیر. نام بخش می‌تواند pre-data، data یا post-data باشد. این گزینه می‌تواند بیش از یک بار برای انتخاب چندین بخش مشخص شود. حالت پیش‌فرض، گرفتن خروجی از تمام بخش‌ها است.

بخش data شامل داده‌های واقعی جدول، محتویات اشیاء بزرگ (large-object)، مقادیر دنباله‌ها، و آمارهای مربوط به جدول‌ها، نماهای مادی‌شده (materialized views) و جدول‌های خارجی (foreign tables) است. موارد post-data شامل تعاریف اندیس‌ها، تریگرها، قواعد (rules)، آمارهای مربوط به اندیس‌ها، و قیدهایی غیر از قیدهای اعتبارسنجی‌شده‌ی check و not-null است. موارد pre-data شامل تمام موارد دیگر تعریف داده هستند.

--sequence-data

داده‌های دنباله (sequence) را در dump بگنجان. این رفتار پیش‌فرض است، مگر زمانی که --no-data، --schema-only یا --statistics-only مشخص شده باشد.

--serializable-deferrable

از یک تراکنش serializable برای dump استفاده کن تا اطمینان حاصل شود که snapshot استفاده‌شده با وضعیت‌های بعدی پایگاه‌داده سازگار است؛ اما این کار با انتظار برای رسیدن به نقطه‌ای در جریان تراکنش‌ها انجام می‌شود که در آن هیچ ناهنجاری نتواند رخ دهد، به طوری که خطری مبنی بر شکست dump یا باعث بازگردانی (roll back) تراکنش‌های دیگر با خطای serialization_failure وجود نداشته باشد. برای اطلاعات بیشتر درباره جداسازی تراکنش‌ها و کنترل همزمانی، به فصل 13 مراجعه کنید.

این گزینه برای dumpای که تنها برای بازیابی پس از بحران (disaster recovery) در نظر گرفته شده است، مزیتی ندارد. این گزینه می‌تواند برای dumpای مفید باشد که جهت بارگذاری یک کپی از پایگاه‌داده برای گزارش‌گیری یا سایر مقاصد تقسیم بار فقط‌خواندنی استفاده می‌شود، در حالی که پایگاه‌داده اصلی همچنان در حال به‌روزرسانی است. بدون آن، dump ممکن است وضعیتی را منعکس کند که با هیچ اجرای سریالی از تراکنش‌هایی که در نهایت ثبت (commit) شده‌اند سازگار نباشد. برای مثال، اگر از روش‌های پردازش دسته‌ای (batch processing) استفاده شود، ممکن است یک دسته بدون ظاهر شدن تمام موارد درون آن، به عنوان بسته‌شده در خروجی نمایش داده شود.

اگر هنگام شروع pg_dump هیچ تراکنش خواندن-نوشتنی فعالی وجود نداشته باشد، این گزینه هیچ تفاوتی ایجاد نخواهد کرد. اگر تراکنش‌های خواندن-نوشتن فعال باشند، شروع dump ممکن است برای مدت نامعلومی به تعویق بیفتد. پس از شروع اجرا، کارایی با وجود این گزینه یا بدون آن یکسان خواهد بود.

--snapshot=snapshotname

هنگام گرفتن خروجی dump از پایگاه‌داده، از snapshot همگام‌سازی‌شده‌ی مشخص‌شده استفاده کن (برای جزئیات بیشتر به جدول 9.100 مراجعه کنید).

این گزینه زمانی مفید است که نیاز به همگام‌سازی dump با یک شکاف تکثیر منطقی (logical replication slot، به فصل 47 مراجعه کنید) یا با یک نشست (session) همزمان وجود داشته باشد.

در حالت خروجی موازی (parallel dump)، به‌جای گرفتن یک snapshot جدید، از نام snapshot تعریف‌شده توسط این گزینه استفاده می‌شود.

--statistics

آمارهای بهینه‌ساز (optimizer statistics) را در خروجی قرار بده.

--statistics-only

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

--strict-names

الزام می‌کند که هر الگوی افزونه (-e/--extension)، طرح‌واره (-n/--schema) و جدول (-t/--table) حداقل با یک افزونه/طرح‌واره/جدول در پایگاه‌داده مورد نظر مطابقت داشته باشد. این موضوع برای فیلترهای استفاده‌شده با --filter نیز صدق می‌کند. توجه داشته باشید که اگر هیچ‌یک از الگوهای افزونه/طرح‌واره/جدول تطابقی پیدا نکنند، pg_dump حتی بدون --strict-names نیز خطا تولید خواهد کرد.

این گزینه تأثیری بر --exclude-extension، -N/--exclude-schema، -T/--exclude-table یا --exclude-table-data ندارد. عدم تطابق یک الگوی استثنا (exclude pattern) با هیچ شیئی، خطا محسوب نمی‌شود.

--sync-method=method

هنگامی که روی fsync تنظیم شده باشد (که حالت پیش‌فرض است)، pg_dump --format=directory تمام فایل‌های موجود در دایرکتوری بایگانی را به‌طور بازگشتی باز کرده و همگام‌سازی (sync) می‌کند.

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

این گزینه در صورتی که --no-sync استفاده شود یا --format روی directory تنظیم نشده باشد، هیچ اثری ندارد.

--table-and-children=pattern

این گزینه مشابه گزینه -t/--table است، با این تفاوت که تمام پارتیشن‌ها یا جدول‌های فرزند وراثتیِ جدول(های) منطبق بر pattern را نیز شامل می‌شود. --use-set-session-authorization
خروجی دادن دستورات استاندارد SQL SET SESSION AUTHORIZATION به جای دستورات ALTER OWNER جهت تعیین مالکیت اشیاء. این کار dump را با استانداردها سازگارتر می‌کند، اما بسته به پیشینه اشیاء موجود در خروجی، ممکن است به‌درستی بازیابی نشود. همچنین، یک dump با استفاده از SET SESSION AUTHORIZATION برای بازیابی درست مسلماً به امتیازات مدیر سیستم (superuser) نیاز خواهد داشت، در حالی که ALTER OWNER به امتیازات کمتری نیاز دارد.

-?
--help

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

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

-d dbname
--dbname=dbname

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

-h host
--host=host

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

-p port
--port=port

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

-U username
--username=username

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

-w
--no-password

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

-W
--password

اجبار pg_dump به درخواست گذرواژه پیش از اتصال به پایگاه‌داده.

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

--role=rolename

نام نقشی را که باید برای ایجاد dump استفاده شود مشخص می‌کند. این گزینه باعث می‌شود که pg_dump پس از اتصال به پایگاه‌داده، دستور SET ROLE rolename را صادر کند. این گزینه زمانی مفید است که کاربر احراز هویت‌شده (مشخص‌شده با -U) فاقد امتیازات لازم برای pg_dump است، اما می‌تواند به نقشی با حقوق دسترسی مورد نیاز جابه‌جا شود. برخی از سامانه‌ها سیاستی علیه ورود مستقیم با عنوان مدیر سیستم (superuser) دارند و استفاده از این گزینه امکان ایجاد dump را بدون نقض آن سیاست فراهم می‌کند.

PGDATABASE
PGHOST
PGOPTIONS
PGPORT
PGUSER

پارامترهای پیش‌فرض اتصال.

PG_COLOR

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

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

pg_dump به‌صورت درونی دستورهای SELECT را اجرا می‌کند. اگر در اجرای pg_dump مشکلی دارید، مطمئن شوید که می‌توانید با استفاده از، مثلاً، psql(1) اطلاعات را از پایگاه داده واکشی کنید. همچنین، هرگونه تنظیمات اتصال پیش‌فرض و متغیرهای محیطی که توسط کتابخانهٔ فرانت‌اند libpq استفاده می‌شوند اعمال خواهند شد.

فعالیت پایگاه دادهٔ pg_dump معمولاً توسط سامانهٔ آمار تجمعی جمع‌آوری می‌شود. اگر این امر مطلوب نیست، می‌توانید پارامتر track_counts را از طریق PGOPTIONS یا دستور ALTER USER روی مقدار false تنظیم کنید.

اگر کلاستر پایگاه دادهٔ شما هرگونه افزودهٔ محلی در پایگاه دادهٔ template1 دارد، دقت کنید که خروجی pg_dump را در یک پایگاه دادهٔ واقعاً خالی بازگردانی کنید؛ در غیر این صورت احتمالاً به دلیل تعاریف تکراری اشیاء اضافه‌شده با خطا مواجه خواهید شد. برای ساختن یک پایگاه دادهٔ خالی بدون هیچ افزودهٔ محلی، به جای template1 از template0 کپی بگیرید، برای مثال:

CREATE DATABASE foo WITH TEMPLATE template0;

هنگامی که یک dump بدون طرح‌واره (schema) انتخاب شده باشد و گزینهٔ --disable-triggers به کار رود، pg_dump دستوراتی را برای غیرفعال کردن تریگرها روی جدول‌های کاربری پیش از درج داده‌ها، و سپس دستوراتی را برای فعال‌سازی مجدد آن‌ها پس از درج داده‌ها صادر می‌کند. اگر فرایند بازگردانی در میانهٔ کار متوقف شود، ممکن است کاتالوگ‌های سیستم در وضعیتی نادرست رها شوند.

هنگامی که --statistics مشخص شده باشد، pg_dump بیشتر آمارهای بهینه‌ساز را در فایل dump حاصل لحاظ خواهد کرد. این امر شامل همهٔ آمارها نمی‌شود، مانند آمارهایی که صراحتاً با CREATE STATISTICS (CREATE_STATISTICS(7)) ایجاد شده‌اند، آمارهای سفارشی اضافه‌شده توسط یک افزونه، یا آمارهای جمع‌آوری‌شده توسط سامانهٔ آمار تجمعی. بنابراین، اجرای ANALYZE پس از بازگردانی از یک فایل dump ممکن است همچنان برای اطمینان از عملکرد بهینه سودمند باشد؛ برای اطلاعات بیشتر ببینید Section 24.1.3 و Section 24.1.6.

از آنجا که pg_dump برای انتقال داده‌ها به نسخه‌های جدیدتر PostgreSQL استفاده می‌شود، می‌توان انتظار داشت که خروجی pg_dump در نسخه‌های سرور PostgreSQL جدیدتر از نسخهٔ خودِ pg_dump بارگذاری شود. همچنین pg_dump می‌تواند از سرورهای PostgreSQL قدیمی‌تر از نسخهٔ خودش dump تهیه کند. (در حال حاضر، سرورها تا نسخهٔ 9.2 پشتیبانی می‌شوند.) با این حال، pg_dump نمی‌تواند از سرورهای PostgreSQL جدیدتر از نسخهٔ اصلی (major version) خودش dump تهیه کند؛ این ابزار حتی اقدام به این کار را رد می‌کند تا ریسک ایجاد یک dump نامعتبر پیش نیاید. همچنین، تضمینی وجود ندارد که خروجی pg_dump بتواند در سروری با نسخهٔ اصلی قدیمی‌تر بارگذاری شود — حتی اگر dump از سروری با همان نسخه گرفته شده باشد. بارگذاری یک فایل dump در سرور قدیمی‌تر ممکن است نیازمند ویرایش دستی فایل dump برای حذف ساختارهای نحوی باشد که توسط سرور قدیمی‌تر درک نمی‌شوند. استفاده از گزینهٔ --quote-all-identifiers در موارد بین‌نسخه‌ای توصیه می‌شود، چرا که می‌تواند از بروز مشکلات ناشی از تفاوت در فهرست واژه‌های رزروشده در نسخه‌های مختلف PostgreSQL جلوگیری کند.

هنگام گرفتن dump از اشتراک‌های تکثیر منطقی (logical replication subscriptions)، دستور pg_dump فرمان‌های CREATE SUBSCRIPTION را طوری تولید می‌کند که از گزینهٔ connect = false استفاده کنند تا بازگردانی اشتراک اتصالات از راه دور برای ایجاد یک replication slot یا کپی اولیهٔ جدول برقرار نکند. بدین ترتیب، فایل dump می‌تواند بدون نیاز به دسترسی شبکه به سرورهای راه دور بازگردانی شود. پس از آن، فعال‌سازی مجدد اشتراک‌ها به روشی مناسب بر عهدهٔ کاربر خواهد بود. اگر میزبان‌های مربوطه تغییر کرده باشند، ممکن است اطلاعات اتصال نیاز به تغییر داشته باشد. همچنین ممکن است خالی کردن (truncate) جدول‌های مقصد پیش از آغاز یک کپی کامل جدید از جدول مناسب باشد. اگر کاربران قصد دارند داده‌های اولیه را در حین نوسازی کپی کنند، باید slot را با two_phase = false بسازند. پس از همگام‌سازی اولیه، اگر اشتراک در اصل با گزینهٔ two_phase = true ایجاد شده باشد، گزینهٔ two_phase به‌طور خودکار توسط مشترک (subscriber) فعال خواهد شد.

به‌طور کلی توصیه می‌شود هنگام بازگردانی یک پایگاه داده از اسکریپت متنی سادهٔ pg_dump از گزینهٔ -X (--no-psqlrc) استفاده کنید تا از یک فرایند بازگردانی تمیز اطمینان حاصل شود و از تداخل‌های احتمالی با پیکربندی‌های غیرپیش‌فرض psql جلوگیری به عمل آید..SH "مثال‌ها (EXAMPLES)"

برای استخراج پایگاه داده‌ای با نام mydb به یک فایل اسکریپت SQL:

$ pg_dump mydb > db.sql

برای بارگذاری مجدد چنین اسکریپتی در یک پایگاه داده (به‌تازگی ایجادشده) با نام newdb:

$ psql -X -d newdb -f db.sql

برای استخراج یک پایگاه داده در یک فایل آرشیو با قالب سفارشی (custom-format):

$ pg_dump -Fc mydb > db.dump

برای استخراج یک پایگاه داده در یک آرشیو با قالب دایرکتوری (directory-format):

$ pg_dump -Fd mydb -f dumpdir

برای استخراج یک پایگاه داده در یک آرشیو با قالب دایرکتوری به‌صورت موازی با ۵ وظیفهٔ کارگر (worker job):

$ pg_dump -Fd mydb -j 5 -f dumpdir

برای بارگذاری مجدد یک فایل آرشیو در یک پایگاه داده (به‌تازگی ایجادشده) با نام newdb:

$ pg_restore -d newdb db.dump

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

$ pg_restore -d postgres --clean --create db.dump

برای استخراج یک جدول مشخص با نام mytab:

$ pg_dump -t mytab mydb > db.sql

برای استخراج تمام جدول‌هایی در طرح‌وارهٔ (schema) detroit که نام آن‌ها با emp شروع می‌شود، به استثنای جدول نام‌گذاری‌شده به employee_log:

$ pg_dump -t 'detroit.emp*' -T detroit.employee_log mydb > db.sql

برای استخراج تمام طرح‌واره‌هایی که نام آن‌ها با east یا west شروع شده و به gsm ختم می‌شود، به استثنای هر طرح‌واره‌ای که نام آن شامل کلمهٔ test باشد:

$ pg_dump -n 'east*gsm' -n 'west*gsm' -N '*test*' mydb > db.sql

همان حالت، با استفاده از نمادگذاری عبارت باقاعده (regular expression) برای ادغام گزینه‌ها:

$ pg_dump -n '(east|west)*gsm' -N '*test*' mydb > db.sql

برای استخراج تمام اشیای پایگاه داده به استثنای جدول‌هایی که نام آن‌ها با ts_ آغاز می‌شود:

$ pg_dump -T 'ts_*' mydb > db.sql

برای مشخص کردن نامی با حروف بزرگ (upper-case) یا ترکیبی از حروف کوچک و بزرگ (mixed-case) در -t و گزینه‌های مرتبط، باید نام را درون علامت نقل‌قول جفتی (double quote) قرار دهید؛ در غیر این صورت به حروف کوچک تبدیل خواهد شد (بخش الگوها (Patterns) را ببینید). اما علامت‌های نقل‌قول جفتی برای پوسته (shell) کاراکتر خاص محسوب می‌شوند، بنابراین خود آن‌ها نیز باید نقل‌قول‌بندی شوند. بنابراین، برای استخراج یک جدول منفرد با نامی مرکب از حروف کوچک و بزرگ، به چیزی شبیه به این نیاز خواهید داشت

$ pg_dump -t "\"MixedCaseName\"" mydb > mytab.sql

برای استخراج تمام جدول‌هایی که نام آن‌ها با mytable آغاز می‌شود، به استثنای جدول mytable2 یک فایل فیلتر به نام filter.txt را مانند زیر مشخص کنید:.sp

include table mytable*
exclude table mytable2
$ pg_dump --filter=filter.txt mydb > db.sql

pg_dumpall(1), pg_restore(1), psql(1)

2026 PostgreSQL 18.6