Issue #1894396 by Mile23, Crell, catch: Mark db_*() wrappers in database.inc as @deprecated for 9.x

core/includes/database.inc

@@ -1,9 +1,5 @@
 <?php
 
-use Drupal\Core\Database\Database;
-use Drupal\Core\Database\Query\Condition;
-use Drupal\Core\Site\Settings;
-
 /**
  * @file
  * Core systems for the database layer.
@@ -13,6 +9,10 @@ use Drupal\Core\Site\Settings;
  * file only, as they cannot auto-load the way classes can.
  */
 
+use Drupal\Core\Database\Database;
+use Drupal\Core\Database\Query\Condition;
+use Drupal\Core\Site\Settings;
+
 /**
  * @addtogroup database
  * @{
@@ -28,23 +28,29 @@ use Drupal\Core\Site\Settings;
  * Do not use this function for INSERT, UPDATE, or DELETE queries. Those should
  * be handled via db_insert(), db_update() and db_delete() respectively.
  *
- * @param $query
+ * @param string|\Drupal\Core\Database\StatementInterface $query
  *   The prepared statement query to run. Although it will accept both named and
  *   unnamed placeholders, named placeholders are strongly preferred as they are
  *   more self-documenting. If the argument corresponding to a placeholder is
  *   an array of values to be expanded, e.g. for an IN query, the placeholder
  *   should be named with a trailing bracket like :example[]
- * @param $args
+ * @param array $args
  *   An array of values to substitute into the query. If the query uses named
  *   placeholders, this is an associative array in any order. If the query uses
  *   unnamed placeholders (?), this is an indexed array and the order must match
  *   the order of placeholders in the query string.
- * @param $options
+ * @param array $options
  *   An array of options to control how the query operates.
  *
  * @return \Drupal\Core\Database\StatementInterface
  *   A prepared statement object, already executed.
  *
+ * @deprecated as of Drupal 8.0.x, will be removed in Drupal 9.0.0. Instead, get
+ *   a database connection injected into your service from the container and
+ *   call query() on it. E.g.
+ *   $injected_database->query($query, $args, $options);
+ *
+ * @see \Drupal\Core\Database\Connection::query()
  * @see \Drupal\Core\Database\Connection::defaultOptions()
  */
 function db_query($query, array $args = array(), array $options = array()) {
@@ -58,7 +64,7 @@ function db_query($query, array $args = array(), array $options = array()) {
 /**
  * Executes a query against the active database, restricted to a range.
  *
- * @param $query
+ * @param string $query
  *   The prepared statement query to run. Although it will accept both named and
  *   unnamed placeholders, named placeholders are strongly preferred as they are
  *   more self-documenting.
@@ -66,17 +72,23 @@ function db_query($query, array $args = array(), array $options = array()) {
  *   The first record from the result set to return.
  * @param $count
  *   The number of records to return from the result set.
- * @param $args
+ * @param array $args
  *   An array of values to substitute into the query. If the query uses named
  *   placeholders, this is an associative array in any order. If the query uses
  *   unnamed placeholders (?), this is an indexed array and the order must match
  *   the order of placeholders in the query string.
- * @param $options
+ * @param array $options
  *   An array of options to control how the query operates.
  *
  * @return \Drupal\Core\Database\StatementInterface
  *   A prepared statement object, already executed.
  *
+ * @deprecated as of Drupal 8.0.x, will be removed in Drupal 9.0.0. Instead, get
+ *   a database connection injected into your service from the container and
+ *   call queryRange() on it. E.g.
+ *   $injected_database->queryRange($query, $from, $count, $args, $options);
+ *
+ * @see \Drupal\Core\Database\Connection::queryRange()
  * @see \Drupal\Core\Database\Connection::defaultOptions()
  */
 function db_query_range($query, $from, $count, array $args = array(), array $options = array()) {
@@ -92,21 +104,27 @@ function db_query_range($query, $from, $count, array $args = array(), array $opt
  *
  * The execution of the query string happens against the active database.
  *
- * @param $query
+ * @param string $query
  *   The prepared SELECT statement query to run. Although it will accept both
  *   named and unnamed placeholders, named placeholders are strongly preferred
  *   as they are more self-documenting.
- * @param $args
+ * @param array $args
  *   An array of values to substitute into the query. If the query uses named
  *   placeholders, this is an associative array in any order. If the query uses
  *   unnamed placeholders (?), this is an indexed array and the order must match
  *   the order of placeholders in the query string.
- * @param $options
+ * @param array $options
  *   An array of options to control how the query operates.
  *
  * @return
  *   The name of the temporary table.
  *
+ * @deprecated as of Drupal 8.0.x, will be removed in Drupal 9.0.0. Instead, get
+ *   a database connection injected into your service from the container and
+ *   call queryTemporary() on it. E.g.
+ *   $injected_database->queryTemporary($query, $args, $options);
+ *
+ * @see \Drupal\Core\Database\Connection::queryTemporary()
  * @see \Drupal\Core\Database\Connection::defaultOptions()
  */
 function db_query_temporary($query, array $args = array(), array $options = array()) {
@@ -120,13 +138,20 @@ function db_query_temporary($query, array $args = array(), array $options = arra
 /**
  * Returns a new InsertQuery object for the active database.
  *
- * @param $table
+ * @param string $table
  *   The table into which to insert.
- * @param $options
+ * @param array $options
  *   An array of options to control how the query operates.
  *
  * @return \Drupal\Core\Database\Query\Insert
  *   A new Insert object for this connection.
+ *
+ * @deprecated as of Drupal 8.0.x, will be removed in Drupal 9.0.0. Instead, get
+ *   a database connection injected into your service from the container and
+ *   call insert() on it. E.g. $injected_database->insert($table, $options);
+ *
+ * @see \Drupal\Core\Database\Connection::insert()
+ * @see \Drupal\Core\Database\Connection::defaultOptions()
  */
 function db_insert($table, array $options = array()) {
   if (empty($options['target']) || $options['target'] == 'replica') {
@@ -138,13 +163,20 @@ function db_insert($table, array $options = array()) {
 /**
  * Returns a new MergeQuery object for the active database.
  *
- * @param $table
+ * @param string $table
- *   The table into which to merge.
+ *   Name of the table to associate with this query.
- * @param $options
+ * @param array $options
  *   An array of options to control how the query operates.
  *
  * @return \Drupal\Core\Database\Query\Merge
  *   A new Merge object for this connection.
+ *
+ * @deprecated as of Drupal 8.0.x, will be removed in Drupal 9.0.0. Instead, get
+ *   a database connection injected into your service from the container and
+ *   call merge() on it. E.g. $injected_database->merge($table, $options);
+ *
+ * @see \Drupal\Core\Database\Connection::merge()
+ * @see \Drupal\Core\Database\Connection::defaultOptions()
  */
 function db_merge($table, array $options = array()) {
   if (empty($options['target']) || $options['target'] == 'replica') {
@@ -156,13 +188,20 @@ function db_merge($table, array $options = array()) {
 /**
  * Returns a new UpdateQuery object for the active database.
  *
- * @param $table
+ * @param string $table
  *   The table to update.
- * @param $options
+ * @param array $options
  *   An array of options to control how the query operates.
  *
  * @return \Drupal\Core\Database\Query\Update
  *   A new Update object for this connection.
+ *
+ * @deprecated as of Drupal 8.0.x, will be removed in Drupal 9.0.0. Instead, get
+ *   a database connection injected into your service from the container and
+ *   call update() on it. E.g. $injected_database->update($table, $options);
+ *
+ * @see \Drupal\Core\Database\Connection::update()
+ * @see \Drupal\Core\Database\Connection::defaultOptions()
  */
 function db_update($table, array $options = array()) {
   if (empty($options['target']) || $options['target'] == 'replica') {
@@ -174,13 +213,20 @@ function db_update($table, array $options = array()) {
 /**
  * Returns a new DeleteQuery object for the active database.
  *
- * @param $table
+ * @param string $table
  *   The table from which to delete.
- * @param $options
+ * @param array $options
  *   An array of options to control how the query operates.
  *
  * @return \Drupal\Core\Database\Query\Delete
  *   A new Delete object for this connection.
+ *
+ * @deprecated as of Drupal 8.0.x, will be removed in Drupal 9.0.0. Instead, get
+ *   a database connection injected into your service from the container and
+ *   call delete() on it. E.g. $injected_database->delete($table, $options);
+ *
+ * @see \Drupal\Core\Database\Connection::delete()
+ * @see \Drupal\Core\Database\Connection::defaultOptions()
  */
 function db_delete($table, array $options = array()) {
   if (empty($options['target']) || $options['target'] == 'replica') {
@@ -192,13 +238,20 @@ function db_delete($table, array $options = array()) {
 /**
  * Returns a new TruncateQuery object for the active database.
  *
- * @param $table
+ * @param string $table
- *   The table from which to delete.
+ *   The table from which to truncate.
- * @param $options
+ * @param array $options
  *   An array of options to control how the query operates.
  *
  * @return \Drupal\Core\Database\Query\Truncate
  *   A new Truncate object for this connection.
+ *
+ * @deprecated as of Drupal 8.0.x, will be removed in Drupal 9.0.0. Instead, get
+ *   a database connection injected into your service from the container and
+ *   call truncate() on it. E.g. $injected_database->truncate($table, $options);
+ *
+ * @see \Drupal\Core\Database\Connection::truncate()
+ * @see \Drupal\Core\Database\Connection::defaultOptions()
  */
 function db_truncate($table, array $options = array()) {
   if (empty($options['target']) || $options['target'] == 'replica') {
@@ -210,16 +263,25 @@ function db_truncate($table, array $options = array()) {
 /**
  * Returns a new SelectQuery object for the active database.
  *
- * @param $table
+ * @param string|\Drupal\Core\Database\Query\SelectInterface $table
- *   The base table for this query. May be a string or another SelectQuery
+ *   The base table for this query. May be a string or another SelectInterface
- *   object. If a query object is passed, it will be used as a subselect.
+ *   object. If a SelectInterface object is passed, it will be used as a
- * @param $alias
+ *   subselect.
+ * @param string $alias
  *   (optional) The alias for the base table of this query.
- * @param $options
+ * @param array $options
  *   (optional) An array of options to control how the query operates.
  *
  * @return \Drupal\Core\Database\Query\Select
  *   A new Select object for this connection.
+ *
+ * @deprecated as of Drupal 8.0.x, will be removed in Drupal 9.0.0. Instead, get
+ *   a database connection injected into your service from the container and
+ *   call select() on it. E.g.
+ *   $injected_database->select($table, $alias, $options);
+ *
+ * @see \Drupal\Core\Database\Connection::select()
+ * @see \Drupal\Core\Database\Connection::defaultOptions()
  */
 function db_select($table, $alias = NULL, array $options = array()) {
   if (empty($options['target'])) {
@@ -239,6 +301,14 @@ function db_select($table, $alias = NULL, array $options = array()) {
  *
  * @return \Drupal\Core\Database\Transaction
  *   A new Transaction object for this connection.
+ *
+ * @deprecated as of Drupal 8.0.x, will be removed in Drupal 9.0.0. Instead, get
+ *   a database connection injected into your service from the container and
+ *   call startTransaction() on it. E.g.
+ *   $injected_database->startTransaction($name);
+ *
+ * @see \Drupal\Core\Database\Connection::startTransaction()
+ * @see \Drupal\Core\Database\Connection::defaultOptions()
  */
 function db_transaction($name = NULL, array $options = array()) {
   if (empty($options['target'])) {
@@ -253,8 +323,11 @@ function db_transaction($name = NULL, array $options = array()) {
  * @param $key
  *   The key in the $databases array to set as the default database.
  *
- * @return
+ * @return string|null
  *   The key of the formerly active database.
+ *
+ * @deprecated as of Drupal 8.0.x, will be removed in Drupal 9.0.0. Use
+ * \Drupal\Core\Database\Database::setActiveConnection().
  */
 function db_set_active($key = 'default') {
   return Database::setActiveConnection($key);
@@ -268,8 +341,14 @@ function db_set_active($key = 'default') {
  * @param $table
  *   The table name to escape.
  *
- * @return
+ * @return string
  *   The escaped table name as a string.
+ *
+ * @deprecated as of Drupal 8.0.x, will be removed in Drupal 9.0.0. Instead, get
+ *   a database connection injected into your service from the container and
+ *   call escapeTable() on it. E.g. $injected_database->escapeTable($table);
+ *
+ * @see \Drupal\Core\Database\Connection::escapeTable()
  */
 function db_escape_table($table) {
   return Database::getConnection()->escapeTable($table);
@@ -280,11 +359,17 @@ function db_escape_table($table) {
  *
  * Only keeps alphanumeric and underscores.
  *
- * @param $field
+ * @param string $field
  *   The field name to escape.
  *
- * @return
+ * @return string
  *   The escaped field name as a string.
+ *
+ * @deprecated as of Drupal 8.0.x, will be removed in Drupal 9.0.0. Instead, get
+ *   a database connection injected into your service from the container and
+ *   call escapeTable() on it. E.g. $injected_database->escapeTable($table);
+ *
+ * @see \Drupal\Core\Database\Connection::escapeField()
  */
 function db_escape_field($field) {
   return Database::getConnection()->escapeField($field);
@@ -314,11 +399,17 @@ function db_escape_field($field) {
  * Backslash is defined as escape character for LIKE patterns in
  * DatabaseCondition::mapConditionOperator().
  *
- * @param $string
+ * @param string $string
  *   The string to escape.
  *
- * @return
+ * @return string
  *   The escaped string.
+ *
+ * @deprecated as of Drupal 8.0.x, will be removed in Drupal 9.0.0. Instead, get
+ *   a database connection injected into your service from the container and
+ *   call escapeLike() on it. E.g. $injected_database->escapeLike($string);
+ *
+ * @see \Drupal\Core\Database\Connection::escapeLike()
  */
 function db_like($string) {
   return Database::getConnection()->escapeLike($string);
@@ -327,8 +418,14 @@ function db_like($string) {
 /**
  * Retrieves the name of the currently active database driver.
  *
- * @return
+ * @return string
  *   The name of the currently active database driver.
+ *
+ * @deprecated as of Drupal 8.0.x, will be removed in Drupal 9.0.0. Instead, get
+ *   a database connection injected into your service from the container and
+ *   call driver() on it. E.g. $injected_database->driver($string);
+ *
+ * @see \Drupal\Core\Database\Connection::driver()
  */
 function db_driver() {
   return Database::getConnection()->driver();
@@ -337,9 +434,14 @@ function db_driver() {
 /**
  * Closes the active database connection.
  *
- * @param $options
+ * @param array $options
  *   An array of options to control which connection is closed. Only the target
  *   key has any meaning in this case.
+ *
+ * @deprecated as of Drupal 8.0.x, will be removed in Drupal 9.0.0. Use
+ *   \Drupal\Core\Database\Database::closeConnection($target).
+ *
+ * @see \Drupal\Core\Database\Database::closeConnection()
  */
 function db_close(array $options = array()) {
   if (empty($options['target'])) {
@@ -355,13 +457,19 @@ function db_close(array $options = array()) {
  * serial field is preferred, and InsertQuery::execute() returns the value of
  * the last ID inserted.
  *
- * @param $existing_id
+ * @param int $existing_id
  *   After a database import, it might be that the sequences table is behind, so
  *   by passing in a minimum ID, it can be assured that we never issue the same
  *   ID.
  *
- * @return
+ * @return int
  *   An integer number larger than any number returned before for this sequence.
+ *
+ * @deprecated as of Drupal 8.0.x, will be removed in Drupal 9.0.0. Instead, get
+ *   a database connection injected into your service from the container and
+ *   call nextId() on it. E.g. $injected_database->nextId($existing_id);
+ *
+ * @see \Drupal\Core\Database\Connection::nextId()
  */
 function db_next_id($existing_id = 0) {
   return Database::getConnection()->nextId($existing_id);
@@ -372,6 +480,12 @@ function db_next_id($existing_id = 0) {
  *
  * @return \Drupal\Core\Database\Query\Condition
  *   A new Condition object, set to "OR" all conditions together.
+ *
+ * @deprecated as of Drupal 8.0.x, will be removed in Drupal 9.0.0. Create
+ *   a \Drupal\Core\Database\Query\Condition object, specifying an OR
+ *   conjunction: new Condition('OR');
+ *
+ * @see \Drupal\Core\Database\Query\Condition
  */
 function db_or() {
   return new Condition('OR');
@@ -382,6 +496,12 @@ function db_or() {
  *
  * @return \Drupal\Core\Database\Query\Condition
  *   A new Condition object, set to "AND" all conditions together.
+ *
+ * @deprecated as of Drupal 8.0.x, will be removed in Drupal 9.0.0. Create
+ *   a \Drupal\Core\Database\Query\Condition object, specifying an AND
+ *   conjunction: new Condition('AND');
+ *
+ * @see \Drupal\Core\Database\Query\Condition
  */
 function db_and() {
   return new Condition('AND');
@@ -392,6 +512,12 @@ function db_and() {
  *
  * @return \Drupal\Core\Database\Query\Condition
  *   A new Condition object, set to "XOR" all conditions together.
+ *
+ * @deprecated as of Drupal 8.0.x, will be removed in Drupal 9.0.0. Create
+ *   a \Drupal\Core\Database\Query\Condition object, specifying an XOR
+ *   conjunction: new Condition('XOR');
+ *
+ * @see \Drupal\Core\Database\Query\Condition
  */
 function db_xor() {
   return new Condition('XOR');
@@ -403,11 +529,17 @@ function db_xor() {
  * Internal API function call.  The db_and(), db_or(), and db_xor()
  * functions are preferred.
  *
- * @param $conjunction
+ * @param string $conjunction
  *   The conjunction to use for query conditions (AND, OR or XOR).
  *
  * @return \Drupal\Core\Database\Query\Condition
  *   A new Condition object, set to the specified conjunction.
+ *
+ * @deprecated as of Drupal 8.0.x, will be removed in Drupal 9.0.0. Create
+ *   a \Drupal\Core\Database\Query\Condition object, specifying the desired
+ *   conjunction: new Condition($conjunctin);
+ *
+ * @see \Drupal\Core\Database\Query\Condition
  */
 function db_condition($conjunction) {
   return new Condition($conjunction);
@@ -426,10 +558,17 @@ function db_condition($conjunction) {
 /**
  * Creates a new table from a Drupal table definition.
  *
- * @param $name
+ * @param string $name
  *   The name of the table to create.
- * @param $table
+ * @param array $table
  *   A Schema API table definition array.
+ *
+ * @deprecated as of Drupal 8.0.x, will be removed in Drupal 9.0.0. Instead, get
+ *   a database connection injected into your service from the container, get
+ *   its schema driver, and call createTable() on it. E.g.
+ *   $injected_database->schema()->createTable($name, $table);
+ *
+ * @see \Drupal\Core\Database\Schema::createTable()
  */
 function db_create_table($name, $table) {
   return Database::getConnection()->schema()->createTable($name, $table);
@@ -441,11 +580,18 @@ function db_create_table($name, $table) {
  * This is usually an identity function but if a key/index uses a column prefix
  * specification, this function extracts just the name.
  *
- * @param $fields
+ * @param array $fields
  *   An array of key/index column specifiers.
  *
- * @return
+ * @return array
  *   An array of field names.
+ *
+ * @deprecated as of Drupal 8.0.x, will be removed in Drupal 9.0.0. Instead, get
+ *   a database connection injected into your service from the container, get
+ *   its schema driver, and call fieldNames() on it. E.g.
+ *   $injected_database->schema()->fieldNames($fields);
+ *
+ * @see \Drupal\Core\Database\Schema::fieldNames()
  */
 function db_field_names($fields) {
   return Database::getConnection()->schema()->fieldNames($fields);
@@ -454,13 +600,20 @@ function db_field_names($fields) {
 /**
  * Checks if an index exists in the given table.
  *
- * @param $table
+ * @param string $table
  *   The name of the table in drupal (no prefixing).
- * @param $name
+ * @param string $name
  *   The name of the index in drupal (no prefixing).
  *
- * @return
+ * @return bool
  *   TRUE if the given index exists, otherwise FALSE.
+ *
+ * @deprecated as of Drupal 8.0.x, will be removed in Drupal 9.0.0. Instead, get
+ *   a database connection injected into your service from the container, get
+ *   its schema driver, and call indexExists() on it. E.g.
+ *   $injected_database->schema()->indexExists($table, $name);
+ *
+ * @see \Drupal\Core\Database\Schema::indexExists()
  */
 function db_index_exists($table, $name) {
   return Database::getConnection()->schema()->indexExists($table, $name);
@@ -469,11 +622,18 @@ function db_index_exists($table, $name) {
 /**
  * Checks if a table exists.
  *
- * @param $table
+ * @param string $table
  *   The name of the table in drupal (no prefixing).
  *
- * @return
+ * @return bool
  *   TRUE if the given table exists, otherwise FALSE.
+ *
+ * @deprecated as of Drupal 8.0.x, will be removed in Drupal 9.0.0. Instead, get
+ *   a database connection injected into your service from the container, get
+ *   its schema driver, and call tableExists() on it. E.g.
+ *   $injected_database->schema()->tableExists($table);
+ *
+ * @see \Drupal\Core\Database\Schema::tableExists()
  */
 function db_table_exists($table) {
   return Database::getConnection()->schema()->tableExists($table);
@@ -487,8 +647,15 @@ function db_table_exists($table) {
  * @param $field
  *   The name of the field.
  *
- * @return
+ * @return bool
  *   TRUE if the given column exists, otherwise FALSE.
+ *
+ * @deprecated as of Drupal 8.0.x, will be removed in Drupal 9.0.0. Instead, get
+ *   a database connection injected into your service from the container, get
+ *   its schema driver, and call fieldExists() on it. E.g.
+ *   $injected_database->schema()->fieldExists($table, $field);
+ *
+ * @see \Drupal\Core\Database\Schema::fieldExists()
  */
 function db_field_exists($table, $field) {
   return Database::getConnection()->schema()->fieldExists($table, $field);
@@ -497,21 +664,24 @@ function db_field_exists($table, $field) {
 /**
  * Finds all tables that are like the specified base table name.
  *
- * @param $table_expression
+ * @param string $table_expression
  *   An SQL expression, for example "simpletest%" (without the quotes).
  *   BEWARE: this is not prefixed, the caller should take care of that.
  *
- * @return
+ * @return array
  *   Array, both the keys and the values are the matching tables.
+ *
+ * @deprecated as of Drupal 8.0.x, will be removed in Drupal 9.0.0. Instead, get
+ *   a database connection injected into your service from the container, get
+ *   its schema driver, and call findTables() on it. E.g.
+ *   $injected_database->schema()->findTables($table_expression);
+ *
+ * @see \Drupal\Core\Database\Schema::findTables()
  */
 function db_find_tables($table_expression) {
   return Database::getConnection()->schema()->findTables($table_expression);
 }
 
-function _db_create_keys_sql($spec) {
-  return Database::getConnection()->schema()->createKeysSql($spec);
-}
-
 /**
  * Renames a table.
  *
@@ -519,6 +689,13 @@ function _db_create_keys_sql($spec) {
  *   The current name of the table to be renamed.
  * @param $new_name
  *   The new name for the table.
+ *
+ * @deprecated as of Drupal 8.0.x, will be removed in Drupal 9.0.0. Instead, get
+ *   a database connection injected into your service from the container, get
+ *   its schema driver, and call renameTable() on it. E.g.
+ *   $injected_database->schema()->renameTable($table, $new_name);
+ *
+ * @see \Drupal\Core\Database\Schema::renameTable()
  */
 function db_rename_table($table, $new_name) {
   return Database::getConnection()->schema()->renameTable($table, $new_name);
@@ -529,6 +706,13 @@ function db_rename_table($table, $new_name) {
  *
  * @param $table
  *   The table to be dropped.
+ *
+ * @deprecated as of Drupal 8.0.x, will be removed in Drupal 9.0.0. Instead, get
+ *   a database connection injected into your service from the container, get
+ *   its schema driver, and call dropTable() on it. E.g.
+ *   $injected_database->schema()->dropTable($table);
+ *
+ * @see \Drupal\Core\Database\Schema::dropTable()
  */
 function db_drop_table($table) {
   return Database::getConnection()->schema()->dropTable($table);
@@ -541,18 +725,24 @@ function db_drop_table($table) {
  *   Name of the table to be altered.
  * @param $field
  *   Name of the field to be added.
- * @param $spec
+ * @param array $spec
  *   The field specification array, as taken from a schema definition. The
  *   specification may also contain the key 'initial'; the newly-created field
  *   will be set to the value of the key in all rows. This is most useful for
  *   creating NOT NULL columns with no default value in existing tables.
- * @param $keys_new
+ * @param array $keys_new
  *   (optional) Keys and indexes specification to be created on the table along
  *   with adding the field. The format is the same as a table specification, but
  *   without the 'fields' element. If you are adding a type 'serial' field, you
  *   MUST specify at least one key or index including it in this array. See
  *   db_change_field() for more explanation why.
  *
+ * @deprecated as of Drupal 8.0.x, will be removed in Drupal 9.0.0. Instead, get
+ *   a database connection injected into your service from the container, get
+ *   its schema driver, and call addField() on it. E.g.
+ *   $injected_database->schema()->addField($table, $field, $spec, $keys_new);
+ *
+ * @see \Drupal\Core\Database\Schema::addField()
  * @see db_change_field()
  */
 function db_add_field($table, $field, $spec, $keys_new = array()) {
@@ -566,6 +756,17 @@ function db_add_field($table, $field, $spec, $keys_new = array()) {
  *   The table to be altered.
  * @param $field
  *   The field to be dropped.
+ *
+ * @return bool
+ *   TRUE if the field was successfully dropped, FALSE if there was no field by
+ *   that name to begin with.
+ *
+ * @deprecated as of Drupal 8.0.x, will be removed in Drupal 9.0.0. Instead, get
+ *   a database connection injected into your service from the container, get
+ *   its schema driver, and call dropField() on it. E.g.
+ *   $injected_database->schema()->dropField($table, $field);
+ *
+ * @see \Drupal\Core\Database\Schema::dropField()
  */
 function db_drop_field($table, $field) {
   return Database::getConnection()->schema()->dropField($table, $field);
@@ -580,6 +781,13 @@ function db_drop_field($table, $field) {
  *   The field to be altered.
  * @param $default
  *   Default value to be set. NULL for 'default NULL'.
+ *
+ * @deprecated as of Drupal 8.0.x, will be removed in Drupal 9.0.0. Instead, get
+ *   a database connection injected into your service from the container, get
+ *   its schema driver, and call fieldSetDefault() on it. E.g.
+ *   $injected_database->schema()->fieldSetDefault($table, $field, $default);
+ *
+ * @see \Drupal\Core\Database\Schema::fieldSetDefault()
  */
 function db_field_set_default($table, $field, $default) {
   return Database::getConnection()->schema()->fieldSetDefault($table, $field, $default);
@@ -592,6 +800,13 @@ function db_field_set_default($table, $field, $default) {
  *   The table to be altered.
  * @param $field
  *   The field to be altered.
+ *
+ * @deprecated as of Drupal 8.0.x, will be removed in Drupal 9.0.0. Instead, get
+ *   a database connection injected into your service from the container, get
+ *   its schema driver, and call fieldSetNoDefault() on it. E.g.
+ *   $injected_database->schema()->fieldSetNoDefault($table, $field);
+ *
+ * @see \Drupal\Core\Database\Schema::fieldSetNoDefault()
  */
 function db_field_set_no_default($table, $field) {
   return Database::getConnection()->schema()->fieldSetNoDefault($table, $field);
@@ -604,6 +819,13 @@ function db_field_set_no_default($table, $field) {
  *   Name of the table to be altered.
  * @param $fields
  *   Array of fields for the primary key.
+ *
+ * @deprecated as of Drupal 8.0.x, will be removed in Drupal 9.0.0. Instead, get
+ *   a database connection injected into your service from the container, get
+ *   its schema driver, and call addPrimaryKey() on it. E.g.
+ *   $injected_database->schema()->addPrimaryKey($table, $fields);
+ *
+ * @see \Drupal\Core\Database\Schema::addPrimaryKey()
  */
 function db_add_primary_key($table, $fields) {
   return Database::getConnection()->schema()->addPrimaryKey($table, $fields);
@@ -614,6 +836,17 @@ function db_add_primary_key($table, $fields) {
  *
  * @param $table
  *   Name of the table to be altered.
+ *
+ * @return bool
+ *   TRUE if the primary key was successfully dropped, FALSE if there was no
+ *   primary key on this table to begin with.
+ *
+ * @deprecated as of Drupal 8.0.x, will be removed in Drupal 9.0.0. Instead, get
+ *   a database connection injected into your service from the container, get
+ *   its schema driver, and call dropPrimaryKey() on it. E.g.
+ *   $injected_database->schema()->dropPrimaryKey($table);
+ *
+ * @see \Drupal\Core\Database\Schema::dropPrimaryKey()
  */
 function db_drop_primary_key($table) {
   return Database::getConnection()->schema()->dropPrimaryKey($table);
@@ -626,8 +859,15 @@ function db_drop_primary_key($table) {
  *   The table to be altered.
  * @param $name
  *   The name of the key.
- * @param $fields
+ * @param array $fields
  *   An array of field names.
+ *
+ * @deprecated as of Drupal 8.0.x, will be removed in Drupal 9.0.0. Instead, get
+ *   a database connection injected into your service from the container, get
+ *   its schema driver, and call addUniqueKey() on it. E.g.
+ *   $injected_database->schema()->addUniqueKey($table, $name, $fields);
+ *
+ * @see \Drupal\Core\Database\Schema::addUniqueKey()
  */
 function db_add_unique_key($table, $name, $fields) {
   return Database::getConnection()->schema()->addUniqueKey($table, $name, $fields);
@@ -640,6 +880,17 @@ function db_add_unique_key($table, $name, $fields) {
  *   The table to be altered.
  * @param $name
  *   The name of the key.
+ *
+ * @return bool
+ *   TRUE if the key was successfully dropped, FALSE if there was no key by
+ *   that name to begin with.
+ *
+ * @deprecated as of Drupal 8.0.x, will be removed in Drupal 9.0.0. Instead, get
+ *   a database connection injected into your service from the container, get
+ *   its schema driver, and call dropUniqueKey() on it. E.g.
+ *   $injected_database->schema()->dropUniqueKey($table, $name);
+ *
+ * @see \Drupal\Core\Database\Schema::dropUniqueKey()
  */
 function db_drop_unique_key($table, $name) {
   return Database::getConnection()->schema()->dropUniqueKey($table, $name);
@@ -652,8 +903,15 @@ function db_drop_unique_key($table, $name) {
  *   The table to be altered.
  * @param $name
  *   The name of the index.
- * @param $fields
+ * @param array $fields
  *   An array of field names.
+ *
+ * @deprecated as of Drupal 8.0.x, will be removed in Drupal 9.0.0. Instead, get
+ *   a database connection injected into your service from the container, get
+ *   its schema driver, and call addIndex() on it. E.g.
+ *   $injected_database->schema()->addIndex($table, $name, $fields);
+ *
+ * @see \Drupal\Core\Database\Schema::addIndex()
  */
 function db_add_index($table, $name, $fields) {
   return Database::getConnection()->schema()->addIndex($table, $name, $fields);
@@ -666,6 +924,17 @@ function db_add_index($table, $name, $fields) {
  *   The table to be altered.
  * @param $name
  *   The name of the index.
+ *
+ * @return bool
+ *   TRUE if the index was successfully dropped, FALSE if there was no index
+ *   by that name to begin with.
+ *
+ * @deprecated as of Drupal 8.0.x, will be removed in Drupal 9.0.0. Instead, get
+ *   a database connection injected into your service from the container, get
+ *   its schema driver, and call dropIndex() on it. E.g.
+ *   $injected_database->schema()->dropIndex($table, $name);
+ *
+ * @see \Drupal\Core\Database\Schema::dropIndex()
  */
 function db_drop_index($table, $name) {
   return Database::getConnection()->schema()->dropIndex($table, $name);
@@ -726,10 +995,17 @@ function db_drop_index($table, $name) {
  *   change the name).
  * @param $spec
  *   The field specification for the new field.
- * @param $keys_new
+ * @param array $keys_new
  *   (optional) Keys and indexes specification to be created on the table along
  *   with changing the field. The format is the same as a table specification
  *   but without the 'fields' element.
+ *
+ * @deprecated as of Drupal 8.0.x, will be removed in Drupal 9.0.0. Instead, get
+ *   a database connection injected into your service from the container, get
+ *   its schema driver, and call changeField() on it. E.g.
+ *   $injected_database->schema()->changeField($table, $field, $field_new, $spec, $keys_new);
+ *
+ * @see \Drupal\Core\Database\Schema::changeField()
  */
 function db_change_field($table, $field, $field_new, $spec, $keys_new = array()) {
   return Database::getConnection()->schema()->changeField($table, $field, $field_new, $spec, $keys_new);