.TH PGSQL_TABLE 5
.ad
.fi
.SH "نام (NAME)"
pgsql_table \- پیکربندی کلاینت PostgreSQL در Postfix
.SH "خلاصه دستور (SYNOPSIS)"
.na
.nf
\fBpostmap \-q "\fIstring\fB" pgsql:/etc/postfix/\fIfilename\fR

\fBpostmap \-q \- pgsql:/etc/postfix/\fIfilename\fB <\fIinputfile\fR
.SH "توضیحات (DESCRIPTION)"
.ad
.fi
سیستم ایمیل Postfix از جدول‌های اختیاری برای بازنویسی نشانی یا مسیریابی
ایمیل استفاده می‌کند. این جدول‌ها معمولاً در قالب‌های
\fBlmdb:\fR، \fBcdb:\fR، \fBhash:\fR یا \fBdbm:\fR هستند.

به‌عنوان روش جایگزین، جدول‌های جستجو می‌توانند به‌صورت پایگاه‌های داده
PostgreSQL مشخص شوند.
برای اطلاع از اینکه سیستم Postfix شما از چه نوع جدول‌های جستجویی پشتیبانی
می‌کند، از دستور "\fBpostconf \-m\fR" استفاده کنید.

به‌منظور استفاده از جستجوهای PostgreSQL، یک منبع PostgreSQL را به‌صورت جدول
جستجو در main.cf تعریف کنید، برای نمونه:
.nf
    alias_maps = pgsql:/etc/postfix/pgsql\-aliases.cf
.fi

فایل /etc/postfix/pgsql\-aliases.cf همان قالبی را دارد که فایل main.cf در
Postfix داراست، و می‌تواند پارامترهای شرح‌داده‌شده در زیر را مشخص کند.
.SH "عضویت در فهرست (LIST MEMBERSHIP)"
.na
.nf
.ad
.fi
هنگام استفاده از SQL برای ذخیره فهرست‌هایی نظیر $mynetworks،
$mydestination، $relay_domains، $local_recipient_maps و غیره،
درک این نکته اهمیت دارد که جدول باید هر عضو فهرست را به‌صورت یک کلید جداگانه
ذخیره کند. جستجوی جدول *وجود داشتن* کلید را اعتبارسنجی می‌کند. برای بحث
بیشتر، به بخش "Postfix lists versus tables" در سند DATABASE_README مراجعه کنید.

جدول‌هایی ایجاد \fBنکنید\fR که فهرست کامل دامنه‌ها را در $mydestination یا
$relay_domains و غیره، یا نشانی‌های IP را در $mynetworks بازگردانند.

جدول‌ها را با قرار دادن هر مورد منطبق به‌صورت یک کلید و با یک مقدار
دلخواه ایجاد \fBکنید\fR. در پایگاه‌های داده SQL غیرمعمول نیست که خود کلید یا
یک مقدار ثابت بازگردانده شود.
.SH "پارامترهای PGSQL (PGSQL PARAMETERS)"
.na
.nf
.ad
.fi
.IP "\fBhosts\fR"
میزبان‌هایی که Postfix تلاش خواهد کرد به آن‌ها متصل شده و پرس‌وجو انجام دهد.
علاوه بر URI اتصال PostgreSQL، این تنظیم از شکل‌های قدیمی
\fBunix:/\fIpathname\fR برای سوکت‌های دامنه یونیکس (UNIX\-domain) و
\fBinet:\fIhost:port\fR برای اتصال‌های TCP پشتیبانی می‌کند، که در آن‌ها
پیشوندهای \fBunix:\fR و \fBinet:\fR پذیرفته شده و برای سازگاری با گذشته نادیده گرفته می‌شوند.
نمونه‌ها:
.nf
    hosts = postgresql://username@example.com/\fIdatabasename\fR?sslmode=require
    hosts = postgres://user:secret@localhost
    hosts = inet:host1.some.domain inet:host2.some.domain:port
    hosts = host1.some.domain host2.some.domain:port
    hosts = unix:/file/name
.fi

برای نحو پشتیبانی‌شده URI اتصال، به نشانی
https://www.postgresql.org/docs/current/libpq\-connect.html
مراجعه کنید.

میزبان‌ها به ترتیب تصادفی آزمایش می‌شوند. اتصال‌ها پس از حدود ۱ دقیقه بیکار
بودن به‌طور خودکار بسته می‌شوند و در صورت نیاز مجدداً باز خواهند شد. برای
جزئیات بیشتر به \fBidle_interval\fR مراجعه کنید.

نکته: اگر تنظیم \fBhosts\fR یک URI اتصال PostgreSQL را مشخص کند، کلاینت
PostgreSQL در Postfix تنظیمات \fBdbname\fR، \fBuser\fR و \fBpassword\fR را
برای آن اتصال نادیده خواهد گرفت.

نکته: اگر تنظیم \fBhosts\fR تنها یک سرور را مشخص کند، این کلاینت فرض می‌کند
که مقصد یک متعادل‌کننده بار (load balancer) است و پس از یک خرابی منفرد بلافاصله
دوباره متصل می‌شود. در نسخه‌های 3.9 و پیشین Postfix، همان سرور را دوبار مشخص کنید.
.IP "\fBuser\fR"
.IP "\fBpassword\fR"
نام کاربری و گذرواژه برای ورود به سرور pgsql.
نمونه:
.nf
    user = someone
    password = some_password
.fi
.sp
تنظیمات \fBuser\fR و \fBpassword\fR برای اتصال‌های \fBhosts\fR که به‌صورت یک URI
مشخص شده‌اند، نادیده گرفته می‌شوند.
.IP "\fBdbname\fR"
نام پایگاه داده روی سرورها. نمونه:
.nf
    dbname = customer_database
.fi
.sp
تنظیم \fBdbname\fR برای اتصال‌های \fBhosts\fR که به‌صورت یک URI مشخص شده‌اند،
نادیده گرفته می‌شود.

تنظیم \fBdbname\fR در Postfix نسخه 3.10 و بالاتر، هنگامی که \fBhosts\fR هرگونه
اتصال غیر URI را مشخص کرده باشد، الزامی است؛ این تنظیم در نسخه‌های پیشین
Postfix همواره الزامی است.
.IP "\fBencoding\fR"
کدگذاری مورداستفاده توسط کلاینت پایگاه داده. تنظیم پیش‌فرض عبارت است از:
.nf
    encoding = UTF8
.fi

از نظر تاریخی، کلاینت پایگاه داده به‌صورت ثابت برای استفاده از LATIN1 کدنویسی
شده بود تا پشتیبانی از نویسه‌های چندبایتی غیرفعال شود.

این قابلیت در Postfix نسخه 3.8 و بالاتر در دسترس است.
.IP "\fBidle_interval (پیش‌فرض: 60)\fR"
تعداد ثانیه‌هایی که پس از آن یک اتصال پایگاه داده بیکار بسته خواهد شد.

این قابلیت در Postfix نسخه 3.9 و بالاتر در دسترس است.
.IP "\fBretry_interval (پیش‌فرض: 60)\fR"
تعداد ثانیه‌هایی که پس از بروز یک خطا، از اتصال پایگاه داده صرف‌نظر خواهد شد.

نکته: اگر تنظیم \fBhosts\fR تنها یک سرور را مشخص کند، این کلاینت فرض می‌کند
که مقصد یک متعادل‌کننده بار است و پس از یک خرابی منفرد بلافاصله دوباره متصل
می‌شود. در نسخه‌های 3.9 و پیشین Postfix، همان سرور را دوبار مشخص کنید.

این قابلیت در Postfix نسخه 3.9 و بالاتر در دسترس است.
.IP "\fBquery\fR"
الگوی پرس‌وجوی SQL مورداستفاده برای جستجو در پایگاه داده، که در آن \fB%s\fR
جایگزینی برای نشانی‌ای است که Postfix در تلاش برای تحلیل آن است، برای نمونه:
.nf
    query = SELECT replacement FROM aliases WHERE mailbox = '%s'
.fi

این پارامتر از بسط‌های '%' زیر پشتیبانی می‌کند:
.RS
.IP "\fB%%\fR"
این مورد با یک نویسه پیش‌پاافتاده '%' جایگزین می‌شود. (Postfix 2.2 و بالاتر)
.IP "\fB%s\fR"
این مورد با کلید ورودی جایگزین می‌شود.
نقل‌قول‌گذاری SQL (SQL quoting) استفاده می‌شود تا اطمینان حاصل گردد که کلید
ورودی نویسه‌های متا (metacharacters) غیرمنتظره اضافه نمی‌کند.
.IP "\fB%u\fR"
هنگامی که کلید ورودی یک نشانی به شکل user@domain باشد، \fB%u\fR با بخش محلی
(local part) نشانی که نقل‌قول‌گذاری SQL شده جایگزین می‌شود. در غیر این صورت،
\fB%u\fR با کل رشته جستجو جایگزین می‌شود. اگر بخش محلی خالی باشد، پرس‌وجو متوقف
شده و هیچ نتیجه‌ای برنمی‌گرداند.
.IP "\fB%d\fR"
هنگامی که کلید ورودی یک نشانی به شکل user@domain باشد، \fB%d\fR با بخش دامنه
نشانی که نقل‌قول‌گذاری SQL شده جایگزین می‌شود. در غیر این صورت، پرس‌وجو متوقف
شده و هیچ نتیجه‌ای برنمی‌گرداند.
.IP "\fB%[SUD]\fR"
معادل‌های با حروف بزرگ بسط‌های بالا در پارامتر \fBquery\fR رفتاری کاملاً همسان
با همتایان حروف کوچک خود دارند. با پارامتر \fBresult_format\fR (زیر را ببینید)،
آن‌ها به‌جای مقدار نتیجه، کلید ورودی را بسط می‌دهند.
.IP
بسط‌های %S، %U و %D بالا در Postfix نسخه 2.2 و بالاتر در دسترس هستند.
.IP "\fB%[1\-9]\fR"
الگوهای %1، %2، ... %9 با مؤلفه متناظر با بیشترین اهمیت از دامنه کلید ورودی
جایگزین می‌شوند. اگر کلید ورودی \fIuser@mail.example.com\fR باشد، آنگاه %1
برابر با \fBcom\fR، %2 برابر با \fBexample\fR و %3 برابر با \fBmail\fR است.
اگر کلید ورودی بدون صلاحیت (unqualified) باشد یا مؤلفه‌های دامنه کافی برای برآورده
کردن تمام الگوهای مشخص‌شده نداشته باشد، پرس‌وجو متوقف شده و هیچ نتیجه‌ای برنمی‌گرداند.
.IP
بسط‌های %1، ... %9 بالا در Postfix نسخه 2.2 و بالاتر در دسترس هستند.
.RE
.IP
پارامتر \fBdomain\fR شرح داده شده در زیر، کلیدهای ورودی را به نشانی‌های دامنه‌های
منطبق محدود می‌کند. هنگامی که پارامتر \fBdomain\fR خالی نباشد، پرس‌وجوهای SQL برای
نشانی‌های فاقد نام دامنه کامل یا نشانی‌های موجود در دامنه‌های غیرمنطبق متوقف شده و
هیچ نتیجه‌ای بازنمی‌گردانند.

تقدم این پارامتر با Postfix نسخه 2.2 تغییر کرده است؛ در نسخه‌های پیشین تقدم
از بالاترین به پایین‌ترین عبارت بود از: \fBselect_function\fR، \fBquery\fR،
\fBselect_field\fR، ...

با Postfix نسخه 2.2 پارامتر \fBquery\fR بالاترین تقدم را دارد، به بخش
رابط‌های پرس‌وجوی منسوخ در زیر مراجعه کنید.

نکته: دور پارامتر \fBquery\fR علامت نقل‌قول قرار ندهید.
.IP "\fBresult_format (پیش‌فرض: \fB%s\fR)\fR"
الگوی قالب اعمال‌شده بر ویژگی‌های نتیجه. معمولاً برای افزودن متن به انتها
(یا ابتدا) نتیجه استفاده می‌شود. این پارامتر از بسط‌های '%' زیر پشتیبانی می‌کند:
.RS
.IP "\fB%%\fR"
این مورد با یک نویسه پیش‌پاافتاده '%' جایگزین می‌شود.
.IP "\fB%s\fR"
این مورد با مقدار ویژگی نتیجه جایگزین می‌شود. هنگامی که نتیجه خالی باشد،
از آن صرف‌نظر می‌شود.
.IP "\fB%u\fR"
هنگامی که مقدار ویژگی نتیجه نشانی‌ای به شکل user@domain باشد، \fB%u\fR با بخش
محلی نشانی جایگزین می‌شود. هنگامی که نتیجه بخش محلی خالی داشته باشد، از آن
صرف‌نظر می‌شود.
.IP "\fB%d\fR"
هنگامی که مقدار ویژگی نتیجه نشانی‌ای به شکل user@domain باشد، \fB%d\fR با بخش
دامنه مقدار ویژگی جایگزین می‌شود. هنگامی که نتیجه فاقد دامنه باشد، از آن
صرف‌نظر می‌شود.
.IP "\fB%[SUD1\-9]\fR"
بسط‌های حروف بزرگ و ارقام ده‌دهی به‌جای نتیجه، بخش‌هایی از کلید ورودی را در متن
درج می‌کنند. رفتار آن‌ها مشابه همان است که در مورد \fBquery\fR شرح داده شد، و در
واقع از آنجا که کلید ورودی از قبل مشخص است، پرس‌وجوهایی که کلید آن‌ها شامل تمام
اطلاعات مشخص‌شده در الگوی نتیجه نباشد متوقف شده و هیچ نتیجه‌ای برنمی‌گردانند.
.RE
.IP
برای نمونه، استفاده از "result_format = smtp:[%s]" امکان استفاده از ویژگی
mailHost را به‌عنوان مبنایی برای جدول transport(5) فراهم می‌کند. پس از اعمال
قالب نتیجه، مقادیر چندگانه به‌صورت رشته‌های جداشده با کاما به هم متصل می‌شوند.
پارامتر expansion_limit که در ادامه توضیح داده شده است، اجازه می‌دهد تعداد
مقادیر در نتیجه محدود شود، که به‌ویژه برای نگاشت‌هایی که باید حداکثر یک مقدار
بازگردانند مفید است.

مقدار پیش‌فرض \fB%s\fR مشخص می‌کند که هر مقدار نتیجه باید همان‌گونه که هست
استفاده شود.

این پارامتر در Postfix نسخه 2.2 و بالاتر در دسترس است.

نکته: دور قالب نتیجه (result format) نقل‌قول قرار ندهید!
.IP "\fBdomain (پیش‌فرض: بدون فهرست دامنه)\fR"
این گزینه‌ای است شامل فهرستی از نام‌های دامنه، مسیرهای فایل‌ها، یا پایگاه‌های داده
"type:table". در صورت تعیین، تنها کلیدهای جستجوی واجد شرایط کامل با بخش محلی
*غیرخالی* و دامنه منطبق، واجد شرایط جستجو هستند: جستجوهای 'user'، جستجوهای صرفاً
دامنه و جستجوهای "@domain" انجام نمی‌شوند. این امر می‌تواند بار پرس‌وجو روی
سرور PostgreSQL را به‌طور چشمگیری کاهش دهد.
.nf
    domain = postfix.org, hash:/etc/postfix/searchdomains
.fi

بهتر است از SQL برای ذخیره دامنه‌های واجد شرایط جستجوهای SQL استفاده نشود.

این پارامتر در Postfix نسخه 2.2 و بالاتر در دسترس است.

نکته: این پارامتر را برای نام‌های مستعار local(8) تعریف \fBنکنید\fR، زیرا
کلیدهای ورودی همیشه بدون صلاحیت (unqualified) هستند.
.IP "\fBexpansion_limit (پیش‌فرض: 0)\fR"
محدودیتی برای تعداد کل عناصر نتیجه بازگردانده‌شده (به‌صورت یک فهرست جداشده با کاما)
توسط یک جستجو در نگاشت. مقدار صفر محدودیت را غیرفعال می‌کند. در صورت فراتر رفتن از
حد مجاز، جستجوها با یک خطای موقت مواجه می‌شوند. تنظیم این محدودیت روی 1 تضمین
می‌کند که جستجوها مقادیر چندگانه بازنگردانند.
.SH "پارامترهای منسوخ MAIN.CF (OBSOLETE MAIN.CF PARAMETERS)"
.na
.nf
.ad
.fi
برای سازگاری با سایر جدول‌های جستجوی Postfix، پارامترهای PostgreSQL را می‌توان
در main.cf نیز تعریف کرد. برای این کار، به‌عنوان منبع PostgreSQL نامی را مشخص
کنید که با یک اسلش یا نقطه شروع نشود. سپس پارامترهای PostgreSQL با نامی که برای منبع
در تعریف آن تعیین کرده‌اید، یک زیرخط (_) و نام پارامتر در دسترس خواهند بود. برای
نمونه، اگر نگاشت به‌صورت "pgsql:\fIpgsqlname\fR" مشخص شود، پارامتر "hosts" در
main.cf به‌صورت "\fIpgsqlname\fR_hosts" تعریف خواهد شد.

نکته: با این شیوه، گذرواژه‌های منابع PostgreSQL در main.cf نوشته می‌شوند که معمولاً
برای همگان قابل خواندن است. پشتیبانی از این شیوه در نسخه‌های آینده Postfix حذف خواهد شد.
.SH "رابط‌های پرس‌وجوی منسوخ (OBSOLETE QUERY INTERFACES)"
.na
.nf
.ad
.fi
این بخش رابط‌های پرس‌وجویی را شرح می‌دهد که از نسخه 2.2 به بعد Postfix منسوخ
شده‌اند. لطفاً به رابط جدید \fBquery\fR مهاجرت کنید زیرا رابط‌های قدیمی در آستانه
حذف تدریجی قرار دارند.
.IP "\fBselect_function\fR"
این پارامتر نام تابع پایگاه داده را مشخص می‌کند. نمونه:
.nf
    select_function = my_lookup_user_alias
.fi

این معادل است با:
.nf
    query = SELECT my_lookup_user_alias('%s')
.fi

این پارامتر فیلدهای قدیمی مرتبط با جدول (که در زیر آمده) را بازنویسی و لغو
می‌کند. در نسخه‌های پیش از 2.2 Postfix، پارامتر \fBquery\fR را نیز لغو می‌کرد.
از نسخه 2.2 Postfix، پارامتر \fBquery\fR بالاترین تقدم را دارد و پارامتر
\fBselect_function\fR منسوخ شده است.
.PP
پارامترهای زیر (با اولویت پایین‌تر نسبت به رابط \fBselect_function\fR شرح داده شده در بالا)
می‌توانند برای ساخت عبارت select در SQL به‌صورت زیر استفاده شوند:

.nf
    SELECT [\fBselect_field\fR]
    FROM [\fBtable\fR]
    WHERE [\fBwhere_field\fR] = '%s'
          [\fBadditional_conditions\fR]
.fi

مشخص‌کننده %s در هر جستجو با کلید جستجو جایگزین می‌شود و اسکیپ می‌شود تا در صورتی که
شامل علامت نقل‌قول تکی یا سایر نویسه‌های غیرمعمول باشد، باعث بروز خطای تجزیه و بدتر
از آن، مشکل امنیتی نگردد.

با شروع از Postfix 2.2، این رابط با رابط عمومی‌تر \fBquery\fR که در بالا شرح
داده شد جایگزین و منسوخ شده است. در صورت تعریف پارامترهای با تقدم بالاتر \fBquery\fR
یا \fBselect_function\fR شرح داده شده در بالا، پارامترهای شرح‌داده‌شده در اینجا
نادیده گرفته می‌شوند.
.IP "\fBselect_field\fR"
پارامتر "select" در SQL. نمونه:
.nf
    \fBselect_field\fR = forw_addr
.fi
.IP "\fBtable\fR"
نام جدول "select .. from" در SQL. نمونه:
.nf
    \fBtable\fR = mxaliases
.fi
.IP "\fBwhere_field\fR"
پارامتر "select .. where" در SQL. نمونه:
.nf
    \fBwhere_field\fR = alias
.fi
.IP "\fBadditional_conditions\fR"
شرایط اضافی برای پرس‌وجوی SQL. نمونه:
.nf
    \fBadditional_conditions\fR = AND status = 'paid'
.fi
.SH "همچنین ببینید (SEE ALSO)"
.na
.nf
postmap(1)، مدیر جدول‌های جستجوی Postfix
postconf(5)، پارامترهای پیکربندی
ldap_table(5)، جدول‌های جستجوی LDAP
mysql_table(5)، جدول‌های جستجوی MySQL
sqlite_table(5)، جدول‌های جستجوی SQLite
.SH "فایل‌های README (README FILES)"
.na
.nf
.ad
.fi
از "\fBpostconf readme_directory\fR" یا
"\fBpostconf html_directory\fR" برای یافتن مکان این اطلاعات استفاده کنید.
.na
.nf
DATABASE_README، نمای کلی جدول جستجوی Postfix
PGSQL_README، راهنمای کلاینت PostgreSQL در Postfix
.SH "مجوز (LICENSE)"
.na
.nf
.ad
.fi
مجوز نرم‌افزار ایمن (Secure Mailer license) باید همراه با این نرم‌افزار توزیع شود.
.SH "تاریخچه (HISTORY)"
.ad
.fi
پشتیبانی از PgSQL با نسخه 2.1 نرم‌افزار Postfix معرفی شد.
.SH "نویسندگان (AUTHORS)"
.na
.nf
بر پایه کلاینت MySQL توسط:
Scott Cotton, Joshua Marcus
IC Group, Inc.

پورت‌شده به PostgreSQL توسط:
Aaron Sethman

بهبودهای بعدی توسط:
Liviu Daia
Institute of Mathematics of the Romanian Academy
P.O. BOX 1\-764
RO\-014700 Bucharest, ROMANIA