Author: paul
Date: 2006-01-04 05:12:52 +0100 (Wed, 04 Jan 2006)
New Revision: 661
Log:
r5803@frost: paul | 2006-01-03 21:41:00 -0600
The bug report procedure isn't an "information source." Promote the
section up a level.
Added:
trunk/refman-common/bug-reports.xml
Modified:
trunk/
trunk/refman-common/information-sources.xml
Property changes on: trunk
___________________________________________________________________
Name: svk:merge
- b5ec3a16-e900-0410-9ad2-d183a3acac99:/mysqldoc-local/mysqldoc/trunk:5801
bf112a9c-6c03-0410-a055-ad865cd57414:/mysqldoc-local/mysqldoc/trunk:1848
+ b5ec3a16-e900-0410-9ad2-d183a3acac99:/mysqldoc-local/mysqldoc/trunk:5803
bf112a9c-6c03-0410-a055-ad865cd57414:/mysqldoc-local/mysqldoc/trunk:1848
Added: trunk/refman-common/bug-reports.xml
===================================================================
--- trunk/refman-common/bug-reports.xml 2006-01-04 03:49:42 UTC (rev 660)
+++ trunk/refman-common/bug-reports.xml 2006-01-04 04:12:52 UTC (rev 661)
@@ -0,0 +1,615 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
+"http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd"
+[
+ <!ENTITY % fixedchars.entities SYSTEM "fixedchars.ent">
+ %fixedchars.entities;
+ <!ENTITY % title.entities SYSTEM "titles.en.ent">
+ %title.entities;
+]>
+<section id="bug-reports">
+
+ <title>&title-bug-reports;</title>
+
+ <indexterm type="concept">
+ <primary>reporting</primary>
+ <secondary>errors</secondary>
+ </indexterm>
+
+ <indexterm type="concept">
+ <primary>errors</primary>
+ <secondary>reporting</secondary>
+ </indexterm>
+
+ <indexterm type="concept">
+ <primary>searching</primary>
+ <secondary>MySQL Web pages</secondary>
+ </indexterm>
+
+ <indexterm type="concept">
+ <primary>bug reports</primary>
+ <secondary>criteria for</secondary>
+ </indexterm>
+
+ <indexterm type="concept">
+ <primary>bugs</primary>
+ <secondary>reporting</secondary>
+ </indexterm>
+
+ <indexterm type="concept">
+ <primary>reporting</primary>
+ <secondary>bugs</secondary>
+ </indexterm>
+
+ <indexterm type="concept">
+ <primary>problems</primary>
+ <secondary>reporting</secondary>
+ </indexterm>
+
+ <indexterm type="concept">
+ <primary>errors</primary>
+ <secondary>reporting</secondary>
+ </indexterm>
+
+ <indexterm type="concept">
+ <primary>creating</primary>
+ <secondary>bug reports</secondary>
+ </indexterm>
+
+ <indexterm type="concept">
+ <primary>bugs.mysql.com</primary>
+ </indexterm>
+
+ <indexterm type="concept">
+ <primary>bugs database</primary>
+ </indexterm>
+
+ <para>
+ 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:
+ </para>
+
+ <itemizedlist>
+
+ <listitem>
+ <para>
+ Start by searching the MySQL online manual at
+ <ulink url="&base-url-docs;"/>. We try to keep the manual up to
+ date by updating it frequently with solutions to newly found
+ problems. The change history
+ (<ulink url="&base-url-docs;mysql/en/news.html"/>) can be
+ particularly useful since it is quite possible that a newer
+ version contains a solution to your problem.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ 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
+ <email>licensing@stripped</email> and ask for an offer to
+ implement it.
+ </para>
+
+ <para>
+ 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.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ For solutions to some common problems, see
+ <xref linkend="problems"/>.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ Search the bugs database at
+ <ulink url="http://bugs.mysql.com/"/> to see whether the bug has
+ been reported and fixed.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ Search the MySQL mailing list archives at
+ <ulink url="http://lists.mysql.com/"/>. See
+ <xref linkend="mailing-lists"/>.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ You can also use <ulink url="http://www.mysql.com/search/"/> to
+ search all the Web pages (including the manual) that are located
+ at the MySQL AB Web site.
+ </para>
+ </listitem>
+
+ </itemizedlist>
+
+ <para>
+ 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.
+ </para>
+
+ <para>
+ The normal way to report bugs is to visit
+ <ulink url="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 <command>mysqlbug</command> script described at the end of
+ this section.
+ </para>
+
+ <para>
+ All bugs posted in the bugs database at
+ <ulink url="http://bugs.mysql.com/"/> are corrected or documented in
+ the next MySQL release. If only minor code changes are needed to
+ correct a problem, we may also post a patch that fixes the problem.
+ </para>
+
+ <para>
+ If you have found a sensitive security bug in MySQL, you can send
+ email to <email>security@stripped</email>.
+ </para>
+
+ <para>
+ To discuss problems with other users, you can use one of the MySQL
+ mailing lists. <xref linkend="mailing-lists"/>.
+ </para>
+
+ <para>
+ 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.
+ </para>
+
+ <para>
+ 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 <literal>mysql test <
+ script_file</literal> 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.
+ </para>
+
+ <para>
+ 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
+ <xref linkend="reproduceable-test-case"/>.
+ </para>
+
+ <para>
+ 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.
+ </para>
+
+ <para>
+ 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,
+ <quote>Why doesn't this work for me?</quote> 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.
+ </para>
+
+ <para>
+ 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.
+ </para>
+
+ <para>
+ 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.
+ </para>
+
+ <para>
+ If you have a problem with Connector/ODBC (MyODBC), please try to
+ generate a trace file and send it with your report. See
+ <xref linkend="myodbc-bug-report"/>.
+ </para>
+
+ <para>
+ If your report includes long query output lines from test cases that
+ you run with the <command>mysql</command> command-line tool, you can
+ make the output more readable by using the
+ <option>--vertical</option> option or the <literal>\G</literal>
+ statement terminator. The <literal>EXPLAIN SELECT</literal> example
+ later in this section demonstrates the use of <literal>\G</literal>.
+ </para>
+
+ <para>
+ Please include the following information in your report:
+ </para>
+
+ <itemizedlist>
+
+ <listitem>
+ <para>
+ 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 <command>mysqladmin version</command>. The
+ <command>mysqladmin</command> program can be found in the
+ <filename>bin</filename> directory under your MySQL installation
+ directory.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ The manufacturer and model of the machine on which you
+ experience the problem.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ 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
+ <quote>Help/About Windows</quote> menu. For most Unix-like
+ operating systems, you can get this information by executing the
+ command <literal>uname -a</literal>.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ Sometimes the amount of memory (real and virtual) is relevant.
+ If in doubt, include these values.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ 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.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ 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.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ If <command>mysqld</command> died, you should also report the
+ statement that crashed <command>mysqld</command>. You can
+ usually get this information by running
+ <command>mysqld</command> with query logging enabled, and then
+ looking in the log after <command>mysqld</command> crashes See
+ <xref linkend="using-log-files"/>.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ If a database table is related to the problem, include the
+ output from the <literal>SHOW CREATE TABLE
+ <replaceable>db_name</replaceable>.<replaceable>tbl_name</replaceable></literal>
+ 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.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ For performance-related bugs or problems with
+ <literal>SELECT</literal> statements, you should always include
+ the output of <literal>EXPLAIN SELECT ...</literal>, and at
+ least the number of rows that the <literal>SELECT</literal>
+ statement produces. You should also include the output from
+ <literal>SHOW CREATE TABLE
+ <replaceable>tbl_name</replaceable></literal> for each table
+ that is involved. The more information you provide about your
+ situation, the more likely it is that someone can help you.
+ </para>
+
+ <para>
+ The following is an example of a very good bug report. The
+ statements are run using the <command>mysql</command>
+ command-line tool. Note the use of the <literal>\G</literal>
+ statement terminator for statements that would otherwise provide
+ very long output lines that are difficult to read.
+ </para>
+
+<programlisting>
+mysql> <userinput>SHOW VARIABLES;</userinput>
+mysql> <userinput>SHOW COLUMNS FROM ...\G</userinput>
+ <replaceable><output from SHOW COLUMNS></replaceable>
+mysql> <userinput>EXPLAIN SELECT ...\G</userinput>
+ <replaceable><output from EXPLAIN></replaceable>
+mysql> <userinput>FLUSH STATUS;</userinput>
+mysql> <userinput>SELECT ...;</userinput>
+ <replaceable><A short version of the output from SELECT,
+ including the time taken to run the query></replaceable>
+mysql> <userinput>SHOW STATUS;</userinput>
+ <replaceable><output from SHOW STATUS></replaceable>
+</programlisting>
+ </listitem>
+
+ <listitem>
+ <para>
+ If a bug or problem occurs while running
+ <command>mysqld</command>, 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.
+ </para>
+
+ <para>
+ If you can't provide a script, you should at least include the
+ output from <command>mysqladmin variables extended-status
+ processlist</command> in your report to provide some information
+ on how your system is performing.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ 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
+ <command>mysqldump</command> and create a
+ <filename>README</filename> file that describes your problem.
+ Create a compressed archive of your files using
+ <command>tar</command> and <command>gzip</command> or
+ <command>zip</command>, and use FTP to transfer the archive to
+ <ulink url="ftp://ftp.mysql.com/pub/mysql/upload/"/>. Then enter
+ the problem into our bugs database at
+ <ulink url="http://bugs.mysql.com/"/>.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ 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.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ 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
+ <ulink url="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.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ Include all the options given to the relevant programs, if
+ possible. For example, indicate the options that you use when
+ you start the <command>mysqld</command> server, as well as the
+ options that you use to run any MySQL client programs. The
+ options to programs such as <command>mysqld</command> and
+ <command>mysql</command>, and to the
+ <command>configure</command> 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 <literal>DBI</literal> and
+ <literal>DBD::mysql</literal> modules, include the version
+ numbers for Perl, <literal>DBI</literal>, and
+ <literal>DBD::mysql</literal>.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ If your question is related to the privilege system, please
+ include the output of <command>mysqlaccess</command>, the output
+ of <command>mysqladmin reload</command>, and all the error
+ messages you get when trying to connect. When you test your
+ privileges, you should first run <command>mysqlaccess</command>.
+ After this, execute <command>mysqladmin reload version</command>
+ and try to connect with the program that gives you trouble.
+ <command>mysqlaccess</command> can be found in the
+ <filename>bin</filename> directory under your MySQL installation
+ directory.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ 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.
+ </para>
+
+ <para>
+ 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.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ 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.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ 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.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ 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
+ <literal>CHECK TABLE</literal> and <literal>REPAIR
+ TABLE</literal> or with <command>myisamchk</command>. See
+ <xref linkend="database-administration"/>.
+ </para>
+
+ <para>
+ If you are running Windows, please verify the value of
+ <literal>lower_case_table_names</literal> using the
+ <literal>SHOW VARIABLES LIKE 'lower_case_table_names'</literal>
+ command.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ 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 <filename>.err</filename>
+ suffix in the name.) See <xref linkend="error-log"/>. Please
+ include any relevant information from this file in your bug
+ report. Normally <command>mysqld</command> should
+ <emphasis>never</emphasis> crash a table if nothing killed it in
+ the middle of an update. If you can find the cause of
+ <command>mysqld</command> dying, it's much easier for us to
+ provide you with a fix for the problem. See
+ <xref linkend="what-is-crashing"/>.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ 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
+ <xref linkend="which-version"/>.
+ </para>
+ </listitem>
+
+ </itemizedlist>
+
+ <indexterm type="concept">
+ <primary>technical support</primary>
+ <secondary>mailing address</secondary>
+ </indexterm>
+
+ <indexterm type="concept">
+ <primary>support</primary>
+ <secondary>mailing address</secondary>
+ </indexterm>
+
+ <indexterm type="concept">
+ <primary>customer support</primary>
+ <secondary>mailing address</secondary>
+ </indexterm>
+
+ <indexterm type="concept">
+ <primary>mailing address</primary>
+ <secondary>for customer support</secondary>
+ </indexterm>
+
+ <para>
+ If you are a support customer, please cross-post the bug report to
+ <email>mysql-support@stripped</email> for higher-priority
+ treatment, as well as to the appropriate mailing list to see whether
+ someone else has experienced (and perhaps solved) the problem.
+ </para>
+
+ <indexterm type="concept">
+ <primary><command>mysqlbug</command> script</primary>
+ </indexterm>
+
+ <indexterm type="concept">
+ <primary>scripts</primary>
+ <secondary><command>mysqlbug</command></secondary>
+ </indexterm>
+
+ <para>
+ If you have no Web access and cannot report a bug by visiting
+ <ulink url="http://bugs.mysql.com/"/>, you can use the
+ <command>mysqlbug</command> script to generate a bug report (or a
+ report about any problem). <command>mysqlbug</command> 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. <command>mysqlbug</command> can be found in
+ the <filename>scripts</filename> directory (source distribution) and
+ in the <filename>bin</filename> directory under your MySQL
+ installation directory (binary distribution).
+ </para>
+
+</section>
Modified: trunk/refman-common/information-sources.xml
===================================================================
--- trunk/refman-common/information-sources.xml 2006-01-04 03:49:42 UTC (rev 660)
+++ trunk/refman-common/information-sources.xml 2006-01-04 04:12:52 UTC (rev 661)
@@ -13,9 +13,8 @@
<para>
This section lists sources of additional information that you may
- find helpful, such as the MySQL mailing lists, user forums, and
- Internet Relay Chat. It also provides information on how to report
- bugs.
+ find helpful, such as the MySQL mailing lists and user forums, and
+ Internet Relay Chat.
</para>
<section id="mailing-lists">
@@ -35,10 +34,6 @@
</indexterm>
<indexterm type="concept">
- <primary>net etiquette</primary>
- </indexterm>
-
- <indexterm type="concept">
<primary>mailing lists</primary>
<secondary>archive location</secondary>
</indexterm>
@@ -408,8 +403,8 @@
<para>
The forums at <ulink url="http://forums.mysql.com"/> are an
- important community resource. A variety of forums is available,
- grouped into these general categories:
+ important community resource. Many forums are available, grouped
+ into these general categories:
</para>
<itemizedlist>
@@ -491,9 +486,9 @@
</indexterm>
<para>
- In addition to the various MySQL mailing lists, you can find
- experienced community people on Internet Relay Chat (IRC). These
- are the best networks/channels currently known to us:
+ In addition to the various MySQL mailing lists and forums, you can
+ find experienced community people on Internet Relay Chat (IRC).
+ These are the best networks/channels currently known to us:
</para>
<para>
@@ -530,633 +525,4 @@
</section>
- <section id="bug-reports">
-
- <title>&title-bug-reports;</title>
-
- <indexterm type="concept">
- <primary>reporting</primary>
- <secondary>errors</secondary>
- </indexterm>
-
- <indexterm type="concept">
- <primary>errors</primary>
- <secondary>reporting</secondary>
- </indexterm>
-
- <indexterm type="concept">
- <primary>searching</primary>
- <secondary>MySQL Web pages</secondary>
- </indexterm>
-
- <indexterm type="concept">
- <primary>bug reports</primary>
- <secondary>criteria for</secondary>
- </indexterm>
-
- <indexterm type="concept">
- <primary>bugs</primary>
- <secondary>reporting</secondary>
- </indexterm>
-
- <indexterm type="concept">
- <primary>reporting</primary>
- <secondary>bugs</secondary>
- </indexterm>
-
- <indexterm type="concept">
- <primary>problems</primary>
- <secondary>reporting</secondary>
- </indexterm>
-
- <indexterm type="concept">
- <primary>errors</primary>
- <secondary>reporting</secondary>
- </indexterm>
-
- <indexterm type="concept">
- <primary>creating</primary>
- <secondary>bug reports</secondary>
- </indexterm>
-
- <indexterm type="concept">
- <primary>bugs.mysql.com</primary>
- </indexterm>
-
- <indexterm type="concept">
- <primary>bugs database</primary>
- </indexterm>
-
- <para>
- 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:
- </para>
-
- <itemizedlist>
-
- <listitem>
- <para>
- Start by searching the MySQL online manual at
- <ulink url="&base-url-docs;"/>. We try to keep the manual up
- to date by updating it frequently with solutions to newly
- found problems. The change history
- (<ulink url="&base-url-docs;mysql/en/news.html"/>) can be
- particularly useful since it is quite possible that a newer
- version contains a solution to your problem.
- </para>
-
- <para>
- 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 <email>licensing@stripped</email>
- and ask for an offer to implement it.
- </para>
-
- <para>
- 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.
- </para>
- </listitem>
-
- <listitem>
- <para>
- For solutions to some common problems, see
- <xref linkend="problems"/>.
- </para>
- </listitem>
-
- <listitem>
- <para>
- Search in the bugs database at
- <ulink url="http://bugs.mysql.com/"/> to see whether the bug
- has been reported and fixed.
- </para>
- </listitem>
-
- <listitem>
- <para>
- Search the MySQL mailing list archives at
- <ulink url="http://lists.mysql.com/"/>. See
- <xref linkend="mailing-lists"/>.
- </para>
- </listitem>
-
- <listitem>
- <para>
- You can also use <ulink url="http://www.mysql.com/search/"/>
- to search all the Web pages (including the manual) that are
- located at the MySQL AB Web site.
- </para>
- </listitem>
-
- </itemizedlist>
-
- <para>
- If you can't find an answer in the manual or the 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.
- </para>
-
- <para>
- The normal way to report bugs is to visit
- <ulink url="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.
- </para>
-
- <para>
- If you have found a sensitive security bug in MySQL, you can send
- email to <email>security@stripped</email>.
- </para>
-
- <para>
- To report other problems, you can use one of the MySQL mailing
- lists. <xref linkend="mailing-lists"/>.
- </para>
-
- <para>
- 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.
- </para>
-
- <para>
- If you have no Web access, you can generate a bug report by using
- the <command>mysqlbug</command> script described at the end of
- this section.
- </para>
-
- <para>
- 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
- <literal>mysql test < script_file</literal> on the included
- 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.
- </para>
-
- <para>
- All bugs posted in the bugs database at
- <ulink url="http://bugs.mysql.com/"/> are corrected or documented
- in the next MySQL release. If only minor code changes are needed
- to correct a problem, we may also post a patch that fixes the
- problem.
- </para>
-
- <para>
- Remember that it is possible for us to respond to a message
- 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 is this: 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.
- </para>
-
- <para>
- 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, <quote>Why doesn't this work for me?</quote> 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. Sometimes the error is
- 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.
- </para>
-
- <para>
- 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 use. Note that every compiling problem should be regarded as a
- bug and reported accordingly.
- </para>
-
- <para>
- 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 <xref linkend="reproduceable-test-case"/>.
- </para>
-
- <para>
- 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.
- </para>
-
- <para>
- If you have a problem with Connector/ODBC (MyODBC), please try to
- generate a trace file and send it with your report. See
- <xref linkend="myodbc-bug-report"/>.
- </para>
-
- <para>
- If your report includes long query output lines from test cases
- that you run with the <command>mysql</command> command-line tool,
- you can make the output more readable by using the
- <option>--vertical</option> option or the <literal>\G</literal>
- statement terminator. The <literal>EXPLAIN SELECT</literal>
- example later in this section demonstrates the use of
- <literal>\G</literal>.
- </para>
-
- <para>
- Please include the following information in your report:
- </para>
-
- <itemizedlist>
-
- <listitem>
- <para>
- 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 <command>mysqladmin
- version</command>. The <command>mysqladmin</command> program
- can be found in the <filename>bin</filename> directory under
- your MySQL installation directory.
- </para>
- </listitem>
-
- <listitem>
- <para>
- The manufacturer and model of the machine on which you
- experience the problem.
- </para>
- </listitem>
-
- <listitem>
- <para>
- 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
- <quote>Help/About Windows</quote> menu. For most Unix-like
- operating systems, you can get this information by executing
- the command <literal>uname -a</literal>.
- </para>
- </listitem>
-
- <listitem>
- <para>
- Sometimes the amount of memory (real and virtual) is relevant.
- If in doubt, include these values.
- </para>
- </listitem>
-
- <listitem>
- <para>
- 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.
- </para>
- </listitem>
-
- <listitem>
- <para>
- 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.
- </para>
- </listitem>
-
- <listitem>
- <para>
- If <command>mysqld</command> died, you should also report the
- statement that crashed <command>mysqld</command>. You can
- usually get this information by running
- <command>mysqld</command> with query logging enabled, and then
- looking in the log after <command>mysqld</command> crashes See
- <xref linkend="using-log-files"/>.
- </para>
- </listitem>
-
- <listitem>
- <para>
- If a database table is related to the problem, include the
- output from <command>mysqldump --no-data
- <replaceable>db_name</replaceable>
- <replaceable>tbl_name</replaceable> >
- <replaceable>file_name</replaceable></command>. This is very
- easy to do and is a powerful way to get information about any
- table in a database. The <command>mysqldump</command> command
- generates a file that you can upload to be attached to the bug
- report. The information helps us create a situation matching
- the one that you have experienced.
- </para>
- </listitem>
-
- <listitem>
- <para>
- For performance-related bugs or problems with
- <literal>SELECT</literal> statements, you should always
- include the output of <literal>EXPLAIN SELECT ...</literal>,
- and at least the number of rows that the
- <literal>SELECT</literal> statement produces. You should also
- include the output from <literal>SHOW CREATE TABLE
- <replaceable>tbl_name</replaceable></literal> for each table
- that is involved. The more information you provide about your
- situation, the more likely it is that someone can help you.
- </para>
-
- <para>
- The following is an example of a very good bug report. The
- statements are run using the <command>mysql</command>
- command-line tool. Note the use of the <literal>\G</literal>
- statement terminator for statements that would otherwise
- provide very long output lines that are difficult to read.
- </para>
-
-<programlisting>
-mysql> <userinput>SHOW VARIABLES;</userinput>
-mysql> <userinput>SHOW COLUMNS FROM ...\G</userinput>
- <replaceable><output from SHOW COLUMNS></replaceable>
-mysql> <userinput>EXPLAIN SELECT ...\G</userinput>
- <replaceable><output from EXPLAIN></replaceable>
-mysql> <userinput>FLUSH STATUS;</userinput>
-mysql> <userinput>SELECT ...;</userinput>
- <replaceable><A short version of the output from SELECT,
- including the time taken to run the query></replaceable>
-mysql> <userinput>SHOW STATUS;</userinput>
- <replaceable><output from SHOW STATUS></replaceable>
-</programlisting>
- </listitem>
-
- <listitem>
- <para>
- If a bug or problem occurs while running
- <command>mysqld</command>, 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.
- </para>
-
- <para>
- If you can't provide a script, you should at least include the
- output from <command>mysqladmin variables extended-status
- processlist</command> in your report to provide some
- information on how your system is performing.
- </para>
- </listitem>
-
- <listitem>
- <para>
- 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
- <command>mysqldump</command> and create a
- <filename>README</filename> file that describes your problem.
- Create a compressed archive of your files using
- <command>tar</command> and <command>gzip</command> or
- <command>zip</command>, and use FTP to transfer the archive to
- <ulink url="ftp://ftp.mysql.com/pub/mysql/upload/"/>. Then
- enter the problem into our bugs database at
- <ulink url="http://bugs.mysql.com/"/>.
- </para>
- </listitem>
-
- <listitem>
- <para>
- 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.
- </para>
- </listitem>
-
- <listitem>
- <para>
- 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
- <ulink url="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, then go ahead and provide an example using other
- names, but please regard this as the last choice.
- </para>
- </listitem>
-
- <listitem>
- <para>
- Include all the options given to the relevant programs, if
- possible. For example, indicate the options that you use when
- you start the <command>mysqld</command> server, as well as the
- options that you use to run any MySQL client programs. The
- options to programs such as <command>mysqld</command> and
- <command>mysql</command>, and to the
- <command>configure</command> script, are often key to
- resolving problems and are very relevant. It is never a bad
- idea to include them. If you problem includes a programm
- 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 <literal>DBI</literal> and
- <literal>DBD::mysql</literal> modules, include the version for
- Perl, <literal>DBI</literal>, and
- <literal>DBD::mysql</literal>.
- </para>
- </listitem>
-
- <listitem>
- <para>
- If your question is related to the privilege system, please
- include the output of <command>mysqlaccess</command>, the
- output of <command>mysqladmin reload</command>, and all the
- error messages you get when trying to connect. When you test
- your privileges, you should first run
- <command>mysqlaccess</command>. After this, execute
- <command>mysqladmin reload version</command> and try to
- connect with the program that gives you trouble.
- <command>mysqlaccess</command> can be found in the
- <filename>bin</filename> directory under your MySQL
- installation directory.
- </para>
- </listitem>
-
- <listitem>
- <para>
- 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.
- </para>
-
- <para>
- If we can't verify exactly what the purpose of the patch is,
- 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.
- </para>
- </listitem>
-
- <listitem>
- <para>
- 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.
- </para>
- </listitem>
-
- <listitem>
- <para>
- 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.
- </para>
- </listitem>
-
- <listitem>
- <para>
- If your 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
- <literal>CHECK TABLE</literal> and <literal>REPAIR
- TABLE</literal> or with <command>myisamchk</command>. See
- <xref linkend="database-administration"/>.
- </para>
-
- <para>
- If you are running Windows, please verify the value of
- <literal>lower_case_table_names</literal> using the
- <literal>SHOW VARIABLES LIKE
- 'lower_case_table_names'</literal> command.
- </para>
- </listitem>
-
- <listitem>
- <para>
- 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 <filename>.err</filename>
- suffix in the name.) See <xref linkend="error-log"/>. Please
- include any relevant information from this file in your bug
- report. Normally <command>mysqld</command> should
- <emphasis>never</emphasis> crash a table if nothing killed it
- in the middle of an update. If you can find the cause of
- <command>mysqld</command> dying, it's much easier for us to
- provide you with a fix for the problem. See
- <xref linkend="what-is-crashing"/>.
- </para>
- </listitem>
-
- <listitem>
- <para>
- 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
- <xref linkend="which-version"/>.
- </para>
- </listitem>
-
- </itemizedlist>
-
- <indexterm type="concept">
- <primary>technical support</primary>
- <secondary>mailing address</secondary>
- </indexterm>
-
- <indexterm type="concept">
- <primary>support</primary>
- <secondary>mailing address</secondary>
- </indexterm>
-
- <indexterm type="concept">
- <primary>customer support</primary>
- <secondary>mailing address</secondary>
- </indexterm>
-
- <indexterm type="concept">
- <primary>mailing address</primary>
- <secondary>for customer support</secondary>
- </indexterm>
-
- <para>
- If you are a support customer, please cross-post the bug report to
- <email>mysql-support@stripped</email> for higher-priority
- treatment, as well as to the appropriate mailing list to see
- whether someone else has experienced (and perhaps solved) the
- problem.
- </para>
-
- <indexterm type="concept">
- <primary><command>mysqlbug</command> script</primary>
- </indexterm>
-
- <indexterm type="concept">
- <primary>scripts</primary>
- <secondary><command>mysqlbug</command></secondary>
- </indexterm>
-
- <para>
- If you have no Web access and cannot report a bug by visiting
- <ulink url="http://bugs.mysql.com/"/>, you can use the
- <command>mysqlbug</command> script to generate a bug report (or a
- report about any problem). <command>mysqlbug</command> can be
- found in the <filename>scripts</filename> directory (source
- distribution) and in the <filename>bin</filename> directory under
- your MySQL installation directory (binary distribution). If you
- are unable to use <command>mysqlbug</command> (for example, if you
- are running on Windows), it is still vital that you include all
- the necessary information noted in this section (most importantly,
- a description of the operating system and the MySQL version).
- </para>
-
- <para>
- The <command>mysqlbug</command> script 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.
- </para>
-
- </section>
-
</section>
| Thread |
|---|
| • svn commit - mysqldoc@docsrva: r661 - in trunk: . refman-common | paul | 4 Jan |
