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.

If you find the bug in the MariaDB bugs database, 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.

Bug report or feature request?

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.

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

How do I report a bug?

Bugs are reported on the MariaDB bug database,

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 hostname.err file. This is normally in your database directory.
  3. Any background information you can provide (stack trace, tables)
  4. A test case or some other way to repeat the bug. This should preferably be in mysqltest format. See mysqltest/README for information about this.
  5. If it's impossible to do a test case, then providing us with a core dump + the corresponding binary would be of great help.

If the bug only affects MariaDB, you can file the bug to the MariaDB bugs database.

If it also affects MySQL, then you should also file the bug to the MySQL bugs database.

How to extract a portion of a binary log

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
/*!40019 SET @@session.max_insert_delayed_threads=0*/;
# 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/*!*/;
# 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
./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> 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.


Comments loading...