Same name and namespace in other branches
  1. 4.6.x includes/database.inc \db_set_active()
  2. 4.7.x includes/database.inc \db_set_active()
  3. 6.x includes/database.inc \db_set_active()
  4. 7.x includes/database/database.inc \db_set_active()
  5. 8.9.x core/includes/database.inc \db_set_active()

Activate a database for future queries.

If it is necessary to use external databases in a project, this function can be used to change where database queries are sent. If the database has not yet been used, it is initialized using the URL specified for that name in Drupal's configuration file. If this name is not defined, a duplicate of the default connection is made instead.

Be sure to change the connection back to the default when done with custom code.

Parameters

$name: The name assigned to the newly active database connection. If omitted, the default connection will be made active.

Return value

the name of the previously active database or FALSE if non was found.

Related topics

2 calls to db_set_active()
install_main in ./install.php
The Drupal installation happens in a series of steps. We begin by verifying that the current environment meets our minimum requirements. We then go on to verify that settings.php is properly configured. From there we connect to the configured database…
watchdog in includes/bootstrap.inc
Log a system message.

File

includes/database.inc, line 100
Wrapper for database interface code.

Code

function db_set_active($name = 'default') {
  global $db_url, $db_type, $active_db;
  static $db_conns, $active_name = FALSE;
  if (!isset($db_conns[$name])) {

    // Initiate a new connection, using the named DB URL specified.
    if (is_array($db_url)) {
      $connect_url = array_key_exists($name, $db_url) ? $db_url[$name] : $db_url['default'];
    }
    else {
      $connect_url = $db_url;
    }
    $db_type = substr($connect_url, 0, strpos($connect_url, '://'));
    $handler = "./includes/database.{$db_type}.inc";
    if (is_file($handler)) {
      include_once $handler;
    }
    else {
      drupal_maintenance_theme();
      drupal_set_title('Unsupported database type');
      print theme('maintenance_page', '<p>The database type ' . theme('placeholder', $db_type) . ' is unsupported. Please use either <var>mysql</var> for MySQL 3.x &amp; 4.0.x databases, <var>mysqli</var> for MySQL 4.1.x+ databases, or <var>pgsql</var> for PostgreSQL databases. The database information is in your <code>settings.php</code> file.</p>
<p>For more help, see the <a href="http://drupal.org/node/258">Installation and upgrading handbook</a>. If you are unsure what these terms mean you should probably contact your hosting provider.</p>');
      exit;
    }
    $db_conns[$name] = db_connect($connect_url);
  }
  $previous_name = $active_name;

  // Set the active connection.
  $active_name = $name;
  $active_db = $db_conns[$name];
  return $previous_name;
}