Enabling Debug Logging in pgcli

You stare at pgcli, watching the prompt blink back at you. The output gives no clues. The database is silent. The problem isn’t your SQL—it’s that you can’t see what’s happening under the hood. Without debug logging, you’re blind. With it, you control the investigation.

Enabling debug logging in pgcli is straightforward once you know where to look. The client is powered by pgcli's Python-based core and uses pgcli configuration files to store settings. Most users don’t realize that pgcli supports verbose logging through PAGER, --verbose, and DEBUG environment levels. When you turn these on, every piece of the connection handshake, query execution, and returned output is revealed in real time.

To get started, locate your pgcli config file—usually found in ~/.config/pgcli/config or ~/.pgclirc. In that file, you can adjust log file paths and verbosity settings. Set log_file to a known location, such as /tmp/pgcli-debug.log, and change the log level to debug. Restart your session, and pgcli will capture everything—command invocations, query timings, connection retries, and error traces.

If you prefer not to edit files, launch pgcli with the --verbose flag. For even deeper inspection, set the environment variable before connecting:

export PGCLI_DEBUG=1
pgcli --verbose postgres://user@localhost/db

Now every layer is speaking to you—authentication steps, SSL negotiation, query parsing, and more. This is especially powerful when debugging deadlocks, query hangs, or unexpected latency spikes.

Once you have debug logging data, you can feed it into metrics, tail it live, or share precise query-response pairs with your team. You eliminate guesswork and move faster toward a fix. Continuous visibility means fewer surprises in production and faster recovery when something breaks.

Systems fail when you can’t see inside them. Logging is your way in. You can set it up in two minutes, and once you see the full query flow, you won’t go back to silence.

If you want to go further—stream logs, monitor queries in real time, and debug without leaving your terminal—connect your database to hoop.dev. You can see live debug logging in minutes, with no extra infrastructure and no waiting.