|
Table of Contents
|
About this manual
License
The owner of this manual is Federico Razzoli, also creator of STK/DBUG.
This manual is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 3.0 Unported License.
Terminology
The following terms are used in this document:
- Buggy code: Code which needs to be debugged.
- Worker: Thread that runs the buggy code.
- Inspector: Thread that inspects the Worker.
STK/DBUG Overview
License
The owners of STK/DBUG iw Federico Razzoli, also owner of this manual.
STK/DBUG is licensed under a GNU Affero General Public License, version 3. You should find it in the COPYING file.
System Requirements
STK/DBUG is being developed on MariaDB 10.
It will fully support MariaDB, Percona Server and Oracle MySQL 5.0 and higher.
Server Configuration
You must be sure that the unique_checks system variable is OFF, when you call config_set() and when you use lock_method='table'.
The local and global values of the following variables don't affect the STK/DBUG (but can still affect the buggy code):
- storage_engine
- sql_mode
- sql_warnings
- innodb_strict_mode
- autocommit
- foreign_key_checks
- max_sp_recursion_depth
Risks
The following section is included to inform users about the potential risks, whether known or unknown, of using this tool. The two main categories of risks are those created by the nature of the tool (e.g. read-only tools vs. read-write tools) and those created by bugs.
At the time of this writing, we know of no bugs that could cause serious harm to users.
The authoritative source for updated information is always the online issue tracking system. Issues that affect this tool will be marked as such. You can see a list of such issues at the following URL: https://bugs.launchpad.net/stk-dbug
Downloads
STK/DBUG project is hosted by Launchpad. No release is avaible yet, but the development tree is public : https://launchpad.net/stk-dbug
Tests
Unit tests will be avaible before the stable release.
General concepts
One of the biggest problems with Stored Procedures, in MariaDB and MySQL, is that a native debugging library does not exist. A debugging library is something which says to the server: "execute this Procedure until line 45, then pause", and then lets the user see all variables values, until he decides to resume or stop the execution. There are some debuggers for MariaDB and MySQL, but they need to use some hacks to emulate a debugging library. Most of them insert some SQL statements into the buggy code. Others contain an SQL interpreter which runs the Procedures and tries to amulate like MariaDB and MySQL. Both the approaches have some problems, but we prefer the first one.
STK/DBUG is a sort of debugging library written in SQL. The most important feature is that it can run in a multithread mode: there is one Worker thread, which runs the buggy code, and one or more Inspector Thread, which runs the debug code. The developer can place some named CheckPoints into the buggy code (calls to the cp() Procedure). When the execution reaches a CheckPoint, the cp() function checks if an Inspector is waiting for a CheckPoint with that name. If so, the Worker Thread waits until the Inspector frees that CheckPoint.
While the Worker is waiting, the Inspector can examine the status of the tables. Of course there is a problem here: user variables, session variables and temporary tables, as well as queries using some particular functions, do not exist out of the Worker's session. To solve this problem, when a CheckPoint is found and someone is waiting for it, local variables and temporary tables are copied in a Snapshot (a database). Local variables are contained in a table, and temporary tables and views are copied as non-temporary tables. The Inspector can examine those objects.
Usage
Examples
You can find usage examples in examples directory. All examples contain an initial comment (after the license note) which explains what the example does, and shows how to use it. Then, there is the code you must run before running the example. Look at that code to see the debug code.
Avaible examples are:
trivial.sql: The most example. It just shows how to setup some CheclPoints and pause the execution when it reaches them.
general_checkpoint.sql: Shows how to use the General CheckPoint.
temp_table.sql: Show how to inspect a TEMPORARY table.
Setting CheckPoints in your Buggy Code
To setup a CheckPoint in the buggy code, this call must be added:
CALL `stk_dbug`.cp(cp_name);
cp_name is any string which does not start with a '*' character.
At the end of the buggy code code (which could possible have more than one "end"!) make sure to call:
CALL `stk_dbug`.clean();
If for some reason that line has not been reached, it should be called it from the Worker Thread's consolle.
How to trigger a CheckPoint
Named CheckPoints
The following statement triggers a specific CheckPoint:
CALL `stk_dbug`.go_to(cp_name);
General CheckPoint
To trigger any CheckPoint as soon as it is reached, the General CheckPoint can be triggered:
CALL ‘stk_dbug`.go_to(’*');
When using the General CheckPoint, it can be useful to get the name of the last triggered CheckPoint:
SELECT `stk_dbug`.last_cp();
Also, it is possible to get a list of all found CheckPoints, even those which were not triggered. The list contains a was_triggered field which tells wether the CheckPoint was triggered. The syntax is:
CALL `stk_dbug`.show_cp();
Disabling all CheckPoints
To free the Worker and let it end the execution regardless of the CheckPoints is may find, run:
CALL ‘stk_dbug`.go_to(’');
When dbug is finished, this should always be done.
Killing the Worker
The tester has an easy way to KILL the Worker without knowing his connection id:
CALL die();
But sometimes the tester can't simply KILL it, because he wants it to complete some task before dying.. In such cases, it is possible for the Inspector to send the Worker a message. The Worker will receive it when a new CheckPoint is triggered.
The (very bad) message is:
CALL tell_die();
STK/DBUG debugging
The following Routines have been implemented to debug STK/DBUG. They probably have no other uses.
void show_inspections()
Shows a list of all Inspector/Worker couples.
void show_watch_list()
Shows a list of all objects that Inspector is currently watching.