Preparing the System to Run MySQL in a Debugger

             
 To fully enjoy the study of MySQL internals, and to be able to execute the examples in the subsequent sections of this chapter, you must have gdb (http://www.gnu.org/software/gdb/) installed on your system, and be present in your PATH. You also need to have the X Window System, including a terminal program such as xterm. There are a number of X standard implementations, perhaps the most popular of them being X.org (http://www.x.org).

The tools just mentioned will be preinstalled by default on most Linux distributions. However, to confirm that you can debug threaded programs under gdb, it is important to make sure that /lib/libpthread.so and /lib/libthread_db.so are not stripped. The following example illustrates how to check this:

     $ file -L /lib/libthread_db.so
     /lib/libthread_db.so: ELF 32-bit LSB shared object, Intel 80386, version 1, not
     stripped
     $ file -L /lib/libpthread.so
     /lib/libpthread.so: ELF 32-bit LSB shared object, Intel 80386, version 1, not
     stripped

            As you can see in the output, both libraries are not stripped. If you happen to have the misfortune of having them stripped by default, and you are not able to find a package with unstripped versions for your distribution, you can fix the problem by recompiling glibc.

Debugger-Guided Source Tour

Now with the tedious but necessary preparation behind your back, you can actually start exploring the source code. I find it particularly helpful, when faced with large quantities of unfamiliar code, to start by running a very simple test case in a debugger. MySQL, being a threaded server, presents a number of difficulties in this respect. Fortunately, MySQL developers have created a set of tools to facilitate the process for their own use, which they make available to the public. In this section, you will learn how to use them.

Instructions for running a simple query in a debugger:

  1. Change to the mysql-test subdirectory in the source tree.
  2. Create a new file named t/example.test. It is important that the file be under the t
     subdirectory, have the extension .test, and be different from the names of the
     already existing test files in the t subdirectory. Outside of those restrictions, the
     name of the file can be anything you want. If you choose a different name, how-
     ever, you must also change references to it accordingly in the rest of this example.
  3. Put the following line in the edited file:
          select 1;
  4. Save the file.
  5. Execute the following command to create the master result file:

          $ ./mysql-test-run --local --record example

  6. Execute the following command to load MySQL server into gdb in a separate
     xterm window (if you’re running it on another computer via SSH, be sure to
     have SSH X-forwarding enabled. If it’s not possible—e.g., because you’re using
     Windows—use --manual-gdb instead of --gdb):

          $ ./mysql-test-run --gdb example

  7. An xterm window will open with a gdb prompt inside. The MySQL server will be
     started with a preset breakpoint in the mysql_parse( ) function in the file sql/sql_
     parse.cc. The mysql-test-run script will spawn a client that will connect to the
     server being debugged, and start executing the queries listed in example.test, in
     our case, select 1. Refer to the sections “Basics of Working with gdb,” and
     “Interesting Breakpoints and Variables,” later in this chapter, to set breakpoints
     of interest, then enter c at the gdb prompt to continue execution.
  8. When the execution of example.test terminates, mysql-test-run returns. How-
     ever, the debugger window will remain open. You may connect using a MySQL
     command client to port 9306 and manually issue various queries, set break-
     points in the debugger, and examine their execution. A few examples follow.
     From the Unix shell, enter:
          $ ../client/mysql -uroot –host=127.0.0.1 –port=9306 test
     You will enter the MySQL command-line client shell, from which you continue
     with:
          $ create table t1(n int);
     When the debugger breaks in mysql_parse( ), type into the debugger window:
          disa 1
          b mysql_insert
          c
     At the MySQL command-line client prompt, type:
          insert into t1 values(345);
     The debugger will break in mysql_insert( ). In the debugger window, type:
          bt
     The debugger shows you the stack trace at the current breakpoint.

  9. When finished with this debugger-guided source tour, press Ctrl-C if you do not
     have the gdb prompt, execute the quit command in the debugger, confirm that
     you want to stop the program being run when prompted, and return to the shell
     prompt from which you have executed mysql-test-run.

10. To speed up the execution of your next debugger-guided source tour, execute
     the following command at the shell prompt to clean up:
          $ rm -f var/run/*.pid