pgfmt

A PostgreSQL SQL formatter with multiple style options.

pgfmt parses SQL using tree-sitter-postgres and reformats it according to one of several well-known style guides. Formatting is powered by libpgfmt.

Installation

Homebrew (macOS / Linux)

brew tap gmr/pgfmt
brew install pgfmt

[!NOTE] Homebrew 6.0 added tap trust, and some versions fail to install third-party taps inside the build sandbox (the error mentions build.rb ... exited with 1). If you hit this, trust the formula first:

brew trust --formula gmr/pgfmt/pgfmt

or, as a temporary workaround, set HOMEBREW_NO_REQUIRE_TAP_TRUST=1 for the install.

Quick Install (Linux / macOS)

curl -fsSL https://raw.githubusercontent.com/gmr/pgfmt/main/install.sh | sh

To install to a custom directory:

INSTALL_DIR=~/.local/bin curl -fsSL https://raw.githubusercontent.com/gmr/pgfmt/main/install.sh | sh

Install a Specific Version

VERSION=v1.0.0 curl -fsSL https://raw.githubusercontent.com/gmr/pgfmt/main/install.sh | sh

From Source (via Cargo)

cargo install pgfmt

Download Binaries

Pre-built binaries for Linux and macOS (x86_64 and aarch64) are available on the GitHub Releases page.

Usage

# Format a file (default: aweber style)
pgfmt query.sql

# Format from stdin
echo "SELECT a,b FROM t WHERE x=1" | pgfmt

# Choose a style
pgfmt --style mozilla query.sql
pgfmt --style dbt query.sql

# Check if already formatted (exit 1 if not)
pgfmt --check query.sql

Styles

aweber (default)

Based on river style with JOINs as river keywords. INNER JOIN, LEFT JOIN, etc. participate in river alignment. Uppercase keywords.

    SELECT r.last_name
      FROM riders AS r
INNER JOIN bikes AS b
        ON r.bike_vin_num = b.vin_num
       AND b.engines > 2;

dbt

Based on dbt Labs' SQL style. Lowercase keywords, 4-space indent, blank lines between clauses, generous whitespace. Explicit join types.

select
    a.title,
    a.release_date

from albums as a

where
    a.title = 'Charcoal Lane'
    or a.title = 'The New Danger'

gitlab

Based on the GitLab SQL Style Guide. Uppercase keywords, 2-space indent, blank lines inside CTE bodies.

SELECT
  a.title,
  a.release_date
FROM albums AS a
WHERE
  a.title = 'Charcoal Lane'
  OR a.title = 'The New Danger';

kickstarter

Based on the Kickstarter SQL Style Guide. Uppercase keywords, 2-space indent, JOIN ON on same line, compact CTE chaining.

SELECT
  a.title,
  a.release_date
FROM albums AS a
INNER JOIN orders AS o ON a.id = o.album_id
WHERE
  a.title = 'Charcoal Lane'
  AND a.year > 2000;

mattmc3

Based on the Modern SQL Style Guide by mattmc3. Lowercase river-style with leading commas. Uses plain join instead of inner join.

select a.title
     , a.release_date
  from albums as a
  join orders as o
    on a.id = o.album_id
 where a.title = 'Charcoal Lane'
   and a.year > 2000;

mozilla

Based on the Mozilla SQL Style Guide. Keywords left-aligned at column 0, content indented 4 spaces underneath. One item per line. Uppercase keywords.

SELECT
    a.title,
    a.release_date
FROM albums AS a
WHERE
    a.title = 'Charcoal Lane'
    OR a.title = 'The New Danger';

river

Based on sqlstyle.guide by Simon Holywell. Keywords are right-aligned to form a visual "river" separating keywords from content. Uppercase keywords.

SELECT a.title,
       a.release_date
  FROM albums AS a
 WHERE a.title = 'Charcoal Lane'
    OR a.title = 'The New Danger';