1. 8.3.x core/includes/database.inc
  2. 8.0.x core/includes/database.inc
  3. 8.1.x core/includes/database.inc
  4. 8.2.x core/includes/database.inc
  5. 8.4.x core/includes/database.inc
  6. 4.6.x includes/database.inc
  7. 4.7.x includes/database.inc
  8. 5.x includes/database.inc
  9. 6.x includes/database.inc
  10. 7.x includes/database/mysql/database.inc
  11. 7.x includes/database/sqlite/database.inc
  12. 7.x includes/database/pgsql/database.inc
  13. 7.x includes/database/database.inc

Core systems for the database layer.

Classes required for basic functioning of the database system should be placed in this file. All utility functions should also be placed in this file only, as they cannot auto-load the way classes can.

File

core/includes/database.inc
View source
  1. <?php
  2. /**
  3. * @file
  4. * Core systems for the database layer.
  5. *
  6. * Classes required for basic functioning of the database system should be
  7. * placed in this file. All utility functions should also be placed in this
  8. * file only, as they cannot auto-load the way classes can.
  9. */
  10. use Drupal\Core\Database\Database;
  11. use Drupal\Core\Database\Query\Condition;
  12. use Drupal\Core\Site\Settings;
  13. /**
  14. * @addtogroup database
  15. * @{
  16. */
  17. /**
  18. * Executes an arbitrary query string against the active database.
  19. *
  20. * Use this function for SELECT queries if it is just a simple query string.
  21. * If the caller or other modules need to change the query, use db_select()
  22. * instead.
  23. *
  24. * Do not use this function for INSERT, UPDATE, or DELETE queries. Those should
  25. * be handled via db_insert(), db_update() and db_delete() respectively.
  26. *
  27. * @param string|\Drupal\Core\Database\StatementInterface $query
  28. * The prepared statement query to run. Although it will accept both named and
  29. * unnamed placeholders, named placeholders are strongly preferred as they are
  30. * more self-documenting. If the argument corresponding to a placeholder is
  31. * an array of values to be expanded (for example, with an IN query), the
  32. * placeholder should be named with a trailing bracket like :example[].
  33. * @param array $args
  34. * An array of values to substitute into the query. If the query uses named
  35. * placeholders, this is an associative array in any order. If the query uses
  36. * unnamed placeholders (?), this is an indexed array and the order must match
  37. * the order of placeholders in the query string.
  38. * @param array $options
  39. * An array of options to control how the query operates.
  40. *
  41. * @return \Drupal\Core\Database\StatementInterface
  42. * A prepared statement object, already executed.
  43. *
  44. * @deprecated as of Drupal 8.0.x, will be removed in Drupal 9.0.0. Instead, get
  45. * a database connection injected into your service from the container and
  46. * call query() on it. For example,
  47. * $injected_database->query($query, $args, $options);
  48. *
  49. * @see \Drupal\Core\Database\Connection::query()
  50. * @see \Drupal\Core\Database\Connection::defaultOptions()
  51. */
  52. function db_query($query, array $args = array(), array $options = array()) {
  53. if (empty($options['target'])) {
  54. $options['target'] = 'default';
  55. }
  56. return Database::getConnection($options['target'])->query($query, $args, $options);
  57. }
  58. /**
  59. * Executes a query against the active database, restricted to a range.
  60. *
  61. * @param string $query
  62. * The prepared statement query to run. Although it will accept both named and
  63. * unnamed placeholders, named placeholders are strongly preferred as they are
  64. * more self-documenting.
  65. * @param $from
  66. * The first record from the result set to return.
  67. * @param $count
  68. * The number of records to return from the result set.
  69. * @param array $args
  70. * An array of values to substitute into the query. If the query uses named
  71. * placeholders, this is an associative array in any order. If the query uses
  72. * unnamed placeholders (?), this is an indexed array and the order must match
  73. * the order of placeholders in the query string.
  74. * @param array $options
  75. * An array of options to control how the query operates.
  76. *
  77. * @return \Drupal\Core\Database\StatementInterface
  78. * A prepared statement object, already executed.
  79. *
  80. * @deprecated as of Drupal 8.0.x, will be removed in Drupal 9.0.0. Instead, get
  81. * a database connection injected into your service from the container and
  82. * call queryRange() on it. For example,
  83. * $injected_database->queryRange($query, $from, $count, $args, $options);
  84. *
  85. * @see \Drupal\Core\Database\Connection::queryRange()
  86. * @see \Drupal\Core\Database\Connection::defaultOptions()
  87. */
  88. function db_query_range($query, $from, $count, array $args = array(), array $options = array()) {
  89. if (empty($options['target'])) {
  90. $options['target'] = 'default';
  91. }
  92. return Database::getConnection($options['target'])->queryRange($query, $from, $count, $args, $options);
  93. }
  94. /**
  95. * Executes a SELECT query string and saves the result set to a temporary table.
  96. *
  97. * The execution of the query string happens against the active database.
  98. *
  99. * @param string $query
  100. * The prepared SELECT statement query to run. Although it will accept both
  101. * named and unnamed placeholders, named placeholders are strongly preferred
  102. * as they are more self-documenting.
  103. * @param array $args
  104. * An array of values to substitute into the query. If the query uses named
  105. * placeholders, this is an associative array in any order. If the query uses
  106. * unnamed placeholders (?), this is an indexed array and the order must match
  107. * the order of placeholders in the query string.
  108. * @param array $options
  109. * An array of options to control how the query operates.
  110. *
  111. * @return
  112. * The name of the temporary table.
  113. *
  114. * @deprecated as of Drupal 8.0.x, will be removed in Drupal 9.0.0. Instead, get
  115. * a database connection injected into your service from the container and
  116. * call queryTemporary() on it. For example,
  117. * $injected_database->queryTemporary($query, $args, $options);
  118. *
  119. * @see \Drupal\Core\Database\Connection::queryTemporary()
  120. * @see \Drupal\Core\Database\Connection::defaultOptions()
  121. */
  122. function db_query_temporary($query, array $args = array(), array $options = array()) {
  123. if (empty($options['target'])) {
  124. $options['target'] = 'default';
  125. }
  126. return Database::getConnection($options['target'])->queryTemporary($query, $args, $options);
  127. }
  128. /**
  129. * Returns a new InsertQuery object for the active database.
  130. *
  131. * @param string $table
  132. * The table into which to insert.
  133. * @param array $options
  134. * An array of options to control how the query operates.
  135. *
  136. * @return \Drupal\Core\Database\Query\Insert
  137. * A new Insert object for this connection.
  138. *
  139. * @deprecated as of Drupal 8.0.x, will be removed in Drupal 9.0.0. Instead, get
  140. * a database connection injected into your service from the container and
  141. * call insert() on it. For example,
  142. * $injected_database->insert($table, $options);
  143. *
  144. * @see \Drupal\Core\Database\Connection::insert()
  145. * @see \Drupal\Core\Database\Connection::defaultOptions()
  146. */
  147. function db_insert($table, array $options = array()) {
  148. if (empty($options['target']) || $options['target'] == 'replica') {
  149. $options['target'] = 'default';
  150. }
  151. return Database::getConnection($options['target'])->insert($table, $options);
  152. }
  153. /**
  154. * Returns a new MergeQuery object for the active database.
  155. *
  156. * @param string $table
  157. * Name of the table to associate with this query.
  158. * @param array $options
  159. * An array of options to control how the query operates.
  160. *
  161. * @return \Drupal\Core\Database\Query\Merge
  162. * A new Merge object for this connection.
  163. *
  164. * @deprecated as of Drupal 8.0.x, will be removed in Drupal 9.0.0. Instead, get
  165. * a database connection injected into your service from the container and
  166. * call merge() on it. For example,
  167. * $injected_database->merge($table, $options);
  168. *
  169. * @see \Drupal\Core\Database\Connection::merge()
  170. * @see \Drupal\Core\Database\Connection::defaultOptions()
  171. */
  172. function db_merge($table, array $options = array()) {
  173. if (empty($options['target']) || $options['target'] == 'replica') {
  174. $options['target'] = 'default';
  175. }
  176. return Database::getConnection($options['target'])->merge($table, $options);
  177. }
  178. /**
  179. * Returns a new UpdateQuery object for the active database.
  180. *
  181. * @param string $table
  182. * The table to update.
  183. * @param array $options
  184. * An array of options to control how the query operates.
  185. *
  186. * @return \Drupal\Core\Database\Query\Update
  187. * A new Update object for this connection.
  188. *
  189. * @deprecated as of Drupal 8.0.x, will be removed in Drupal 9.0.0. Instead, get
  190. * a database connection injected into your service from the container and
  191. * call update() on it. For example,
  192. * $injected_database->update($table, $options);
  193. *
  194. * @see \Drupal\Core\Database\Connection::update()
  195. * @see \Drupal\Core\Database\Connection::defaultOptions()
  196. */
  197. function db_update($table, array $options = array()) {
  198. if (empty($options['target']) || $options['target'] == 'replica') {
  199. $options['target'] = 'default';
  200. }
  201. return Database::getConnection($options['target'])->update($table, $options);
  202. }
  203. /**
  204. * Returns a new DeleteQuery object for the active database.
  205. *
  206. * @param string $table
  207. * The table from which to delete.
  208. * @param array $options
  209. * An array of options to control how the query operates.
  210. *
  211. * @return \Drupal\Core\Database\Query\Delete
  212. * A new Delete object for this connection.
  213. *
  214. * @deprecated as of Drupal 8.0.x, will be removed in Drupal 9.0.0. Instead, get
  215. * a database connection injected into your service from the container and
  216. * call delete() on it. For example,
  217. * $injected_database->delete($table, $options);
  218. *
  219. * @see \Drupal\Core\Database\Connection::delete()
  220. * @see \Drupal\Core\Database\Connection::defaultOptions()
  221. */
  222. function db_delete($table, array $options = array()) {
  223. if (empty($options['target']) || $options['target'] == 'replica') {
  224. $options['target'] = 'default';
  225. }
  226. return Database::getConnection($options['target'])->delete($table, $options);
  227. }
  228. /**
  229. * Returns a new TruncateQuery object for the active database.
  230. *
  231. * @param string $table
  232. * The table from which to truncate.
  233. * @param array $options
  234. * An array of options to control how the query operates.
  235. *
  236. * @return \Drupal\Core\Database\Query\Truncate
  237. * A new Truncate object for this connection.
  238. *
  239. * @deprecated as of Drupal 8.0.x, will be removed in Drupal 9.0.0. Instead, get
  240. * a database connection injected into your service from the container and
  241. * call truncate() on it. For example,
  242. * $injected_database->truncate($table, $options);
  243. *
  244. * @see \Drupal\Core\Database\Connection::truncate()
  245. * @see \Drupal\Core\Database\Connection::defaultOptions()
  246. */
  247. function db_truncate($table, array $options = array()) {
  248. if (empty($options['target']) || $options['target'] == 'replica') {
  249. $options['target'] = 'default';
  250. }
  251. return Database::getConnection($options['target'])->truncate($table, $options);
  252. }
  253. /**
  254. * Returns a new SelectQuery object for the active database.
  255. *
  256. * @param string|\Drupal\Core\Database\Query\SelectInterface $table
  257. * The base table for this query. May be a string or another SelectInterface
  258. * object. If a SelectInterface object is passed, it will be used as a
  259. * subselect.
  260. * @param string $alias
  261. * (optional) The alias for the base table of this query.
  262. * @param array $options
  263. * (optional) An array of options to control how the query operates.
  264. *
  265. * @return \Drupal\Core\Database\Query\Select
  266. * A new Select object for this connection.
  267. *
  268. * @deprecated as of Drupal 8.0.x, will be removed in Drupal 9.0.0. Instead, get
  269. * a database connection injected into your service from the container and
  270. * call select() on it. For example,
  271. * $injected_database->select($table, $alias, $options);
  272. *
  273. * @see \Drupal\Core\Database\Connection::select()
  274. * @see \Drupal\Core\Database\Connection::defaultOptions()
  275. */
  276. function db_select($table, $alias = NULL, array $options = array()) {
  277. if (empty($options['target'])) {
  278. $options['target'] = 'default';
  279. }
  280. return Database::getConnection($options['target'])->select($table, $alias, $options);
  281. }
  282. /**
  283. * Returns a new transaction object for the active database.
  284. *
  285. * @param string $name
  286. * Optional name of the transaction.
  287. * @param array $options
  288. * An array of options to control how the transaction operates:
  289. * - target: The database target name.
  290. *
  291. * @return \Drupal\Core\Database\Transaction
  292. * A new Transaction object for this connection.
  293. *
  294. * @deprecated as of Drupal 8.0.x, will be removed in Drupal 9.0.0. Instead, get
  295. * a database connection injected into your service from the container and
  296. * call startTransaction() on it. For example,
  297. * $injected_database->startTransaction($name);
  298. *
  299. * @see \Drupal\Core\Database\Connection::startTransaction()
  300. * @see \Drupal\Core\Database\Connection::defaultOptions()
  301. */
  302. function db_transaction($name = NULL, array $options = array()) {
  303. if (empty($options['target'])) {
  304. $options['target'] = 'default';
  305. }
  306. return Database::getConnection($options['target'])->startTransaction($name);
  307. }
  308. /**
  309. * Sets a new active database.
  310. *
  311. * @param $key
  312. * The key in the $databases array to set as the default database.
  313. *
  314. * @return string|null
  315. * The key of the formerly active database.
  316. *
  317. * @deprecated as of Drupal 8.0.x, will be removed in Drupal 9.0.0. Use
  318. * \Drupal\Core\Database\Database::setActiveConnection().
  319. */
  320. function db_set_active($key = 'default') {
  321. return Database::setActiveConnection($key);
  322. }
  323. /**
  324. * Restricts a dynamic table name to safe characters.
  325. *
  326. * Only keeps alphanumeric and underscores.
  327. *
  328. * @param $table
  329. * The table name to escape.
  330. *
  331. * @return string
  332. * The escaped table name as a string.
  333. *
  334. * @deprecated as of Drupal 8.0.x, will be removed in Drupal 9.0.0. Instead, get
  335. * a database connection injected into your service from the container and
  336. * call escapeTable() on it. For example,
  337. * $injected_database->escapeTable($table);
  338. *
  339. * @see \Drupal\Core\Database\Connection::escapeTable()
  340. */
  341. function db_escape_table($table) {
  342. return Database::getConnection()->escapeTable($table);
  343. }
  344. /**
  345. * Restricts a dynamic column or constraint name to safe characters.
  346. *
  347. * Only keeps alphanumeric and underscores.
  348. *
  349. * @param string $field
  350. * The field name to escape.
  351. *
  352. * @return string
  353. * The escaped field name as a string.
  354. *
  355. * @deprecated as of Drupal 8.0.x, will be removed in Drupal 9.0.0. Instead, get
  356. * a database connection injected into your service from the container and
  357. * call escapeTable() on it. For example,
  358. * $injected_database->escapeTable($table);
  359. *
  360. * @see \Drupal\Core\Database\Connection::escapeField()
  361. */
  362. function db_escape_field($field) {
  363. return Database::getConnection()->escapeField($field);
  364. }
  365. /**
  366. * Escapes characters that work as wildcard characters in a LIKE pattern.
  367. *
  368. * The wildcard characters "%" and "_" as well as backslash are prefixed with
  369. * a backslash. Use this to do a search for a verbatim string without any
  370. * wildcard behavior.
  371. *
  372. * You must use a query builder like db_select() in order to use db_like() on
  373. * all supported database systems. Using db_like() with db_query() or
  374. * db_query_range() is not supported.
  375. *
  376. * For example, the following does a case-insensitive query for all rows whose
  377. * name starts with $prefix:
  378. * @code
  379. * $result = db_select('person', 'p')
  380. * ->fields('p')
  381. * ->condition('name', db_like($prefix) . '%', 'LIKE')
  382. * ->execute()
  383. * ->fetchAll();
  384. * @endcode
  385. *
  386. * Backslash is defined as escape character for LIKE patterns in
  387. * DatabaseCondition::mapConditionOperator().
  388. *
  389. * @param string $string
  390. * The string to escape.
  391. *
  392. * @return string
  393. * The escaped string.
  394. *
  395. * @deprecated as of Drupal 8.0.x, will be removed in Drupal 9.0.0. Instead, get
  396. * a database connection injected into your service from the container and
  397. * call escapeLike() on it. For example,
  398. * $injected_database->escapeLike($string);
  399. *
  400. * @see \Drupal\Core\Database\Connection::escapeLike()
  401. */
  402. function db_like($string) {
  403. return Database::getConnection()->escapeLike($string);
  404. }
  405. /**
  406. * Retrieves the name of the currently active database driver.
  407. *
  408. * @return string
  409. * The name of the currently active database driver.
  410. *
  411. * @deprecated as of Drupal 8.0.x, will be removed in Drupal 9.0.0. Instead, get
  412. * a database connection injected into your service from the container and
  413. * call driver() on it. For example, $injected_database->driver($string);
  414. *
  415. * @see \Drupal\Core\Database\Connection::driver()
  416. */
  417. function db_driver() {
  418. return Database::getConnection()->driver();
  419. }
  420. /**
  421. * Closes the active database connection.
  422. *
  423. * @param array $options
  424. * An array of options to control which connection is closed. Only the target
  425. * key has any meaning in this case.
  426. *
  427. * @deprecated as of Drupal 8.0.x, will be removed in Drupal 9.0.0. Use
  428. * \Drupal\Core\Database\Database::closeConnection($target).
  429. *
  430. * @see \Drupal\Core\Database\Database::closeConnection()
  431. */
  432. function db_close(array $options = array()) {
  433. if (empty($options['target'])) {
  434. $options['target'] = NULL;
  435. }
  436. Database::closeConnection($options['target']);
  437. }
  438. /**
  439. * Retrieves a unique id.
  440. *
  441. * Use this function if for some reason you can't use a serial field. Using a
  442. * serial field is preferred, and InsertQuery::execute() returns the value of
  443. * the last ID inserted.
  444. *
  445. * @param int $existing_id
  446. * After a database import, it might be that the sequences table is behind, so
  447. * by passing in a minimum ID, it can be assured that we never issue the same
  448. * ID.
  449. *
  450. * @return int
  451. * An integer number larger than any number returned before for this sequence.
  452. *
  453. * @deprecated as of Drupal 8.0.x, will be removed in Drupal 9.0.0. Instead, get
  454. * a database connection injected into your service from the container and
  455. * call nextId() on it. For example, $injected_database->nextId($existing_id);
  456. *
  457. * @see \Drupal\Core\Database\Connection::nextId()
  458. */
  459. function db_next_id($existing_id = 0) {
  460. return Database::getConnection()->nextId($existing_id);
  461. }
  462. /**
  463. * Returns a new DatabaseCondition, set to "OR" all conditions together.
  464. *
  465. * @return \Drupal\Core\Database\Query\Condition
  466. * A new Condition object, set to "OR" all conditions together.
  467. *
  468. * @deprecated as of Drupal 8.0.x, will be removed in Drupal 9.0.0. Create
  469. * a \Drupal\Core\Database\Query\Condition object, specifying an OR
  470. * conjunction: new Condition('OR');
  471. *
  472. * @see \Drupal\Core\Database\Query\Condition
  473. */
  474. function db_or() {
  475. return new Condition('OR');
  476. }
  477. /**
  478. * Returns a new DatabaseCondition, set to "AND" all conditions together.
  479. *
  480. * @return \Drupal\Core\Database\Query\Condition
  481. * A new Condition object, set to "AND" all conditions together.
  482. *
  483. * @deprecated as of Drupal 8.0.x, will be removed in Drupal 9.0.0. Create
  484. * a \Drupal\Core\Database\Query\Condition object, specifying an AND
  485. * conjunction: new Condition('AND');
  486. *
  487. * @see \Drupal\Core\Database\Query\Condition
  488. */
  489. function db_and() {
  490. return new Condition('AND');
  491. }
  492. /**
  493. * Returns a new DatabaseCondition, set to "XOR" all conditions together.
  494. *
  495. * @return \Drupal\Core\Database\Query\Condition
  496. * A new Condition object, set to "XOR" all conditions together.
  497. *
  498. * @deprecated as of Drupal 8.0.x, will be removed in Drupal 9.0.0. Create
  499. * a \Drupal\Core\Database\Query\Condition object, specifying an XOR
  500. * conjunction: new Condition('XOR');
  501. *
  502. * @see \Drupal\Core\Database\Query\Condition
  503. */
  504. function db_xor() {
  505. return new Condition('XOR');
  506. }
  507. /**
  508. * Returns a new DatabaseCondition, set to the specified conjunction.
  509. *
  510. * Internal API function call. The db_and(), db_or(), and db_xor()
  511. * functions are preferred.
  512. *
  513. * @param string $conjunction
  514. * The conjunction to use for query conditions (AND, OR or XOR).
  515. *
  516. * @return \Drupal\Core\Database\Query\Condition
  517. * A new Condition object, set to the specified conjunction.
  518. *
  519. * @deprecated as of Drupal 8.0.x, will be removed in Drupal 9.0.0. Create
  520. * a \Drupal\Core\Database\Query\Condition object, specifying the desired
  521. * conjunction: new Condition($conjunctin);
  522. *
  523. * @see \Drupal\Core\Database\Query\Condition
  524. */
  525. function db_condition($conjunction) {
  526. return new Condition($conjunction);
  527. }
  528. /**
  529. * @} End of "addtogroup database".
  530. */
  531. /**
  532. * @addtogroup schemaapi
  533. * @{
  534. */
  535. /**
  536. * Creates a new table from a Drupal table definition.
  537. *
  538. * @param string $name
  539. * The name of the table to create.
  540. * @param array $table
  541. * A Schema API table definition array.
  542. *
  543. * @deprecated as of Drupal 8.0.x, will be removed in Drupal 9.0.0. Instead, get
  544. * a database connection injected into your service from the container, get
  545. * its schema driver, and call createTable() on it. For example,
  546. * $injected_database->schema()->createTable($name, $table);
  547. *
  548. * @see \Drupal\Core\Database\Schema::createTable()
  549. */
  550. function db_create_table($name, $table) {
  551. return Database::getConnection()->schema()->createTable($name, $table);
  552. }
  553. /**
  554. * Returns an array of field names from an array of key/index column specifiers.
  555. *
  556. * This is usually an identity function but if a key/index uses a column prefix
  557. * specification, this function extracts just the name.
  558. *
  559. * @param array $fields
  560. * An array of key/index column specifiers.
  561. *
  562. * @return array
  563. * An array of field names.
  564. *
  565. * @deprecated as of Drupal 8.0.x, will be removed in Drupal 9.0.0. Instead, get
  566. * a database connection injected into your service from the container, get
  567. * its schema driver, and call fieldNames() on it. For example,
  568. * $injected_database->schema()->fieldNames($fields);
  569. *
  570. * @see \Drupal\Core\Database\Schema::fieldNames()
  571. */
  572. function db_field_names($fields) {
  573. return Database::getConnection()->schema()->fieldNames($fields);
  574. }
  575. /**
  576. * Checks if an index exists in the given table.
  577. *
  578. * @param string $table
  579. * The name of the table in drupal (no prefixing).
  580. * @param string $name
  581. * The name of the index in drupal (no prefixing).
  582. *
  583. * @return bool
  584. * TRUE if the given index exists, otherwise FALSE.
  585. *
  586. * @deprecated as of Drupal 8.0.x, will be removed in Drupal 9.0.0. Instead, get
  587. * a database connection injected into your service from the container, get
  588. * its schema driver, and call indexExists() on it. For example,
  589. * $injected_database->schema()->indexExists($table, $name);
  590. *
  591. * @see \Drupal\Core\Database\Schema::indexExists()
  592. */
  593. function db_index_exists($table, $name) {
  594. return Database::getConnection()->schema()->indexExists($table, $name);
  595. }
  596. /**
  597. * Checks if a table exists.
  598. *
  599. * @param string $table
  600. * The name of the table in drupal (no prefixing).
  601. *
  602. * @return bool
  603. * TRUE if the given table exists, otherwise FALSE.
  604. *
  605. * @deprecated as of Drupal 8.0.x, will be removed in Drupal 9.0.0. Instead, get
  606. * a database connection injected into your service from the container, get
  607. * its schema driver, and call tableExists() on it. For example,
  608. * $injected_database->schema()->tableExists($table);
  609. *
  610. * @see \Drupal\Core\Database\Schema::tableExists()
  611. */
  612. function db_table_exists($table) {
  613. return Database::getConnection()->schema()->tableExists($table);
  614. }
  615. /**
  616. * Checks if a column exists in the given table.
  617. *
  618. * @param $table
  619. * The name of the table in drupal (no prefixing).
  620. * @param $field
  621. * The name of the field.
  622. *
  623. * @return bool
  624. * TRUE if the given column exists, otherwise FALSE.
  625. *
  626. * @deprecated as of Drupal 8.0.x, will be removed in Drupal 9.0.0. Instead, get
  627. * a database connection injected into your service from the container, get
  628. * its schema driver, and call fieldExists() on it. For example,
  629. * $injected_database->schema()->fieldExists($table, $field);
  630. *
  631. * @see \Drupal\Core\Database\Schema::fieldExists()
  632. */
  633. function db_field_exists($table, $field) {
  634. return Database::getConnection()->schema()->fieldExists($table, $field);
  635. }
  636. /**
  637. * Finds all tables that are like the specified base table name.
  638. *
  639. * @param string $table_expression
  640. * An SQL expression, for example "simpletest%" (without the quotes).
  641. *
  642. * @return array
  643. * Array, both the keys and the values are the matching tables.
  644. *
  645. * @deprecated as of Drupal 8.0.x, will be removed in Drupal 9.0.0. Instead, get
  646. * a database connection injected into your service from the container, get
  647. * its schema driver, and call findTables() on it. For example,
  648. * $injected_database->schema()->findTables($table_expression);
  649. *
  650. * @see \Drupal\Core\Database\Schema::findTables()
  651. */
  652. function db_find_tables($table_expression) {
  653. return Database::getConnection()->schema()->findTables($table_expression);
  654. }
  655. /**
  656. * Renames a table.
  657. *
  658. * @param $table
  659. * The current name of the table to be renamed.
  660. * @param $new_name
  661. * The new name for the table.
  662. *
  663. * @deprecated as of Drupal 8.0.x, will be removed in Drupal 9.0.0. Instead, get
  664. * a database connection injected into your service from the container, get
  665. * its schema driver, and call renameTable() on it. For example,
  666. * $injected_database->schema()->renameTable($table, $new_name);
  667. *
  668. * @see \Drupal\Core\Database\Schema::renameTable()
  669. */
  670. function db_rename_table($table, $new_name) {
  671. return Database::getConnection()->schema()->renameTable($table, $new_name);
  672. }
  673. /**
  674. * Drops a table.
  675. *
  676. * @param $table
  677. * The table to be dropped.
  678. *
  679. * @deprecated as of Drupal 8.0.x, will be removed in Drupal 9.0.0. Instead, get
  680. * a database connection injected into your service from the container, get
  681. * its schema driver, and call dropTable() on it. For example,
  682. * $injected_database->schema()->dropTable($table);
  683. *
  684. * @see \Drupal\Core\Database\Schema::dropTable()
  685. */
  686. function db_drop_table($table) {
  687. return Database::getConnection()->schema()->dropTable($table);
  688. }
  689. /**
  690. * Adds a new field to a table.
  691. *
  692. * @param $table
  693. * Name of the table to be altered.
  694. * @param $field
  695. * Name of the field to be added.
  696. * @param array $spec
  697. * The field specification array, as taken from a schema definition. The
  698. * specification may also contain the key 'initial'; the newly-created field
  699. * will be set to the value of the key in all rows. This is most useful for
  700. * creating NOT NULL columns with no default value in existing tables.
  701. * @param array $keys_new
  702. * (optional) Keys and indexes specification to be created on the table along
  703. * with adding the field. The format is the same as a table specification, but
  704. * without the 'fields' element. If you are adding a type 'serial' field, you
  705. * MUST specify at least one key or index including it in this array. See
  706. * db_change_field() for more explanation why.
  707. *
  708. * @deprecated as of Drupal 8.0.x, will be removed in Drupal 9.0.0. Instead, get
  709. * a database connection injected into your service from the container, get
  710. * its schema driver, and call addField() on it. For example,
  711. * $injected_database->schema()->addField($table, $field, $spec, $keys_new);
  712. *
  713. * @see \Drupal\Core\Database\Schema::addField()
  714. * @see db_change_field()
  715. */
  716. function db_add_field($table, $field, $spec, $keys_new = array()) {
  717. return Database::getConnection()->schema()->addField($table, $field, $spec, $keys_new);
  718. }
  719. /**
  720. * Drops a field.
  721. *
  722. * @param $table
  723. * The table to be altered.
  724. * @param $field
  725. * The field to be dropped.
  726. *
  727. * @return bool
  728. * TRUE if the field was successfully dropped, FALSE if there was no field by
  729. * that name to begin with.
  730. *
  731. * @deprecated as of Drupal 8.0.x, will be removed in Drupal 9.0.0. Instead, get
  732. * a database connection injected into your service from the container, get
  733. * its schema driver, and call dropField() on it. For example,
  734. * $injected_database->schema()->dropField($table, $field);
  735. *
  736. * @see \Drupal\Core\Database\Schema::dropField()
  737. */
  738. function db_drop_field($table, $field) {
  739. return Database::getConnection()->schema()->dropField($table, $field);
  740. }
  741. /**
  742. * Sets the default value for a field.
  743. *
  744. * @param $table
  745. * The table to be altered.
  746. * @param $field
  747. * The field to be altered.
  748. * @param $default
  749. * Default value to be set. NULL for 'default NULL'.
  750. *
  751. * @deprecated as of Drupal 8.0.x, will be removed in Drupal 9.0.0. Instead, get
  752. * a database connection injected into your service from the container, get
  753. * its schema driver, and call fieldSetDefault() on it. For example,
  754. * $injected_database->schema()->fieldSetDefault($table, $field, $default);
  755. *
  756. * @see \Drupal\Core\Database\Schema::fieldSetDefault()
  757. */
  758. function db_field_set_default($table, $field, $default) {
  759. return Database::getConnection()->schema()->fieldSetDefault($table, $field, $default);
  760. }
  761. /**
  762. * Sets a field to have no default value.
  763. *
  764. * @param $table
  765. * The table to be altered.
  766. * @param $field
  767. * The field to be altered.
  768. *
  769. * @deprecated as of Drupal 8.0.x, will be removed in Drupal 9.0.0. Instead, get
  770. * a database connection injected into your service from the container, get
  771. * its schema driver, and call fieldSetNoDefault() on it. For example,
  772. * $injected_database->schema()->fieldSetNoDefault($table, $field);
  773. *
  774. * @see \Drupal\Core\Database\Schema::fieldSetNoDefault()
  775. */
  776. function db_field_set_no_default($table, $field) {
  777. return Database::getConnection()->schema()->fieldSetNoDefault($table, $field);
  778. }
  779. /**
  780. * Adds a primary key to a database table.
  781. *
  782. * @param $table
  783. * Name of the table to be altered.
  784. * @param $fields
  785. * Array of fields for the primary key.
  786. *
  787. * @deprecated as of Drupal 8.0.x, will be removed in Drupal 9.0.0. Instead, get
  788. * a database connection injected into your service from the container, get
  789. * its schema driver, and call addPrimaryKey() on it. For example,
  790. * $injected_database->schema()->addPrimaryKey($table, $fields);
  791. *
  792. * @see \Drupal\Core\Database\Schema::addPrimaryKey()
  793. */
  794. function db_add_primary_key($table, $fields) {
  795. return Database::getConnection()->schema()->addPrimaryKey($table, $fields);
  796. }
  797. /**
  798. * Drops the primary key of a database table.
  799. *
  800. * @param $table
  801. * Name of the table to be altered.
  802. *
  803. * @return bool
  804. * TRUE if the primary key was successfully dropped, FALSE if there was no
  805. * primary key on this table to begin with.
  806. *
  807. * @deprecated as of Drupal 8.0.x, will be removed in Drupal 9.0.0. Instead, get
  808. * a database connection injected into your service from the container, get
  809. * its schema driver, and call dropPrimaryKey() on it. For example,
  810. * $injected_database->schema()->dropPrimaryKey($table);
  811. *
  812. * @see \Drupal\Core\Database\Schema::dropPrimaryKey()
  813. */
  814. function db_drop_primary_key($table) {
  815. return Database::getConnection()->schema()->dropPrimaryKey($table);
  816. }
  817. /**
  818. * Adds a unique key.
  819. *
  820. * @param $table
  821. * The table to be altered.
  822. * @param $name
  823. * The name of the key.
  824. * @param array $fields
  825. * An array of field names.
  826. *
  827. * @deprecated as of Drupal 8.0.x, will be removed in Drupal 9.0.0. Instead, get
  828. * a database connection injected into your service from the container, get
  829. * its schema driver, and call addUniqueKey() on it. For example,
  830. * $injected_database->schema()->addUniqueKey($table, $name, $fields);
  831. *
  832. * @see \Drupal\Core\Database\Schema::addUniqueKey()
  833. */
  834. function db_add_unique_key($table, $name, $fields) {
  835. return Database::getConnection()->schema()->addUniqueKey($table, $name, $fields);
  836. }
  837. /**
  838. * Drops a unique key.
  839. *
  840. * @param $table
  841. * The table to be altered.
  842. * @param $name
  843. * The name of the key.
  844. *
  845. * @return bool
  846. * TRUE if the key was successfully dropped, FALSE if there was no key by
  847. * that name to begin with.
  848. *
  849. * @deprecated as of Drupal 8.0.x, will be removed in Drupal 9.0.0. Instead, get
  850. * a database connection injected into your service from the container, get
  851. * its schema driver, and call dropUniqueKey() on it. For example,
  852. * $injected_database->schema()->dropUniqueKey($table, $name);
  853. *
  854. * @see \Drupal\Core\Database\Schema::dropUniqueKey()
  855. */
  856. function db_drop_unique_key($table, $name) {
  857. return Database::getConnection()->schema()->dropUniqueKey($table, $name);
  858. }
  859. /**
  860. * Adds an index.
  861. *
  862. * @param $table
  863. * The table to be altered.
  864. * @param $name
  865. * The name of the index.
  866. * @param array $fields
  867. * An array of field names.
  868. * @param array $spec
  869. * The table specification of the table to be altered, as taken from a schema
  870. * definition. See \Drupal\Core\Database\Schema::addIndex() for how to obtain
  871. * this specification.
  872. *
  873. * @deprecated as of Drupal 8.0.x, will be removed in Drupal 9.0.0. Instead, get
  874. * a database connection injected into your service from the container, get
  875. * its schema driver, and call addIndex() on it. For example,
  876. * $injected_database->schema()->addIndex($table, $name, $fields, $spec);
  877. *
  878. * @see hook_schema()
  879. * @see schemaapi
  880. * @see \Drupal\Core\Database\Schema::addIndex()
  881. */
  882. function db_add_index($table, $name, $fields, array $spec) {
  883. return Database::getConnection()->schema()->addIndex($table, $name, $fields, $spec);
  884. }
  885. /**
  886. * Drops an index.
  887. *
  888. * @param $table
  889. * The table to be altered.
  890. * @param $name
  891. * The name of the index.
  892. *
  893. * @return bool
  894. * TRUE if the index was successfully dropped, FALSE if there was no index
  895. * by that name to begin with.
  896. *
  897. * @deprecated as of Drupal 8.0.x, will be removed in Drupal 9.0.0. Instead, get
  898. * a database connection injected into your service from the container, get
  899. * its schema driver, and call dropIndex() on it. For example,
  900. * $injected_database->schema()->dropIndex($table, $name);
  901. *
  902. * @see \Drupal\Core\Database\Schema::dropIndex()
  903. */
  904. function db_drop_index($table, $name) {
  905. return Database::getConnection()->schema()->dropIndex($table, $name);
  906. }
  907. /**
  908. * Changes a field definition.
  909. *
  910. * IMPORTANT NOTE: To maintain database portability, you have to explicitly
  911. * recreate all indices and primary keys that are using the changed field.
  912. *
  913. * That means that you have to drop all affected keys and indexes with
  914. * db_drop_{primary_key,unique_key,index}() before calling db_change_field().
  915. * To recreate the keys and indices, pass the key definitions as the optional
  916. * $keys_new argument directly to db_change_field().
  917. *
  918. * For example, suppose you have:
  919. * @code
  920. * $schema['foo'] = array(
  921. * 'fields' => array(
  922. * 'bar' => array('type' => 'int', 'not null' => TRUE)
  923. * ),
  924. * 'primary key' => array('bar')
  925. * );
  926. * @endcode
  927. * and you want to change foo.bar to be type serial, leaving it as the primary
  928. * key. The correct sequence is:
  929. * @code
  930. * db_drop_primary_key('foo');
  931. * db_change_field('foo', 'bar', 'bar',
  932. * array('type' => 'serial', 'not null' => TRUE),
  933. * array('primary key' => array('bar')));
  934. * @endcode
  935. *
  936. * The reasons for this are due to the different database engines:
  937. *
  938. * On PostgreSQL, changing a field definition involves adding a new field and
  939. * dropping an old one which causes any indices, primary keys and sequences
  940. * (from serial-type fields) that use the changed field to be dropped.
  941. *
  942. * On MySQL, all type 'serial' fields must be part of at least one key or index
  943. * as soon as they are created. You cannot use
  944. * db_add_{primary_key,unique_key,index}() for this purpose because the ALTER
  945. * TABLE command will fail to add the column without a key or index
  946. * specification. The solution is to use the optional $keys_new argument to
  947. * create the key or index at the same time as field.
  948. *
  949. * You could use db_add_{primary_key,unique_key,index}() in all cases unless you
  950. * are converting a field to be type serial. You can use the $keys_new argument
  951. * in all cases.
  952. *
  953. * @param $table
  954. * Name of the table.
  955. * @param $field
  956. * Name of the field to change.
  957. * @param $field_new
  958. * New name for the field (set to the same as $field if you don't want to
  959. * change the name).
  960. * @param $spec
  961. * The field specification for the new field.
  962. * @param array $keys_new
  963. * (optional) Keys and indexes specification to be created on the table along
  964. * with changing the field. The format is the same as a table specification
  965. * but without the 'fields' element.
  966. *
  967. * @deprecated as of Drupal 8.0.x, will be removed in Drupal 9.0.0. Instead, get
  968. * a database connection injected into your service from the container, get
  969. * its schema driver, and call changeField() on it. For example,
  970. * $injected_database->schema()->changeField($table, $field, $field_new, $spec, $keys_new);
  971. *
  972. * @see \Drupal\Core\Database\Schema::changeField()
  973. */
  974. function db_change_field($table, $field, $field_new, $spec, $keys_new = array()) {
  975. return Database::getConnection()->schema()->changeField($table, $field, $field_new, $spec, $keys_new);
  976. }
  977. /**
  978. * @} End of "addtogroup schemaapi".
  979. */
  980. /**
  981. * Sets a session variable specifying the lag time for ignoring a replica
  982. * server (A replica server is traditionally referred to as
  983. * a "slave" in database server documentation).
  984. * @see https://www.drupal.org/node/2275877
  985. */
  986. function db_ignore_replica() {
  987. $connection_info = Database::getConnectionInfo();
  988. // Only set ignore_replica_server if there are replica servers being used,
  989. // which is assumed if there are more than one.
  990. if (count($connection_info) > 1) {
  991. // Five minutes is long enough to allow the replica to break and resume
  992. // interrupted replication without causing problems on the Drupal site from
  993. // the old data.
  994. $duration = Settings::get('maximum_replication_lag', 300);
  995. // Set session variable with amount of time to delay before using replica.
  996. $_SESSION['ignore_replica_server'] = REQUEST_TIME + $duration;
  997. }
  998. }

Functions

Namesort descending Description
db_add_field Deprecated Adds a new field to a table.
db_add_index Deprecated Adds an index.
db_add_primary_key Deprecated Adds a primary key to a database table.
db_add_unique_key Deprecated Adds a unique key.
db_and Deprecated Returns a new DatabaseCondition, set to "AND" all conditions together.
db_change_field Deprecated Changes a field definition.
db_close Deprecated Closes the active database connection.
db_condition Deprecated Returns a new DatabaseCondition, set to the specified conjunction.
db_create_table Deprecated Creates a new table from a Drupal table definition.
db_delete Deprecated Returns a new DeleteQuery object for the active database.
db_driver Deprecated Retrieves the name of the currently active database driver.
db_drop_field Deprecated Drops a field.
db_drop_index Deprecated Drops an index.
db_drop_primary_key Deprecated Drops the primary key of a database table.
db_drop_table Deprecated Drops a table.
db_drop_unique_key Deprecated Drops a unique key.
db_escape_field Deprecated Restricts a dynamic column or constraint name to safe characters.
db_escape_table Deprecated Restricts a dynamic table name to safe characters.
db_field_exists Deprecated Checks if a column exists in the given table.
db_field_names Deprecated Returns an array of field names from an array of key/index column specifiers.
db_field_set_default Deprecated Sets the default value for a field.
db_field_set_no_default Deprecated Sets a field to have no default value.
db_find_tables Deprecated Finds all tables that are like the specified base table name.
db_ignore_replica Sets a session variable specifying the lag time for ignoring a replica server (A replica server is traditionally referred to as a "slave" in database server documentation).
db_index_exists Deprecated Checks if an index exists in the given table.
db_insert Deprecated Returns a new InsertQuery object for the active database.
db_like Deprecated Escapes characters that work as wildcard characters in a LIKE pattern.
db_merge Deprecated Returns a new MergeQuery object for the active database.
db_next_id Deprecated Retrieves a unique id.
db_or Deprecated Returns a new DatabaseCondition, set to "OR" all conditions together.
db_query Deprecated Executes an arbitrary query string against the active database.
db_query_range Deprecated Executes a query against the active database, restricted to a range.
db_query_temporary Deprecated Executes a SELECT query string and saves the result set to a temporary table.
db_rename_table Deprecated Renames a table.
db_select Deprecated Returns a new SelectQuery object for the active database.
db_set_active Deprecated Sets a new active database.
db_table_exists Deprecated Checks if a table exists.
db_transaction Deprecated Returns a new transaction object for the active database.
db_truncate Deprecated Returns a new TruncateQuery object for the active database.
db_update Deprecated Returns a new UpdateQuery object for the active database.
db_xor Deprecated Returns a new DatabaseCondition, set to "XOR" all conditions together.