Schema.php 27 KB
Newer Older
1 2 3 4
<?php

/**
 * @file
Crell's avatar
Crell committed
5
 * Definition of Drupal\Core\Database\Schema
6 7
 */

8
namespace Drupal\Core\Database;
9

10 11 12
use Drupal\Core\Database\SchemaObjectExistsException;
use Drupal\Core\Database\Query\Condition;
use Drupal\Core\Database\Query\PlaceholderInterface;
13

14 15 16
/**
 * @defgroup schemaapi Schema API
 * @{
17
 * API to handle database schemas.
18 19 20 21 22 23 24 25 26 27 28 29 30 31 32
 *
 * A Drupal schema definition is an array structure representing one or
 * more tables and their related keys and indexes. A schema is defined by
 * hook_schema(), which usually lives in a modulename.install file.
 *
 * By implementing hook_schema() and specifying the tables your module
 * declares, you can easily create and drop these tables on all
 * supported database engines. You don't have to deal with the
 * different SQL dialects for table creation and alteration of the
 * supported database engines.
 *
 * hook_schema() should return an array with a key for each table that
 * the module defines.
 *
 * The following keys are defined:
33 34
 *   - 'description': A string in non-markup plain text describing this table
 *     and its purpose. References to other tables should be enclosed in
35
 *     curly-brackets. For example, the node_field_revision table
36 37 38
 *     description field might contain "Stores per-revision title and
 *     body data for each {node}."
 *   - 'fields': An associative array ('fieldname' => specification)
39 40
 *     that describes the table's database columns. The specification
 *     is also an array. The following specification parameters are defined:
41 42
 *     - 'description': A string in non-markup plain text describing this field
 *       and its purpose. References to other tables should be enclosed in
43
 *       curly-brackets. For example, the node table vid field
44
 *       description might contain "Always holds the largest (most
45
 *       recent) {node_field_revision}.vid value for this nid."
46
 *     - 'type': The generic datatype: 'char', 'varchar', 'text', 'blob', 'int',
47 48 49 50 51 52 53 54 55 56
 *       'float', 'numeric', or 'serial'. Most types just map to the according
 *       database engine specific datatypes. Use 'serial' for auto incrementing
 *       fields. This will expand to 'INT auto_increment' on MySQL.
 *     - 'mysql_type', 'pgsql_type', 'sqlite_type', etc.: If you need to
 *       use a record type not included in the officially supported list
 *       of types above, you can specify a type for each database
 *       backend. In this case, you can leave out the type parameter,
 *       but be advised that your schema will fail to load on backends that
 *       do not have a type specified. A possible solution can be to
 *       use the "text" type as a fallback.
57 58
 *     - 'serialize': A boolean indicating whether the field will be stored as
 *       a serialized string.
59
 *     - 'size': The data size: 'tiny', 'small', 'medium', 'normal',
60
 *       'big'. This is a hint about the largest value the field will
61 62 63 64 65
 *       store and determines which of the database engine specific
 *       datatypes will be used (e.g. on MySQL, TINYINT vs. INT vs. BIGINT).
 *       'normal', the default, selects the base type (e.g. on MySQL,
 *       INT, VARCHAR, BLOB, etc.).
 *       Not all sizes are available for all data types. See
66
 *       DatabaseSchema::getFieldTypeMap() for possible combinations.
67
 *     - 'not null': If true, no NULL values will be allowed in this
68 69 70
 *       database column. Defaults to false.
 *     - 'default': The field's default value. The PHP type of the
 *       value matters: '', '0', and 0 are all different. If you
71 72 73
 *       specify '0' as the default value for a type 'int' field it
 *       will not work because '0' is a string containing the
 *       character "zero", not an integer.
74
 *     - 'length': The maximal length of a type 'char', 'varchar' or 'text'
75
 *       field. Ignored for other field types.
76
 *     - 'unsigned': A boolean indicating whether a type 'int', 'float'
77 78
 *       and 'numeric' only is signed or unsigned. Defaults to
 *       FALSE. Ignored for other field types.
79 80
 *     - 'precision', 'scale': For type 'numeric' fields, indicates
 *       the precision (total number of significant digits) and scale
81 82
 *       (decimal digits right of the decimal point). Both values are
 *       mandatory. Ignored for other field types.
83 84 85 86
 *     - 'binary': A boolean indicating that MySQL should force 'char',
 *       'varchar' or 'text' fields to use case-sensitive binary collation.
 *       This has no effect on other database types for which case sensitivity
 *       is already the default behavior.
87
 *     All parameters apart from 'type' are optional except that type
88 89
 *     'numeric' columns must specify 'precision' and 'scale', and type
 *     'varchar' must specify the 'length' parameter.
90 91
 *  - 'primary key': An array of one or more key column specifiers (see below)
 *    that form the primary key.
92
 *  - 'unique keys': An associative array of unique keys ('keyname' =>
93
 *    specification). Each specification is an array of one or more
94
 *    key column specifiers (see below) that form a unique key on the table.
95 96 97 98 99
 *  - 'foreign keys': An associative array of relations ('my_relation' =>
 *    specification). Each specification is an array containing the name of
 *    the referenced table ('table'), and an array of column mappings
 *    ('columns'). Column mappings are defined by key pairs ('source_column' =>
 *    'referenced_column').
100
 *  - 'indexes':  An associative array of indexes ('indexname' =>
101
 *    specification). Each specification is an array of one or more
102 103 104 105 106 107 108 109
 *    key column specifiers (see below) that form an index on the
 *    table.
 *
 * A key column specifier is either a string naming a column or an
 * array of two elements, column name and length, specifying a prefix
 * of the named column.
 *
 * As an example, here is a SUBSET of the schema definition for
110
 * Drupal's 'node' table. It show four fields (nid, vid, type, and
111 112 113 114 115 116 117
 * title), the primary key on field 'nid', a unique key named 'vid' on
 * field 'vid', and two indexes, one named 'nid' on field 'nid' and
 * one named 'node_title_type' on the field 'title' and the first four
 * bytes of the field 'type':
 *
 * @code
 * $schema['node'] = array(
118
 *   'description' => 'The base table for nodes.',
119
 *   'fields' => array(
120 121 122 123 124 125 126 127 128 129 130 131 132 133
 *     'nid'       => array('type' => 'serial', 'unsigned' => TRUE, 'not null' => TRUE),
 *     'vid'       => array('type' => 'int', 'unsigned' => TRUE, 'not null' => TRUE,'default' => 0),
 *     'type'      => array('type' => 'varchar','length' => 32,'not null' => TRUE, 'default' => ''),
 *     'language'  => array('type' => 'varchar','length' => 12,'not null' => TRUE,'default' => ''),
 *     'title'     => array('type' => 'varchar','length' => 255,'not null' => TRUE, 'default' => ''),
 *     'uid'       => array('type' => 'int', 'not null' => TRUE, 'default' => 0),
 *     'status'    => array('type' => 'int', 'not null' => TRUE, 'default' => 1),
 *     'created'   => array('type' => 'int', 'not null' => TRUE, 'default' => 0),
 *     'changed'   => array('type' => 'int', 'not null' => TRUE, 'default' => 0),
 *     'comment'   => array('type' => 'int', 'not null' => TRUE, 'default' => 0),
 *     'promote'   => array('type' => 'int', 'not null' => TRUE, 'default' => 0),
 *     'moderate'  => array('type' => 'int', 'not null' => TRUE,'default' => 0),
 *     'sticky'    => array('type' => 'int', 'not null' => TRUE, 'default' => 0),
 *     'translate' => array('type' => 'int', 'not null' => TRUE, 'default' => 0),
134 135
 *   ),
 *   'indexes' => array(
136 137 138 139 140
 *     'node_changed'        => array('changed'),
 *     'node_created'        => array('created'),
 *     'node_moderate'       => array('moderate'),
 *     'node_frontpage'      => array('promote', 'status', 'sticky', 'created'),
 *     'node_status_type'    => array('status', 'type', 'nid'),
141
 *     'node_title_type'     => array('title', array('type', 4)),
142 143 144
 *     'node_type'           => array(array('type', 4)),
 *     'uid'                 => array('uid'),
 *     'translate'           => array('translate'),
145
 *   ),
146 147 148 149
 *   'unique keys' => array(
 *     'vid' => array('vid'),
 *   ),
 *   'foreign keys' => array(
150
 *     'node_revision' => array(
151
 *       'table' => 'node_field_revision',
152 153 154 155 156 157
 *       'columns' => array('vid' => 'vid'),
 *      ),
 *     'node_author' => array(
 *       'table' => 'users',
 *       'columns' => array('uid' => 'uid'),
 *      ),
158 159
 *    ),
 *   'primary key' => array('nid'),
160 161 162 163 164 165
 * );
 * @endcode
 *
 * @see drupal_install_schema()
 */

166
abstract class Schema implements PlaceholderInterface {
167

168
  protected $connection;
169

170 171 172 173 174
  /**
   * The placeholder counter.
   */
  protected $placeholder = 0;

175 176 177 178 179 180 181 182 183 184
  /**
   * Definition of prefixInfo array structure.
   *
   * Rather than redefining DatabaseSchema::getPrefixInfo() for each driver,
   * by defining the defaultSchema variable only MySQL has to re-write the
   * method.
   *
   * @see DatabaseSchema::getPrefixInfo()
   */
  protected $defaultSchema = 'public';
185

186 187 188 189 190
  /**
   * A unique identifier for this query object.
   */
  protected $uniqueIdentifier;

191
  public function __construct($connection) {
192
    $this->uniqueIdentifier = uniqid('', TRUE);
193 194
    $this->connection = $connection;
  }
195

196 197 198 199 200 201 202 203
  /**
   * Implements the magic __clone function.
   */
  public function __clone() {
    $this->uniqueIdentifier = uniqid('', TRUE);
  }

  /**
204
   * Implements PlaceHolderInterface::uniqueIdentifier().
205 206 207 208 209 210
   */
  public function uniqueIdentifier() {
    return $this->uniqueIdentifier;
  }

  /**
211
   * Implements PlaceHolderInterface::nextPlaceholder().
212
   */
213 214 215 216
  public function nextPlaceholder() {
    return $this->placeholder++;
  }

217
  /**
218
   * Get information about the table name and schema from the prefix.
219 220
   *
   * @param
221
   *   Name of table to look prefix up for. Defaults to 'default' because that's
222
   *   default key for prefix.
223 224 225
   * @param $add_prefix
   *   Boolean that indicates whether the given table name should be prefixed.
   *
226 227 228
   * @return
   *   A keyed array with information about the schema, table name and prefix.
   */
229
  protected function getPrefixInfo($table = 'default', $add_prefix = TRUE) {
230 231 232 233
    $info = array(
      'schema' => $this->defaultSchema,
      'prefix' => $this->connection->tablePrefix($table),
    );
234 235 236
    if ($add_prefix) {
      $table = $info['prefix'] . $table;
    }
237 238 239 240
    // If the prefix contains a period in it, then that means the prefix also
    // contains a schema reference in which case we will change the schema key
    // to the value before the period in the prefix. Everything after the dot
    // will be prefixed onto the front of the table.
241
    if (($pos = strpos($table, '.')) !== FALSE) {
242
      // Grab everything before the period.
243 244 245
      $info['schema'] = substr($table, 0, $pos);
      // Grab everything after the dot.
      $info['table'] = substr($table, ++$pos);
246 247
    }
    else {
248
      $info['table'] = $table;
249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264
    }
    return $info;
  }

  /**
   * Create names for indexes, primary keys and constraints.
   *
   * This prevents using {} around non-table names like indexes and keys.
   */
  function prefixNonTable($table) {
    $args = func_get_args();
    $info = $this->getPrefixInfo($table);
    $args[0] = $info['table'];
    return implode('_', $args);
  }

265 266 267 268 269
  /**
   * Build a condition to match a table name against a standard information_schema.
   *
   * The information_schema is a SQL standard that provides information about the
   * database server and the databases, schemas, tables, columns and users within
Dries's avatar
Dries committed
270
   * it. This makes information_schema a useful tool to use across the drupal
271 272 273 274 275 276 277
   * database drivers and is used by a few different functions. The function below
   * describes the conditions to be meet when querying information_schema.tables
   * for drupal tables or information associated with drupal tables. Even though
   * this is the standard method, not all databases follow standards and so this
   * method should be overwritten by a database driver if the database provider
   * uses alternate methods. Because information_schema.tables is used in a few
   * different functions, a database driver will only need to override this function
278 279
   * to make all the others work. For example see
   * core/includes/databases/mysql/schema.inc.
280 281
   *
   * @param $table_name
282
   *   The name of the table in question.
283 284
   * @param $operator
   *   The operator to apply on the 'table' part of the condition.
285 286
   * @param $add_prefix
   *   Boolean to indicate whether the table name needs to be prefixed.
287
   *
288 289
   * @return \Drupal\Core\Database\Query\Condition
   *   A Condition object.
290
   */
291
  protected function buildTableNameCondition($table_name, $operator = '=', $add_prefix = TRUE) {
292
    $info = $this->connection->getConnectionOptions();
293

294
    // Retrieve the table name and schema
295
    $table_info = $this->getPrefixInfo($table_name, $add_prefix);
296

297
    $condition = new Condition('AND');
298
    $condition->condition('table_catalog', $info['database']);
299 300
    $condition->condition('table_schema', $table_info['schema']);
    $condition->condition('table_name', $table_info['table'], $operator);
301 302 303
    return $condition;
  }

304 305
  /**
   * Check if a table exists.
Dries's avatar
Dries committed
306
   *
307 308
   * @param $table
   *   The name of the table in drupal (no prefixing).
309
   *
310
   * @return
311
   *   TRUE if the given table exists, otherwise FALSE.
312
   */
313
  public function tableExists($table) {
314
    $condition = $this->buildTableNameCondition($table);
315
    $condition->compile($this->connection, $this);
316
    // Normally, we would heartily discourage the use of string
317
    // concatenation for conditionals like this however, we
318 319
    // couldn't use db_select() here because it would prefix
    // information_schema.tables and the query would fail.
320
    // Don't use {} around information_schema.tables table.
321
    return (bool) $this->connection->query("SELECT 1 FROM information_schema.tables WHERE " . (string) $condition, $condition->arguments())->fetchField();
322 323 324 325 326 327 328 329
  }

  /**
   * Find all tables that are like the specified base table name.
   *
   * @param $table_expression
   *   An SQL expression, for example "simpletest%" (without the quotes).
   *   BEWARE: this is not prefixed, the caller should take care of that.
330
   *
331 332 333 334
   * @return
   *   Array, both the keys and the values are the matching tables.
   */
  public function findTables($table_expression) {
335 336
    $condition = $this->buildTableNameCondition($table_expression, 'LIKE', FALSE);

337
    $condition->compile($this->connection, $this);
338
    // Normally, we would heartily discourage the use of string
339
    // concatenation for conditionals like this however, we
340 341
    // couldn't use db_select() here because it would prefix
    // information_schema.tables and the query would fail.
342
    // Don't use {} around information_schema.tables table.
343
    return $this->connection->query("SELECT table_name FROM information_schema.tables WHERE " . (string) $condition, $condition->arguments())->fetchAllKeyed(0, 0);
344
  }
345

346 347
  /**
   * Check if a column exists in the given table.
348 349 350 351 352
   *
   * @param $table
   *   The name of the table in drupal (no prefixing).
   * @param $name
   *   The name of the column.
353
   *
354 355
   * @return
   *   TRUE if the given column exists, otherwise FALSE.
356
   */
357
  public function fieldExists($table, $column) {
358
    $condition = $this->buildTableNameCondition($table);
359
    $condition->condition('column_name', $column);
360
    $condition->compile($this->connection, $this);
361
    // Normally, we would heartily discourage the use of string
362
    // concatenation for conditionals like this however, we
363 364
    // couldn't use db_select() here because it would prefix
    // information_schema.tables and the query would fail.
365
    // Don't use {} around information_schema.columns table.
366
    return (bool) $this->connection->query("SELECT 1 FROM information_schema.columns WHERE " . (string) $condition, $condition->arguments())->fetchField();
367
  }
368

369
  /**
370 371 372 373 374 375 376 377 378
   * Returns a mapping of Drupal schema field names to DB-native field types.
   *
   * Because different field types do not map 1:1 between databases, Drupal has
   * its own normalized field type names. This function returns a driver-specific
   * mapping table from Drupal names to the native names for each database.
   *
   * @return array
   *   An array of Schema API field types to driver-specific field types.
   */
379
  abstract public function getFieldTypeMap();
380

381 382 383 384 385 386 387
  /**
   * Rename a table.
   *
   * @param $table
   *   The table to be renamed.
   * @param $new_name
   *   The new name for the table.
388
   *
389
   * @throws \Drupal\Core\Database\SchemaObjectDoesNotExistException
390
   *   If the specified table doesn't exist.
391
   * @throws \Drupal\Core\Database\SchemaObjectExistsException
392
   *   If a table with the specified new name already exists.
393
   */
394
  abstract public function renameTable($table, $new_name);
395 396 397 398 399 400

  /**
   * Drop a table.
   *
   * @param $table
   *   The table to be dropped.
401
   *
402 403 404
   * @return
   *   TRUE if the table was successfully dropped, FALSE if there was no table
   *   by that name to begin with.
405
   */
406
  abstract public function dropTable($table);
407

408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425
  /**
   * Copies the table schema.
   *
   * @param string $source
   *   The name of the table to be used as source.
   * @param string $destination
   *   The name of the table to be used as destination.
   *
   * @return \Drupal\Core\Database\StatementInterface
   *   The result of the executed query.
   *
   * @throws \Drupal\Core\Database\SchemaObjectExistsException
   *   Thrown when the source table does not exist.
   * @throws \Drupal\Core\Database\SchemaObjectDoesNotExistException
   *   Thrown when the destination table already exists.
   */
  abstract public function copyTable($source, $destination);

426 427 428 429 430 431 432 433 434 435 436 437 438 439
  /**
   * Add a new field to a table.
   *
   * @param $table
   *   Name of the table to be altered.
   * @param $field
   *   Name of the field to be added.
   * @param $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
440
   *   (optional) Keys and indexes specification to be created on the
441
   *   table along with adding the field. The format is the same as a
442
   *   table specification but without the 'fields' element. If you are
443
   *   adding a type 'serial' field, you MUST specify at least one key
444
   *   or index including it in this array. See db_change_field() for more
445
   *   explanation why.
446
   *
447
   * @throws \Drupal\Core\Database\SchemaObjectDoesNotExistException
448
   *   If the specified table doesn't exist.
449
   * @throws \Drupal\Core\Database\SchemaObjectExistsException
450
   *   If the specified table already has a field by that name.
451
   */
452
  abstract public function addField($table, $field, $spec, $keys_new = array());
453 454 455 456 457 458 459 460

  /**
   * Drop a field.
   *
   * @param $table
   *   The table to be altered.
   * @param $field
   *   The field to be dropped.
461
   *
462 463 464
   * @return
   *   TRUE if the field was successfully dropped, FALSE if there was no field
   *   by that name to begin with.
465
   */
466
  abstract public function dropField($table, $field);
467 468 469 470 471 472 473 474 475 476

  /**
   * Set the default value for a field.
   *
   * @param $table
   *   The table to be altered.
   * @param $field
   *   The field to be altered.
   * @param $default
   *   Default value to be set. NULL for 'default NULL'.
477
   *
478
   * @throws \Drupal\Core\Database\SchemaObjectDoesNotExistException
479
   *   If the specified table or field doesn't exist.
480
   */
481
  abstract public function fieldSetDefault($table, $field, $default);
482 483 484 485 486 487 488 489

  /**
   * Set a field to have no default value.
   *
   * @param $table
   *   The table to be altered.
   * @param $field
   *   The field to be altered.
490
   *
491
   * @throws \Drupal\Core\Database\SchemaObjectDoesNotExistException
492
   *   If the specified table or field doesn't exist.
493
   */
494
  abstract public function fieldSetNoDefault($table, $field);
495

496
  /**
497
   * Checks if an index exists in the given table.
498 499
   *
   * @param $table
500
   *   The name of the table in drupal (no prefixing).
501
   * @param $name
502
   *   The name of the index in drupal (no prefixing).
503
   *
504
   * @return
505
   *   TRUE if the given index exists, otherwise FALSE.
506 507 508
   */
  abstract public function indexExists($table, $name);

509 510 511 512 513 514 515
  /**
   * Add a primary key.
   *
   * @param $table
   *   The table to be altered.
   * @param $fields
   *   Fields for the primary key.
516
   *
517
   * @throws \Drupal\Core\Database\SchemaObjectDoesNotExistException
518
   *   If the specified table doesn't exist.
519
   * @throws \Drupal\Core\Database\SchemaObjectExistsException
520
   *   If the specified table already has a primary key.
521
   */
522
  abstract public function addPrimaryKey($table, $fields);
523 524 525 526 527 528

  /**
   * Drop the primary key.
   *
   * @param $table
   *   The table to be altered.
529
   *
530 531 532
   * @return
   *   TRUE if the primary key was successfully dropped, FALSE if there was no
   *   primary key on this table to begin with.
533
   */
534
  abstract public function dropPrimaryKey($table);
535 536 537 538 539 540 541 542 543 544

  /**
   * Add a unique key.
   *
   * @param $table
   *   The table to be altered.
   * @param $name
   *   The name of the key.
   * @param $fields
   *   An array of field names.
545
   *
546
   * @throws \Drupal\Core\Database\SchemaObjectDoesNotExistException
547
   *   If the specified table doesn't exist.
548
   * @throws \Drupal\Core\Database\SchemaObjectExistsException
549
   *   If the specified table already has a key by that name.
550
   */
551
  abstract public function addUniqueKey($table, $name, $fields);
552 553 554 555 556 557 558 559

  /**
   * Drop a unique key.
   *
   * @param $table
   *   The table to be altered.
   * @param $name
   *   The name of the key.
560
   *
561 562 563
   * @return
   *   TRUE if the key was successfully dropped, FALSE if there was no key by
   *   that name to begin with.
564
   */
565
  abstract public function dropUniqueKey($table, $name);
566 567 568 569 570 571 572 573 574 575

  /**
   * Add an index.
   *
   * @param $table
   *   The table to be altered.
   * @param $name
   *   The name of the index.
   * @param $fields
   *   An array of field names.
576
   *
577
   * @throws \Drupal\Core\Database\SchemaObjectDoesNotExistException
578
   *   If the specified table doesn't exist.
579
   * @throws \Drupal\Core\Database\SchemaObjectExistsException
580
   *   If the specified table already has an index by that name.
581
   */
582
  abstract public function addIndex($table, $name, $fields);
583 584 585 586 587 588 589 590

  /**
   * Drop an index.
   *
   * @param $table
   *   The table to be altered.
   * @param $name
   *   The name of the index.
591
   *
592 593 594
   * @return
   *   TRUE if the index was successfully dropped, FALSE if there was no index
   *   by that name to begin with.
595
   */
596
  abstract public function dropIndex($table, $name);
597 598 599 600 601 602 603 604 605 606 607 608 609 610 611 612 613 614 615 616 617 618

  /**
   * Change a field definition.
   *
   * IMPORTANT NOTE: To maintain database portability, you have to explicitly
   * recreate all indices and primary keys that are using the changed field.
   *
   * That means that you have to drop all affected keys and indexes with
   * db_drop_{primary_key,unique_key,index}() before calling db_change_field().
   * To recreate the keys and indices, pass the key definitions as the
   * optional $keys_new argument directly to db_change_field().
   *
   * For example, suppose you have:
   * @code
   * $schema['foo'] = array(
   *   'fields' => array(
   *     'bar' => array('type' => 'int', 'not null' => TRUE)
   *   ),
   *   'primary key' => array('bar')
   * );
   * @endcode
   * and you want to change foo.bar to be type serial, leaving it as the
619
   * primary key. The correct sequence is:
620
   * @code
621 622
   * db_drop_primary_key('foo');
   * db_change_field('foo', 'bar', 'bar',
623 624 625 626 627 628 629 630 631 632 633
   *   array('type' => 'serial', 'not null' => TRUE),
   *   array('primary key' => array('bar')));
   * @endcode
   *
   * The reasons for this are due to the different database engines:
   *
   * On PostgreSQL, changing a field definition involves adding a new field
   * and dropping an old one which* causes any indices, primary keys and
   * sequences (from serial-type fields) that use the changed field to be dropped.
   *
   * On MySQL, all type 'serial' fields must be part of at least one key
634
   * or index as soon as they are created. You cannot use
635 636
   * db_add_{primary_key,unique_key,index}() for this purpose because
   * the ALTER TABLE command will fail to add the column without a key
637
   * or index specification. The solution is to use the optional
638 639 640 641 642 643 644 645 646 647 648 649 650 651 652 653
   * $keys_new argument to create the key or index at the same time as
   * field.
   *
   * You could use db_add_{primary_key,unique_key,index}() in all cases
   * unless you are converting a field to be type serial. You can use
   * the $keys_new argument in all cases.
   *
   * @param $table
   *   Name of the table.
   * @param $field
   *   Name of the field to change.
   * @param $field_new
   *   New name for the field (set to the same as $field if you don't want to change the name).
   * @param $spec
   *   The field specification for the new field.
   * @param $keys_new
654
   *   (optional) Keys and indexes specification to be created on the
655 656
   *   table along with changing the field. The format is the same as a
   *   table specification but without the 'fields' element.
657
   *
658
   * @throws \Drupal\Core\Database\SchemaObjectDoesNotExistException
659
   *   If the specified table or source field doesn't exist.
660
   * @throws \Drupal\Core\Database\SchemaObjectExistsException
661
   *   If the specified destination field already exists.
662
   */
663
  abstract public function changeField($table, $field, $field_new, $spec, $keys_new = array());
664 665 666 667 668 669 670 671

  /**
   * Create a new table from a Drupal table definition.
   *
   * @param $name
   *   The name of the table to create.
   * @param $table
   *   A Schema API table definition array.
672
   *
673
   * @throws \Drupal\Core\Database\SchemaObjectExistsException
674
   *   If the specified table already exists.
675
   */
676
  public function createTable($name, $table) {
677
    if ($this->tableExists($name)) {
678
      throw new SchemaObjectExistsException(t('Table @name already exists.', array('@name' => $name)));
679
    }
680
    $statements = $this->createTableSql($name, $table);
681
    foreach ($statements as $statement) {
682
      $this->connection->query($statement);
683 684
    }
  }
685

686 687 688 689 690 691 692 693
  /**
   * Return an array of field names from an array of key/index column specifiers.
   *
   * This is usually an identity function but if a key/index uses a column prefix
   * specification, this function extracts just the name.
   *
   * @param $fields
   *   An array of key/index column specifiers.
694
   *
695 696 697 698
   * @return
   *   An array of field names.
   */
  public function fieldNames($fields) {
699
    $return = array();
700 701
    foreach ($fields as $field) {
      if (is_array($field)) {
702
        $return[] = $field[0];
703 704
      }
      else {
705
        $return[] = $field;
706 707
      }
    }
708
    return $return;
709
  }
710 711 712

  /**
   * Prepare a table or column comment for database query.
713
   *
714 715 716 717
   * @param $comment
   *   The comment string to prepare.
   * @param $length
   *   Optional upper limit on the returned string length.
718
   *
719 720 721 722 723 724
   * @return
   *   The prepared comment.
   */
  public function prepareComment($comment, $length = NULL) {
    return $this->connection->quote($comment);
  }
725 726 727 728 729 730 731 732 733 734 735 736 737 738 739 740 741

  /**
   * Return an escaped version of its parameter to be used as a default value
   * on a column.
   *
   * @param mixed $value
   *   The value to be escaped (int, float, null or string).
   *
   * @return string|int|float
   *   The escaped value.
   */
  protected function escapeDefaultValue($value) {
    if (is_null($value)) {
      return 'NULL';
    }
    return is_string($value) ? $this->connection->quote($value) : $value;
  }
742
}