PG_RESTORE(1) PostgreSQL 18.6 Documentation PG_RESTORE(1)

pg_restore - بازیابی یک پایگاه داده PostgreSQL از یک فایل بایگانی ایجاد شده توسط pg_dump

pg_restore [connection-option...] [option...] [filename]

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

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

بدیهی است که pg_restore نمی‌تواند اطلاعاتی را که در فایل بایگانی وجود ندارد بازیابی کند. برای مثال، اگر بایگانی با استفاده از گزینهٔ “تخلیه داده‌ها به‌صورت دستورهای INSERT” ایجاد شده باشد، pg_restore قادر نخواهد بود داده‌ها را با استفاده از دستورهای COPY بارگذاری کند.


هشدار

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

pg_restore آرگومان‌های خط فرمان زیر را می‌پذیرد.

filename

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

-a
--data-only

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

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

-c
--clean

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

-C
--create

پایگاه داده را پیش از بازیابی اطلاعات درون آن ایجاد می‌کند. اگر --clean نیز مشخص شده باشد، پایگاه داده هدف را پیش از اتصال به آن حذف و دوباره ایجاد می‌کند.

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

هنگامی که از این گزینه استفاده می‌شود، از پایگاه داده مشخص‌شده با -d تنها برای صدور دستورهای اولیهٔ DROP DATABASE و CREATE DATABASE استفاده می‌شود. تمامی داده‌ها در پایگاه داده‌ای با نام درج‌شده در بایگانی بازیابی می‌شوند.

-d dbname
--dbname=dbname

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

-e
--exit-on-error

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

-f filename
--file=filename

فایل خروجی را برای اسکریپت تولیدشده، یا برای فهرست هنگام استفاده به همراه -l مشخص می‌کند. برای stdout از - استفاده کنید.

-F format
--format=format

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

c
custom

بایگانی در قالب سفارشی (custom) متعلق به pg_dump است.

d
directory

بایگانی یک بایگانی دایرکتوری (directory) است.

t
tar

بایگانی یک بایگانی tar است.

-I index
--index=index

تنها تعریف شاخص (index) نام‌برده را بازیابی می‌کند. با چندین سوئیچ -I می‌توان چندین شاخص را مشخص کرد.

-j number-of-jobs
--jobs=number-of-jobs

زمان‌برترین مراحل pg_restore — آن‌هایی که داده‌ها را بارگذاری می‌کنند، شاخص‌ها را ایجاد می‌کنند یا قیدها را می‌سازند — را به طور همزمان با استفاده از حداکثر number-of-jobs نشست همزمان اجرا می‌کند. این گزینه می‌تواند زمان بازیابی یک پایگاه داده بزرگ را روی سروری که روی یک ماشین چندپردازنده‌ای اجرا می‌شود، به طور چشمگیری کاهش دهد. هنگام خروجی گرفتن به صورت اسکریپت به جای اتصال مستقیم به سرور پایگاه داده، از این گزینه صرف‌نظر می‌شود.

هر کار (job) بسته به سیستم‌عامل، یک فرایند یا یک ریسه (thread) است و از یک اتصال مجزا به سرور استفاده می‌کند.

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

با این گزینه تنها قالب‌های بایگانی custom و directory پشتیبانی می‌شوند. ورودی باید یک فایل عادی یا دایرکتوری باشد (نه برای مثال یک pipe یا ورودی استاندارد). همچنین نمی‌توان از چند کار به طور همزمان به همراه گزینهٔ --single-transaction استفاده کرد.

-l
--list

فهرست محتویات بایگانی را لیست می‌کند. خروجی این عملیات می‌تواند به عنوان ورودی برای گزینهٔ -L استفاده شود. توجه داشته باشید که اگر سوئیچ‌های پالایشی مانند -n یا -t به همراه -l استفاده شوند، موارد فهرست‌شده را محدود خواهند کرد.

-L list-file
--use-list=list-file

تنها آن دسته از عناصر بایگانی را بازیابی می‌کند که در list-file فهرست شده‌اند، و آن‌ها را به ترتیبی که در فایل آمده‌اند بازیابی می‌کند. توجه داشته باشید که اگر سوئیچ‌های پالایشی مانند -n یا -t به همراه -L استفاده شوند، موارد بازیابی‌شده را بیش از پیش محدود خواهند کرد.

فایل list-file معمولاً با ویرایش خروجی یک عملیات قبلی -l ایجاد می‌شود. خطوط را می‌توان جابجا یا حذف کرد، و همچنین می‌توان با قرار دادن یک نقطه‌ویرگول (;) در ابتدای سطر، آن‌ها را تبدیل به توضیح کرد. برای مثال‌ها به ادامه مراجعه کنید. -n schema
--schema=schema

تنها اشیائی را بازیابی می‌کند که در طرح‌وارهٔ (schema) نام‌برده قرار دارند. چندین طرح‌واره را می‌توان با چند سوئیچ -n مشخص کرد. این گزینه می‌تواند با گزینهٔ -t برای بازیابی تنها یک جدول خاص ترکیب شود.

-N schema
--exclude-schema=schema

اشیائی را که در طرح‌وارهٔ نام‌برده قرار دارند بازیابی نمی‌کند. چندین طرح‌واره برای مستثنی شدن را می‌توان با چند سوئیچ -N مشخص کرد.

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

-O
--no-owner

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

-P function-name(argtype [, ...])
--function=function-name(argtype [, ...])

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

-R
--no-reconnect

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

-s
--schema-only

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

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

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

-S username
--superuser=username

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

-t table
--table=table

تعریف و/یا داده‌های تنها جدول نام‌برده را بازیابی می‌کند. برای این منظور، “table” شامل نماها (views)، نماهای مادی‌شده (materialized views)، توالی‌ها (sequences) و جدول‌های خارجی (foreign tables) نیز می‌شود. با درج چندین سوئیچ -t می‌توان چندین جدول را انتخاب کرد. این گزینه می‌تواند با گزینهٔ -n برای مشخص کردن جدول(ها) در یک طرح‌وارهٔ خاص ترکیب شود.

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

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

نکته
در نسخه‌های پیش از PostgreSQL 9.6، این پرچم تنها با جدول‌ها مطابقت داشت، نه با هیچ نوع رابطهٔ (relation) دیگر.

-T trigger
--trigger=trigger

تنها تریگرِ نام‌برده را بازیابی می‌کند. چندین تریگر را می‌توان با چند سوئیچ -T مشخص کرد.

-v
--verbose

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

-V
--version

نسخهٔ pg_restore را چاپ کرده و خارج می‌شود. -x
--no-privileges
--no-acl
از بازیابی امتیازات دسترسی (دستورهای grant/revoke) جلوگیری می‌کند.

-1
--single-transaction

بازیابی را به عنوان یک تراکنش واحد اجرا می‌کند (یعنی دستورهای صادرشده را درون BEGIN/COMMIT قرار می‌دهد). این امر تضمین می‌کند که یا همه دستورها با موفقیت به پایان برسند، یا هیچ تغییری اعمال نشود. این گزینه به‌طور ضمنی شامل --exit-on-error است.

--disable-triggers

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

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

--enable-row-security

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

توجه داشته باشید که این گزینه در حال حاضر نیازمند این است که فایل پشتیبان در قالب INSERT باشد، زیرا COPY FROM از row security پشتیبانی نمی‌کند.

--filter=filename

نام فایلی را مشخص می‌کند که الگوهای مربوط به اشیاء مستثنی یا گنجانده‌شده در بازیابی از آن خوانده شود. این الگوها طبق همان قواعد -n/--schema برای گنجاندن اشیاء در طرحواره‌ها، -N/--exclude-schema برای مستثنی کردن اشیاء در طرحواره‌ها، -P/--function برای بازیابی توابع مشخص‌شده، -I/--index برای بازیابی نمایه‌های (indexes) مشخص‌شده، -t/--table برای بازیابی جدول‌های مشخص‌شده یا -T/--trigger برای بازیابی تریگرها تفسیر می‌شوند. برای خواندن از STDIN، از - به عنوان نام فایل استفاده کنید. گزینه --filter می‌تواند همراه با گزینه‌های ذکر شده در بالا برای گنجاندن یا مستثنی کردن اشیاء مشخص شود، و همچنین می‌توان آن را چندین بار برای تعیین چندین فایل فیلتر به کار برد.

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

{ include | exclude } { function | index | schema | table | trigger } PATTERN

نخستین کلیدواژه مشخص می‌کند که آیا اشیاء منطبق با الگو باید گنجانده (include) یا مستثنی (exclude) شوند. کلیدواژه دوم نوع شیء مورد نظر برای فیلتر شدن با الگو را تعیین می‌کند:

•function: توابع؛ مانند گزینه -P/--function عمل می‌کند. این کلیدواژه تنها همراه با کلیدواژه include قابل استفاده است.
•index: نمایه‌ها؛ مانند گزینه -I/--indexes عمل می‌کند. این کلیدواژه تنها همراه با کلیدواژه include قابل استفاده است.
•schema: طرحواره‌ها؛ مانند گزینه‌های -n/--schema و -N/--exclude-schema عمل می‌کند.
•table: جدول‌ها؛ مانند گزینه -t/--table عمل می‌کند. این کلیدواژه تنها همراه با کلیدواژه include قابل استفاده است.
•trigger: تریگرها؛ مانند گزینه -T/--trigger عمل می‌کند. این کلیدواژه تنها همراه با کلیدواژه include قابل استفاده است.

سطرهایی که با # آغاز می‌شوند به عنوان یادداشت (کامنت) تلقی شده و نادیده گرفته می‌شوند. همچنین می‌توان کامنت‌ها را بعد از یک سطر الگوی شیء قرار داد. سطرهای خالی نیز نادیده گرفته می‌شوند. برای آگاهی از نحوه نقل‌قول کردن (quoting) در الگوها، بخش Patterns را مشاهده کنید.

--if-exists

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

--no-data

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

--no-data-for-failed-tables

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

این گزینه تنها زمانی مؤثر است که بازیابی مستقیماً در یک پایگاه داده انجام شود، نه هنگام تولید خروجی اسکریپت SQL.

--no-policies

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

--no-publications

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

--no-schema

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

--no-security-labels

دستورات بازیابی برچسب‌های امنیتی را در خروجی قرار نده، حتی اگر بایگانی شامل آن‌ها باشد.

--no-statistics

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

--no-subscriptions

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

--no-table-access-method

دستوراتی برای انتخاب روش‌های دسترسی به جدول (table access methods) در خروجی قرار نده. با این گزینه، تمام اشیاء با هر روش دسترسی به جدولی که در حین بازیابی پیش‌فرض است ایجاد خواهند شد.

--no-tablespaces

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

--restrict-key=restrict_key

از رشته ارائه شده به عنوان کلید \restrict در psql برای خروجی dump استفاده کن. این مورد تنها می‌تواند برای خروجی اسکریپت SQL مشخص شود، یعنی زمانی که گزینه --file استفاده شده باشد. اگر هیچ کلید محدودیتی مشخص نشده باشد، pg_restore در صورت نیاز یک کلید تصادفی تولید خواهد کرد. کلیدها ممکن است فقط شامل نویسه‌های الفبایی‌عددی باشند.

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

--section=sectionname

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

بخش data شامل داده‌های واقعی جدول و همچنین تعاریف اشیاء بزرگ (large-object) است. موارد post-data شامل تعاریف نمایه‌ها (indexes)، تریگرها (triggers)، قوانین (rules) و قیود (constraints) به غیر از قیود اعتبارسنجی‌شده‌ی check است. موارد pre-data شامل تمامی موارد دیگر تعریف داده است.

--statistics

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

--statistics-only

تنها آمارها را بازیابی کن، نه شِما (تعاریف داده) یا داده‌ها را.

--strict-names

الزام می‌کند که هر مشخص‌کننده‌ی شِما (-n/--schema) و جدول (-t/--table) حداقل با یک شِما/جدول در فایل در حال بازیابی مطابقت داشته باشد.

--transaction-size=N

بازیابی را به صورت مجموعه‌ای از تراکنش‌ها اجرا کن که هر کدام حداکثر تا N شیء پایگاه داده را پردازش می‌کنند. این گزینه مستلزم --exit-on-error است.

گزینه --transaction-size انتخابی بینابینی میان رفتار پیش‌فرض (یک تراکنش به ازای هر دستور SQL) و -1/--single-transaction (یک تراکنش برای تمام اشیاء بازیابی‌شده) ارائه می‌دهد. در حالی که --single-transaction کمترین بار اضافی (overhead) را دارد، ممکن است برای پایگاه‌های داده بزرگ غیرعملی باشد زیرا تراکنش روی هر شیء بازیابی‌شده یک قفل می‌گیرد که این امر احتمالاً فضای جدول قفل (lock table space) سرور را به اتمام می‌رساند. استفاده از --transaction-size با اندازه‌ای در حدود چند هزار شیء، تقریباً همان مزایای عملکردی را فراهم می‌کند و در عین حال میزان فضای مورد نیاز جدول قفل را محدود می‌سازد.

--use-set-session-authorization

برای تعیین مالکیت شیء، به جای دستورات ALTER OWNER، دستورات استاندارد SQL یعنی SET SESSION AUTHORIZATION را در خروجی قرار بده. این کار dump را با استانداردها سازگارتر می‌کند، اما بسته به پیشینه اشیاء درون dump، ممکن است به درستی بازیابی نشود.

-?
--help

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

ابزار pg_restore همچنین آرگومان‌های خط فرمان زیر را برای پارامترهای اتصال می‌پذیرد:

-h host
--host=host

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

-p port
--port=port

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

-U username
--username=username

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

-w
--no-password

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

-W
--password

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

--role=rolename

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

PGHOST
PGOPTIONS
PGPORT
PGUSER

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

PG_COLOR

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

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

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

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

CREATE DATABASE foo WITH TEMPLATE template0;

محدودیت‌های pg_restore در زیر با جزئیات آمده است.

•هنگام بازیابی داده‌ها به یک جدول از پیش موجود و در صورت استفاده از گزینهٔ --disable-triggers، pg_restore پیش از درج داده‌ها، دستوراتی را برای غیرفعال کردن تریگرها روی جداول کاربر صادر می‌کند، سپس دستوراتی برای فعال‌سازی مجدد آن‌ها پس از درج داده‌ها صادر می‌نماید. اگر بازیابی در میانهٔ کار متوقف شود، کاتالوگ‌های سیستم ممکن است در وضعیتی نادرست رها شوند.
•pg_restore نمی‌تواند اشیاء بزرگ (large objects) را به‌طور گزینشی بازیابی کند؛ برای نمونه، فقط مواردی را که متعلق به یک جدول خاص هستند. اگر یک بایگانی شامل اشیاء بزرگ باشد، تمام اشیاء بزرگ بازیابی خواهند شد، یا در صورتی که از طریق گزینه‌های -L، -t یا سایر گزینه‌ها مستثنی شده باشند، هیچ‌کدام بازیابی نمی‌شوند.

همچنین برای جزئیات بیشتر دربارهٔ محدودیت‌های pg_dump، مستندات pg_dump(1) را ببینید.

به‌طور پیش‌فرض، اگر آمارهای بهینه‌ساز در فایل روگرفت (dump) موجود باشند، pg_restore آن‌ها را بازیابی خواهد کرد. اگر همهٔ آمارها بازیابی نشدند، ممکن است اجرای ANALYZE روی هر جدول بازیابی‌شده مفید باشد تا بهینه‌ساز به آمارهای سودمندی دسترسی داشته باشد؛ برای اطلاعات بیشتر به بخش 24.1.3 و بخش 24.1.6 مراجعه کنید..SH "مثال‌ها (EXAMPLES)"

فرض کنید از پایگاه داده‌ای به نام mydb در یک فایل دامپ با قالب سفارشی (custom-format) خروجی گرفته‌ایم:

$ pg_dump -Fc mydb > db.dump

برای حذف پایگاه داده و ایجاد مجدد آن از فایل دامپ:

$ dropdb mydb
$ pg_restore -C -d postgres db.dump

پایگاه داده مشخص‌شده در سوییچ -d می‌تواند هر پایگاه داده موجود در کلاستر باشد؛ pg_restore تنها از آن برای صدور دستور CREATE DATABASE برای mydb استفاده می‌کند. با گزینه -C، داده‌ها همیشه در پایگاه داده‌ای با نام درج‌شده در فایل دامپ بازیابی می‌شوند.

برای بازیابی فایل دامپ در یک پایگاه داده جدید به نام newdb:

$ createdb -T template0 newdb
$ pg_restore -d newdb db.dump

توجه داشته باشید که از -C استفاده نمی‌کنیم و در عوض مستقیماً به پایگاه داده‌ای متصل می‌شویم که قرار است داده‌ها در آن بازیابی شوند. همچنین توجه داشته باشید که پایگاه داده جدید را از روی template0 شبیه‌سازی می‌کنیم، نه template1، تا اطمینان حاصل شود که در ابتدا کاملاً خالی است.

برای تغییر ترتیب آیتم‌های پایگاه داده، ابتدا لازم است فهرست محتویات (table of contents) آرشیو استخراج شود:

$ pg_restore -l db.dump > db.list

فایل فهرست شامل یک سربرگ و یک خط برای هر آیتم است؛ برای مثال:

;
; Archive created at Mon Sep 14 13:55:39 2009
;     dbname: DBDEMOS
;     TOC Entries: 81
;     Compression: 9
;     Dump Version: 1.10-0
;     Format: CUSTOM
;     Integer: 4 bytes
;     Offset: 8 bytes
;     Dumped from database version: 8.3.5
;     Dumped by pg_dump version: 8.3.8
;
;
; Selected TOC Entries:
;
3; 2615 2200 SCHEMA - public pasha
1861; 0 0 COMMENT - SCHEMA public pasha
1862; 0 0 ACL - public pasha
317; 1247 17715 TYPE public composite pasha
319; 1247 25899 DOMAIN public domain0 pasha

علامت‌های نقطه‌ویرگول (;) نشان‌دهنده کامنت هستند و اعداد ابتدای خطوط به شناسه داخلی آرشیو (internal archive ID) اختصاص‌یافته به هر آیتم اشاره دارند.

خطوط درون فایل را می‌توان کامنت کرد، حذف نمود و ترتیب آن‌ها را تغییر داد. برای مثال:

10; 145433 TABLE map_resolutions postgres
;2; 145344 TABLE species postgres
;4; 145359 TABLE nt_header postgres
6; 145402 TABLE species_records postgres
;8; 145416 TABLE ss_old postgres

می‌تواند به عنوان ورودی برای pg_restore استفاده شود و تنها آیتم‌های 10 و 6 را با همان ترتیب بازیابی خواهد کرد:

$ pg_restore -L db.list db.dump
pg_dump(1), pg_dumpall(1), psql(1)
2026 PostgreSQL 18.6