Preparing for Drupal 12: Auditing Deprecated Database API Usage via CLI

Preparing for Drupal 12: I Built a CLI to Audit Your Database API Usage

Drupal 12 is removing procedural Database API wrappers like db_query() and db_select(). These functions have been deprecated since Drupal 8, and their removal in 2026 will cause fatal errors for unupdated codebases.

Why This Matters

The transition from procedural wrappers to the injected database service represents a shift from legacy Drupal 7 patterns to modern OOP standards. While the grace period has lasted since 2015, the hard break in Drupal 12 means that any missed function call will result in a fatal error, making automated auditing essential for enterprise stability and preventing technical debt from entering production environments.

Key Insights

• Drupal Core issue #3525077 outlines the plan to strip legacy wrappers from core/includes/database.inc in Drupal 12.
• Procedural functions like db_query() and db_insert() have been deprecated since the 2015 release of Drupal 8.
• The Drupal 12 Readiness CLI scans PHP, .module, .install, and .theme files for over 30 deprecated procedural functions.
• In Drupal 12, remaining legacy database calls will trigger fatal errors instead of graceful fallbacks or deprecation warnings.
• The tool serves as a lightweight audit gate for CI/CD, complementing Drupal Rector’s automated fixing capabilities.

Working Examples

Comparison between deprecated procedural database calls and the modern injected database service.

// Legacy (Fatal Error in D12)
$result = db_query("SELECT nid FROM {node} LIMIT 1");

// Modern (D12 Ready)
$result = \Drupal::database()->query("SELECT nid FROM {node} LIMIT 1");

Installation and execution of the Drupal 12 Readiness CLI tool for auditing codebases.

composer require --dev victorstack-ai/drupal-12-readiness-cli
./vendor/bin/drupal-12-readiness check:db-api web/modules/custom/my_module

Practical Applications

• Continuous Integration: Implement the check:db-api command as a pre-merge gate to block the introduction of legacy code.
• Legacy Audit: Run the scanner on custom modules and themes to identify technical debt ahead of the Drupal 12 release.
• Pitfall: Manual searching for ‘db_’ prefixes often results in excessive noise; the CLI tool specifically targets precise API functions to reduce false positives.
• Refactor Workflow: Use the CLI to identify issues and Drupal Rector to automate the actual code replacement.

References:

• https://dev.to/victorstackai/preparing-for-drupal-12-i-built-a-cli-to-audit-your-database-api-usage-5595