Preparing for Drupal 12: Auditing Database API Usage
Drupal 12 is on the horizon, and with it comes the final removal of a long-standing legacy layer: the procedural Database API wrappers.
If your codebase still relies on db_query(), db_select(), or db_insert(), you are looking at a hard break when D12 lands. These functions have been deprecated since Drupal 8, but they've stuck around for backward compatibility. That grace period is ending.
The Issue: [D12] Remove Deprecated Paths
The Drupal Core issue #3525077: [D12] Remove deprecated paths from the Database API & friends outlines the plan to strip these wrappers from core/includes/database.inc.
This means code like this will fatal error in Drupal 12:
// ❌ Legacy (Removed in D12)
$result = db_query("SELECT nid FROM {node} LIMIT 1");
Instead, you must use the injected database service or the static container wrapper:
// ✅ Modern (D12 Ready)
$result = \Drupal::database()->query("SELECT nid FROM {node} LIMIT 1");
Automating the Audit
Manually searching for db_ functions can be noisy because db_ is a common prefix. I added a new command to my Drupal 12 Readiness CLI to specifically target these deprecated API calls.
You can now run a targeted audit on your custom modules:
# Install the tool
composer require --dev victorstack-ai/drupal-12-readiness-cli
# Run the DB API check
./vendor/bin/drupal-12-readiness check:db-api web/modules/custom/my_module
The tool scans your PHP, module, install, and theme files for 30+ deprecated procedural functions, including db_transaction, db_or, db_like, and db_driver.
Example Output
Scanning modules/custom/legacy_module for deprecated Database API usage...
[WARNING] Found 2 instances of deprecated Database API usage:
Location Function Suggested Replacement
----------------------- ----------- ------------------------------------------------
legacy_module.module:10 db_query Use \Drupal::database()->query()
legacy_module.module:13 db_select Use \Drupal::database()->select()
Why Not Just Use Rector?
Drupal Rector is fantastic and should be your first choice for fixing these issues. However, sometimes you just need a lightweight audit—a quick check in CI or a pre-commit hook to say "stop adding new legacy code" without running a full Rector process.
This CLI tool is designed to be that fast, lightweight gatekeeper.
View Code