Tips for using mysqli::debug in Docker or virtual machine environment

M66 2025-06-01

In PHP development, mysqli::debug() is a little-known but very useful function. It can be used to debug the internal execution of MySQLi extensions, especially when dealing with complex database connections or query problems.

This article will explain how to enable and use mysqli::debug() in a Docker or virtual machine environment to improve debugging efficiency.

1. What is mysqli::debug() ?

mysqli::debug() is a debugging tool provided by the PHP MySQLi extension. Its function is to output the debugging information of MySQLi to the specified file. It does not output to standard output or browser, but writes to log files on the server.

The call method is very simple:

 mysqli::debug("d:t:o,/tmp/client.trace");

The meaning of the parameter "d:t:o,/tmp/client.trace" is:

d : debug information;
t : thread information;
o : Output to file;
/tmp/client.trace : Output file path.

Note: Debugging support for the MySQL client library must be enabled before using this function, otherwise this function call will be invalid.

2. Enable debugging function in Docker or virtual machine

When using this function in a Docker container or virtual machine, two prerequisites need to be paid attention to:

PHP must run in CLI or FPM mode and enable the mysqlnd driver;
PHP in a container or virtual machine must be compiled with debug support.

1. Confirm that PHP supports debugging function

Run the following command to check whether PHP supports mysqli debugging:

 php -i | grep 'Client API version'

If the result contains mysqlnd , it means support. Otherwise, you may need to recompile PHP or install a PHP image containing mysqlnd .

2. Dockerfile example (enable mysqli debug)

If you use Docker, you can configure it in the Dockerfile as follows:

 FROM php:8.2-cli

RUN docker-php-ext-install mysqli \
    && echo "mysqli.allow_local_infile=On" >> /usr/local/etc/php/php.ini

# Optional：Mount debug file path
VOLUME /tmp

Then write the following code test in PHP:

 <?php
mysqli::debug("d:t:o,/tmp/client.trace");

$mysqli = new mysqli("db.m66.net", "root", "password", "test");

if ($mysqli->connect_errno) {
    echo "Connection failed: " . $mysqli->connect_error;
    exit();
}

$result = $mysqli->query("SELECT * FROM users");

while ($row = $result->fetch_assoc()) {
    print_r($row);
}

$mysqli->close();

After running this script, you can view debugging information in the /tmp/client.trace file.

3. Virtual machine environment description (such as using Vagrant)

Use in a virtual machine is no different from using native or Docker. The only thing to note is that the PHP process must have permission to write to the path of the log file you set, such as /tmp or the mount directory you specify.

3. Debugging log sample

The debug log content is roughly as follows (excerpt):

 >mysql_real_connect
>mysql_send_query
<mysql_read_query_result
...

Through these logs, you can locate the reasons for connection failure, the execution of slow queries, and even find delays caused by DNS configuration errors.

4. Safety recommendations

In production environments, you should avoid enabling mysqli::debug() because it will leak sensitive data such as database connection information and query content. It is recommended only in development or testing environments, and be careful to clean up generated log files.

5. Summary

Using mysqli::debug() in Docker or virtual machine environment is not complicated, the key is:

Make sure PHP uses mysqlnd ;
Set the permissions for log paths in the container or virtual machine;
Disable or delete the logs in time after debugging is completed.

By using this tool reasonably, it can be more efficient and accurate when troubleshooting database problems.

If you have similar debugging requirements, you might as well give it a try!

mysqli::debug