PG_CTL(1) PostgreSQL 18.6 Documentation PG_CTL(1)

pg_ctl - مقداردهی اولیه، راه‌اندازی، متوقف‌سازی یا کنترل یک سرور PostgreSQL

pg_ctl init[db] [-D datadir] [-s] [-o initdb-options]

pg_ctl start [-D datadir] [-l filename] [-W] [-t seconds] [-s] [-o options] [-p path] [-c]

pg_ctl stop [-D datadir] [-m s[mart] | f[ast] | i[mmediate]] [-W] [-t seconds] [-s]

pg_ctl restart [-D datadir] [-m s[mart] | f[ast] | i[mmediate]] [-W] [-t seconds] [-s] [-o options] [-c]

pg_ctl reload [-D datadir] [-s]

pg_ctl status [-D datadir]

pg_ctl promote [-D datadir] [-W] [-t seconds] [-s]

pg_ctl logrotate [-D datadir] [-s]

pg_ctl kill signal_name process_id

همچنین در Microsoft Windows:

pg_ctl register [-D datadir] [-N servicename] [-U username] [-P password] [-S a[uto] | d[emand]] [-e source] [-W] [-t seconds] [-s] [-o options]

pg_ctl unregister [-N servicename]

ابزار pg_ctl برای مقداردهی اولیهٔ یک کلاستر پایگاه‌دادهٔ PostgreSQL، راه‌اندازی، متوقف‌سازی یا راه‌اندازی مجدد سرور پایگاه‌دادهٔ PostgreSQL (postgres(1))، یا نمایش وضعیت یک سرور در حال اجرا به کار می‌رود. اگرچه سرور می‌تواند به‌صورت دستی نیز راه‌اندازی شود، pg_ctl وظایفی مانند تغییر مسیر خروجی گزارش‌ها (logs) و جدا شدن مناسب از ترمینال و گروه فرایند (process group) را کپسوله‌سازی می‌کند. این ابزار همچنین گزینه‌های مناسبی برای خاموش‌سازی کنترل‌شده فراهم می‌آورد.

حالت init یا initdb یک کلاستر پایگاه‌دادهٔ جدید PostgreSQL ایجاد می‌کند؛ یعنی مجموعه‌ای از پایگاه‌های داده که توسط یک نمونهٔ واحد از سرور مدیریت خواهند شد. این حالت دستور initdb را فراخوانی می‌کند. برای جزئیات به initdb(1) مراجعه کنید.

حالت start یک سرور جدید را راه‌اندازی می‌کند. سرور در پس‌زمینه اجرا می‌شود و ورودی استاندارد آن به /dev/null (یا در ویندوز به nul) متصل می‌گردد. در سیستم‌های شبه‌یونیکس، به‌طور پیش‌فرض، خروجی استاندارد و خطای استاندارد سرور به خروجی استاندارد pg_ctl (نه خطای استاندارد آن) فرستاده می‌شوند. در این حالت، خروجی استاندارد pg_ctl باید به یک فایل هدایت شود یا از طریق لوله (pipe) به فرایند دیگری مانند یک برنامهٔ چرخش گزارش‌ها نظیر rotatelogs فرستاده شود؛ در غیر این صورت، postgres خروجی خود را (از پس‌زمینه) روی ترمینال کنترلی می‌نویسد و از گروه فرایندِ شل خارج نخواهد شد. در Windows، به‌طور پیش‌فرض خروجی استاندارد و خطای استاندارد سرور به ترمینال فرستاده می‌شوند. این رفتارهای پیش‌فرض را می‌توان با استفاده از -l برای الحاق خروجی سرور به یک فایل لاگ تغییر داد. استفاده از -l یا تغییر مسیر خروجی توصیه می‌شود.

حالت stop سروری را که در دایرکتوری داده‌های مشخص‌شده در حال اجراست خاموش می‌کند. سه روش مختلف برای خاموش‌سازی را می‌توان با گزینهٔ -m انتخاب کرد. حالت “Smart” اتصالات جدید را رد می‌کند، سپس منتظر می‌ماند تا تمام کلاینت‌های موجود قطع شوند. اگر سرور در حالت hot standby باشد، پس از قطع ارتباط تمام کلاینت‌ها، فرایند بازیابی و همانندسازی جریانی (streaming replication) پایان می‌یابد. حالت “Fast” (حالت پیش‌فرض) منتظر قطع اتصال کلاینت‌ها نمی‌ماند. تمام تراکنش‌های فعال rollback می‌شوند و ارتباط کلاینت‌ها به اجبار قطع می‌گردد، سپس سرور خاموش می‌شود. حالت “Immediate” تمام فرایندهای سرور را فوراً و بدون خاموش‌سازی تمیز متوقف می‌کند. این انتخاب منجر به یک چرخهٔ بازیابی پس از خرابی (crash-recovery) در راه‌اندازی بعدی سرور خواهد شد.

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

حالت reload تنها یک سیگنال SIGHUP به فرایند سرور postgres ارسال می‌کند که باعث می‌شود فایل‌های پیکربندی خود (postgresql.conf، pg_hba.conf و غیره) را دوباره بخواند. این ویژگی اجازه می‌دهد گزینه‌هایی از فایل‌های پیکربندی تغییر داده شوند که اعمال آن‌ها نیازی به راه‌اندازی مجدد کامل سرور ندارد.

حالت status بررسی می‌کند که آیا سروری در دایرکتوری داده‌های مشخص‌شده در حال اجرا هست یا خیر. در صورت اجرا بودن، PID سرور و گزینه‌های خط فرمانی که برای فراخوانی آن استفاده شده‌اند نمایش داده می‌شوند. اگر سرور در حال اجرا نباشد، pg_ctl وضعیت خروج 3 را برمی‌گرداند. اگر دایرکتوری داده‌های قابل دسترسی مشخص نشده باشد، pg_ctl وضعیت خروج 4 را برمی‌گرداند.

حالت promote به سرور standby که در دایرکتوری داده‌های مشخص‌شده در حال اجراست دستور می‌دهد تا به حالت standby پایان داده و عملیات خواندن/نوشتن را آغاز کند.

حالت logrotate فایل گزارش سرور را می‌چرخاند (rotate می‌کند). برای جزئیات در مورد نحوهٔ استفاده از این حالت با ابزارهای خارجی چرخش گزارش‌ها، به Section 24.3 مراجعه کنید.

حالت kill سیگنالی را به یک فرایند مشخص ارسال می‌کند. این قابلیت عمدتاً در Microsoft Windows که فاقد دستور توکار kill است کاربرد دارد. برای مشاهدهٔ فهرستی از نام‌های سیگنال پشتیبانی‌شده از --help استفاده کنید.

حالت register سرور PostgreSQL را به‌عنوان یک سرویس سیستمی در Microsoft Windows ثبت می‌کند. گزینهٔ -S امکان انتخاب نوع راه‌اندازی سرویس را فراهم می‌کند، که می‌تواند “auto” (راه‌اندازی خودکار سرویس هنگام بالا آمدن سیستم) یا “demand” (راه‌اندازی سرویس بر حسب تقاضا) باشد.

حالت unregister یک سرویس سیستمی را در Microsoft Windows حذف (لغو ثبت) می‌کند. این عمل اثرات دستور register را خنثی می‌کند..SH "گزینه‌ها (OPTIONS)"

-c
--core-files

تلاش برای ایجاد فایل‌های core هنگام فروپاشی سرور، در پلتفرم‌هایی که این امر ممکن است، از طریق برداشتن هرگونه محدودیت نرم منابع (soft resource limit) اعمال‌شده روی فایل‌های core. این امر برای عیب‌یابی یا اشکال‌زدایی مشکلات از طریق امکان دریافت یک stack trace از فرایند ناموفق سرور مفید است.

-D datadir
--pgdata=datadir

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

-l filename
--log=filename

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

-m mode
--mode=mode

حالت خاموش کردن (shutdown) را تعیین می‌کند. mode می‌تواند smart، fast یا immediate یا حرف نخست یکی از این سه باشد. در صورت حذف این گزینه، fast پیش‌فرض است.

-o options
--options=options

گزینه‌هایی را مشخص می‌کند که مستقیماً به دستور postgres ارسال می‌شوند. -o را می‌توان چند بار مشخص کرد، که تمام گزینه‌های داده‌شده منتقل می‌شوند.

options معمولاً باید داخل کوتیشن تکی یا دوتایی قرار گیرد تا اطمینان حاصل شود که به عنوان یک گروه منتقل می‌شوند.

-o initdb-options
--options=initdb-options

گزینه‌هایی را مشخص می‌کند که مستقیماً به دستور initdb ارسال می‌شوند. -o را می‌توان چند بار مشخص کرد، که تمام گزینه‌های داده‌شده منتقل می‌شوند.

initdb-options معمولاً باید داخل کوتیشن تکی یا دوتایی قرار گیرد تا اطمینان حاصل شود که به عنوان یک گروه منتقل می‌شوند.

-p path

مکان فایل اجرایی postgres را مشخص می‌کند. به‌طور پیش‌فرض فایل اجرایی postgres از همان دایرکتوری که pg_ctl قرار دارد برداشته می‌شود، یا در صورت عدم موفقیت، از دایرکتوری نصب ثابت (hard-wired). استفاده از این گزینه ضروری نیست مگر اینکه در حال انجام کار غیرمعمولی باشید و با خطای پیدا نشدن فایل اجرایی postgres مواجه شوید.

در حالت init، این گزینه به طور مشابه مکان فایل اجرایی initdb را مشخص می‌کند.

-s
--silent

تنها خطاها را چاپ می‌کند، بدون پیام‌های اطلاعاتی.

-t seconds
--timeout=seconds

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

-V
--version

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

-w
--wait

منتظر تکمیل عملیات می‌ماند. این گزینه برای حالت‌های start، stop، restart، promote و register پشتیبانی می‌شود، و حالت پیش‌فرض برای این موارد است.

هنگام انتظار، pg_ctl به طور مکرر فایل PID سرور را بررسی کرده و بین هر بررسی، مدت کوتاهی به خواب (sleep) می‌رود. راه‌اندازی (Startup) زمانی کامل در نظر گرفته می‌شود که فایل PID نشان دهد سرور برای پذیرش اتصالات آماده است. خاموش شدن (Shutdown) زمانی کامل در نظر گرفته می‌شود که سرور فایل PID را حذف کند. pg_ctl بر اساس موفقیت راه‌اندازی یا خاموش شدن، یک کد خروج برمی‌گرداند.

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

-W
--no-wait

برای تکمیل عملیات منتظر نمی‌ماند. این برعکس گزینهٔ -w است.

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

در نسخه‌های پیشین PostgreSQL، این حالت پیش‌فرض بود به جز برای حالت stop.

-?
--help

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

اگر گزینه‌ای مشخص شود که معتبر است، اما به حالت عملیاتی انتخاب‌شده ارتباطی ندارد، pg_ctl آن را نادیده می‌گیرد..SS "گزینه‌های ویندوز (Options for Windows)"

-e source

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

-N servicename

نام سرویس سیستمی جهت ثبت. این نام هم به‌عنوان نام سرویس و هم به‌عنوان نام نمایشی استفاده خواهد شد. پیش‌فرض، PostgreSQL است.

-P password

گذرواژه کاربری که سرویس با دسترسی آن اجرا می‌شود.

-S start-type

نوع راه‌اندازی سرویس سیستم. start-type می‌تواند auto یا demand یا حرف اول یکی از این دو باشد. در صورت حذف این گزینه، auto پیش‌فرض است.

-U username

نام کاربری کاربری که سرویس با دسترسی آن اجرا می‌شود. برای کاربران دامنه، از قالب DOMAIN\username استفاده کنید.

PGCTLTIMEOUT

حد پیش‌فرض تعداد ثانیه‌های انتظار در زمان منتظر ماندن برای اتمام راه‌اندازی یا خاموش شدن. در صورت عدم تنظیم، مقدار پیش‌فرض ۶۰ ثانیه است.

PGDATA

مکان پیش‌فرض دایرکتوری داده.

بیشتر حالت‌های pg_ctl نیازمند دانستن مکان دایرکتوری داده هستند؛ بنابراین، گزینه -D الزامی است مگر اینکه PGDATA تنظیم شده باشد.

برای متغیرهای دیگری که بر سرور اثر می‌گذارند، postgres(1) را ببینید.

postmaster.pid

ابزار pg_ctl این فایل را در دایرکتوری داده بررسی می‌کند تا مشخص کند آیا سرور در حال حاضر در حال اجرا است یا خیر.

postmaster.opts

اگر این فایل در دایرکتوری داده وجود داشته باشد، pg_ctl (در حالت restart) محتویات آن را به‌عنوان گزینه به postgres ارسال می‌کند، مگر اینکه توسط گزینه -o لغو و جایگزین شود. محتویات این فایل همچنین در حالت status نمایش داده می‌شود.

برای راه‌اندازی سرور و منتظر ماندن تا زمانی که سرور پذیرای اتصالات باشد:

$ pg_ctl start

برای راه‌اندازی سرور با استفاده از پورت 5433 و اجرا بدون fsync، استفاده کنید:

$ pg_ctl -o "-F -p 5433" start

برای متوقف کردن سرور، استفاده کنید:

$ pg_ctl stop

گزینهٔ -m امکان کنترل بر روی چگونگی خاموش شدن سرور را فراهم می‌کند:

$ pg_ctl stop -m smart

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

$ pg_ctl restart

اما اگر -o مشخص شود، جایگزین هر گزینهٔ پیشین خواهد شد. برای راه‌اندازی مجدد با استفاده از پورت 5433 و غیرفعال کردن fsync در هنگام راه‌اندازی مجدد:

$ pg_ctl -o "-F -p 5433" restart

در اینجا یک نمونه از خروجی وضعیت از pg_ctl آمده است:

$ pg_ctl status
pg_ctl: server is running (PID: 13718)
/usr/local/pgsql/bin/postgres "-D" "/usr/local/pgsql/data" "-p" "5433" "-B" "128"

خط دوم، دستوری است که در حالت restart فراخوانی خواهد شد.

initdb(1), postgres(1)

2026 PostgreSQL 18.6