Add item about server-side debugging.

Author: bmomjian

doc/FAQ_DEV

@@ -1,7 +1,7 @@
 
           Developer's Frequently Asked Questions (FAQ) for PostgreSQL
 
-   Last updated: Sun Mar 13 22:07:18 EST 2005
+   Last updated: Sat Apr 23 14:57:40 EDT 2005
 
    Current maintainer: Bruce Momjian (pgman@candle.pha.pa.us)
 
@@ -42,6 +42,7 @@ Technical Questions
    2.5) Why do we use palloc() and pfree() to allocate memory?
    2.6) What is ereport()?
    2.7) What is CommandCounterIncrement()?
+   2.8) What debugging features are available?
      _________________________________________________________________
 
 General Questions
@@ -762,3 +763,37 @@ typedef struct nameData
    to be broken into pieces so each piece can see rows modified by
    previous pieces. CommandCounterIncrement() increments the Command
    Counter, creating a new part of the transaction.
+   
+  2.8) What debugging features are available?
+  
+   First, try running configure with the --enable-cassert option, many
+   assert()s monitor the progress of the backend and halt the program
+   when something unexpected occurs.
+   
+   The postmaster has a -d option that allows even more detailed
+   information to be reported. The -d option takes a number that
+   specifies the debug level. Be warned that high debug level values
+   generate large log files.
+   
+   If the postmaster is not running, you can actually run the postgres
+   backend from the command line, and type your SQL statement directly.
+   This is recommended only for debugging purposes. If you have compiled
+   with debugging symbols, you can use a debugger to see what is
+   happening. Because the backend was not started from postmaster, it is
+   not running in an identical environment and locking/backend
+   interaction problems may not be duplicated.
+   
+   If the postmaster is running, start psql in one window, then find the
+   PID of the postgres process used by psql using SELECT
+   pg_backend_pid(). Use a debugger to attach to the postgres PID. You
+   can set breakpoints in the debugger and issue queries from psql. If
+   you are debugging postgres startup, you can set PGOPTIONS="-W n", then
+   start psql. This will cause startup to delay for n seconds so you can
+   attach to the process with the debugger, set any breakpoints, and
+   continue through the startup sequence.
+   
+   You can also compile with profiling to see what functions are taking
+   execution time. The backend profile files will be deposited in the
+   pgsql/data/base/dbname directory. The client profile file will be put
+   in the client's current directory. Linux requires a compile with
+   -DLINUX_PROFILE for proper profiling.

doc/src/FAQ/FAQ_DEV.html

@@ -13,7 +13,7 @@
     <H1>Developer's Frequently Asked Questions (FAQ) for
     PostgreSQL</H1>
 
-    <P>Last updated: Sun Mar 13 22:07:18 EST 2005</P>
+    <P>Last updated: Sat Apr 23 14:57:40 EDT 2005</P>
 
     <P>Current maintainer: Bruce Momjian (<A href=
     "mailto:pgman@candle.pha.pa.us">pgman@candle.pha.pa.us</A>)<BR>
@@ -71,6 +71,8 @@ <H2>Technical Questions</H2>
     <I>pfree</I>() to allocate memory?<BR>
      <A href="#2.6">2.6</A>) What is ereport()?<BR>
      <A href="#2.7">2.7</A>) What is CommandCounterIncrement()?<BR>
+     <A href="#2.8">2.8</A>) What debugging features are available?<BR>
+
      <BR>
 
     <HR>
@@ -941,6 +943,45 @@ <H3><A name="2.7">2.7</A>) What is CommandCounterIncrement()?</H3>
     modified by previous pieces. <I>CommandCounterIncrement()</I>
     increments the Command Counter, creating a new part of the
     transaction.</P>
+
+    <H3><A name="2.8">2.8</A>) What debugging features are
+    available?</H3>
+
+    <P>First, try running <I>configure</I> with the --enable-cassert
+    option, many <I>assert()</I>s monitor the progress of the backend
+    and halt the program when something unexpected occurs.</P>
+
+    <P>The <I>postmaster</I> has a <I>-d</I> option that allows even more
+    detailed information to be reported. The <I>-d</I> option takes a
+    number that specifies the debug level. Be warned that high debug
+    level values generate large log files.</P>
+
+    <P>If the <I>postmaster</I> is not running, you can actually run the
+    <I>postgres</I> backend from the command line, and type your
+    <SMALL>SQL</SMALL> statement directly. This is recommended
+    <B>only</B> for debugging purposes. If you have compiled with debugging
+    symbols, you can use a debugger to see what is happening. Because
+    the backend was not started from <I>postmaster</I>, it is not
+    running in an identical environment and locking/backend interaction
+    problems may not be duplicated.</P>
+
+    <P>If the <I>postmaster</I> is running, start <I>psql</I> in one
+    window, then find the <SMALL>PID</SMALL> of the <I>postgres</I>
+    process used by <I>psql</I> using <CODE>SELECT pg_backend_pid()</CODE>.
+    Use a debugger to attach to the <I>postgres</I> <SMALL>PID</SMALL>.
+    You can set breakpoints in the debugger and issue queries from
+
+    <I>psql</I>. If you are debugging <I>postgres</I> startup, you can
+    set PGOPTIONS="-W n", then start <I>psql</I>. This will cause startup
+    to delay for <I>n</I> seconds so you can attach to the process with
+    the debugger, set any breakpoints, and continue through the startup
+    sequence.</P>
+
+    <P>You can also compile with profiling to see what functions are
+    taking execution time. The backend profile files will be deposited
+    in the <I>pgsql/data/base/dbname</I> directory. The client profile
+    file will be put in the client's current directory. Linux requires
+    a compile with <I>-DLINUX_PROFILE</I> for proper profiling.</P>
   </BODY>
 </HTML>