(mysql.info) bug-reports
Info Catalog
(mysql.info) information-sources
(mysql.info) introduction
(mysql.info) compatibility
1.8 How to Report Bugs or Problems
==================================
Before posting a bug report about a problem, please try to verify that
it is a bug and that it has not been reported already:
* Start by searching the MySQL online manual at
`http://dev.mysql.com/doc/'. We try to keep the manual up to date
by updating it frequently with solutions to newly found problems.
The change history (`http://dev.mysql.com/doc/mysql/en/news.html')
can be particularly useful since it is quite possible that a newer
version contains a solution to your problem.
* If you get a parse error for a SQL statement, please check your
syntax closely. If you can't find something wrong with it, it's
extremely likely that your current version of MySQL Server doesn't
support the syntax you are using. If you are using the current
version and the manual doesn't cover the syntax that you are
using, MySQL Server doesn't support your statement. In this case,
your options are to implement the syntax yourself or email
<licensing@mysql.com> and ask for an offer to implement it.
If the manual covers the syntax you are using, but you have an
older version of MySQL Server, you should check the MySQL change
history to see when the syntax was implemented. In this case, you
have the option of upgrading to a newer version of MySQL Server.
* For solutions to some common problems, see problems.
* Search the bugs database at `http://bugs.mysql.com/' to see
whether the bug has been reported and fixed.
* Search the MySQL mailing list archives at
`http://lists.mysql.com/'. See mailing-lists.
* You can also use `http://www.mysql.com/search/' to search all the
Web pages (including the manual) that are located at the MySQL AB
Web site.
If you can't find an answer in the manual, the bugs database, or the
mailing list archives, check with your local MySQL expert. If you still
can't find an answer to your question, please use the following
guidelines for reporting the bug.
The normal way to report bugs is to visit `http://bugs.mysql.com/',
which is the address for our bugs database. This database is public and
can be browsed and searched by anyone. If you log in to the system, you
can enter new reports. If you have no Web access, you can generate a
bug report by using the `mysqlbug' script described at the end of this
section.
Bugs posted in the bugs database at `http://bugs.mysql.com/' that are
corrected for a given release are noted in the change history.
If you have found a sensitive security bug in MySQL, you can send email
to <security@mysql.com>.
To discuss problems with other users, you can use one of the MySQL
mailing lists. mailing-lists.
Writing a good bug report takes patience, but doing it right the first
time saves time both for us and for yourself. A good bug report,
containing a full test case for the bug, makes it very likely that we
will fix the bug in the next release. This section helps you write your
report correctly so that you don't waste your time doing things that
may not help us much or at all. Please read this section carefully and
make sure that all the information described here is included in your
report.
Preferably, you should test the problem using the latest production or
development version of MySQL Server before posting. Anyone should be
able to repeat the bug by just using `mysql test < script_file' on your
test case or by running the shell or Perl script that you include in
the bug report. Any bug that we are able to repeat has a high chance of
being fixed in the next MySQL release.
It is most helpful when a good description of the problem is included
in the bug report. That is, give a good example of everything you did
that led to the problem and describe, in exact detail, the problem
itself. The best reports are those that include a full example showing
how to reproduce the bug or problem. See reproducible-test-case.
Remember that it is possible for us to respond to a report containing
too much information, but not to one containing too little. People
often omit facts because they think they know the cause of a problem
and assume that some details don't matter. A good principle to follow
is that if you are in doubt about stating something, state it. It is
faster and less troublesome to write a couple more lines in your report
than to wait longer for the answer if we must ask you to provide
information that was missing from the initial report.
The most common errors made in bug reports are (a) not including the
version number of the MySQL distribution that you use, and (b) not
fully describing the platform on which the MySQL server is installed
(including the platform type and version number). These are highly
relevant pieces of information, and in 99 cases out of 100, the bug
report is useless without them. Very often we get questions like, `Why
doesn't this work for me?' Then we find that the feature requested
wasn't implemented in that MySQL version, or that a bug described in a
report has been fixed in newer MySQL versions. Errors often are
platform-dependent. In such cases, it is next to impossible for us to
fix anything without knowing the operating system and the version
number of the platform.
If you compiled MySQL from source, remember also to provide information
about your compiler if it is related to the problem. Often people find
bugs in compilers and think the problem is MySQL-related. Most
compilers are under development all the time and become better version
by version. To determine whether your problem depends on your compiler,
we need to know what compiler you used. Note that every compiling
problem should be regarded as a bug and reported accordingly.
If a program produces an error message, it is very important to include
the message in your report. If we try to search for something from the
archives, it is better that the error message reported exactly matches
the one that the program produces. (Even the lettercase should be
observed.) It is best to copy and paste the entire error message into
your report. You should never try to reproduce the message from memory.
If you have a problem with Connector/ODBC (MyODBC), please try to
generate a trace file and send it with your report. See
myodbc-bug-report.
If your report includes long query output lines from test cases that
you run with the `mysql' command-line tool, you can make the output
more readable by using the -vertical option or the `\G' statement
terminator. The `EXPLAIN SELECT' example later in this section
demonstrates the use of `\G'.
Please include the following information in your report:
* The version number of the MySQL distribution you are using (for
example, MySQL 5.0.19). You can find out which version you are
running by executing `mysqladmin version'. The `mysqladmin'
program can be found in the `bin' directory under your MySQL
installation directory.
* The manufacturer and model of the machine on which you experience
the problem.
* The operating system name and version. If you work with Windows,
you can usually get the name and version number by double-clicking
your My Computer icon and pulling down the `Help/About Windows'
menu. For most Unix-like operating systems, you can get this
information by executing the command `uname -a'.
* Sometimes the amount of memory (real and virtual) is relevant. If
in doubt, include these values.
* If you are using a source distribution of the MySQL software,
include the name and version number of the compiler that you used.
If you have a binary distribution, include the distribution name.
* If the problem occurs during compilation, include the exact error
messages and also a few lines of context around the offending code
in the file where the error occurs.
* If `mysqld' died, you should also report the statement that
crashed `mysqld'. You can usually get this information by running
`mysqld' with query logging enabled, and then looking in the log
after `mysqld' crashes. See using-log-files.
* If a database table is related to the problem, include the output
from the `SHOW CREATE TABLE DB_NAME.TBL_NAME' statement in the bug
report. This is a very easy way to get the definition of any table
in a database. The information helps us create a situation
matching the one that you have experienced.
* For performance-related bugs or problems with `SELECT' statements,
you should always include the output of `EXPLAIN SELECT ...', and
at least the number of rows that the `SELECT' statement produces.
You should also include the output from `SHOW CREATE TABLE
TBL_NAME' for each table that is involved. The more information
you provide about your situation, the more likely it is that
someone can help you.
The following is an example of a very good bug report. The
statements are run using the `mysql' command-line tool. Note the
use of the `\G' statement terminator for statements that would
otherwise provide very long output lines that are difficult to
read.
mysql> SHOW VARIABLES;
mysql> SHOW COLUMNS FROM ...\G
<OUTPUT FROM SHOW COLUMNS>
mysql> EXPLAIN SELECT ...\G
<OUTPUT FROM EXPLAIN>
mysql> FLUSH STATUS;
mysql> SELECT ...;
<A SHORT VERSION OF THE OUTPUT FROM SELECT,
INCLUDING THE TIME TAKEN TO RUN THE QUERY>
mysql> SHOW STATUS;
<OUTPUT FROM SHOW STATUS>
* If a bug or problem occurs while running `mysqld', try to provide
an input script that reproduces the anomaly. This script should
include any necessary source files. The more closely the script
can reproduce your situation, the better. If you can make a
reproducible test case, you should upload it to be attached to the
bug report.
If you can't provide a script, you should at least include the
output from `mysqladmin variables extended-status processlist' in
your report to provide some information on how your system is
performing.
* If you can't produce a test case with only a few rows, or if the
test table is too big to be included in the bug report (more than
10 rows), you should dump your tables using `mysqldump' and create
a `README' file that describes your problem. Create a compressed
archive of your files using `tar' and `gzip' or `zip', and use FTP
to transfer the archive to
`ftp://ftp.mysql.com/pub/mysql/upload/'. Then enter the problem
into our bugs database at `http://bugs.mysql.com/'.
* If you believe that the MySQL server produces a strange result
from a statement, include not only the result, but also your
opinion of what the result should be, and an explanation
describing the basis for your opinion.
* When you provide an example of the problem, it's better to use the
table names, variable names, and so forth that exist in your
actual situation than to come up with new names. The problem could
be related to the name of a table or variable. These cases are
rare, perhaps, but it is better to be safe than sorry. After all,
it should be easier for you to provide an example that uses your
actual situation, and it is by all means better for us. If you
have data that you don't want to be visible to others in the bug
report, you can use FTP to transfer it to
`ftp://ftp.mysql.com/pub/mysql/upload/'. If the information is
really top secret and you don't want to show it even to us, go
ahead and provide an example using other names, but please regard
this as the last choice.
* Include all the options given to the relevant programs, if
possible. For example, indicate the options that you use when you
start the `mysqld' server, as well as the options that you use to
run any MySQL client programs. The options to programs such as
`mysqld' and `mysql', and to the `configure' script, are often key
to resolving problems and are very relevant. It is never a bad
idea to include them. If your problem involves a program written
in a language such as Perl or PHP, please include the language
processor's version number, as well as the version for any modules
that the program uses. For example, if you have a Perl script that
uses the `DBI' and `DBD::mysql' modules, include the version
numbers for Perl, `DBI', and `DBD::mysql'.
* If your question is related to the privilege system, please
include the output of `mysqlaccess', the output of `mysqladmin
reload', and all the error messages you get when trying to
connect. When you test your privileges, you should first run
`mysqlaccess'. After this, execute `mysqladmin reload version'
and try to connect with the program that gives you trouble.
`mysqlaccess' can be found in the `bin' directory under your MySQL
installation directory.
* If you have a patch for a bug, do include it. But don't assume
that the patch is all we need, or that we can use it, if you don't
provide some necessary information such as test cases showing the
bug that your patch fixes. We might find problems with your patch
or we might not understand it at all. If so, we can't use it.
If we can't verify the exact purpose of the patch, we won't use
it. Test cases help us here. Show that the patch handles all the
situations that may occur. If we find a borderline case (even a
rare one) where the patch won't work, it may be useless.
* Guesses about what the bug is, why it occurs, or what it depends
on are usually wrong. Even the MySQL team can't guess such things
without first using a debugger to determine the real cause of a
bug.
* Indicate in your bug report that you have checked the reference
manual and mail archive so that others know you have tried to
solve the problem yourself.
* If the problem is that your data appears corrupt or you get errors
when you access a particular table, you should first check your
tables and then try to repair them with `CHECK TABLE' and `REPAIR
TABLE' or with `myisamchk'. See database-administration.
If you are running Windows, please verify the value of
`lower_case_table_names' using the `SHOW VARIABLES LIKE
'lower_case_table_names'' command. This variable affects how the
server handles lettercase of database and table names. Its effect
for a given value should be as described in
name-case-sensitivity.
* If you often get corrupted tables, you should try to find out when
and why this happens. In this case, the error log in the MySQL
data directory may contain some information about what happened.
(This is the file with the `.err' suffix in the name.) See
error-log. Please include any relevant information from this
file in your bug report. Normally `mysqld' should _never_ crash a
table if nothing killed it in the middle of an update. If you can
find the cause of `mysqld' dying, it's much easier for us to
provide you with a fix for the problem. See
what-is-crashing.
* If possible, download and install the most recent version of MySQL
Server and check whether it solves your problem. All versions of
the MySQL software are thoroughly tested and should work without
problems. We believe in making everything as backward-compatible
as possible, and you should be able to switch MySQL versions
without difficulty. See which-version.
If you have no Web access and cannot report a bug by visiting
`http://bugs.mysql.com/', you can use the `mysqlbug' script to generate
a bug report (or a report about any problem). `mysqlbug' helps you
generate a report by determining much of the following information
automatically, but if something important is missing, please include it
with your message. `mysqlbug' can be found in the `scripts' directory
(source distribution) and in the `bin' directory under your MySQL
installation directory (binary distribution).
Info Catalog
(mysql.info) information-sources
(mysql.info) introduction
(mysql.info) compatibility
automatically generated byinfo2html