.\" Automatically generated by Pod::Man 4.10 (Pod::Simple 3.35) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "PG_FORMAT 1p" .TH PG_FORMAT 1p "2018-11-21" "perl v5.28.0" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" pg_format \- PostgreSQL SQL syntax beautifier .SH "DESCRIPTION" .IX Header "DESCRIPTION" This \s-1SQL\s0 formatter/beautifier supports keywords from \s-1SQL\-92, SQL\-99, SQL\-2003, SQL\-2008, SQL\-2011\s0 and PostgreSQL specifics keywords. May works with any other databases too. .PP pgFormatter can work as a console program or as a \s-1CGI.\s0 It will automatically detect his environment and output as text or as \s-1HTML\s0 following the context. .PP Keywords highlighting will only be available in \s-1CGI\s0 context. .SS "Terminal/console execution" .IX Subsection "Terminal/console execution" Usage: pg_format [options] file.sql .PP .Vb 1 \& PostgreSQL SQL queries and PL/PGSQL code beautifier. .Ve .PP Arguments: .PP .Vb 1 \& file.sql can be a file or use \- to read query from stdin. \& \& Returning the SQL formatted to stdout or into a file specified with \& the \-o | \-\-output option. .Ve .PP Options: .PP .Vb 10 \& \-a | \-\-anonymize : obscure all literals in queries, useful to hide \& confidential data before formatting. \& \-b | \-\-comma\-start : in a parameters list, start with the comma (see \-e) \& \-B | \-\-comma\-break : in insert statement, add a newline after each comma \& \-d | \-\-debug : enable debug mode. Disabled by default. \& \-e | \-\-comma\-end : in a parameters list, end with the comma (default) \& \-f | \-\-function\-case N: Change the case of the reserved keyword. Default is \& unchanged: 0. Values: 0=>unchanged, 1=>lowercase, \& 2=>uppercase, 3=>capitalize. \& \-F | \-\-format STR : output format: text or html. Default: text. \& \-h | \-\-help : show this message and exit. \& \-m | \-\-maxlength SIZE : maximum length of a query, it will be cutted above \& the given size. Default: no truncate. \& \-n | \-\-nocomment : remove any comment from SQL code. \& \-o | \-\-output file : define the filename for the output. Default: stdout. \& \-p | \-\-placeholder re : set regex to find code that must not be changed. \& \-s | \-\-spaces size : change space indent, default 4 spaces. \& \-S | \-\-separator STR : dynamic code separator, default to single quote. \& \-u | \-\-keyword\-case N : Change the case of the reserved keyword. Default is \& uppercase: 2. Values: 0=>unchanged, 1=>lowercase, \& 2=>uppercase, 3=>capitalize. \& \-v | \-\-version : show pg_format version and exit. .Ve .PP Examples: .PP .Vb 3 \& cat samples/ex1.sql | pg_format \- \& pg_format \-n samples/ex1.sql \& pg_format \-f 2 \-n \-o result.sql samples/ex1.sql .Ve .SS "\s-1CGI\s0 context" .IX Subsection "CGI context" Install pg_format into your cgi-bin folder, grant execution on it as a \s-1CGI\s0 script (maybe you should add the .cgi extension) and get it from your favorite browser. Copy files logo_pgformatter.png and icon_pgformatter.ico in the \s-1CGI\s0 directory, pg_format.cgi look for them in the same repository. .PP You have a live example without limitation than ten thousand characters in your \s-1SQL\s0 query here: .PP .Vb 1 \& http://sqlformat.darold.net/ .Ve .PP pg_format will automatically detected that it is running in a \s-1CGI\s0 environment and will output all html code needed to run an online code formatter site. There's nothing more to do. .SH "INSTALLATION" .IX Header "INSTALLATION" Download the tarball from github and unpack the archive as follow: .PP .Vb 4 \& tar xzf pgFormatter\-x.x.tar.gz \& cd pgFormatter\-x.x/ \& perl Makefile.PL \& make && sudo make install .Ve .PP This will copy the Perl script pg_format in /usr/local/bin/pg_format directory by default and the man page into /usr/local/share/man/man1/pg_format.1. Those are the default installation directory for 'site' install. .PP If you want to install all under /usr/ location, use INSTALLDIRS='perl' as argument of Makefile.PL. The script will be installed into /usr/bin/pg_format and the manpage into /usr/share/man/man1/pg_format.1. .PP For example, to install everything just like Debian does, proceed as follow: .PP .Vb 1 \& perl Makefile.PL INSTALLDIRS=vendor .Ve .PP By default \s-1INSTALLDIRS\s0 is set to site. .SH "HINTS" .IX Header "HINTS" .SS "Formatting from \s-1VI\s0" .IX Subsection "Formatting from VI" With pgFormatter, you can just add the following line to your ~/.vimrc file: .PP .Vb 1 \& au FileType sql setl formatprg=/usr/local/bin/pg_format\e \- .Ve .PP This lets your gq commands use pgFormatter automagically. For example if you are on the first line, typing: .PP .Vb 1 \& ESC+gq+G .Ve .PP will format the entire file. .PP .Vb 1 \& ESC+gq+2j .Ve .PP will format the next two line. .PP Thanks to David Fetter for the hint. .SS "Formatting from Atom" .IX Subsection "Formatting from Atom" If you use atom as your favorite editor you can install the pg-formatter package which is a Node.js wrapper of pgFormatter. .PP Features: .PP .Vb 2 \& * Format selected text or a whole file via keyboard shortcut or command. \& * Format SQL files on save. .Ve .PP Installation: .PP Search for pg-formatter in Atom \s-1UI\s0 or get it via command line: .PP .Vb 1 \& apm install pg\-formatter .Ve .PP Usage: .PP Hit Ctrl-Alt-F to format selected text (or a whole file) or define your shortcut: .PP .Vb 1 \& \*(Aqctrl\-alt\-p\*(Aq: \*(Aqpg\-formatter:format\*(Aq .Ve .PP Also, you can automatically format \s-1SQL\s0 files on save (disabled by default). .PP You can download the package from url: .PP .Vb 1 \& https://atom.io/packages/pg\-formatter .Ve .PP the sources are available at https://github.com/gajus/pg\-formatter .PP Thanks to Alex Fedoseev for the atom package. .SS "Prevent replacing code snippets" .IX Subsection "Prevent replacing code snippets" Using \-p or \-\-placeholder command line option it is possible to keep code untouched by pgFormatter in your \s-1SQL\s0 queries. For example, in query like: .PP .Vb 2 \& SELECT * FROM projects WHERE projectnumber \& IN <> AND username = <>; .Ve .PP you may want pgFormatter to not interpret << and >> as bit-shift keywords and modify your code snippets. You can use a Perl regular expression to instruct pgFormatter to keep some part of the query untouched. For example: .PP .Vb 1 \& pg_format samples/ex9.sql \-p \*(Aq<<(?:.*)?>>\*(Aq .Ve .PP will not format the bit-shift like operators. .SS "Prevent dynamic code formatting" .IX Subsection "Prevent dynamic code formatting" By default pgFormatter takes all code between single quote as string constant and do not perform any formatting on this code. It is common to use a string as code separator to avoid doubling single quote in dynamic code generation, in this case pgFormatter can fail to auto detect the code separator. By default it will search for any string after the \s-1EXECUTE\s0 keyword starting with dollar sign. If it can not auto detect your code separator you can use the command line option \-S or \-\-separator to set the code separator that must be used. .SS "Node.js thin-wrapper" .IX Subsection "Node.js thin-wrapper" Gajus Kuizinas has written a Node.js wrapper for executing pgFormatter. You can find it at https://github.com/gajus/pg\-formatter .SS "Customize \s-1CSS\s0 for the \s-1CGI\s0 output" .IX Subsection "Customize CSS for the CGI output" You can change the \s-1HTML\s0 style rendered through the default \s-1CSS\s0 style by creating a file named custom_css_file.css into the pgFormatter \s-1CGI\s0 script directory. The default \s-1CSS\s0 will be fully overridden by this custom file content. You have to look at the generated \s-1HTML\s0 output to get the default \&\s-1CSS\s0 code used. .SH "AUTHORS" .IX Header "AUTHORS" pgFormatter is an original work from Gilles Darold with major code refactoring by Hubert depesz Lubaczewski. .SH "COPYRIGHT" .IX Header "COPYRIGHT" Copyright 2012\-2018 Gilles Darold. All rights reserved. .SH "LICENSE" .IX Header "LICENSE" pgFormatter is free software distributed under the PostgreSQL Licence. .PP A modified version of the SQL::Beautify Perl Module is embedded in pgFormatter with copyright (C) 2009 by Jonas Kramer and is published under the terms of the Artistic License 2.0.