forked from EnterpriseDB/pldebugger
-
Notifications
You must be signed in to change notification settings - Fork 3
/
README.pldebugger
113 lines (74 loc) · 3.71 KB
/
README.pldebugger
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
PostgreSQL pl/pgsql Debugger API
================================
This module is a set of shared libraries which implement an API for debugging
pl/pgsql functions on PostgreSQL 8.4 and above. The pgAdmin project
(http://www.pgadmin.org/) provides a client user interface as part of pgAdmin
III v1.10.0 and above, and pgAdmin 4.
If you wish to debug functions on PostgreSQL 8.4, 9.0 or 9.1, please checkout
the PRE-9_2 branch from GIT.
If you wish to debug functions on PostgreSQL 8.2 or 8.3, please checkout the
PRE_8_4_SERVER branch from CVS.
Installation
------------
- Copy this directory to contrib/ in your PostgreSQL source tree.
- Run 'make; make install'
- Edit your postgresql.conf file, and modify the shared_preload_libraries config
option to look like:
shared_preload_libraries = '$libdir/plugin_debugger'
- Restart PostgreSQL for the new setting to take effect.
- Run the following command in the database or databases that you wish to
debug functions in:
CREATE EXTENSION pldbgapi;
(on server versions older than 9.1, you must instead run the pldbgapi--1.1.sql
script directly using psql).
Usage
-----
Connect pgAdmin to the database containing the functions you wish to debug.
Right-click the function to debug, and select Debugging->Debug to execute and
debug the function immediately, or select Debugging->Set Global Breakpoint to
set a breakpoint on the function. This will cause the debugger to wait for
another session (such as a backend servicing a web app) to execute the function
and allow you to debug in-context.
For further information, please see the pgAdmin documentation.
Troubleshooting
---------------
The majority of problems we've encountered with the plugin are caused by
failing to add (or incorrectly adding) the debugger plugin library to the
shared_preload_libraries configuration directive in postgresql.conf (following
which, the server *must* be restarted). This will prevent global breakpoints
working on all platforms, and on some (notably Windows) may prevent the
pldbgapi.sql script from executing correctly.
Architecture
------------
The debugger consists of three parts:
1. The client. This is typically a GUI displays the source code, current
stack frame, variables etc, and allows the user to set breakpoints and
step throught the code. The client can reside on a different host than
the database server.
2. The target backend. This is the backend that runs the code being debugged.
The plugin_debugger.so library must be loaded into the target backend.
3. Debugging proxy. This is another backend process that the client is
connected to. The API functions, pldbg_* in pldbgapi.so library, are
run in this backend.
The client is to connected to the debugging proxy using a regular libpq
connection. When a debugging session is active, the proxy is connected
to the target via a socket. The protocol between the proxy and the target
backend is not visible to others, and is subject to change. The pldbg_*
API functions form the public interface to the debugging facility.
debugger client *------ libpq --------* Proxy backend
(pgAdmin) *
|
pldebugger socket connection
|
*
application client *----- libpq -------* Target backend
Licence
-------
The pl/pgsql debugger API is released under the Artistic Licence v2.0.
https://opensource.org/licenses/artistic-license-2.0
Copyright (c) 2004-2022 EnterpriseDB Corporation. All Rights Reserved.
Contact
-------
For support, please email the pgAdmin support mailing list. See
http://www.pgadmin.org/support/
for more details.