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 key in the $db_url global variable from settings.php. If omitted, the default connection will be made active.

Return value

The name of the previously active database, or FALSE if none was found.

Related topics

Database abstraction layer

Allow the use of different database servers using the same code base.

3 calls to db_set_active()

File

includes/database.inc, line 124

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 (empty($db_url)) {
    include_once 'includes/install.inc';
    install_goto('install.php');
  }

  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 {
      _db_error_page("The database type '" . $db_type . "' is unsupported. Please use either 'mysql' or 'mysqli' for MySQL, or 'pgsql' for PostgreSQL databases.");
    }

    $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;
}