mirror of
https://github.com/pgadmin-org/pgadmin4.git
synced 2024-11-21 16:27:39 -06:00
172 lines
8.9 KiB
ReStructuredText
172 lines
8.9 KiB
ReStructuredText
.. _debugger:
|
|
|
|
*****************
|
|
`Debugger`:index:
|
|
*****************
|
|
|
|
.. image:: images/debug_main.png
|
|
:alt: Debugger page
|
|
:align: center
|
|
|
|
The debugger may be used to debug PL/pgSQL functions in PostgreSQL, as well as
|
|
EDB-SPL functions, stored procedures and packages in EDB Postgres Advanced
|
|
Server. The Debugger is available as an extension for your PostgreSQL
|
|
installation, and is distributed as part of Advanced Server. You must have
|
|
superuser privileges to use the debugger.
|
|
|
|
Before using the debugger, you must modify the *postgresql.conf* file, adding
|
|
the server-side debugger components to the value of the
|
|
*shared_preload_libraries* parameter, for example:
|
|
|
|
shared_preload_libraries = '$libdir/plugin_debugger'
|
|
|
|
After modifying the *shared_preload_libraries* parameter, restart the server to
|
|
apply the changes.
|
|
|
|
The debugger may be used for either in-context debugging or direct debugging of
|
|
a target function or procedure. When you use the debugger for in-context
|
|
debugging, you set a breakpoint at the first line of a program; when a session
|
|
invokes the target, control is transferred to the debugger. When using direct
|
|
debugging, the debugger prompts you for any parameters required by the target,
|
|
and then allows you to step through the code.
|
|
|
|
In-context Debugging
|
|
********************
|
|
|
|
To set a breakpoint at the first line of a program, right-click the name of the
|
|
object you would like to debug, and select *Set breakpoint* from the *Debugging*
|
|
sub-menu. The debugger window will open, waiting for another session to invoke
|
|
the program.
|
|
|
|
.. image:: images/debug_set_breakpoint.png
|
|
:alt: Debugger set a breakpoint demo
|
|
:align: center
|
|
|
|
When another session invokes the target, the debugger will display the code,
|
|
allowing you to add break points, or step through line-by-line. The other
|
|
session is suspended until the debugging completes; then control is returned
|
|
to the session.
|
|
|
|
.. image:: images/debug_ic_step_in.png
|
|
:alt: Debugger step-in demo
|
|
:align: center
|
|
|
|
Direct Debugging
|
|
****************
|
|
|
|
To use the debugger for direct debugging, right click on the name of the object
|
|
that you wish to debug in the pgAdmin tree control and select *Debug* from the
|
|
*Debugging* sub-menu. The debugger window will open, prompting you for any
|
|
values required by the program:
|
|
|
|
.. image:: images/debug_params.png
|
|
:alt: Debugger parameter dialog
|
|
:align: center
|
|
|
|
Use the fields on the *Debugger* dialog to provide a value for each parameter:
|
|
|
|
* The *Name* field contains the formal parameter name.
|
|
* The *Type* field contains the parameter data type.
|
|
* Check the *Null?* checkbox to indicate that the parameter is a NULL value.
|
|
* Check the *Expression?* checkbox if the Value field contains an expression.
|
|
* Use the *Value* field to provide the parameter value that will be passed to
|
|
the program. When entering parameter values, type the value into the
|
|
appropriate cell on the grid, or, leave the cell empty to represent NULL,
|
|
enter '' (two single quotes) to represent an empty string, or to enter a
|
|
literal string consisting of just two single quotes, enter \'\'. PostgreSQL
|
|
8.4 and above supports variadic function parameters. These may be entered as
|
|
a comma-delimited list of values, quoted and/or cast as required.
|
|
* Check the *Use default?* checkbox to indicate that the program should use
|
|
the value in the Default Value field.
|
|
* The *Default Value* field contains the default value of the parameter.
|
|
|
|
Provide values required by the program, and click the *Debug* button to start
|
|
stepping through the program.
|
|
The values of the arguments provided here are saved. The values will be pre-filled
|
|
next time the dialog opens. To clear the values, use the *Clear All* button.
|
|
|
|
.. image:: images/debug_step_in.png
|
|
:alt: Debugger step-in demo
|
|
:align: center
|
|
|
|
Using the Debugger
|
|
******************
|
|
|
|
The main debugger window consists of two panels and a context-sensitive toolbar.
|
|
Use toolbar icons to manage breakpoints and step into or through code; hover
|
|
over an icon for a tooltip that identifies the option associated with the icon.
|
|
The toolbar options are:
|
|
|
|
.. image:: images/debug_toolbar.png
|
|
:alt: Debugger navigation toolbar
|
|
:align: center
|
|
|
|
.. table::
|
|
:class: longtable
|
|
:widths: 1 4 1
|
|
|
|
+-------------------------+-----------------------------------------------------------------------------------------------------------+------------------------+
|
|
| Option | Action | Shortcut |
|
|
+=========================+===========================================================================================================+========================+
|
|
| *Step into* | Click the *Step into* icon to execute the currently highlighted line of code. | Option/Alt + Shift + I |
|
|
+-------------------------+-----------------------------------------------------------------------------------------------------------+------------------------+
|
|
| *Step over* | Click the *Step over* icon to execute a line of code, stepping over any sub-functions invoked by the code.| Option/Alt + Shift + O |
|
|
| | The sub-function executes, but is not debugged unless it contains a breakpoint. | |
|
|
+-------------------------+-----------------------------------------------------------------------------------------------------------+------------------------+
|
|
| *Continue/Start* | Click the *Continue/Start* icon to execute the highlighted code, and continue until the program | Option/Alt + Shift + C |
|
|
| | encounters a breakpoint or completes. | |
|
|
+-------------------------+-----------------------------------------------------------------------------------------------------------+------------------------+
|
|
| *Toggle breakpoint* | Use the *Toggle breakpoint* icon to enable or disable a breakpoint (without removing the breakpoint). | Option/Alt + Shift + T |
|
|
+-------------------------+-----------------------------------------------------------------------------------------------------------+------------------------+
|
|
| *Clear all breakpoints* | Click the *Clear all breakpoints* icon to remove all breakpoints from the program. | Option/Alt + Shift + X |
|
|
+-------------------------+-----------------------------------------------------------------------------------------------------------+------------------------+
|
|
| *Stop* | Click the *Stop* icon to halt the execution of a program. | Option/Alt + Shift + S |
|
|
+-------------------------+-----------------------------------------------------------------------------------------------------------+------------------------+
|
|
| *Help* | Click the *Help* icon to open debugger documentation. | |
|
|
+-------------------------+-----------------------------------------------------------------------------------------------------------+------------------------+
|
|
|
|
The top panel of the debugger window displays the program body; click in the
|
|
grey margin next to a line number to add a breakpoint. The highlighted line in
|
|
the top panel is the line that is about to execute.
|
|
|
|
.. image:: images/debug_main.png
|
|
:alt: Debugger main window
|
|
:align: center
|
|
|
|
The lower panel of the debugger window provides a set of tabs that allow you to
|
|
review information about the program:
|
|
|
|
* The *Parameters* tab displays the value of each parameter.
|
|
* The *Local* variables tab displays the current value of the program variables.
|
|
* The *Messages* tab displays any messages returned by the server (errors,
|
|
warnings and informational messages).
|
|
* The *Results* tab displays the server message when the program completes.
|
|
* The *Stack* tab displays the list of functions that have been invoked, but
|
|
which have not yet completed.
|
|
|
|
As you step through a program, the *Local variables* tab displays the current
|
|
value of each variable:
|
|
|
|
.. image:: images/debug_variables.png
|
|
:alt: Debugger local variables tab
|
|
:align: center
|
|
|
|
When you step into a subroutine, the *Stack* tab displays the call stack,
|
|
including the name of each caller, the parameter values for each caller (if
|
|
any), and the line number within each caller:
|
|
|
|
.. image:: images/debug_stack.png
|
|
:alt: Debugger local stack tab
|
|
:align: center
|
|
|
|
Select a caller to change focus to that stack frame and display the state of
|
|
the caller in the upper panel.
|
|
|
|
When the program completes, the *Results* tab displays the message returned by
|
|
the server. If the program encounters an error, the *Messages* tab displays
|
|
details:
|
|
|
|
.. image:: images/debug_error_message.png
|
|
:alt: Debugger error message
|
|
:align: center
|