Drupal 7 Line by Line Part 5 - DRUPAL_BOOTSTRAP_DATABASE

Welcome to the 5th installment of the Drupal 7 Line by Line series of articles.

In the first four installments I covered index.php, the basics of the drupal_bootstrap() function and the first two phases of the Drupal bootstrap process: DRUPAL_BOOTSTRAP_CONFIGURATION and DRUPAL_BOOTSTRAP_PAGE_CACHE. (There are links to those articles found at the bottom of this article if you want to catch up.)

In the previous article about the page cache bootstrap process I noted that unless your site is configured in a specific way, both the DRUPAL_BOOTSTRAP_DATABASE (phase 3) and DRUPAL_BOOTSTRAP_VARIABLES (phase 4) bootstrapping phases will be completed before the page cache (phase2) bootstrap process can itself finish. As a result, I am technically covering the database bootstrapping process out of order and am not literally following the line by line code execution of Drupal exactly. I hope you can forgive me.


The third Drupal bootstrap phase begins with a call to the _drupal_bootstrap_database() function.

The first few lines of this function can put to rest any argument that Drupal is an application development framework (like Zend framework, or CakePHP, or symfony). In its current state it simply isn't. Here, on virtually every page load, Drupal checks to see if it in an installation state.

// Redirect the user to the installation script if Drupal has not been
  // installed yet (i.e., if no $databases array has been defined in the
  // settings.php file) and we are not already installing.
if (empty($GLOBALS['databases']) && !drupal_installation_attempted()) {
DRUPAL_ROOT . '/includes/install.inc';

If Drupal decides that it is in an installation state it would load install.inc and redirect the request to install.php. With a specific installer baked into its core Drupal has no separated between the framework that its functionality is built on and the product that exposes that functionality. Please don't misunderstand my point here. Drupal is a very flexible, extensible and developer friendly CMS product. It is very much like a framework. It looks like a duck and quacks like a duck, but it might be a swan or some other mixed metaphor.

But, I digress.

Drupal Testing System

Drupal 7 comes with a testing suite that allows developers to write functional tests and run them to make sure that whatever they are working on doesn't break the rest of their Drupal site. Part of that testing system is a fake 'user agent' / fake browser that makes page requests and makes the results available for testing in an automated way.

Here Drupal checks to see if the request is being made by this testing user agent with a call to drupal_valid_test_ua(). If it is a request from the testing user agent Drupal overrides the database settings defined in settings.php. The reason for this is that if you are running tests (which require reading and writing of bogus test data to the database), you don't want to impact any real data on your site. So, if you are running tests they are run on a different set of tables.

The Database System

Finally, Drupal includes /database/database.inc.

// Initialize the database system. Note that the connection
  // won't be initialized until it is actually requested.
require_once DRUPAL_ROOT . '/includes/database/database.inc';

This file contains the core of the new Drupal 7 database abstraction layer.

Here is a part of the code comments from database.inc:

/* Drupal provides a database abstraction layer to provide developers with
* the ability to support multiple database servers easily. The intent of
* this layer is to preserve the syntax and power of SQL as much as possible,
* but also allow developers a way to leverage more complex functionality in
* a unified way. It also provides a structured interface for dynamically
* constructing queries when appropriate, and enforcing security checks and
* similar good practices.
* The system is built atop PHP's PDO (PHP Data Objects) database API and
* inherits much of its syntax and semantics.

The workings of the new database abstraction layer is enough material for several articles. You may want to do some reading on your own. I would suggest:
The main API documentation: http://api.drupal.org/api/group/database/7
Developing with the database API: http://drupal.org/developing/api/database


Last but not least Drupal registers two autoloading functions. PHP provides a file autoloading mechanism so that if it encounters the instantiation of a previously undefined Class or encounters the implementation of a previously undefined Interface it can be told where to look in the file system to load the file that contains the Class or Interface definition.

// Register autoload functions so that we can access classes and interfaces.
  // The database autoload routine comes first so that we can load the database
  // system without hitting the database. That is especially important during
  // the install or upgrade process.

These two lines tell php to use the drupal_autoload_class() and drupal_autoload_interface() functions for loading undefined classes and interfaces. Both of these functions are actually a wrapper for the _registry_check_code() function.

The name of the function implies that Drupal now has a code registry. And indeed it does. What that means is that modules now have a way to tell Drupal where to find certain include files so that when they are needed they can be 'lazy loaded'. To find out more I suggest reading: Drupal's code registry.


DRUPAL_BOOTSTRAP_DATABASE is the third bootstrap phase. It checks to see if the site is currently in an installation state (rarely) and whether it is in a automated testing state (rarely). Most of the time it simply does two things: load database.inc and register autoloader functions.

As always feel free to leave comments, corrections or questions.

January 10th 2011 4PM
By: andre



Excellent Inspiration

I love breaking stuff down, although I've mostly limited that to just themes. However having come across these posts, it's inspiring to see some breakdown of the innerworkings of Drupal. It does leave you less intimidated!

Definitely a great way to gain confidence, comfort and better understanding with the CMS you spend the most time working with. And of course, by better understanding...you can have a much easier time figuring how to get the CMS working to your needs, instead of just working around say the various module capabilities.



Thank you for diving us to

Thank you for diving us to the deepest of Drupal's Bootstrap system. You should edit your first 3 articles to add a summary of the folowing posts, like you did for the following :)