Reporting Bugs

This page contains general guidelines for reporting bugs in MariaDB.

If you want to discuss a problem or a new feature with other MariaDB developers, you can find the email lists and forums here.

Is the bug already known?

First, check that the bug isn't already filed in the MariaDB bugs database or MySQL bugs database.

For MariaDB bugs database, use JIRA search to check if a report you are going to submit already exists. You are not expected to be a JIRA search guru, but please at least make some effort.

• Choose Issues => Search for issues;
• If the form opens for you with a long blank line at top, press Basic on the right to switch to a simpler mode;
• in the Project field, choose MDEV;
• in Contains text text field, enter the most significant key words from your future report;
• press Enter or the magnifying glass icon to search.

If you see bug reports which are already closed, pay attention to the 'Fix version/s' field -- it is possible that they were fixed in the upcoming release. If they are said to be fixed in the release that you are currently using or earlier, you can ignore them and file a new one (although please mention in your bug report that you found them, it might be useful).

If you find an open bug report, please add a comment that the bug also affects you along with any additional information you have that may help us to find and fix the bug.

If the bug is not in the MariaDB bugs database yet, then it's time to file a bug report. If you're filing a bug report about a bug that's already in MySQL bugs database, please indicate so at the start of the report. Filing bug reports from MySQL in MariaDB bugs database makes sense, because

• it shows the MariaDB team that there is interest in having this bug fixed in MariaDB.
• it allows work to start on fixing the bug in MariaDB - assigning versions, assigning MariaDB developers to the bug, etc.

How do I report a bug?

Bugs and feature requests are reported to the MariaDB bugs database.

JIRA privacy

Please note that our JIRA entries are public, and JIRA is very good and keeping a record of everything that has been done. What it means is that if you ever put confidential information into description, even after you deleted it, there will still be a log containing it. The only way to get rid of it will be removing the JIRA entry completely.

Attachments in JIRA are also public.

Access to a comment can be restricted to a certain group (e.g. Developers only), but the existing groups are rather wide, so you should not rely on it either.

If you have private information -- SQL fragments, logs, database dumps, etc. -- that you are willing to share with MariaDB team, but not with the entire world, put it into a file, compress if necessary, upload to ftp.askmonty.org/private, and just mention it in the JIRA description. This way only MariaDB team will have access to it.

Contents of a good bug report

Below is the information we need to be able to fix bugs. The more information we get and the easier we can repeat the bug, the faster it will be fixed.

A good bug report consists of:

1. The environment (Operating system, hardware and MariaDB version) where the bug happened.
2. Any related errors or warnings from the server error log file. Normally it is hostname.err file in your database directory, but it can be different depending on the distribution and version; if you cannot find it, run SELECT @@log_error on the running server. If either the variable or the file it points at is empty, the error log most likely goes to your system log. If possible, attach the full unabridged error log at least from the last server restart and till the end of the log -- or, even the problem is related to updates, recovery from a previous crash, and such, then include several latest server sessions.
3. The content of your my.cnf file or alternatively the output from mysqld --print-defaults or SHOW VARIABLES.
4. Any background information you can provide (stack trace, tables, table definitions, data dumps, query logs).
5. If the bug is about server producing wrong query results: the actual result (what you are getting), the expected result (what you think should be produced instead), and, unless it is obvious, the reason why you think the current result is wrong.
6. If the bug about a performance problem, e.g. a certain query is slower on one version than on another, output of EXPLAIN EXTENDED <query> on both servers.
7. A test case or some other way to repeat the bug. This should preferably be in plain SQL or in mysqltest format. See mysqltest/README for information about this.
8. If it's impossible to do a test case, then providing us with a core dump + the corresponding binary would be of great help.

JIRA fields

The section below describes which JIRA fields need to be populated while filing reports, and what should be put there. Apart from what's mentioned below, you don't have to fill or change any fields while creating a new bug report.

Project

If you are filing a report for MariaDB server, or client program, or MariaDB Galera cluster, the target project is MDEV. Connectors and MaxScale have separate projects with corresponding names. If you choose a wrong project, bug processing can be delayed, but there is no reason to panic -- we'll correct it. If you inform us about the mistake, we'll change it faster.

Type

Feature requests are not the same as bug reports. Specify a Task type for feature requests in Jira, and a Bug type for bug reports. Like with the project field, choosing a wrong type will put the request to the wrong queue and can delay its processing, but eventually it will be noticed and amended.

See also plans for next release for things that we are considering to have in the next MariaDB release.

Summary

Please make sure the summary line is informative and distinctive. It should always be easy to recognize your report among other similar ones, otherwise a reasonable question arises -- why are they not duplicates?

Examples:

• good summary: Server crash with insert statement containing DEFAULT into view
• not a good summary: mysqld crash

Generally, we try not to change the summary without a good reason to do it, so that you can always recognize your own reports easily.

Affects version/s

Put everything you know about which versions are affected. There are both major versions (10.1, 10.0 etc.) and minor versions (10.0.23, 5.5.47, etc.) available for choosing. Please always specify there the exact version(s) (X.Y.Z) which you are working with, and where you experience the problem.

Additionally, If you know the exact version where the problem appeared, please put it as well. If the problem has been present, as far as you know, in all previous releases, you can also put there the major version, e.g. 10.0. Alternatively, you can mention all of it in the description or comments. Please also note in the description or comments which versions you know as not affected. This information will help to shorten further processing.

Environment

Put here environment-related information that might be important for reproducing or analyzing the problem: operating system, hardware, related 3rd-party applications, compilers, etc.

Description

The most important part of the description are steps to reproduce the problem. See more details about bug report contents above in the section Contents of a good bug report.

if in the process of reproducing you executed some SQL, don't describe it in words, like "I created a table with text columns and date columns and populated it with some rows" -- instead, whenever possible, put the exact SQL queries that you ran. The same goes for problems that you encountered: instead of saying "it did not work, the query failed, I got an error", always paste the exact output that you received.

Use {noformat}...{noformat} and {code}...{code} blocks for code and console output in the description.

Attachments

if you have SQL code, a database dump, a log etc. of a reasonable size, attach them to the report (archive them first if necessary). If they are too big, you can upload them to ftp.askmonty.org/private. It is always a good idea to attach your cnf file(s), unless it is absolutely clear from the nature of the report that configuration is irrelevant.

Links

If you found or filed a bug report either in MariaDB or MySQL or Percona bug base which you think is related to yours, you can put them in the Links section; same for any external links to 3rd-party resources which you find important to mention. Alternatively, you can just mention them in the description or comments.

Tags

You don't have to set any tags, but if you want to use any for your convenience, feel free to do so. However, please don't put too generic values -- for example, the tag mariadb is meaningless, because everything there is mariadb. Don't be surprised if some tags are removed later during report processing.

What if the bug affects MySQL or XtraDB/TokuDB in Percona too?

Our normal practice is to report a bug upstream if it's applicable to their version. While we can do it on your behalf, it is always better if you do it yourself -- it will be easier for you to track it further.

If the bug affects MySQL, it should also be reported at MySQL bugs database. If the bug affects XtraDB or TokuDB and reproducible with Percona server, it should go to Percona Launchpad.

This section is relevant if the problem is on a replication slave.

Sometimes a binary log event causes an error of some sort. A whole binary log file is sometimes impractical due to size or sensitivity reasons.

Step 1: Copy the binary log locally

This is just in case you don't quite extract the right information first. If the binlog expired off and you haven't got the right information, your bug report may not easily be reproducible.

sudo cp /var/lib/mysql/mysql-bin.000687 ~/
sudo chown $USER: ~/mysql-bin.000687

Step 2: Create an extract header

Binary logs have a header portion. Without the header mysqlbinlog won't be able to read it. The header also contains valuable session information

We look at the binary log to see how big the header and session information is:

mysqlbinlog --base64-output=decode-rows --verbose mysql-bin.000687 | more
/*!50530 SET @@SESSION.PSEUDO_SLAVE_MODE=1*/;
/*!40019 SET @@session.max_insert_delayed_threads=0*/;
/*!50003 SET @OLD_COMPLETION_TYPE=@@COMPLETION_TYPE,COMPLETION_TYPE=0*/;
DELIMITER /*!*/;
# at 4
#150323 22:45:58 server id 76  end_log_pos 245  Start: binlog v 4, server v 5.5.39-MariaDB-log created 150323 22:45:58
# at 245
#150323 22:45:58 server id 76  end_log_pos 328  Query   thread_id=9709067       exec_time=0     error_code=0
SET TIMESTAMP=1427116558.923924/*!*/;
SET @@session.pseudo_thread_id=9709067/*!*/;
SET @@session.foreign_key_checks=1, @@session.sql_auto_is_null=0, @@session.unique_checks=1, @@session.autocommit=1/*!*/;
SET @@session.sql_mode=0/*!*/;
SET @@session.auto_increment_increment=1, @@session.auto_increment_offset=1/*!*/;
/*!\C utf8 *//*!*/;
SET @@session.character_set_client=33,@@session.collation_connection=33,@@session.collation_server=8/*!*/;
SET @@session.time_zone='SYSTEM'/*!*/;
SET @@session.lc_time_names=0/*!*/;
SET @@session.collation_database=DEFAULT/*!*/;
BEGIN
/*!*/;
# at 328

We see that the session information ends at 328 because of the last line, so we extract to that point.

dd if=mysql-bin.000687 of=mysql-bin.000687-extract-offset-129619 bs=1 count=328

We need to find out at what offset the entry at 129619 ends and it might be useful to extract some previous entries as well.

mysqlbinlog --base64-output=decode-rows --verbose mysql-bin.000687 | grep  '^# at ' |  grep -C 10 '^# at 129619$'
# at 127602
# at 127690
# at 128201
# at 128290
# at 128378
# at 128829
# at 128918
# at 129006
# at 129459
# at 129548
# at 129619
# at 129647
# at 130070
# at 130097
# at 130168
# at 130196
# at 130738
# at 130942
# at 130969
# at 131040
# at 131244

Take a look at those entries with:

mysqlbinlog --base64-output=decode-rows --verbose --start-position 129006  --stop-position 130168  mysql-bin.000687 | more

Now let's assume we want to start at our original 129619 and finish before 130168

dd if=mysql-bin.000687 bs=1 skip=129619 count=$(( 130168 - 129619 ))  >> mysql-bin.000687-extract-offset-129619

Check the extract:

mysqlbinlog mysql-bin.000687-extract-offset-129619

Upload this to the private uploads or attach to the public bug report if nothing sensitive there.

How to build a MariaDB server that contains debug information

Here are instructions on how to build a mysqld that contains all the information we need to fix the problem: (A more detailed explanation can be found here.)

• Add the --core-file option to your /.my.cnf or /etc/my.cnf file under the [mysqld] tag.
• Get the latest MariaDB code from GitHub.
• Compile MariaDB with the -g compiler flag (Unix). The scripts in the BUILD directory will do this automatically for you.
• Shut down your old mysqld server
• Install the new compiled mysqld
• restart mysqld

Compiling with -g should not cause any notable slowdown of the server.

Example of doing a debug build

Here is an example of how to do the compilation (assuming you are using AMD or Intel hardware)

cd mariadb-source-dir
./BUILD/compile-pentium-max
make
./client/mysqladmin shutdown
mv mariadb-install-dir/mysqld mariadb-install-dir/mysqld-old
cp sql/mysqld mariadb-install-dir/mysqld
 
'restart mysqld'

You can of course also do make install, but the above way allows you to go back to your old binary if needed.

If you get any errors about wrong number of error messages, you can fix that by copying the corresponding language file from sql/share over your old ones (this should be reasonably safe to do).

cp sql/share/english/* mariadb-install-dir/share/mysql/english

What to do when you get a crash after installing a debug binary

Now when you get a crash do the following:

• Create a README file that described the problem. (You can use the mysqlbug script to generate a template for this).
• Create a tar file containing the core, the mysqld binary and README. If possible, also add any database files that could help us repeat the problem!

  sh> tar cvfz /tmp/mariadb-bug-'short-description'.tgz mariadb-data-dir/core* mariadb-install-dir/libexec/mysqld README
  

• Send it to our secure ftp server:

  sh> ftp -a ftp.askmonty.org
  ftp> cd private
  ftp> binary 
  ftp> put /tmp/mariadb-bug-'short-description'.tgz
  ftp> quit
  

• To be able to follow the progress, create a bug report in JIRA about this. This should be easy to do based on the information you have in your README file.

If you require help with the above, want to ensure that the bug is fixed with high priority, or want someone to login to your server to find out what's wrong, you can always purchase a Support contract from MariaDB Corporation or use their consulting services.