1. class
  2. Drupal
  3. \
  4. Core
  5. \
  6. Database
  7. \
  8. Schema

Schema

abstract class Schema implements PlaceholderInterface (View source)

Provides a base implementation for Database Schema.

Properties

protected Connection $connection

The database connection.
protected int $placeholder

The placeholder counter.
protected string $defaultSchema

Definition of prefixInfo array structure.
protected string $uniqueIdentifier

A unique identifier for this query object.

Methods

__construct($connection)

No description

__clone()

Implements the magic __clone function.

uniqueIdentifier()

Returns a unique identifier for this object.

The
nextPlaceholder()

Returns the next placeholder ID for the query.

array
getPrefixInfo(string $table = 'default', bool $add_prefix = TRUE)

Get information about the table name and schema from the prefix.

prefixNonTable($table)

Create names for indexes, primary keys and constraints.

Condition
buildTableNameCondition($table_name, $operator = '=', $add_prefix = TRUE)

Build a condition to match a table name against a standard information_schema.

true
tableExists($table)

Check if a table exists.

array
findTables(string $table_expression)

Finds all tables that are like the specified base table name.

true
fieldExists(string $table, string $column)

Check if a column exists in the given table.

array
getFieldTypeMap()

Returns a mapping of Drupal schema field names to DB-native field types.

renameTable($table, $new_name)

Rename a table.

true
dropTable($table)

Drop a table.

addField($table, $field, $spec, $keys_new = [])

Add a new field to a table.

true
dropField($table, $field)

Drop a field.

true
indexExists($table, $name)

Checks if an index exists in the given table.

addPrimaryKey($table, $fields)

Add a primary key.

true
dropPrimaryKey($table)

Drop the primary key.

string[]|false
findPrimaryKeyColumns(string $table)

Finds the primary key columns of a table, from the database.

addUniqueKey($table, $name, $fields)

Add a unique key.

true
dropUniqueKey($table, $name)

Drop a unique key.

addIndex($table, $name, $fields, array $spec)

Add an index.

true
dropIndex($table, $name)

Drop an index.

array
introspectIndexSchema(string $table)

Finds the columns for the primary key, unique keys and indexes of a table.

changeField($table, $field, $field_new, $spec, $keys_new = [])

Change a field definition.

createTable($name, $table)

Create a new table from a Drupal table definition.

An
fieldNames($fields)

Return an array of field names from an array of key/index column specifiers.

The
prepareComment($comment, $length = NULL)

Prepare a table or column comment for database query.

string|int|float
escapeDefaultValue(mixed $value)

Return an escaped version of its parameter to be used as a default value on a column.

ensureNotNullPrimaryKey(array $primary_key, array $fields)

Ensures that all the primary key fields are correctly defined.

Details

at line 46
__construct($connection)

No description

Parameters

$connection

at line 54
__clone()

Implements the magic __clone function.

at line 61
uniqueIdentifier()

Returns a unique identifier for this object.

at line 68
The nextPlaceholder()

Returns the next placeholder ID for the query.

Return Value

The

next available placeholder ID as an integer.

at line 84
protected array getPrefixInfo(string $table = 'default', bool $add_prefix = TRUE)

Get information about the table name and schema from the prefix.

Parameters

string $table

Name of table to look prefix up for. Defaults to 'default' because that's default key for prefix.
bool $add_prefix

Boolean that indicates whether the given table name should be prefixed.

Return Value

array

A keyed array with information about the schema, table name and prefix.

at line 113
prefixNonTable($table)

Create names for indexes, primary keys and constraints.

This prevents using } around non-table names like indexes and keys.

Parameters

$table

at line 146
protected Condition buildTableNameCondition($table_name, $operator = '=', $add_prefix = TRUE)

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 it. This makes information_schema a useful tool to use across the drupal 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 to make all the others work. For example see core/includes/databases/mysql/schema.inc.

Parameters

$table_name

The name of the table in question.
$operator

The operator to apply on the 'table' part of the condition.
$add_prefix

Boolean to indicate whether the table name needs to be prefixed.

Return Value

Condition

A Condition object.

at line 168
true tableExists($table)

Check if a table exists.

Parameters

$table

The name of the table in drupal (no prefixing).

Return Value

true

if the given table exists, otherwise FALSE.

at line 188
array findTables(string $table_expression)

Finds all tables that are like the specified base table name.

Parameters

string $table_expression

An SQL expression, for example "cache_%" (without the quotes).

Return Value

array

Both the keys and the values are the matching tables.

at line 249
true fieldExists(string $table, string $column)

Check if a column exists in the given table.

Parameters

string $table

The name of the table in drupal (no prefixing).
string $column

The name of the column.

Return Value

true

if the given column exists, otherwise FALSE.

at line 271
abstract array getFieldTypeMap()

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 Value

array

An array of Schema API field types to driver-specific field types.

at line 286
abstract renameTable($table, $new_name)

Rename a table.

Parameters

$table

The table to be renamed.
$new_name

The new name for the table.

Exceptions

SchemaObjectDoesNotExistException
SchemaObjectExistsException

at line 298
abstract true dropTable($table)

Drop a table.

Parameters

$table

The table to be dropped.

Return Value

true

if the table was successfully dropped, FALSE if there was no table by that name to begin with.

at line 328
abstract addField($table, $field, $spec, $keys_new = [])

Add a new field to a table.

Parameters

$table

Name of the table to be altered.
$field

Name of the field to be added.
$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. Alternatively, the 'initial_form_field' key may be used, which will auto-populate the new field with values from the specified field.
$keys_new

(optional) Keys and indexes specification to be created on the table along with adding the field. The format is the same as a table specification but without the 'fields' element. If you are adding a type 'serial' field, you MUST specify at least one key or index including it in this array. See ::changeField() for more explanation why.

Exceptions

SchemaObjectDoesNotExistException
SchemaObjectExistsException

at line 342
abstract true dropField($table, $field)

Drop a field.

Parameters

$table

The table to be altered.
$field

The field to be dropped.

Return Value

true

if the field was successfully dropped, FALSE if there was no field by that name to begin with.

at line 355
abstract true indexExists($table, $name)

Checks if an index exists in the given table.

Parameters

$table

The name of the table in drupal (no prefixing).
$name

The name of the index in drupal (no prefixing).

Return Value

true

if the given index exists, otherwise FALSE.

at line 370
abstract addPrimaryKey($table, $fields)

Add a primary key.

Parameters

$table

The table to be altered.
$fields

Fields for the primary key.

Exceptions

SchemaObjectDoesNotExistException
SchemaObjectExistsException

at line 382
abstract true dropPrimaryKey($table)

Drop the primary key.

Parameters

$table

The table to be altered.

Return Value

true

if the primary key was successfully dropped, FALSE if there was no primary key on this table to begin with.

at line 397
protected string[]|false findPrimaryKeyColumns(string $table)

Finds the primary key columns of a table, from the database.

Parameters

string $table

The name of the table.

Return Value

string[]|false

A simple array with the names of the columns composing the table's primary key, or FALSE if the table does not exist.

Exceptions

RuntimeException

at line 419
abstract addUniqueKey($table, $name, $fields)

Add a unique key.

Parameters

$table

The table to be altered.
$name

The name of the key.
$fields

An array of field names.

Exceptions

SchemaObjectDoesNotExistException
SchemaObjectExistsException

at line 433
abstract true dropUniqueKey($table, $name)

Drop a unique key.

Parameters

$table

The table to be altered.
$name

The name of the key.

Return Value

true

if the key was successfully dropped, FALSE if there was no key by that name to begin with.

at line 495
abstract addIndex($table, $name, $fields, array $spec)

Add an index.

remove the $spec argument whenever schema introspection is added.

Parameters

$table

The table to be altered.
$name

The name of the index.
$fields

An array of field names or field information; if field information is passed, it's an array whose first element is the field name and whose second is the maximum length in the index. For example, the following will use the full length of the foo field, but limit the bar field to 4 characters: @code $fields = ['foo', ['bar', 4]]; @endcode
array $spec

The table specification for the table to be altered. This is used in order to be able to ensure that the index length is not too long. This schema definition can usually be obtained through hook_schema(), or in case the table was created by the Entity API, through the schema handler listed in the entity class definition. For reference, see SqlContentEntityStorageSchema::getDedicatedTableSchema() and SqlContentEntityStorageSchema::getSharedTableFieldSchema().

In order to prevent human error, it is recommended to pass in the complete table specification. However, in the edge case of the complete table specification not being available, we can pass in a partial table definition containing only the fields that apply to the index: @code $spec = [ // Example partial specification for a table: 'fields' => [ 'example_field' => [ 'description' => 'An example field', 'type' => 'varchar', 'length' => 32, 'not null' => TRUE, 'default' => '', ], ], 'indexes' => [ 'table_example_field' => ['example_field'], ], ]; @endcode Note that the above is a partial table definition and that we would usually pass a complete table definition as obtained through hook_schema() instead.

Exceptions

SchemaObjectDoesNotExistException
SchemaObjectExistsException

See also

schemaapi
hook_schema()

at line 509
abstract true dropIndex($table, $name)

Drop an index.

Parameters

$table

The table to be altered.
$name

The name of the index.

Return Value

true

if the index was successfully dropped, FALSE if there was no index by that name to begin with.

at line 526
protected array introspectIndexSchema(string $table)

Finds the columns for the primary key, unique keys and indexes of a table.

Parameters

string $table

The name of the table.

Return Value

array

A schema array with the following keys: 'primary key', 'unique keys' and 'indexes', and values as arrays of database columns.

Exceptions

SchemaObjectDoesNotExistException
RuntimeException

at line 599
abstract changeField($table, $field, $field_new, $spec, $keys_new = [])

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 Schema::dropPrimaryKey(), Schema::dropUniqueKey(), or Schema::dropIndex() before calling ::changeField(). To recreate the keys and indices, pass the key definitions as the optional $keys_new argument directly to ::changeField().

For example, suppose you have:

Parameters

$table

Name of the table.
$field

Name of the field to change.
$field_new

New name for the field (set to the same as $field if you don't want to change the name).
$spec

The field specification for the new field.
$keys_new

(optional) Keys and indexes specification to be created on the table along with changing the field. The format is the same as a table specification but without the 'fields' element.

Exceptions

SchemaObjectDoesNotExistException
SchemaObjectExistsException

at line 612
createTable($name, $table)

Create a new table from a Drupal table definition.

Parameters

$name

The name of the table to create.
$table

A Schema API table definition array.

Exceptions

SchemaObjectExistsException

at line 634
An fieldNames($fields)

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.

Parameters

$fields

An array of key/index column specifiers.

Return Value

An

array of field names.

at line 658
The prepareComment($comment, $length = NULL)

Prepare a table or column comment for database query.

Parameters

$comment

The comment string to prepare.
$length

Optional upper limit on the returned string length.

Return Value

The

prepared comment.

at line 674
protected string|int|float escapeDefaultValue(mixed $value)

Return an escaped version of its parameter to be used as a default value on a column.

Parameters

mixed $value

The value to be escaped (int, float, null or string).

Return Value

string|int|float

The escaped value.

at line 694
protected ensureNotNullPrimaryKey(array $primary_key, array $fields)

Ensures that all the primary key fields are correctly defined.

Parameters

array $primary_key

An array containing the fields that will form the primary key of a table.
array $fields

An array containing the field specifications of the table, as per the schema data structure format.

Exceptions

SchemaException