INITDB(1) PostgreSQL 18.6 Documentation INITDB(1)

initdb - ایجاد یک کلاستر جدید پایگاه‌داده PostgreSQL

initdb [گزینه...] [--pgdata | -D] دایرکتوری

دستور initdb یک کلاستر جدید پایگاه‌داده PostgreSQL ایجاد می‌کند.

ایجاد یک کلاستر پایگاه‌داده شامل ایجاد دایرکتوری‌هایی است که داده‌های کلاستر در آن‌ها قرار می‌گیرد، تولید جدول‌های کاتالوگ مشترک (جدول‌هایی که به کل کلاستر تعلق دارند و نه به یک پایگاه‌داده خاص)، و ساخت پایگاه‌های داده postgres، template1 و template0 است. پایگاه‌داده postgres یک پایگاه‌داده پیش‌فرض است که برای استفاده کاربران، ابزارها و برنامه‌های ثالث در نظر گرفته شده است. پایگاه‌های داده template1 و template0 به عنوان پایگاه‌های داده منبع در نظر گرفته شده‌اند تا توسط دستورات بعدی CREATE DATABASE کپی شوند. پایگاه‌داده template0 هرگز نباید تغییر داده شود، اما می‌توانید اشیایی را به template1 اضافه کنید، که به‌طور پیش‌فرض در پایگاه‌های داده‌ای که بعداً ایجاد می‌شوند کپی خواهند شد. برای جزئیات بیشتر به بخش 22.3 مراجعه کنید.

اگرچه initdb تلاش خواهد کرد تا دایرکتوری داده تعیین‌شده را ایجاد کند، اما اگر دایرکتوری والدِ آن متعلق به کاربر ریشه (root) باشد، ممکن است مجوز لازم را نداشته باشد. برای مقداردهی اولیه در چنین ساختاری، ابتدا یک دایرکتوری داده خالی با دسترسی ریشه ایجاد کنید، سپس از chown برای واگذاری مالکیت آن دایرکتوری به حساب کاربری پایگاه‌داده استفاده کنید، و در نهایت با su به کاربر پایگاه‌داده تغییر وضعیت داده و initdb را اجرا نمایید.

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

به دلایل امنیتی، کلاستر جدید ایجاد شده توسط initdb به‌طور پیش‌فرض تنها برای مالک کلاستر قابل دسترسی خواهد بود. گزینه --allow-group-access به هر کاربری در همان گروه کاربریِ مالک کلاستر اجازه می‌دهد فایل‌های موجود در کلاستر را بخواند. این قابلیت برای گرفتن نسخه پشتیبان توسط یک کاربر غیرممتاز مفید است.

دستور initdb تنظیمات محلی (locale) و کدگذاری مجموعه نویسه‌ها (character set encoding) پیش‌فرض کلاستر پایگاه‌داده را مقداردهی اولیه می‌کند. همچنین می‌توان این موارد را هنگام ساخت هر پایگاه‌داده به‌طور جداگانه تعیین کرد. دستور initdb این تنظیمات را برای پایگاه‌های داده الگو (template) مشخص می‌کند، که به عنوان پیش‌فرض برای تمامی پایگاه‌های داده دیگر عمل خواهند کرد.

به‌طور پیش‌فرض، initdb از ارائه‌دهنده تنظیمات محلی libc استفاده می‌کند (به بخش 23.1.4 مراجعه کنید). ارائه‌دهنده تنظیمات محلی libc این تنظیمات را از محیط سیستم دریافت کرده و کدگذاری را بر اساس تنظیمات محلی تعیین می‌کند.

برای انتخاب یک تنظیم محلی متفاوت برای کلاستر، از گزینه --locale استفاده کنید. همچنین گزینه‌های مجزای --lc-* و --icu-locale (پایین‌تر را ببینید) برای تعیین مقادیر دسته‌بندی‌های مختلف محلی‌سازی وجود دارند. توجه داشته باشید که تنظیمات ناسازگار برای دسته‌بندی‌های مختلف محلی‌سازی می‌تواند نتایج نامفهومی ایجاد کند، بنابراین این گزینه‌ها باید با احتیاط به کار گرفته شوند.

به عنوان روشی جایگزین، initdb می‌تواند با تعیین --locale-provider=icu از کتابخانه ICU برای ارائه خدمات تنظیمات محلی استفاده کند. سرور باید همراه با پشتیبانی از ICU ساخته شده باشد. برای انتخاب شناسه محلی خاص ICU جهت اعمال، از گزینه --icu-locale استفاده کنید. توجه داشته باشید که به دلایل پیاده‌سازی و برای پشتیبانی از کدهای قدیمی، initdb حتی در صورت استفاده از ارائه‌دهنده محلی ICU نیز تنظیمات محلی libc را انتخاب و مقداردهی خواهد کرد.

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

جزئیات بیشتر درباره تنظیمات محلی را می‌توان در بخش 23.1 یافت.

برای تغییر کدگذاری پیش‌فرض، از گزینه --encoding استفاده کنید. جزئیات بیشتر در بخش 23.3 در دسترس است..SH "گزینه‌ها (OPTIONS)"

-A authmethod
--auth=authmethod

این گزینه روش احراز هویت پیش‌فرض را برای کاربران محلی مورد استفاده در pg_hba.conf (خطوط host و local) مشخص می‌کند. برای مشاهده نمایی کلی از مقادیر معتبر به Section 20.1 مراجعه کنید.

دستور initdb مدخل‌های pg_hba.conf را با استفاده از روش احراز هویت تعیین‌شده هم برای اتصالات تکثیر (replication) و هم غیرتکثیر از پیش مقداردهی خواهد کرد.

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

--auth-host=authmethod

این گزینه روش احراز هویت را برای کاربران محلی از طریق اتصالات TCP/IP مورد استفاده در pg_hba.conf (خطوط host) مشخص می‌کند.

--auth-local=authmethod

این گزینه روش احراز هویت را برای کاربران محلی از طریق اتصالات سوکت یونیکس (Unix-domain socket) مورد استفاده در pg_hba.conf (خطوط local) مشخص می‌کند.

-D directory
--pgdata=directory

این گزینه دایرکتوری محل ذخیره‌سازی کلاستر پایگاه‌داده را مشخص می‌کند. این تنها اطلاعات مورد نیاز initdb است، اما می‌توانید با تنظیم متغیر محیطی PGDATA از نوشتن آن خودداری کنید؛ این کار می‌تواند راحت‌تر باشد زیرا سرور پایگاه‌داده (postgres) می‌تواند بعداً از طریق همین متغیر، دایرکتوری داده را پیدا کند.

-E encoding
--encoding=encoding

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

به طور پیش‌فرض، کدگذاری پایگاه‌داده الگو از لوکال (locale) مشتق می‌شود. اگر --no-locale مشخص شده باشد (یا به طور معادل، اگر لوکال C یا POSIX باشد)، پیش‌فرض برای ارائه‌دهنده ICU برابر با UTF8 و برای ارائه‌دهنده libc برابر با SQL_ASCII خواهد بود.

-g
--allow-group-access

به کاربرانی که در همان گروه مالک کلاستر هستند اجازه می‌دهد تمام فایل‌های کلاستر ایجادشده توسط initdb را بخوانند. این گزینه در Windows نادیده گرفته می‌شود زیرا از مجوزهای گروهی به سبک POSIX پشتیبانی نمی‌کند.

--icu-locale=locale

در صورت استفاده از ارائه‌دهنده ICU، لوکال ICU را مشخص می‌کند. پشتیبانی از لوکال در Section 23.1 شرح داده شده است.

--icu-rules=rules

قواعد تطبیق (collation rules) اضافی را برای سفارشی‌سازی رفتار تطبیق پیش‌فرض مشخص می‌کند. این ویژگی تنها برای ICU پشتیبانی می‌شود.

-k
--data-checksums

از چکسام‌ها روی صفحات داده برای کمک به تشخیص خرابی‌های سیستم I/O که در غیر این صورت پنهان می‌مانند، استفاده می‌کند. این گزینه به طور پیش‌فرض فعال است؛ از --no-data-checksums برای غیرفعال کردن چکسام‌ها استفاده کنید.

فعال کردن چکسام‌ها ممکن است جریمه عملکردی اندکی به همراه داشته باشد. در صورت تنظیم، چکسام‌ها برای تمام اشیاء، در تمام پایگاه‌های داده محاسبه می‌شوند. تمام موارد خرابی چکسام در نمای pg_stat_database گزارش خواهند شد. برای جزئیات به Section 28.2 مراجعه کنید.

--locale=locale

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

اگر --locale-provider برابر با builtin باشد، گزینه --locale یا --builtin-locale باید مشخص شده و روی C، C.UTF-8 یا PG_UNICODE_FAST تنظیم شود.

--lc-collate=locale
--lc-ctype=locale
--lc-messages=locale
--lc-monetary=locale
--lc-numeric=locale
--lc-time=locale

مانند --locale، اما لوکال را فقط در دسته‌بندی مشخص‌شده تنظیم می‌کند.

--no-locale

معادل --locale=C.

--builtin-locale=locale

در صورت استفاده از ارائه‌دهنده builtin، نام لوکال را مشخص می‌کند. پشتیبانی از لوکال در Section 23.1 شرح داده شده است.

--locale-provider={builtin|libc|icu}

این گزینه ارائه‌دهنده لوکال را برای پایگاه‌های داده ایجادشده در کلاستر جدید تعیین می‌کند. هنگامی که پایگاه‌های داده جدید بعداً ایجاد شوند، می‌توان این مقدار را در دستور CREATE DATABASE لغو و بازنویسی کرد. مقدار پیش‌فرض libc است (به Section 23.1.4 مراجعه کنید).

--no-data-checksums

چکسام‌های داده را فعال نمی‌کند.

--pwfile=filename

باعث می‌شود initdb گذرواژه ابرکاربر راه‌انداز (bootstrap superuser) را از یک فایل بخواند. اولین خط این فایل به عنوان گذرواژه در نظر گرفته می‌شود.

-T config
--text-search-config=config

پیکربندی جستجوی متنی پیش‌فرض را تنظیم می‌کند. برای اطلاعات بیشتر به default_text_search_config مراجعه کنید.

-U username
--username=username

نام کاربری ابرکاربر راه‌انداز (bootstrap superuser) را تنظیم می‌کند. این مقدار به طور پیش‌فرض نام کاربری کاربر سیستم‌عاملی است که initdb را اجرا می‌کند. -W
--pwprompt
باعث می‌شود initdb برای تعیین گذرواژه برای ابرکاربر اولیه (bootstrap superuser) اعلان درخواست نمایش دهد. اگر قصد استفاده از احراز هویت با گذرواژه را ندارید، این مورد اهمیتی ندارد. در غیر این صورت تا زمانی که گذرواژه‌ای تعیین نکنید، قادر به استفاده از احراز هویت با گذرواژه نخواهید بود.

-X directory
--waldir=directory

این گزینه دایرکتوری محل ذخیره‌سازی لاگ پیش‌نویس (write-ahead log) را مشخص می‌کند.

--wal-segsize=size

اندازه قطعه (segment) لاگ WAL را بر حسب مگابایت تنظیم می‌کند. این مقدار اندازه هر فایل مجزا در لاگ WAL است. اندازه پیش‌فرض ۱۶ مگابایت است. مقدار باید توانی از ۲ بین ۱ و ۱۰۲۴ (مگابایت) باشد. این گزینه تنها در زمان راه‌اندازی اولیه قابل تنظیم است و پس از آن نمی‌توان آن را تغییر داد.

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

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

-c name=value
--set name=value

پارامتر سرور name را در طول اجرای initdb به‌اجبار برابر با value قرار می‌دهد و همچنین این تنظیم را در فایل ایجادشده postgresql.conf قرار می‌دهد تا در اجراهای آینده سرور اعمال شود. این گزینه را می‌توان بیش از یک بار برای تنظیم چندین پارامتر به کار برد. این گزینه عمدتاً زمانی مفید است که شرایط محیطی به گونه‌ای باشد که سرور با استفاده از پارامترهای پیش‌فرض اصلاً راه‌اندازی نشود.

-d
--debug

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

--discard-caches

بک‌اند bootstrap را با گزینه debug_discard_caches=1 اجرا می‌کند. این کار زمان بسیار زیادی می‌برد و تنها برای اشکال‌زدایی عمیق کاربرد دارد.

-L directory

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

-n
--no-clean

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

-N
--no-sync

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

--no-sync-data-files

به‌طور پیش‌فرض، initdb تمام فایل‌های پایگاه داده را با ایمنی روی دیسک می‌نویسد. این گزینه به initdb دستور می‌دهد تا از همگام‌سازی تمام فایل‌های موجود در دایرکتوری‌های پایگاه‌های داده مجزا، خود دایرکتوری‌های پایگاه داده، و دایرکتوری‌های tablespace صرف‌نظر کند؛ یعنی همه‌چیز در زیردایرکتوری base و هر دایرکتوری tablespace دیگر. سایر فایل‌ها، مانند موارد موجود در pg_wal و pg_xact، همچنان همگام‌سازی خواهند شد مگر اینکه گزینه --no-sync نیز مشخص شده باشد.

توجه داشته باشید که اگر --no-sync-data-files همراه با --sync-method=syncfs استفاده شود، برخی یا تمام فایل‌ها و دایرکتوری‌های ذکرشده همگام‌سازی خواهند شد زیرا syncfs کل سیستم‌های فایل را پردازش می‌کند.

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

--no-instructions

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

-s
--show

تنظیمات داخلی را نمایش می‌دهد و بدون انجام هیچ کار دیگری خارج می‌شود. این گزینه می‌تواند برای اشکال‌زدایی نصب initdb مورد استفاده قرار گیرد.

--sync-method=method

هنگامی که روی fsync تنظیم شود (که حالت پیش‌فرض است)، initdb تمام فایل‌های موجود در دایرکتوری داده را به‌صورت بازگشتی باز کرده و همگام‌سازی می‌کند. جستجوی فایل‌ها، پیوندهای نمادین را برای دایرکتوری WAL و هر tablespace پیکربندی‌شده دنبال خواهد کرد.

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

این گزینه در صورت استفاده از --no-sync هیچ تأثیری ندارد.

-S
--sync-only

تمام فایل‌های پایگاه داده را به‌طور ایمن روی دیسک نوشته و خارج می‌شود. این کار هیچ‌یک از عملیات‌های معمولی initdb را انجام نمی‌دهد. به‌طور کلی، این گزینه برای اطمینان از بازیابی مطمئن پس از تغییر fsync از off به on مفید است.

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

-V
--version

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

-?
--help

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

PGDATA

دایرکتوری محل ذخیره‌سازی کلاستر پایگاه‌داده را مشخص می‌کند؛ این مقدار می‌تواند با استفاده از گزینهٔ -D بازنویسی شود.

PG_COLOR

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

TZ

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

initdb را می‌توان از طریق pg_ctl initdb نیز فراخوانی کرد.

pg_ctl(1)، postgres(1)، بخش 20.1

2026 PostgreSQL 18.6