اجرا در ترمینال/کنسول (Terminal/console execution)

نحوه استفاده: pg_format [گزینه‌ها] file.sql

PostgreSQL SQL queries and PL/PGSQL code beautifier.

آرگومان‌ها:

شناسه file.sql می‌تواند یک فایل، چندین فایل یا - برای خواندن کوئری از stdin باشد.
خروجی SQL قالب‌بندی‌شده را به stdout یا در فایل مشخص‌شده با گزینه -o | --output بازمی‌گرداند.

گزینه‌ها:

-a | --anonymize      : مبهم‌سازی تمام مقادیر لغوی (literals) در کوئری‌ها؛ مفید برای مخفی‌سازی
                        داده‌های محرمانه پیش از قالب‌بندی.
-b | --comma-start    : در فهرست پارامترها، شروع با کاما (به -e مراجعه کنید).
-B | --comma-break    : در دستورات insert، افزودن خط جدید پس از هر کاما.
-c | --config FILE    : استفاده از فایل پیکربندی. در حالت پیش‌فرض از فایل پیکربندی
                        استفاده نمی‌شود مگر اینکه فایل‌های ./.pg_format یا
                        $HOME/.pg_format یا فایل مسیر پایه XDG یعنی
                        $XDG_CONFIG_HOME/pg_format/pg_format.conf وجود داشته باشند.
-C | --wrap-comment   : همراه با --wrap-limit، اعمال قالب‌بندی مجدد روی کامنت‌ها.
-d | --debug          : فعال‌سازی حالت اشکال‌زدایی. به‌طور پیش‌فرض غیرفعال است.
-e | --comma-end      : در فهرست پارامترها، پایان با کاما (پیش‌فرض).
-f | --function-case N: تغییر حالت حروف توابع PostgreSQL. حالت پیش‌فرض بدون تغییر
                        است: 0. مقادیر: 0=>بدون تغییر، 1=>حروف کوچک،
                        2=>حروف بزرگ، 3=>بزرگ کردن حرف اول کلمات.
-F | --format STR     : فرمت خروجی: text یا html. پیش‌فرض: text.
-g | --nogrouping     : افزودن یک خط جدید میان دستورات در گروه‌بندی تراکنش‌ها.
                        حالت پیش‌فرض گروه‌بندی دستورات است.
-h | --help           : نمایش این پیام راهنما و خروج.
-i | --inplace        : بازنویسی فایل‌های ورودی با محتوای قالب‌بندی‌شده.
-k | --keep-newline   : حفظ خطوط خالی در کدهای plpgsql.
-L | --no-extra-line  : عدم افزودن خط خالی اضافی در انتهای خروجی.
-m | --maxlength SIZE : حداکثر طول یک کوئری؛ کوئری بیش از اندازه تعیین‌شده بریده
                        خواهد شد. پیش‌فرض: بدون برش (no truncate).
-M | --multiline      : فعال‌سازی جستجوی چندخطی برای -p یا --placeholder.
-n | --nocomment      : حذف تمامی کامنت‌ها از کد SQL.
-N | --numbering      : شماره‌گذاری دستورات به صورت کامنت قبل از هر کوئری.
-o | --output file    : تعیین نام فایل برای خروجی. پیش‌فرض: stdout.
-p | --placeholder RE : تنظیم عبارت منظم (regex) برای یافتن کدهایی که نباید تغییر کنند.
-r | --redshift       : افزودن کلمات کلیدی RedShift به فهرست کلمات کلیدی SQL.
                        اکنون منسوخ شده است، به جای آن از --extra-keyword 'redshift' استفاده کنید.
-s | --spaces size    : تغییر فاصله تورفتگی، پیش‌فرض ۴ فاصله.
-S | --separator STR  : جداکننده کد پویا، پیش‌فرض علامت نقل‌قول تکی (').
-t | --format-type    : آزمودن نوع قالب‌بندی دیگر برای برخی دستورات.
-T | --tabs           : استفاده از تب به جای نویسه‌های فاصله؛ در صورت استفاده،
                        فاصله‌ها صرف‌نظر از مقدار تنظیم‌شده برای -s برابر ۱ قرار می‌گیرد.
-u | --keyword-case N : تغییر حالت حروف کلمات کلیدی رزروشده. حالت پیش‌فرض حروف
                        بزرگ است: 2. مقادیر: 0=>بدون تغییر، 1=>حروف کوچک،
                        2=>حروف بزرگ، 3=>بزرگ کردن حرف اول کلمات.
-U | --type-case N    : تغییر حالت حروف نام انواع داده. حالت پیش‌فرض حروف
                        کوچک است: 1. مقادیر: 0=>بدون تغییر، 1=>حروف کوچک،
                        2=>حروف بزرگ، 3=>بزرگ کردن حرف اول کلمات.
-v | --version        : نمایش نسخه pg_format و خروج.
-w | --wrap-limit N   : شکستن و پیچیدن خطوط کوئری‌ها در یک طول مشخص.
-W | --wrap-after N   : تعداد ستون‌هایی که پس از آن فهرست‌ها باید شکسته شوند.
                        پیش‌فرض: هر مورد در خط خودش قرار می‌گیرد.
-X | --no-rcfile      : عدم خواندن خودکار فایل‌های rc (مانند ./.pg_format یا
                        $HOME/.pg_format یا $XDG_CONFIG_HOME/pg_format).
                        گزینه --config / -c این گزینه را لغو می‌کند.
--extra-function FILE : فایل حاوی فهرستی از توابع جهت اعمال قالب‌بندی یکسان با توابع داخلی PostgreSQL.
--extra-keyword FILE  : فایل حاوی فهرستی از کلمات کلیدی جهت اعمال قالب‌بندی یکسان با کلمات کلیدی
                        داخلی PostgreSQL. از مقدار ویژه 'redshift' برای پشتیبانی از
                        کلمات کلیدی Redshift که به صورت داخلی در pgFormatter تعریف شده‌اند استفاده کنید.
--no-space-function : حذف فاصله میان فراخوانی تابع و پرانتز باز پس از آن.
--redundant-parenthesis: عدم حذف پرانتزهای اضافی در دستورات DML.

مثال‌ها:

cat samples/ex1.sql | pg_format -
pg_format -n samples/ex1.sql
pg_format -f 2 -n -o result.sql samples/ex1.sql

محیط CGI (CGI context)

فایل pg_format را در پوشه cgi-bin خود نصب کنید، مجوز اجرای آن را به عنوان یک اسکریپت CGI اعطا نمایید (شاید نیاز باشد پسوند .cgi را اضافه کنید) و آن را از مرورگر دلخواه خود فراخوانی کنید. فایل‌های logo_pgformatter.png و icon_pgformatter.ico را در دایرکتوری CGI کپی کنید؛ اسکریپت pg_format.cgi در همان مسیر به دنبال آن‌ها می‌گردد.

یک نمونه زنده بدون محدودیت بیش از ده هزار کاراکتر در کوئری SQL در اینجا در دسترس است:

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

ابتدا باید ماژول‌های پرل CGI و JSON را نصب کنید. اگر از قبل نصب نشده‌اند، با توجه به توزیع خود دستور زیر را اجرا کنید:

        yum install perl-cgi
        yum install perl-json
یا
        apt install libcgi-pm-perl
        apt install libjson-perl

با توجه به توزیع شما.

گزینه -W، --wrap-after (Option -W, --wrap-after)

از این گزینه می‌توان برای تعیین تعداد ستون‌هایی که پس از آن فهرست‌ها باید شکسته شوند استفاده کرد. به‌طور پیش‌فرض pgFormatter هر مورد را در خط خودش قرار می‌دهد. این قالب‌بندی روی فهرست‌های SELECT و FROM اعمال می‌شود. برای نمونه کوئری زیر:

SELECT a, b, c, d FROM t_1, t_2, t3 WHERE a = 10 AND b = 10;

با گزینه -W 4 به این صورت قالب‌بندی خواهد شد:

SELECT a, b, c, d
FROM t_1, t_2, t3
WHERE a = 10
    AND b = 10;

توجه داشته باشید که این شیوه قالب‌بندی با زیرکوئری‌های درون فهرست به خوبی سازگار نیست.

گزینه -w، --wrap-limit (Option -w, --wrap-limit)

این گزینه خطوط کوئری‌ها را در یک طول مشخص می‌شکند، فارغ از اینکه چه بخشی از کوئری در مرز این محدودیت قرار داشته باشد، مگر اینکه آن بخش یک کامنت باشد. برای نمونه اگر محدودیت درون یک ثابت متنی رخ دهد، متن شکسته خواهد شد. تورفتگی‌ها در شمارش کاراکترها محاسبه نمی‌شوند. این گزینه در تمام حالات اعمال می‌شود، حتی زمانی که سایر گزینه‌ها استفاده شده باشند.

گزینه -C، --wrap-comment (Option -C, --wrap-comment)

این گزینه کامنت‌ها را در طولی که توسط -w یا --wrap-limit مشخص شده می‌شکند، بدون توجه به اینکه چه بخشی از کامنت باشد. تورفتگی‌ها در شمارش کاراکترها محاسبه نمی‌شوند.

گزینه -t، --format-type (Option -t, --format-type)

این گزینه یک قالب‌بندی جایگزین را فعال می‌کند که موارد زیر را اضافه می‌نماید:

* خط جدید در فهرست پارامترهای رویه/تابع
* خط جدید در تعاریف DDL مربوط به PUBLICATION و POLICY
* حفظ عبارات شمارشی در بند GROUP BY در یک تک‌خط

انتظار می‌رود این فهرست در آینده با توجه به دیدگاه‌های جایگزین گسترش یابد.

گزینه -g، --nogrouping (Option -g, --nogrouping)

به‌طور پیش‌فرض pgFormatter تمام دستوراتی را که درون یک تراکنش قرار دارند گروه‌بندی می‌کند:

BEGIN;
INSERT INTO foo VALUES (1, 'text 1');
INSERT INTO foo VALUES (2, 'text 2');
...
COMMIT;

با غیرفعال کردن گروه‌بندی دستورات، pgFormatter همیشه نویسه‌های خط جدید اضافی بین دستورات قرار می‌دهد، دقیقاً مشابه خارج از یک تراکنش:

BEGIN;
INSERT INTO foo VALUES (1, 'text 1');
INSERT INTO foo VALUES (2, 'text 2');
...
COMMIT;

این کار ممکن است خوانایی را در تراکنش‌های غیر DML افزایش دهد.

گزینه -L، --no-extra-line (Option -L, --no-extra-line)

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

گزینه --extra-function (Option --extra-function)

برنامه pgFormatter قالب‌بندی‌هایی را بر روی فراخوانی توابع داخلی PostgreSQL اعمال می‌کند اما قادر به شناسایی توابع تعریف‌شده توسط کاربر نیست. می‌توان فهرستی از توابع را درون یک فایل (در هر خط نام یک تابع) مشخص کرد و آن را از طریق گزینه --extra-function به pgFormatter ارسال نمود تا مانند توابع داخلی PostgreSQL قالب‌بندی شوند.

گزینه --extra-keyword (Option --extra-keyword)

برنامه pgFormatter قالب‌بندی‌هایی را بر روی کلمات کلیدی داخلی PostgreSQL اعمال می‌کند اما کلمات کلیدی سایر پایگاه‌های داده را تشخیص نمی‌دهد. می‌توان فهرستی از کلمات کلیدی را درون یک فایل (در هر خط یک کلمه کلیدی) مشخص کرد و آن را از طریق گزینه --extra-keyword به pgFormatter ارسال نمود تا همانند کلمات کلیدی داخلی PostgreSQL قالب‌بندی شوند.

همچنین می‌توانید مقدار ویژه 'redshift' را ارسال نمایید تا کلمات کلیدی تعریف‌شده به صورت داخلی در pgFormatter برای این پایگاه داده بارگذاری شوند. این امکان پیش‌تر از طریق گزینه -r | --redshift فراهم بود که اکنون منسوخ شده و در آینده حذف خواهد شد.

گزینه --no-space-function (Option --no-space-function)

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

DROP FUNCTION IF EXISTS app_public.hello (a text);

هنگام استفاده از این گزینه، کوئری حاصل به صورت زیر قالب‌بندی می‌شود:

DROP FUNCTION IF EXISTS app_public.hello(a text);

گزینه --redundant-parenthesis (Option --redundant-parenthesis)

به‌طور پیش‌فرض، pgFormatter تلاش می‌کند تا پرانتزهای زائد را در دستورات DML حذف کند، اما در برخی موارد حفظ آن‌ها الزامی است. استفاده از این گزینه، پرانتزهای زائد را دست‌نخورده نگه می‌دارد.

گزینه --vertical-align (Option --vertical-align)

از این گزینه برای تراز کردن عمودی تعاریف مستقیم و تک‌خطی ستون‌ها درون دستورات CREATE TABLE استفاده کنید. این گزینه نام ستون‌ها، انواع داده، قیود ستونی نظیر DEFAULT و کامنت‌های انتهایی را تراز می‌کند. برای نمونه:

CREATE TABLE example (
    id         serial PRIMARY KEY,                                -- some comment
    name       varchar(100)             NOT NULL,                 -- another comment
    email      varchar(100)             NOT NULL,                 -- third comment
    created_at timestamp with time zone DEFAULT CURRENT_TIMESTAMP -- last comment
);

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

پیکربندی (Configuration)

اگر تنظیمات پیش‌فرض pg_format تمام نیازهای شما را برآورده نمی‌کند، می‌توانید رفتار pg_format را با استفاده از یک فایل پیکربندی سفارشی‌سازی کنید، به جای آنکه مکرراً گزینه‌های خط فرمان را تکرار نمایید. به‌طور پیش‌فرض pgFormatter در صورت وجود، به دنبال فایل‌های ./.pg_format یا $HOME/.pg_format یا $XDG_CONFIG_HOME/pg_format/pg_format.conf می‌گردد، اما می‌توانید با استفاده از گزینه خط فرمان -c | --config یک فایل پیکربندی جایگزین را انتخاب کنید.

برای سفارشی‌سازی CGI، اسکریپت pg_format.cgi به دنبال یک فایل پیکربندی به نام pg_format.conf در همان دایرکتوری اسکریپت CGI می‌گردد.

برای مشاهده یک نمونه فایل پیکربندی به doc/pg_format.conf.sample مراجعه فرمایید.

برای جلوگیری از بررسی فایل‌های $XDG_CONFIG_HOME/pg_format یا $HOME/.pg_format توسط pg_format، می‌توانید از گزینه خط فرمان -X | --no-rcfile استفاده نمایید.

قالب‌بندی از ورودی استاندارد (Formatting from stdin)

می‌توانید pg_format را بدون هیچ آرگومانی یا با - اجرا کنید تا کد SQL از طریق stdin برای قالب‌بندی ارسال شود.

اگر از حالت تعاملی استفاده می‌کنید، پس از تایپ دستور SQL برای قالب‌بندی، باید کلیدهای `ctrl+d` را فشار دهید تا ورود متن خاتمه یابد.

$ pg_format
select * from customers;
< ctrl+d >

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

echo "select * from customers;" | pg_format

قالب‌بندی از VI (Formatting from VI)

با pgFormatter، کافی است خط زیر را به فایل ~/.vimrc خود اضافه کنید:

au FileType sql setl formatprg=/usr/local/bin/pg_format\ -

این کار باعث می‌شود دستورات gq شما به‌طور خودکار از pgFormatter استفاده کنند. برای نمونه اگر در خط اول هستید، با تایپ:

ESC+gq+G

کل فایل قالب‌بندی می‌شود.

ESC+gq+2j

دو خط بعدی قالب‌بندی خواهد شد.

با تشکر از David Fetter برای این نکته.

همچنین افزونه (Neo)vim برای قالب‌بندی کد برای انواع مختلف فایل وجود دارد که از pg_format برای قالب‌بندی فایل‌های نوع SQL پشتیبانی می‌کند. با تشکر از Anders Riutta برای پچ به (Neo)vim.

قالب‌بندی از Atom (Formatting from Atom)

اگر از atom به عنوان ویرایشگر دلخواه خود استفاده می‌کنید، می‌توانید بسته pg-formatter را نصب کنید که یک پوشش Node.js برای pgFormatter است.

ویژگی‌ها:

* قالب‌بندی متن انتخاب‌شده یا کل فایل از طریق کلید میانبر یا دستور.
* قالب‌بندی فایل‌های SQL هنگام ذخیره‌سازی.

نصب:

بسته pg-formatter را در رابط کاربری Atom جستجو کنید یا آن را از طریق خط فرمان دریافت نمایید:

apm install pg-formatter

نحوه استفاده:

کلیدهای Ctrl-Alt-F را برای قالب‌بندی متن انتخاب‌شده (یا کل فایل) فشار دهید یا میانبر خود را تعریف کنید:

'ctrl-alt-p': 'pg-formatter:format'

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

می‌توانید بسته را از نشانی زیر دریافت کنید:

سورس‌کدها در نشانی https://github.com/gajus/pg-formatter در دسترس هستند.

با تشکر از Alex Fedoseev برای بسته atom.

قالب‌بندی از Visual Studio (Formatting from Visual Studio)

با تشکر از Brady Holt یک افزونه Visual Studio Code برای قالب‌بندی SQL در PostgreSQL با استفاده از pgFormatter در دسترس است.

برای مشاهده دستورالعمل نصب و نحوه استفاده به نشانی بالا مراجعه فرمایید.

جلوگیری از جایگزینی قطعه‌کدها (Prevent replacing code snippets)

با استفاده از گزینه خط فرمان -p یا --placeholder می‌توانید بخش‌هایی از کد را در کوئری‌های SQL خود توسط pgFormatter دست‌نخورده نگه دارید. برای نمونه در کوئری‌هایی مانند:

SELECT * FROM projects WHERE projectnumber
        IN <<internalprojects>> AND username = <<loginname>>;

ممکن است بخواهید pgFormatter علامت‌های << و >> را به عنوان کلمات کلیدی جابجایی بیتی (bit-shift) تفسیر نکند و قطعه‌کدهای شما را تغییر ندهد. می‌توانید از یک عبارت منظم پرل استفاده کنید تا به pgFormatter دستور دهید بخشی از کوئری را دست‌نخورده حفظ کند. برای نمونه:

pg_format samples/ex9.sql -p '<<(?:.*)?>>'

عملگرهای شبیه جابجایی بیتی را قالب‌بندی نخواهد کرد.

اگر می‌خواهید کوئری‌ها پس از ۶۰ کاراکتر شکسته شوند (-w 60) و این محدودیت روی کامنت‌ها نیز اعمال شود (-C)، ممکن است نشانی‌های وب (URL) موجود در کامنت‌ها نیز شکسته شوند. اگر ترجیح می‌دهید نشانی‌های وب شکسته نشوند، می‌توانید از یک عبارت منظم برای جلوگیری از شکستن نشانی‌های اینترنتی استفاده کنید. برای نمونه:

pg_format samples/ex62.sql -C -w 60 -p 'https?:\/\/(www\.)?[-a-zA-Z0-9@:%._\+~#=]{1,256}\.[a-zA-Z0-9()]{1,6}\b([-a-zA-Z0-9()@:%_\+.~#?&//=]*)'

کوئری‌ها و کامنت‌ها شکسته می‌شوند، اما نشانی‌های وب بدون شکستگی باقی خواهند ماند.

جلوگیری از قالب‌بندی کد پویا (Prevent dynamic code formatting)

به‌طور پیش‌فرض pgFormatter تمام کدهای بین نقل‌قول تکی را به عنوان ثابت رشته‌ای در نظر می‌گیرد و هیچ قالب‌بندی روی این کدها انجام نمی‌دهد. استفاده از یک رشته به عنوان جداکننده کد برای جلوگیری از دو برابر کردن نقل‌قول تکی در تولید کدهای پویا متداول است، در این حالت ممکن است pgFormatter در تشخیص خودکار جداکننده کد ناموفق باشد. به‌طور پیش‌فرض هر رشته پس از کلمه کلیدی EXECUTE که با علامت دلار شروع شود جستجو خواهد شد. اگر نتواند جداکننده کد شما را به‌طور خودکار تشخیص دهد، می‌توانید از گزینه خط فرمان -S یا --separator برای تنظیم جداکننده کد مورد نظر استفاده کنید.

پوشش‌دهنده سبک Node.js (Node.js thin-wrapper)

آقای Gajus Kuizinas یک پوشش Node.js برای اجرای pgFormatter نوشته است. می‌توانید آن را در نشانی https://github.com/gajus/pg-formatter بیابید.

سفارشی‌سازی CSS برای خروجی CGI (Customize CSS for the CGI output)

می‌توانید استایل HTML رندرشده توسط استایل پیش‌فرض CSS را با ایجاد فایلی به نام custom_css_file.css در پوشه اسکریپت CGI برنامه pgFormatter تغییر دهید. استایل پیش‌فرض CSS به‌طور کامل با محتوای این فایل سفارشی جایگزین خواهد شد. برای مشاهده کدهای پیش‌فرض CSS استفاده‌شده باید به خروجی HTML تولیدشده نگاه کنید.

استفاده از pgFormatter به عنوان API (Using pgFormatter as an API)

می‌توانید با تنظیم سرآیند HTTP به نام 'Accept' روی مقدار 'application/json' هنگام فراخوانی آن به عنوان یک برنامه CGI، از pgFormatter به عنوان یک API استفاده کنید. در صورتی که نمی‌خواهید این ویژگی فعال باشد، مقدار "$self->{ 'enable_api' } = 0" را در تابع "set_config" در lib/pgFormatter/CGI.pm تنظیم کنید.