PHP mysqli_debug() Function

Beginner
5 min read
Updated: Nov 2026
3 examples
MySQLi

Definition

In PHP, mysqli_debug() turns on low-level MySQLi client debugging using a control string of flags.

Object-oriented style uses $mysqli->debug($options), though many examples call the procedural form before connecting. A common pattern writes a trace file with options like "d:t:o,/tmp/client.trace". This is for diagnosing the client library, not everyday application logging.

Syntax

Call mysqli_debug() with the values you need. Start with this line.

PHP
mysqli_debug("d:t:o,/tmp/client.trace");
CallWhat it does
mysqli_debug("d:t:o,/tmp/client.trace")Starts a debug trace written to a file.
mysqli_debug("d:t:O,/tmp/client.trace")Similar trace with flush behavior depending on build flags.
$mysqli->debug("d:t:o,/tmp/client.trace")Object-oriented method form.

Debugging support must be available in the MySQL native driver / client build. On many shared hosts mysqli_debug() will not produce a useful file. Prefer application logging and mysqli_error() for normal troubleshooting.

Library declarations
PHP
mysqli_debug(string $options): true

Parameters

ParameterDescription
optionsRequired. A colon-separated debug control string (flags and optional output path).

Return Value

Return ValueDescription
trueAlways true in PHP 8+.

PHP Examples

Example 1 — Enable a Client Trace File

Call mysqli_debug with a typical options string before connecting.

PHP
<?php
mysqli_debug("d:t:o,/tmp/client.trace");
echo "debug options set", PHP_EOL;

$mysqli = @mysqli_connect("localhost", "demo", "secret", "shop");
if ($mysqli) {
    echo "connected", PHP_EOL;
    mysqli_close($mysqli);
}

How It Works

  1. mysqli_debug() installs the trace options string.
  2. A demo connect follows so the client has activity to log.
  3. Sample output shows the options call succeeded.
  4. Whether /tmp/client. trace appears depends on the PHP build.

Example 2 — Object Style Debug Call

Invoke debug on a mysqli instance.

PHP
<?php
$mysqli = new mysqli("localhost", "demo", "secret", "shop");
$mysqli->debug("d:t:o,/tmp/oo-client.trace");
echo "oo debug set", PHP_EOL;
$mysqli->close();

How It Works

  1. A connection object is created.
  2. debug() is called with an output path flag.
  3. The method returns true in modern PHP.
  4. The script prints a short confirmation message.

Example 3 — Prefer Error Helpers for App Bugs

For SQL problems, print errno/error instead of relying on client traces.

PHP
<?php
$mysqli = mysqli_connect("localhost", "demo", "secret", "shop");
mysqli_query($mysqli, "SELECT * FROM no_such_table");
echo mysqli_errno($mysqli), ": ", mysqli_error($mysqli), PHP_EOL;
mysqli_close($mysqli);

How It Works

  1. A bad table name triggers a server error.
  2. mysqli_errno() and mysqli_error() explain it clearly.
  3. This is the beginner-friendly alternative to mysqli_debug().
  4. Sample output when connected to a demo database shows error 1146.

Frequently Asked Questions

It configures low-level tracing in the MySQL client library using a special options string, often writing a trace file.
No. For tutorials and app bugs, use connect_error, errno, error and clear sample queries first.
Your PHP build may lack debugging support, or the path may not be writable. Shared hosts often disable this.
They are flags such as t for trace and o for output file, separated by colons. See the PHP manual table for the full list.
Functionally the same. You can call mysqli_debug($options) or $mysqli->debug($options).

Next: mysqli_dump_debug_info()

mysqli_dump_debug_info() asks the MySQL server to dump debug information related to the cu.

mysqli_dump_debug_info() tutorial →

About the author

Mari Selvan M P
Mari Selvan M P 🔗

Developer, cloud engineer, and technical writer

  • Experience 12 years building web and cloud systems
  • Focus Full Stack Development, AWS, and Developer Education

I write practical tutorials so students and working developers can learn by doing—from databases and APIs to deployment on AWS.

8 people found this page helpful