PG_AMCHECK(1) PostgreSQL 18.6 Documentation PG_AMCHECK(1)

pg_amcheck - بررسی خرابی در یک یا چند پایگاه داده PostgreSQL

pg_amcheck [option...] [dbname]

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

در حال حاضر تنها رابطه‌های جدول معمولی و toast، نماهای مادی‌سازی‌شده (materialized views)، توالی‌ها (sequences) و نمایه‌های btree پشتیبانی می‌شوند. از سایر انواع رابطه‌ها بدون نمایش پیامی صرف‌نظر می‌شود.

اگر dbname مشخص شده باشد، باید نام یک پایگاه داده تکی برای بررسی باشد و هیچ گزینهٔ دیگری برای انتخاب پایگاه داده نباید وجود داشته باشد. در غیر این صورت، اگر هر یک از گزینه‌های انتخاب پایگاه داده مشخص شده باشند، تمام پایگاه‌های دادهٔ منطبق بررسی خواهند شد. در صورت عدم وجود چنین گزینه‌هایی، پایگاه دادهٔ پیش‌فرض بررسی می‌شود. گزینه‌های انتخاب پایگاه داده شامل --all، --database و --exclude-database هستند. این گزینه‌ها همچنین شامل --relation، --exclude-relation، --table، --exclude-table، --index و --exclude-index می‌شوند، اما تنها زمانی که این گزینه‌ها همراه با یک الگوی سه‌بخشی (به عنوان مثال mydb*.myschema*.myrel*) به کار روند. در نهایت، شامل --schema و --exclude-schema نیز هستند هنگامی که با یک الگوی دو‌بخشی (به عنوان مثال mydb*.myschema*) استفاده شوند.

dbname می‌تواند یک رشتهٔ اتصال (connection string) نیز باشد.

گزینه‌های خط فرمان زیر مشخص می‌کنند چه مواردی بررسی شوند:

-a
--all

تمام پایگاه‌های داده را بررسی می‌کند، به جز مواردی که با --exclude-database مستثنی شده‌اند.

-d pattern
--database=pattern

پایگاه‌های دادهٔ منطبق با pattern مشخص‌شده را بررسی می‌کند، به جز مواردی که توسط --exclude-database مستثنی شده‌اند. این گزینه می‌تواند بیش از یک بار مشخص شود.

-D pattern
--exclude-database=pattern

پایگاه‌های دادهٔ منطبق با pattern داده‌شده را مستثنی می‌کند. این گزینه می‌تواند بیش از یک بار مشخص شود.

-i pattern
--index=pattern

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

این گزینه مشابه با گزینهٔ --relation است، با این تفاوت که تنها برای نمایه‌ها اعمال می‌شود و شامل سایر انواع رابطه‌ها نمی‌شود.

-I pattern
--exclude-index=pattern

نمایه‌های منطبق با pattern مشخص‌شده را مستثنی می‌کند. این گزینه می‌تواند بیش از یک بار مشخص شود.

این گزینه مشابه با گزینهٔ --exclude-relation است، با این تفاوت که تنها برای نمایه‌ها اعمال می‌شود، نه سایر انواع رابطه‌ها.

-r pattern
--relation=pattern

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

الگوها می‌توانند نامقید (unqualified) باشند، مانند myrel*، یا دارای قید طرح‌واره (schema-qualified) باشند، مانند myschema*.myrel* یا دارای قید پایگاه داده و طرح‌واره، مانند mydb*.myschema*.myrel*. یک الگوی مقید به پایگاه داده، پایگاه‌های دادهٔ منطبق را به فهرست پایگاه‌های داده‌ای که باید بررسی شوند اضافه خواهد کرد.

-R pattern
--exclude-relation=pattern

رابطه‌های منطبق با pattern مشخص‌شده را مستثنی می‌کند. این گزینه می‌تواند بیش از یک بار مشخص شود.

همانند --relation، الگوی pattern می‌تواند نامقید، مقید به طرح‌واره، یا مقید به پایگاه داده و طرح‌واره باشد.

-s pattern
--schema=pattern

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

برای انتخاب صرفاً جدول‌ها در طرح‌واره‌های منطبق با یک الگوی خاص، می‌توانید از عبارتی مانند --table=SCHEMAPAT.* --no-dependent-indexes استفاده کنید. برای انتخاب صرفاً نمایه‌ها، از عبارتی مانند --index=SCHEMAPAT.* استفاده کنید.

الگوی طرح‌واره می‌تواند مقید به پایگاه داده باشد. برای نمونه، می‌توانید بنویسید --schema=mydb*.myschema* تا طرح‌واره‌های منطبق با myschema* در پایگاه‌های دادهٔ منطبق با mydb* انتخاب شوند.

-S pattern
--exclude-schema=pattern

جدول‌ها و نمایه‌های موجود در طرح‌واره‌های منطبق با pattern مشخص‌شده را مستثنی می‌کند. این گزینه می‌تواند بیش از یک بار مشخص شود.

همانند --schema، الگو می‌تواند مقید به پایگاه داده باشد.

-t pattern
--table=pattern

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

این گزینه مشابه با گزینهٔ --relation است، با این تفاوت که تنها برای جدول‌ها، نماهای مادی‌سازی‌شده و دنباله‌ها اعمال می‌شود، نه نمایه‌ها.

-T pattern
--exclude-table=pattern

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

این گزینه مشابه با گزینهٔ --exclude-relation است، با این تفاوت که تنها برای جدول‌ها، نماهای مادی‌سازی‌شده و دنباله‌ها اعمال می‌شود، نه نمایه‌ها.

--no-dependent-indexes

به‌طور پیش‌فرض، اگر جدولی بررسی شود، تمام نمایه‌های btree آن جدول نیز بررسی خواهند شد، حتی اگر صراحتاً توسط گزینه‌ای مانند --index یا --relation انتخاب نشده باشند. این گزینه این رفتار را غیرفعال می‌کند. --no-dependent-toast
به‌طور پیش‌فرض، اگر یک جدول بررسی شود، جدول toast آن (در صورت وجود) نیز بررسی خواهد شد، حتی اگر صریحاً توسط گزینه‌ای مانند --table یا --relation انتخاب نشده باشد. این گزینه این رفتار را لغو می‌کند.

--no-strict-names

به‌طور پیش‌فرض، اگر آرگومانی به --database، --table، --index یا --relation با هیچ شیئی مطابقت نداشته باشد، یک خطای مهلک است. این گزینه آن خطا را به یک هشدار تنزل می‌دهد.

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

--exclude-toast-pointers

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

--on-error-stop

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

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

--skip=option

اگر all-frozen داده شود، بررسی‌های خرابی جدول از صفحاتی در تمام جدول‌ها که به عنوان all frozen علامت‌گذاری شده‌اند صرف‌نظر خواهد کرد.

اگر all-visible داده شود، بررسی‌های خرابی جدول از صفحاتی در تمام جدول‌ها که به عنوان all visible علامت‌گذاری شده‌اند صرف‌نظر خواهد کرد.

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

--startblock=block

بررسی را از شماره بلوک مشخص‌شده آغاز می‌کند. اگر relation جدول در حال بررسی، کمتر از این تعداد بلوک داشته باشد، خطایی رخ خواهد داد. این گزینه برای نمایه‌ها اعمال نمی‌شود و احتمالاً تنها هنگام بررسی یک relation جدول منفرد مفید است. برای هشدارهای بیشتر به --endblock مراجعه کنید.

--endblock=block

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

گزینه‌های خط فرمان زیر، بررسی نمایه‌های B-tree را کنترل می‌کنند:

--checkunique

به ازای هر نمایه با قید یکتایی که بررسی می‌شود، با استفاده از گزینه checkunique در amcheck، بررسی می‌کند که بیش از یکی از مدخل‌های تکراری در نمایه قابل مشاهده نباشد.

--heapallindexed

به ازای هر نمایهٔ بررسی‌شده، با استفاده از گزینه heapallindexed در amcheck، حضور تمام تاپل‌های heap به عنوان تاپل‌های نمایه در نمایه را تأیید می‌کند.

--parent-check

به ازای هر نمایهٔ btree که بررسی می‌شود، از تابع bt_index_parent_check در amcheck استفاده می‌کند که بررسی‌های بیشتری را روی روابط والد/فرزند در طول بررسی نمایه انجام می‌دهد.

حالت پیش‌فرض استفاده از تابع bt_index_check در amcheck است، اما توجه داشته باشید که استفاده از گزینه --rootdescend به طور ضمنی bt_index_parent_check را انتخاب می‌کند.

--rootdescend

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

استفاده از این گزینه به‌طور ضمنی گزینه --parent-check را نیز انتخاب می‌کند.

این شکل از اعتبارسنجی در اصل برای کمک به توسعه ویژگی‌های نمایه btree نوشته شده بود. این گزینه ممکن است کاربرد محدودی داشته باشد یا حتی در کمک به شناسایی انواع خرابی‌هایی که در عمل رخ می‌دهند هیچ کاربردی نداشته باشد. همچنین ممکن است باعث شود بررسی خرابی بسیار طولانی‌تر شود و منابع بسیار بیشتری را روی سرور مصرف کند.


هشدار

بررسی‌های اضافی انجام‌شده روی نمایه‌های B-tree هنگام مشخص شدن گزینه --parent-check یا گزینه --rootdescend، به قفل‌های نسبتاً قوی در سطح relation نیاز دارند. این بررسی‌ها تنها بررسی‌هایی هستند که تغییر هم‌روند داده توسط دستورهای INSERT، UPDATE و DELETE را مسدود می‌کنند.

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

-h hostname
--host=hostname

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

-p port
--port=port

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

-U
--username=username

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

-w
--no-password

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

-W
--password

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

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

--maintenance-db=dbname

یک پایگاه‌داده یا connection string را مشخص می‌کند که برای کشف فهرست پایگاه‌های داده‌ای که باید بررسی شوند به کار رود. اگر نه از --all و نه از هیچ گزینه‌ای شامل الگوی پایگاه‌داده استفاده نشده باشد، چنین اتصالی لازم نیست و این گزینه کاری انجام نمی‌دهد. در غیر این صورت، هر پارامتر connection string به‌جز نام پایگاه‌داده که در مقدار این گزینه گنجانده شده باشد، هنگام اتصال به پایگاه‌های داده در حال بررسی نیز استفاده خواهد شد. اگر این گزینه نادیده گرفته شود، مقدار پیش‌فرض postgres یا در صورت عدم موفقیت آن، template1 است.

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

-e
--echo

تمام دستورات SQL ارسال‌شده به سرور را در stdout بازتاب (echo) می‌کند. -j num
--jobs=num
استفاده از num اتصال هم‌روند به سرور، یا یک اتصال به ازای هر شیء برای بررسی، هر کدام که کمتر باشد.

پیش‌فرض استفاده از یک اتصال منفرد است.

-P
--progress

نمایش اطلاعات پیشرفت کار. اطلاعات پیشرفت شامل تعداد رابطه‌هایی است که بررسی آن‌ها تکمیل شده است، و اندازهٔ کل آن رابطه‌ها. همچنین شامل تعداد کل رابطه‌هایی است که در نهایت بررسی خواهند شد، و اندازهٔ تخمینی آن رابطه‌ها.

-v
--verbose

چاپ پیام‌های بیشتر. به‌ویژه، این گزینه برای هر رابطه‌ای که در حال بررسی است پیامی چاپ می‌کند و سطح جزئیات ارائه‌شده برای خطاهای سرور را افزایش می‌دهد.

-V
--version

چاپ نسخهٔ pg_amcheck و خروج.

--install-missing
--install-missing=schema

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

در حال حاضر، تنها افزونهٔ مورد نیاز amcheck است.

-?
--help

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

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

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

pg_amcheck برای کار با PostgreSQL نسخهٔ 14.0 و بالاتر طراحی شده است.

amcheck

2026 PostgreSQL 18.6