database.inc

  1. 7.x drupal/includes/database/database.inc
  2. 7.x drupal/includes/database/pgsql/database.inc
  3. 7.x drupal/includes/database/sqlite/database.inc
  4. 7.x drupal/includes/database/mysql/database.inc
  5. 5.x drupal/includes/database.inc
  6. 6.x drupal/includes/database.inc
  7. 8.x drupal/core/includes/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.

Functions

Namesort descending Description
db_add_field Adds a new field to a table.
db_add_index Adds an index.
db_add_primary_key Adds a primary key to a database table.
db_add_unique_key Adds a unique key.
db_and Returns a new DatabaseCondition, set to "AND" all conditions together.
db_change_field Changes a field definition.
db_close Closes the active database connection.
db_condition Returns a new DatabaseCondition, set to the specified conjunction.
db_copy_table_schema Copies the structure of a table.
db_create_table Creates a new table from a Drupal table definition.
db_delete Returns a new DeleteQuery object for the active database.
db_driver Retrieves the name of the currently active database driver.
db_drop_field Drops a field.
db_drop_index Drops an index.
db_drop_primary_key Drops the primary key of a database table.
db_drop_table Drops a table.
db_drop_unique_key Drops a unique key.
db_escape_field Restricts a dynamic column or constraint name to safe characters.
db_escape_table Restricts a dynamic table name to safe characters.
db_field_exists Checks if a column exists in the given table.
db_field_names Returns an array of field names from an array of key/index column specifiers.
db_field_set_default Sets the default value for a field.
db_field_set_no_default Sets a field to have no default value.
db_find_tables 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 Checks if an index exists in the given table.
db_insert Returns a new InsertQuery object for the active database.
db_like Escapes characters that work as wildcard characters in a LIKE pattern.
db_merge Returns a new MergeQuery object for the active database.
db_next_id Retrieves a unique id.
db_or Returns a new DatabaseCondition, set to "OR" all conditions together.
db_query Executes an arbitrary query string against the active database.
db_query_range Executes a query against the active database, restricted to a range.
db_query_temporary Executes a SELECT query string and saves the result set to a temporary table.
db_rename_table Renames a table.
db_select Returns a new SelectQuery object for the active database.
db_set_active Sets a new active database.
db_table_exists Checks if a table exists.
db_transaction Returns a new transaction object for the active database.
db_truncate Returns a new TruncateQuery object for the active database.
db_update Returns a new UpdateQuery object for the active database.
db_xor Returns a new DatabaseCondition, set to "XOR" all conditions together.
_db_create_keys_sql

File

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