Database
abstract class Database (View source)
Primary front-controller for the database system.
This class is uninstantiatable and un-extendable. It acts to encapsulate all control and shepherding of database connections into a single location without the use of globals.
Constants
| RETURN_NULL |
Flag to indicate a query call should simply return NULL. This is used for queries that have no reasonable return value anyway, such as INSERT statements to a table without a serial primary key. |
| RETURN_STATEMENT |
Flag to indicate a query call should return the prepared statement. |
| RETURN_AFFECTED |
Flag to indicate a query call should return the number of affected rows. |
| RETURN_INSERT_ID |
Flag to indicate a query call should return the "last insert id". |
Properties
| static protected array | $connections | A nested array of all active connections. It is keyed by database name and target. |
|
| static protected array | $databaseInfo | A processed copy of the database connection information from settings.php. |
|
| static protected array | $ignoreTargets | A list of key/target credentials to simply ignore. |
|
| static protected string | $activeKey | The key of the currently active database connection. |
|
| static protected array | $logs | An array of active query log objects. |
Methods
Starts logging a given logging key on the specified connection.
Retrieves the queries logged on for given logging key.
Gets the connection object for the specified database key and target.
Determines if there is an active connection.
Sets the active connection to the specified key.
Process the configuration file for database information.
Adds database connection information for a given key/target.
Gets information on the specified database connection.
Gets connection information for all available databases.
Sets connection information for multiple databases.
Rename a connection and its corresponding connection information.
Remove a connection and its corresponding connection information.
Opens a connection to the server specified by the given key and target.
Closes a connection to the server specified by the given key and target.
Instructs the system to temporarily ignore a given key/target.
Converts a URL to a database connection info array.
Finds the directory to add to the autoloader for the driver's namespace.
Gets database connection info as a URL.
Gets the PHP namespace of a database driver from the connection info.
Details
final static Log
startLog(string $logging_key, string $key = 'default')
Starts logging a given logging key on the specified connection.
final static array
getLog(string $logging_key, string $key = 'default')
Retrieves the queries logged on for given logging key.
This method also ends logging for the specified key. To get the query log to date without ending the logger request the logging object by starting it again (which does nothing to an open log key) and call methods on it as desired.
final static Connection
getConnection(string $target = 'default', string $key = NULL)
Gets the connection object for the specified database key and target.
final static bool
isActiveConnection()
Determines if there is an active connection.
Note that this method will return FALSE if no connection has been established yet, even if one could be.
final static string|null
setActiveConnection($key = 'default')
Sets the active connection to the specified key.
final static
parseConnectionInfo(array $info)
Process the configuration file for database information.
final static
addConnectionInfo(string $key, string $target, array $info)
Adds database connection information for a given key/target.
This method allows to add new connections at runtime.
Under normal circumstances the preferred way to specify database credentials is via settings.php. However, this method allows them to be added at arbitrary times, such as during unit tests, when connecting to admin-defined third party databases, etc.
If the given key/target pair already exists, this method will be ignored.
final static array|null
getConnectionInfo(string $key = 'default')
Gets information on the specified database connection.
final static array
getAllConnectionInfo()
Gets connection information for all available databases.
final static
setMultipleConnectionInfo(array $databases)
Sets connection information for multiple databases.
final static bool
renameConnection(string $old_key, string $new_key)
Rename a connection and its corresponding connection information.
final static bool
removeConnection(string $key)
Remove a connection and its corresponding connection information.
final static protected
openConnection(string $key, string $target)
Opens a connection to the server specified by the given key and target.
static
closeConnection(string $target = NULL, string $key = NULL)
Closes a connection to the server specified by the given key and target.
static
ignoreTarget(string $key, string $target)
Instructs the system to temporarily ignore a given key/target.
At times we need to temporarily disable replica queries. To do so, call this method with the database key and the target to disable. That database key will then always fall back to 'default' for that key, even if it's defined.
static array
convertDbUrlToConnectionInfo(string $url, string $root)
Converts a URL to a database connection info array.
static string|false
findDriverAutoloadDirectory(string $namespace, string $root)
Finds the directory to add to the autoloader for the driver's namespace.
For Drupal sites that manage their codebase with Composer, the package that provides the database driver should add the driver's namespace to Composer's autoloader. However, to support sites that add Drupal modules without Composer, and because the database connection must be established before Drupal adds the module's entire namespace to the autoloader, the database connection info array can include an "autoload" key containing the autoload directory for the driver's namespace. For requests that connect to the database via a connection info array, the value of the "autoload" key is automatically added to the autoloader.
This method can be called to find the default value of that key when the database connection info array isn't available. This includes:
- Console commands and test runners that connect to a database specified by a database URL rather than a connection info array.
- During installation, prior to the connection info array being written to settings.php.
This method returns the directory that must be added to the autoloader for the given namespace.
- If the namespace is a sub-namespace of a Drupal module, then this method returns the autoload directory for that namespace, allowing Drupal modules containing database drivers to be added to a Drupal website without Composer.
- If the namespace is a sub-namespace of Drupal\Core or Drupal\Driver, then this method returns FALSE, because Drupal core's autoloader already includes these namespaces, so no additional autoload directory is required for any code within them.
- If the namespace is anything else, then this method returns FALSE, because neither drupal_get_database_types() nor static::convertDbUrlToConnectionInfo() support that anyway. One can manually edit the connection info array in settings.php to reference any arbitrary namespace, but requests using that would use the corresponding 'autoload' key in that connection info rather than calling this method.
static string
getConnectionInfoAsUrl(string $key = 'default')
Gets database connection info as a URL.
static protected string
getDatabaseDriverNamespace(array $connection_info)
deprecated
deprecated
Gets the PHP namespace of a database driver from the connection info.