Connection

Constructs a Connection object.

Opens a PDO connection.

Destroys this Connection object.

PHP does not destruct an object if it is still referenced in other variables. In case of PDO database connection objects, PHP only closes the connection when the PDO object is destructed, so any references to this object may cause the number of maximum allowed connections to be exceeded.

Ensures that the PDO connection can be garbage collected.

Returns the default query options for any given query.

A given query can be customized with a number of option flags in an associative array:

• fetch: This element controls how rows from a result set will be returned. Legal values include PDO::FETCH_ASSOC, PDO::FETCH_BOTH, PDO::FETCH_OBJ, PDO::FETCH_NUM, or a string representing the name of a class. If a string is specified, each record will be fetched into a new object of that class. The behavior of all other values is defined by PDO. See http://php.net/manual/pdostatement.fetch.php
• return: Depending on the type of query, different return values may be meaningful. This directive instructs the system which type of return value is desired. The system will generally set the correct value automatically, so it is extremely rare that a module developer will ever need to specify this value. Setting it incorrectly will likely lead to unpredictable results or fatal errors. Legal values include:
  • Database::RETURN_STATEMENT: Return the prepared statement object for the query. This is usually only meaningful for SELECT queries, where the statement object is how one accesses the result set returned by the query.
  • Database::RETURN_AFFECTED: Return the number of rows affected by an UPDATE or DELETE query. Be aware that means the number of rows actually changed, not the number of rows matched by the WHERE clause.
  • Database::RETURN_INSERT_ID: Return the sequence ID (primary key) created by an INSERT statement on a table that contains a serial column.
  • Database::RETURN_NULL: Do not return anything, as there is no meaningful value to return. That is the case for INSERT queries on tables that do not contain a serial column.
• throw_exception: (deprecated) By default, the database system will catch any errors on a query as an Exception, log it, and then rethrow it so that code further up the call chain can take an appropriate action. To suppress that behavior and simply return NULL on failure, set this option to FALSE.
• allow_delimiter_in_query: By default, queries which have the ; delimiter any place in them will cause an exception. This reduces the chance of SQL injection attacks that terminate the original query and add one or more additional queries (such as inserting new user accounts). In rare cases, such as creating an SQL function, a ; is needed and can be allowed by changing this option to TRUE.
• allow_square_brackets: By default, queries which contain square brackets will have them replaced with the identifier quote character for the database type. In rare cases, such as creating an SQL function, [] characters might be needed and can be allowed by changing this option to TRUE.
• pdo: By default, queries will execute with the PDO options set on the connection. In particular cases, it could be necessary to override the PDO driver options on the statement level. In such case, pass the required setting as an array here, and they will be passed to the prepared statement. See https://www.php.net/manual/en/pdo.prepare.php.

Returns the connection information for this connection object.

Note that Database::getConnectionInfo() is for requesting information about an arbitrary database connection that is defined. This method is for requesting the connection information of this specific open connection object.

Allows the connection to access additional databases.

Database systems usually group tables in 'databases' or 'schemas', that can be accessed with syntax like 'SELECT * FROM database.table'. Normally Drupal accesses tables in a single database/schema, but in some cases it may be necessary to access tables from other databases/schemas in the same database server. This method can be called to ensure that the additional database/schema is accessible.

For MySQL, PostgreSQL and most other databases no action need to be taken to query data in another database or schema. For SQLite this is however necessary and the database driver for SQLite will override this method.

Set the list of prefixes used by this database connection.

Appends a database prefix to all tables in a query.

Queries sent to Drupal should wrap all table names in curly brackets. This function searches for this syntax and adds Drupal's table prefix to all tables, allowing Drupal to coexist with other systems in the same database and/or schema if necessary.

Quotes all identifiers in a query.

Queries sent to Drupal should wrap all unquoted identifiers in square brackets. This function searches for this syntax and replaces them with the database specific identifier. In ANSI SQL this a double quote.

Note that :variable[] is used to denote array arguments but Connection::expandArguments() is always called first.

Find the prefix for a table.

This function is for when you want to know the prefix of a table. This is not used in prefixTables due to performance reasons.

Gets a list of individually prefixed table names.

Get a fully qualified table name.

Returns a prepared statement given a SQL string.

This method caches prepared statements, reusing them when possible. It also prefixes tables names enclosed in curly braces and, optionally, quotes identifiers enclosed in square brackets.

Returns a string SQL statement ready for preparation.

This method replaces table names in curly braces and identifiers in square brackets with platform specific replacements, appropriately escaping them and wrapping them with platform quote characters.

Prepares a query string and returns the prepared statement.

This method caches prepared statements, reusing them when possible. It also prefixes tables names enclosed in curly-braces and, optionally, quotes identifiers enclosed in square brackets.

Tells this connection object what its target value is.

This is needed for logging and auditing. It's sloppy to do in the constructor because the constructor for child classes has a different signature. We therefore also ensure that this function is only ever called once.

Returns the target this connection is associated with.

Tells this connection object what its key is.

Returns the key this connection is associated with.

Associates a logging object with this connection.

Gets the current logging object for this connection.

Creates the appropriate sequence name for a given table and serial field.

This information is exposed to all database drivers, although it is only useful on some of them. This method is table prefix-aware.

Note that if a sequence was generated automatically by the database, its name might not match the one returned by this function. Therefore, in those cases, it is generally advised to use a database-specific way of retrieving the name of an auto-created sequence. For example, PostgreSQL provides a dedicated function for this purpose: pg_get_serial_sequence().

Flatten an array of query comments into a single comment string.

The comment string will be sanitized to avoid SQL injection attacks.

Sanitize a query comment string.

Ensure a query comment does not include strings such as "* /" that might terminate the comment early. This avoids SQL injection attacks via the query comment. The comment strings in this example are separated by a space to avoid PHP parse errors.

For example, the comment:

Executes a query string against the database.

This method provides a central handler for the actual execution of every query. All queries executed by Drupal are executed as PDO prepared statements.

Wraps and re-throws any PDO exception thrown by static::query().

Expands out shorthand placeholders.

Drupal supports an alternate syntax for doing arrays of values. We therefore need to expand them out into a full, executable query string.

Gets the driver-specific override class if any for the specified class.

Returns the database exceptions handler.

Prepares and returns a SELECT query object.

Prepares and returns an INSERT query object.

Prepares and returns a MERGE query object.

Prepares and returns an UPSERT query object.

Prepares and returns an UPDATE query object.

Prepares and returns a DELETE query object.

Prepares and returns a TRUNCATE query object.

Returns a DatabaseSchema object for manipulating the schema.

This method will lazy-load the appropriate schema library file.

Prepares and returns a CONDITION query object.

Escapes a database name string.

Force all database names to be strictly alphanumeric-plus-underscore. For some database drivers, it may also wrap the database name in database-specific escape characters.

Escapes a table name string.

Force all table names to be strictly alphanumeric-plus-underscore. Database drivers should never wrap the table name in database-specific escape characters. This is done in Connection::prefixTables(). The database-specific escape characters are added in Connection::setPrefix().

Escapes a field name string.

Force all field names to be strictly alphanumeric-plus-underscore. For some database drivers, it may also wrap the field name in database-specific escape characters.

Escapes an alias name string.

Force all alias names to be strictly alphanumeric-plus-underscore. In contrast to DatabaseConnection::escapeField() / DatabaseConnection::escapeTable(), this doesn't allow the period (".") because that is not allowed in aliases.

Escapes characters that work as wildcard characters in a LIKE pattern.

The wildcard characters "%" and "_" as well as backslash are prefixed with a backslash. Use this to do a search for a verbatim string without any wildcard behavior.

For example, the following does a case-insensitive query for all rows whose name starts with $prefix:

Determines if there is an active transaction open.

Determines the current transaction depth.

Returns a new DatabaseTransaction object on this connection.

Rolls back the transaction entirely or to a named savepoint.

This method throws an exception if no transaction is active.

Increases the depth of transaction nesting.

If no transaction is already active, we begin a new transaction.

Decreases the depth of transaction nesting.

If we pop off the last transaction layer, then we either commit or roll back the transaction as necessary. If no transaction is active, we return because the transaction may have manually been rolled back.

Adds a root transaction end callback.

These callbacks are invoked immediately after the transaction has been committed.

It can for example be used to avoid deadlocks on write-heavy tables that do not need to be part of the transaction, like cache tag invalidations.

Another use case is that services using alternative backends like Redis and Memcache cache implementations can replicate the transaction-behavior of the database cache backend and avoid race conditions.

An argument is passed to the callbacks that indicates whether the transaction was successful or not.

Overridden to work around issues to MySQL not supporting transactional DDL.

Do the actual commit, invoke post-commit callbacks.

Runs a limited-range query on this database object.

Use this as a substitute for ->query() when a subset of the query is to be returned. User-supplied arguments to the query should be passed in as separate parameters so that they can be properly escaped to avoid SQL injection attacks.

Generates a temporary table name.

Runs a SELECT query and stores its results in a temporary table.

Use this as a substitute for ->query() when the results need to stored in a temporary table. Temporary tables exist for the duration of the page request. User-supplied arguments to the query should be passed in as separate parameters so that they can be properly escaped to avoid SQL injection attacks.

Note that if you need to know how many results were returned, you should do a SELECT COUNT(*) on the temporary table afterwards.

Returns the type of database driver.

This is not necessarily the same as the type of the database itself. For instance, there could be two MySQL drivers, mysql and mysqlMock. This function would return different values for each, but both would return "mysql" for databaseType().

Returns the version of the database server.

Returns the version of the database client.

Determines if this driver supports transactions.

Determines if this driver supports transactional DDL.

DDL queries are those that change the schema, such as ALTER queries.

Returns the name of the PDO driver for this connection.

Overrides \Drupal\Core\Database\Connection::createDatabase().

Gets any special processing requirements for the condition operator.

Some condition types require special processing, such as IN, because the value data they pass in is not a simple value. This is a simple overridable lookup function. Database connections should define only those operators they wish to be handled differently than the default.

Throws an exception to deny direct access to transaction commits.

We do not want to allow users to commit transactions at any time, only by destroying the transaction object or allowing it to go out of scope. A direct commit bypasses all of the safety checks we've built on top of PDO's transaction routines.

Retrieves a unique ID from a given sequence.

Use this function if for some reason you can't use a serial field. For example, MySQL has no ways of reading of the current value of a sequence and PostgreSQL can not advance the sequence to be larger than a given value. Or sometimes you just need a unique integer.

Prepares a statement for execution and returns a statement object.

Emulated prepared statements do not communicate with the database server so this method does not check the statement.

Quotes a string for use in a query.

Extracts the SQLSTATE error from the PDOException.

Prevents the database connection from being serialized.

Creates an array of database connection options from a URL.

Creates a URL from an array of database connection options.

Get the module name of the module that is providing the database driver.

Get the pager manager service, if available.

Determines whether the MySQL distribution is MariaDB or not.

Gets the MariaDB portion of the server version.

Gets the server version.

No description