PL/pgSQL Debugger

Native PL/pgSQL debugging for VS Code. Set breakpoints, step through stored functions and procedures, and inspect variables directly where you write SQL. With an enhanced pldebugger build, records, composites, arrays, and JSONB are rendered as structured, expandable values.

Built for your development database: local PostgreSQL, Docker, or self-hosted.

Getting a debug-ready PostgreSQL in 10 seconds

The debugger requires the pldebugger server extension. The fastest way is the prebuilt Docker image (PostgreSQL 13–18, amd64/arm64):

docker run -d --name pg-debug -p 5432:5432 \
  -e POSTGRES_PASSWORD=postgres \
  galien0xffffff/postgres-debugger:17

Already have a server? Run PL/pgSQL: Check Server Requirements — the extension diagnoses what's missing and guides you through the setup, including running CREATE EXTENSION pldbgapi for you when possible.

Managed PostgreSQL services generally do not expose pldebugger. Check your provider's supported-extension list. If plugin_debugger and pldbgapi are unavailable, debug against a local, Docker, or self-hosted development database, then deploy.

Features

• Step-by-step debugging — step over, step into, continue, across nested calls
• Breakpoints — validated against executable lines; conditional breakpoints and logpoints supported
• Rich variables panel — records, composites, arrays, and JSONB expand into structured trees when the server exposes them
• Anonymous record inspection — expands record values populated by SELECT INTO and FOR ... SELECT; explicit SQL casts preserve precise field types
• Set variable — change a variable's value mid-session from the Variables panel
• Inline values — variable values displayed in the editor while stepping
• Debug Console — RAISE NOTICE/WARNING output, plus SQL evaluation in the REPL
• SQL results panel — bounded result grid with JSON/composite inspection, history, copy, and CSV/JSON preview export
• CodeLens — assign a PostgreSQL connection to each standalone CALL / SELECT, then debug it in one click; routine definitions remain directly debuggable
• Function explorer — browse servers → schemas → functions in the sidebar, debug from a right-click
• Zero launch.json needed — registered servers appear in "Run and Debug"; launched sessions are saved to launch.json for one-key replay with F5
• Connection manager — paste a connection string, import from SQLTools/pgsql extensions, passwords stored in VS Code secrets
• Session recovery — inspect and terminate stale or blocked DAP sessions from the connected server in the Functions view
• Semantic highlighting — rich PL/pgSQL coloring including dollar quoting

Quick Start

1. Open a .sql file containing a PL/pgSQL routine definition, or a standalone CALL / SELECT statement
2. For a callsite, click Choose PostgreSQL connection and assign the server that should execute this statement
3. Click Debug PL/pgSQL; the selected connection remains visible beside that callsite and can be changed independently
4. The debugger stops on entry — step with F10/F11, inspect variables, or set breakpoints in the source
5. When the call completes, its result appears in the PL/pgSQL Results panel

Notes:

• Debug call is intentionally shown only for standalone SQL calls that can be replayed safely.
• Callsite connections are assigned per statement, not globally; assigning one callsite does not change another.
• Virtual source documents (plpgsql://...) expose routine-definition debugging, not call-site replay.

Debug Configuration

Sessions launched from CodeLens or the sidebar are automatically saved to .vscode/launch.json, so you can relaunch them with F5. You can also write configurations by hand:

{
  "type": "plpgsql",
  "request": "launch",
  "name": "Debug my_function",
  "server": "localhost:5432/mydb:postgres",
  "sql": "SELECT my_function()",
  "stopOnEntry": true
}

server is the server ID shown in the sidebar; if omitted, the active connection is used. Configurations never contain credentials — passwords stay in VS Code secret storage. stopOnEntry defaults to true; set it to false only for an intentional run-to-breakpoint launch. An optional attachTimeoutMs (default 30000) bounds how long a still-running target may wait to reach the debugged routine.

Result safety limits

Target rows are streamed through the adapter instead of being accumulated by the PostgreSQL client. The call always runs to completion, while the UI retains only a bounded preview:

• 200 rows by default, configurable with plpgsql-debugger.results.maxRows (20–1000)
• 64 KiB maximum per displayed cell
• 1 MiB maximum per structured result event
• 10 recent results and 5 MiB maximum retained by the extension

These are retention limits, not PostgreSQL wire-protocol limits: PostgreSQL and node-postgres still receive each individual field before the adapter can truncate its preview. To prevent avoidable copies, bytea, JSON, and JSONB stay textual on the target connection, and binary buffers are sliced before hex conversion. Do not use the debugger to fetch intentionally enormous individual values.

The panel records running, completed, and failed calls in the same bounded history. Result labels include the originating callsite when available. The grid uses one keyboard tab stop: navigate cells with the arrow keys, inspect with Enter or Space, and copy with Ctrl/Cmd+C. JSON values can be inspected in formatted or raw form.

Truncation warnings distinguish row, cell, and payload limits. Copying or exporting an incomplete preview requires confirmation. The Debug Console receives only a portable scalar value or compact summary, never an unbounded table. plpgsql-debugger.results.autoReveal opens the panel without taking keyboard focus when a call completes or fails. A running call updates history silently so it cannot compete with debugger source navigation.

CSV and clipboard TSV exports neutralize spreadsheet formulas and represent PostgreSQL NULL as \N, keeping it distinct from an empty string. JSON export preserves native null values and includes truncation metadata.

Requirements

• PostgreSQL 13+ with the pldebugger extension
• shared_preload_libraries = 'plugin_debugger' in postgresql.conf (needs a restart)
• CREATE EXTENSION pldbgapi; in your database — the extension offers to run this for you

pldebugger compatibility

The debugger works with the standard EnterpriseDB pldebugger packages (postgresql-17-pldebugger on Debian/Ubuntu), distribution packages, and the ng-galien fork.

• Standard/legacy builds: stepping, breakpoints, stack frames, and scalar variables work. Some builds do not publish PL/pgSQL records, rows, or record fields; those values are omitted cleanly without breaking the session.
• Enhanced fork / Docker image: additionally publishes composite and anonymous record values as JSON, enabling structured expansion in VS Code.

The extension never requires the fork for basic debugging.

How It Works

This extension implements the Debug Adapter Protocol (DAP) over PostgreSQL's pldbgapi debugging interface. Two database connections are used: one controls the debugger, the other executes your SQL. Every session uses a unique application_name and cleans up its own backends — concurrent debug sessions (multiple windows or teammates on a shared dev server) don't interfere with each other.

If a client crash still leaves a session behind, expand the connected server in Functions & Procedures, open Debug sessions, select the stale session, and confirm Terminate. Recovery groups the listener and target as one logical session and revalidates their reserved DAP application names before terminating them; unrelated PostgreSQL connections are never selected.

Telemetry

This extension does not collect any telemetry data.

Support and security

• Problems and feature requests: GitHub Issues
• Setup diagnostics: run PL/pgSQL: Check Server Requirements
• Security reports: see SECURITY.md
• Support policy and useful diagnostic information: see SUPPORT.md

License

MIT. Third-party components bundled in the extension are listed in THIRD_PARTY_NOTICES.md.