Skip to content

agneum/plan-exporter

Repository files navigation

Query plan exporter

Build Status License Go Report

The utility receives Postgres Query Plans from psql and sends them to a visualizer for sharing. It will compute and highlight the most important information to make them easier to understand.

Installation

Precompiled binary (Linux)

It's highly recommended installing a specific version of the plan-exporter available on the releases page.

To quickly install the tool on Linux, download and decompress the binary, use an example:

wget https://github.com/agneum/plan-exporter/releases/download/v0.0.5/plan-exporter-0.0.5-linux-amd64.tar.gz
tar -zxvf plan-exporter-0.0.5-linux-amd64.tar.gz
sudo mv plan-exporter-*/plan-exporter /usr/local/bin/
rm -rf ./plan-exporter-*

Build from sources

Version 1.13+ is required.

git clone git@github.com:agneum/plan-exporter.git
cd plan-exporter
go install github.com/agneum/plan-exporter

On default, make install puts the compiled binary in go/bin.

Usage

  1. Run psql

  2. Set up output to the query plan exporter:

    postgres=# \o | plan-exporter
    • You may wish to specify --target [dalibo|depesz|tensor] to customize your visualizer
    • You may also specify --post-url <URL> if you are deploying one of these targets on-premise
  3. Run explain query:

    postgres=# explain select 1;
    postgres=# 
                          QUERY PLAN                      
    ------------------------------------------------------
     Seq Scan on hypo  (cost=0.00..180.00 rows=1 width=0)
       Filter: (id = 1)
    (2 rows)
    
    Do you want to post this plan to the visualizer?
    Send '\qecho Y' to confirm
  4. Confirm of posting the plan to the visualizer: \qecho Y

    postgres=# \qecho Y
    postgres=# Posting to the visualizer...

    That's it! Receive the link!

    The plan has been posted successfully.
    URL: https://explain.depesz.com/s/XXX
    postgres=#

Command-Line Options

  • --target - (string, optional) - defines a visualizer to export query plans. Available targets:
  • --post-url- (string, optional, default: "") - the absolute URL to which the <form> will POST to. A good reference would be to look for the action param in the <form> tag.
  • --auto-confirm (bool, optional, default: false) - send an execution plan automatically without additional confirmation. The option allows using plan-exporter outside psql. For example,
    psql -f my_explain_file.sql | plan-exporter --target=dalibo --auto-confirm

Contact Information

Follow the news and releases on twitter.