codekingpro/portable-devtools

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