=head1 NAME

pg_format - PostgreSQL SQL syntax beautifier

=head1 DESCRIPTION

This SQL formatter/beautifier supports keywords from SQL-92, SQL-99,
SQL-2003, SQL-2008, SQL-2011 and PostgreSQL specifics keywords. Works
with any other databases too.

pgFormatter can work as a console program or as a CGI. It will automatically
detect its environment and format output as text or as HTML following the context.

Keywords highlighting will only be available in CGI context.

=head2 Terminal/console execution

Usage: pg_format [options] file.sql

    PostgreSQL SQL queries and PL/PGSQL code beautifier.

Arguments:

    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.

Options:

    -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.
    -g | --nogrouping     : add a newline between statements in transaction
                            regroupement. Default is to group statements.
    -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.
    -t | --format-type    : try another formatting type for some statements.
    -T | --tabs           : use tabs instead of space characters, when used
                            spaces is set to 1 whatever is the value set to -s.
    -u | --keyword-case N : Change the case of the reserved keyword. Default is
                            uppercase: 2. Values: 0=>unchanged, 1=>lowercase,
                            2=>uppercase, 3=>capitalize.
    -U | --type-case N    : Change the case of the data type name. Default is
                            lowercase: 1. Values: 0=>unchanged, 1=>lowercase,
                            2=>uppercase, 3=>capitalize.
    -v | --version        : show pg_format version and exit.
    -w | --wrap-limit N   : wrap queries at a certain length.
    -W | --wrap-after N   : number of column after which lists must be wrapped.
                            Default: puts every item on its own line.

Examples:

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

=head2 CGI context

Install pg_format into your cgi-bin folder, grant execution on it as a CGI
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 CGI
directory, pg_format.cgi look for them in the same repository.

You have a live example without limitation than ten thousand characters in
your SQL query here:

	http://sqlformat.darold.net/

pg_format will automatically detected that it is running in a CGI environment
and will output all html code needed to run an online code formatter site.
There's nothing more to do.

You need to install Perl CGI module first if it is not already the case:

	yum install perl-cgi
or
	apt-get install libcgi-pm-perl

following your distribution.


=head1 INSTALLATION

Download the tarball from github and unpack the archive as follow:

	tar xzf pgFormatter-x.x.tar.gz
	cd pgFormatter-x.x/
	perl Makefile.PL
	make && sudo make install

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.

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.

For example, to install everything just like Debian does, proceed as follow:

	perl Makefile.PL INSTALLDIRS=vendor

By default INSTALLDIRS is set to site.

Regression tests can be executed with the following command:

	make test


=head1 SPECIAL FORMATTING

=head2 Option -W, --wrap-after

This option can be used to set number of column after which lists must be
wrapped. By default pgFormatter puts every item on its own line. This format
applies to SELECT and FROM list. For example the following query:
    
    SELECT a, b, c, d FROM t_1, t_2, t3 WHERE a = 10 AND b = 10;
    
will be formatted into with -W 4:
    
    SELECT a, b, c, d
    FROM t_1, t_2, t3
    WHERE a = 10
        AND b = 10;

Note this formatting doesn't fits well with sub queries in list.

=head2 Option -w, --wrap-limit

This option wraps queries at a certain length whatever is the part
of the query at the limit unless it is a comment. For example if
the limit is reach in a text constant the text will be wrapped.
Indentation is not included in the character count. This option
is applied in all cases even if other options are used.

=head2 Option -t, --format-type

This option activate an alternative formatting that adds:

  * newline in procedure/function parameter list
  * new line in PUBLICATION and POLICY DDL

Expect this list grow following alternative thoughts.

=head2 Option -g, --no-grouping

By default pgFormatter groups all statements when they are in a
transaction:

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

By disabling grouping of statement pgFormatter will always add an
extra newline characters between statements just like outside a
transaction:

    BEGIN;

    INSERT INTO foo VALUES (1, 'text 1');

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

    COMMIT;

This might add readability to not DML transactions.

=head1 HINTS

=head2 Formatting from VI

With pgFormatter, you can just add the following line to your ~/.vimrc file:

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

This lets your gq commands use pgFormatter automagically. For example if you
are on the first line, typing:

	ESC+gq+G

will format the entire file.

	ESC+gq+2j

will format the next two line.

Thanks to David Fetter for the hint.

There is also the (Neo)vim plugin for formatting code for many file types
that support pg_format to format SQL file type.  Thanks to Anders Riutta
for the patch to (Neo)vim.

=head2 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.

Features:

  * Format selected text or a whole file via keyboard shortcut or command.
  * Format SQL files on save.

Installation:

Search for pg-formatter in Atom UI or get it via command line:

    apm install pg-formatter

Usage:

Hit Ctrl-Alt-F to format selected text (or a whole file) or define
your shortcut:

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

Also, you can automatically format SQL files on save (disabled by default).

You can download the package from url:

	https://atom.io/packages/pg-formatter

the sources are available at https://github.com/gajus/pg-formatter

Thanks to Alex Fedoseev for the atom package.

=head2 Formatting from Visual Studio

Thanks to Brady Holt a Visual Studio Code extension is available to formats
PostgresSQL SQL using pgFormatter.

	https://marketplace.visualstudio.com/items?itemName=bradymholt.pgformatter

For installation and use have a look at URL above.

=head2 Prevent replacing code snippets

Using -p or --placeholder command line option it is possible to keep code
untouched by pgFormatter in your SQL queries. For example, in query like:

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

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:

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

will not format the bit-shift like operators.

=head2 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 EXECUTE 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.

=head2 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

=head2 Customize CSS for the CGI output

You can change the HTML style rendered through the default CSS style by
creating a file named custom_css_file.css into the pgFormatter CGI script
directory. The default CSS will be fully overridden by this custom file
content. You have to look at the generated HTML output to get the default
CSS code used.

=head1 AUTHORS

pgFormatter is an original work from Gilles Darold with major code refactoring
by Hubert depesz Lubaczewski.

=head1 COPYRIGHT

Copyright 2012-2020 Gilles Darold. All rights reserved.

=head1 LICENSE

pgFormatter is free software distributed under the PostgreSQL Licence.

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.

