The db.php Drop-In

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 native wpdb class through DBTK_DB and overrides the query() method to capture full PHP backtraces before each query executes, enabling component attribution, caller identification, and detailed performance data in the Query Viewer.

In This Guide

• What Is the db.php Drop-In
• How It Works
• Key Concepts
• Configuration
• Common Issues and How to Fix Them

What Is the db.php Drop-In

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 in place of the default database class, giving any plugin that installs one a hook point into every SQL query the site executes.

WPDT uses this mechanism to replace the standard wpdb class with its own DBTK_DB class. Every query your site runs passes through the overridden query() method, where WPDT captures backtrace data before results return to the calling code.

How It Works

WPDT’s drop-in intercepts queries at the lowest available hook point in WordPress, before any plugin or theme code can alter or suppress them. Three phases describe the full process.

What Happens Before Each Query

When the DBTK_DB class intercepts a query, it performs two operations. First, it calls debug_backtrace() to record every function, file, and line number in the PHP call chain leading back to the code that originated the query. 

Second, after the query completes, it records the number of affected rows or any WP_Error returned. Both pieces of data attach to the query entry, which WPDT writes to the encrypted query log during the PHP shutdown phase. 

Writing during shutdown rather than inline with each query contains the performance impact. This mechanism is what makes component attribution precise: the backtrace identifies the plugin, theme, or core subsystem that initiated the query with more accuracy than SAVEQUERIES provides.

Enhanced vs. Basic Logging

Without the drop-in, WPDT falls back to basic logging using the WordPress SAVEQUERIES constant. Here is what each mode provides:

Enhanced logging provides structured backtraces with precise component attribution while Basic mode parses partial backtrace data from the comma-separated SAVEQUERIES stack trace, which gives less detail and accuracy.

Conflicts

WordPress loads only one db.php file. If another plugin has already placed a in wp-content/, WPDT cannot install its own. Confirmed conflict sources include Query Monitor (by John Blackbourn), Debug Bar, and some caching plugins. 

When a conflict exists, WPDT falls back to basic logging automatically: SQL statements and timing data are still captured, but without backtraces or component attribution.

To check which drop-in is active, run:

bash
grep "DBTK_DB" wp-content/db.php

An empty output means that WPDT’s drop-in is not active. Read the file’s contents to identify the plugin that installed it, disable that plugin’s drop-in through its own settings, then re-enable WPDT’s enhanced logging. WPDT does not depend on another plugin’s db.php and does not require running both simultaneously.

✅ Key Guarantees

• WPDT installs and removes the db.php drop-in automatically. No manual file handling is needed for either operation.
• When WPDT removes the drop-in, WordPress continues running normally using its default wpdb class.
• A conflict with another plugin’s db.php does not break query logging. WPDT automatically falls back to basic mode.
• Enhanced logging writes backtrace data to an encrypted query log file during the PHP shutdown phase, not during the query itself. The performance impact is contained.

Key Concepts

Configuration

WPDT manages the db.php file entirely. You do not need any FTP access, nor is manual file handling required for installation or removal.

Step 1: Enable Enhanced Query Logging from the Admin

Navigate to WP Debug Toolkit › Overview. In the Database Queries card, toggle Enhanced Query Logging to enable it. WPDT copies its db.php template to wp-content/db.php. To enable from the command line instead, use Step 2.

Step 2: Enable via WP-CLI

bash
wp dbtk query-log on

WPDT installs the drop-in with this command. Use this path when you prefer CLI-based workflows or are working in a scripted environment.

✅ What You Should See: The Database Queries card on the Overview page displays a status indicator confirming the Enhanced Query Logging (drop-in) is active. Query entries in the Query Viewer will include backtrace and component attribution data.

Step 3: Disable Enhanced Query Logging

Navigate to WP Debug Toolkit › Overview and toggle Enhanced Query Logging to disable it, or run:

bash
wp dbtk query-log off

WPDT deletes wp-content/db.php. If query logging remains enabled, WPDT continues to capture SQL statements and timing data in basic mode using SAVEQUERIES.

Common Issues and How to Fix Them

Enhanced Logging Is Enabled but Queries Show No Backtraces

Likely cause: another plugin’s db.php is overriding WPDT’s file. 

Fix: run grep “DBTK_DB” wp-content/db.php. If the output is empty, WPDT’s drop-in is not active. Read the file’s contents to identify the conflicting plugin, disable its drop-in through its own settings, then re-enable WPDT’s enhanced logging.

Permission Error When Enabling Enhanced Logging

Likely cause: the PHP process does not have write access to wp-content/. 

Fix: confirm that wp-content/ has permissions of 0755 with the web server user as owner. On managed hosting, the web server user may differ from the file owner. Contact your host if you cannot resolve this through file manager or SSH.

Drop-In Not Removed After Disabling Enhanced Logging

Likely cause: wp-content/db.php was modified by another plugin after WPDT installed it, or the PHP process lacks delete permission on the file. 

Fix: remove the file manually:

bash
rm wp-content/db.php

This is safe. WordPress runs without wp-content/db.php and uses the default wpdb class.

db.php Drop-In — Frequently Asked Questions

Does Removing the db.php Drop-In Break WordPress?

No. WordPress runs normally without wp-content/db.php and uses its default wpdb class. The drop-in is optional: its presence enhances query logging, but its absence does not cause errors. Whether WPDT removes it on disable or you remove it manually, the site continues operating without interruption.

Can WPDT Work Alongside Query Monitor if Both Need db.php?

Not simultaneously in enhanced mode as WordPress loads only one db.php. If Query Monitor’s drop-in is active, WPDT automatically falls back to basic logging, so you still get SQL statements and timing data. To use WPDT’s full backtrace and component attribution capabilities, disable Query Monitor’s drop-in through Query Monitor’s own settings, then enable WPDT’s enhanced logging.

Does the Drop-In Slow Down Queries?

The drop-in calls debug_backtrace() before each query and records additional data, both of which add a small overhead per query. WPDT writes backtrace data to the encrypted log file during the PHP shutdown phase rather than inline with the query, which contains the impact. 

On low-to-moderate traffic sites, the overhead is negligible. On high-traffic production sites with always-on logging, you should consider using time-limited recordings rather than continuous capture to minimize the cumulative effect.

Related Documentation

Filtering and Searching Recorded Queries – The All components filter only works when the drop-in is active in enhanced mode. This article shows you how to use it to isolate any query by plugin, theme, or core.

Slow Query, N+1, and Duplicate Detection – These detection features run on the backtrace and caller data the drop-in captures. Start here if you’re investigating a performance problem.

Always-On Logging Mode – Leaving enhanced logging running on every request has performance implications. Read this before enabling continuous capture on a production site.