The db.php drop-in is a WordPress database override file that WP Debug Toolkit (WPDT) installs at wp-content/db.php. It extends the default wpdb class to capture full PHP backtraces before each query, which enables component attribution, caller identification, and detailed performance analysis in the Query Viewer.
WordPress supports a “drop-in” file at wp-content/db.php. When this file exists, WordPress loads it early in its bootstrap process and uses it instead of the default database class.
WPDT’s drop-in defines a DBTK_DB class that extends wpdb. The custom class overrides the query() method to do two things before each query executes:
debug_backtrace() to record the full chain of PHP function calls leading to the query.WP_Error returned by the query.This data is attached to each query entry and later written to the encrypted query log during the PHP shutdown phase.
Without the drop-in, WPDT falls back to basic logging using the WordPress SAVEQUERIES constant. Here is what each mode provides:
| Capability | Basic (SAVEQUERIES) | Enhanced (db.php) |
|---|---|---|
| SQL statement | Yes | Yes |
| Execution time | Yes | Yes |
| Backtrace | Basic — parsed from SAVEQUERIES comma-separated stack trace | Yes — full PHP call stack with file, line, and function for each frame |
| Component attribution | Basic — derived from parsed backtrace | Yes — identifies the plugin, theme, or core subsystem responsible |
| Caller function | Basic — derived from parsed backtrace | Yes — the specific function or method that triggered the query |
| Affected rows / errors | No | Yes |
Enhanced logging provides full, structured backtraces with precise component attribution and caller identification. Basic mode parses backtrace data from the SAVEQUERIES comma-separated stack trace, which provides partial component and caller information but with less detail and accuracy.
The drop-in installs automatically when you enable enhanced query logging. Two ways to enable it:
From the admin dashboard:
From WP-CLI:
wp dbtk query-log enableWPDT copies its db.php template to wp-content/db.php. No manual file handling is needed.
The drop-in is removed automatically when you disable enhanced query logging:
From the admin dashboard:
From WP-CLI:
wp dbtk query-log disableWPDT deletes wp-content/db.php. Query logging continues in basic mode (SAVEQUERIES) if query logging itself is still enabled.
WordPress loads only one db.php file. If another plugin has already placed a db.php in wp-content/, WPDT cannot install its own.
Several plugins install their own db.php drop-in:
db.php for its own backtrace capturedb.php to intercept queriesOnly one db.php can be active at a time. If a conflict exists, WPDT falls back to basic logging automatically. You still get SQL and timing data, but without backtraces or component attribution.
Look at the contents of wp-content/db.php. If it contains a reference to the DBTK_DB class, it is WPDT’s drop-in:
grep "DBTK_DB" wp-content/db.phpIf the file exists but does not reference DBTK_DB, another plugin owns it.
If you want WPDT’s enhanced logging and another plugin’s db.php is in the way:
db.php (check its contents for class names or plugin references).db.php.You do not need both — WPDT provides its own backtrace capture and does not depend on another plugin’s db.php.
Another plugin’s db.php may be overriding WPDT’s drop-in. Check wp-content/db.php to confirm it references the DBTK_DB class. If it does not, another plugin replaced the file after WPDT installed it. Disable the conflicting plugin’s drop-in and re-enable WPDT’s enhanced logging.
The PHP process needs write access to the wp-content/ directory to create or remove db.php. If you see a permission error:
wp-content/ allow writing (typically 0755 with the web server user as owner).If wp-content/db.php remains after you disable enhanced logging, the file may have been modified by another plugin or the PHP process may lack delete permission. You can remove it manually:
rm wp-content/db.phpThis is safe — WordPress runs without db.php and uses its default wpdb class.
