# ColumnSchemaBuilder

> ColumnSchemaBuilder helps to define database schema types using a PHP interface.

[API reference](/docs/api/index.md) › [yii](/docs/api/yii/index.md) › [db](/docs/api/yii/db/index.md) › ColumnSchemaBuilder

| class | `yii\db\ColumnSchemaBuilder` |
| --- | --- |
| Extends | [`yii\base\BaseObject`](/docs/api/yii/base/baseobject/index.md) |
| Implements | [`Stringable`](https://www.php.net/manual/en/class.stringable.php), [`yii\base\Configurable`](/docs/api/yii/base/configurable/index.md) |
| Since | 2.0.6 |
| Source | [`framework/db/ColumnSchemaBuilder.php`](https://github.com/yiisoft/yii2/blob/22.0/framework/db/ColumnSchemaBuilder.php#L27) |

4 subclasses:

- [`yii\db\mssql\ColumnSchemaBuilder`](/docs/api/yii/db/mssql/columnschemabuilder/index.md)
- [`yii\db\mysql\ColumnSchemaBuilder`](/docs/api/yii/db/mysql/columnschemabuilder/index.md)
- [`yii\db\oci\ColumnSchemaBuilder`](/docs/api/yii/db/oci/columnschemabuilder/index.md)
- [`yii\db\sqlite\ColumnSchemaBuilder`](/docs/api/yii/db/sqlite/columnschemabuilder/index.md)

ColumnSchemaBuilder helps to define database schema types using a PHP interface.

See [`SchemaBuilderTrait`](/docs/api/yii/db/schemabuildertrait/index.md) for more detailed description and usage examples.

## Properties

| Property | Type | Description | Defined by |
| --- | --- | --- | --- |
| <span id="property-categoryMap"></span>`$categoryMap` | `array` | Mapping of abstract column types (keys) to type categories (values). | `ColumnSchemaBuilder` |
| <span id="property-comment"></span>`$comment` | `string` | Comment value of the column. Default: `null`. Available since 2.0.8. | `ColumnSchemaBuilder` |
| [`$db`](#property-db) | [`Connection`](/docs/api/yii/db/connection/index.md) | The current database connection. Default: `null`. Available since 2.0.8. | `ColumnSchemaBuilder` |
| <span id="property-typeCategoryMap"></span>`$typeCategoryMap` static | `array` | Mapping of abstract column types (keys) to type categories (values). Default: `[\yii\db\Schema::TYPE_PK => self::CATEGORY_PK, \yii\db\Schema::TYPE_UPK => self::CATEGORY_PK, \yii\db\Schema::TYPE_BIGPK => self::CATEGORY_PK, \yii\db\Schema::TYPE_UBIGPK => self::CATEGORY_PK, \yii\db\Schema::TYPE_CHAR => self::CATEGORY_STRING, \yii\db\Schema::TYPE_STRING => self::CATEGORY_STRING, \yii\db\Schema::TYPE_TEXT => self::CATEGORY_STRING, \yii\db\Schema::TYPE_TINYINT => self::CATEGORY_NUMERIC, \yii\db\Schema::TYPE_SMALLINT => self::CATEGORY_NUMERIC, \yii\db\Schema::TYPE_INTEGER => self::CATEGORY_NUMERIC, \yii\db\Schema::TYPE_BIGINT => self::CATEGORY_NUMERIC, \yii\db\Schema::TYPE_FLOAT => self::CATEGORY_NUMERIC, \yii\db\Schema::TYPE_DOUBLE => self::CATEGORY_NUMERIC, \yii\db\Schema::TYPE_DECIMAL => self::CATEGORY_NUMERIC, \yii\db\Schema::TYPE_DATETIME => self::CATEGORY_TIME, \yii\db\Schema::TYPE_TIMESTAMP => self::CATEGORY_TIME, \yii\db\Schema::TYPE_TIME => self::CATEGORY_TIME, \yii\db\Schema::TYPE_DATE => self::CATEGORY_TIME, \yii\db\Schema::TYPE_BINARY => self::CATEGORY_OTHER, \yii\db\Schema::TYPE_BOOLEAN => self::CATEGORY_NUMERIC, \yii\db\Schema::TYPE_MONEY => self::CATEGORY_NUMERIC]`. Available since 2.0.43. | `ColumnSchemaBuilder` |
| <span id="property-typeDefinition"></span>`$typeDefinition` read-only | `string` | Abstract type plus optional length, for example `string(255)`. Available since 22.0. | `ColumnSchemaBuilder` |
| <span id="property-after"></span>`$after` protected | `string` | The column after which this column will be added. Default: `null`. Available since 2.0.8. | `ColumnSchemaBuilder` |
| <span id="property-append"></span>`$append` protected | `mixed` | SQL string to be appended to column schema definition. Default: `null`. Available since 2.0.9. | `ColumnSchemaBuilder` |
| <span id="property-check"></span>`$check` protected | `string` | The `CHECK` constraint for the column. Default: `null`. | `ColumnSchemaBuilder` |
| <span id="property-default"></span>`$default` protected | `mixed` | Default value of the column. Default: `null`. | `ColumnSchemaBuilder` |
| <span id="property-isFirst"></span>`$isFirst` protected | `bool` | Whether this column is to be inserted at the beginning of the table. Default: `null`. Available since 2.0.8. | `ColumnSchemaBuilder` |
| [`$isNotNull`](#property-isNotNull) protected | `bool\|null` | Whether the column is or not nullable. Default: `null`. | `ColumnSchemaBuilder` |
| [`$isUnique`](#property-isUnique) protected | `bool` | Whether the column values should be unique. Default: `false`. | `ColumnSchemaBuilder` |
| [`$isUnsigned`](#property-isUnsigned) protected | `bool` | Whether the column values should be unsigned. Default: `false`. Available since 2.0.7. | `ColumnSchemaBuilder` |
| [`$length`](#property-length) protected | `int\|string\|array` | Column size or precision definition. Default: `null`. | `ColumnSchemaBuilder` |
| <span id="property-type"></span>`$type` protected | `string` | The column type definition such as INTEGER, VARCHAR, DATETIME, etc. Default: `null`. | `ColumnSchemaBuilder` |

## Methods

| Method | Description | Defined by |
| --- | --- | --- |
| [`__construct()`](#method-__construct) | Create a column schema builder instance giving the type and value precision. | `ColumnSchemaBuilder` |
| <span id="method-__call"></span>[`__call()`](/docs/api/yii/base/baseobject/index.md#method-__call) | Calls the named method which is not a class method. | [`yii\base\BaseObject`](/docs/api/yii/base/baseobject/index.md) |
| <span id="method-__get"></span>[`__get()`](/docs/api/yii/base/baseobject/index.md#method-__get) | Returns the value of an object property. | [`yii\base\BaseObject`](/docs/api/yii/base/baseobject/index.md) |
| <span id="method-__isset"></span>[`__isset()`](/docs/api/yii/base/baseobject/index.md#method-__isset) | Checks if a property is set, i.e. defined and not null. | [`yii\base\BaseObject`](/docs/api/yii/base/baseobject/index.md) |
| <span id="method-__set"></span>[`__set()`](/docs/api/yii/base/baseobject/index.md#method-__set) | Sets value of an object property. | [`yii\base\BaseObject`](/docs/api/yii/base/baseobject/index.md) |
| [`__toString()`](#method-__toString) | Builds the full string for the column's schema. | `ColumnSchemaBuilder` |
| <span id="method-__unset"></span>[`__unset()`](/docs/api/yii/base/baseobject/index.md#method-__unset) | Sets an object property to null. | [`yii\base\BaseObject`](/docs/api/yii/base/baseobject/index.md) |
| [`after()`](#method-after) | Adds an `AFTER` constraint to the column. | `ColumnSchemaBuilder` |
| [`append()`](#method-append) | Specify additional SQL to be appended to column definition. | `ColumnSchemaBuilder` |
| <span id="method-canGetProperty"></span>[`canGetProperty()`](/docs/api/yii/base/baseobject/index.md#method-canGetProperty) | Returns a value indicating whether a property can be read. | [`yii\base\BaseObject`](/docs/api/yii/base/baseobject/index.md) |
| <span id="method-canSetProperty"></span>[`canSetProperty()`](/docs/api/yii/base/baseobject/index.md#method-canSetProperty) | Returns a value indicating whether a property can be set. | [`yii\base\BaseObject`](/docs/api/yii/base/baseobject/index.md) |
| [`check()`](#method-check) | Sets a `CHECK` constraint for the column. | `ColumnSchemaBuilder` |
| <span id="method-className"></span>[`className()`](/docs/api/yii/base/baseobject/index.md#method-className) static | Returns the fully qualified name of this class. | [`yii\base\BaseObject`](/docs/api/yii/base/baseobject/index.md) |
| [`comment()`](#method-comment) | Specifies the comment for column. | `ColumnSchemaBuilder` |
| [`defaultExpression()`](#method-defaultExpression) | Specify the default SQL expression for the column. | `ColumnSchemaBuilder` |
| [`defaultValue()`](#method-defaultValue) | Specify the default value for the column. | `ColumnSchemaBuilder` |
| [`first()`](#method-first) | Adds an `FIRST` constraint to the column. | `ColumnSchemaBuilder` |
| [`getAppend()`](#method-getAppend) | Returns the raw SQL fragment appended to the column definition. | `ColumnSchemaBuilder` |
| [`getCategoryMap()`](#method-getCategoryMap) |  | `ColumnSchemaBuilder` |
| [`getCheck()`](#method-getCheck) | Returns the raw `CHECK` constraint expression of the column. | `ColumnSchemaBuilder` |
| [`getDefault()`](#method-getDefault) | Returns the raw default value of the column. | `ColumnSchemaBuilder` |
| [`getTypeDefinition()`](#method-getTypeDefinition) | Returns the abstract type together with its length or precision, without any constraint keywords. | `ColumnSchemaBuilder` |
| <span id="method-hasMethod"></span>[`hasMethod()`](/docs/api/yii/base/baseobject/index.md#method-hasMethod) | Returns a value indicating whether a method is defined. | [`yii\base\BaseObject`](/docs/api/yii/base/baseobject/index.md) |
| <span id="method-hasProperty"></span>[`hasProperty()`](/docs/api/yii/base/baseobject/index.md#method-hasProperty) | Returns a value indicating whether a property is defined. | [`yii\base\BaseObject`](/docs/api/yii/base/baseobject/index.md) |
| <span id="method-init"></span>[`init()`](/docs/api/yii/base/baseobject/index.md#method-init) | Initializes the object. | [`yii\base\BaseObject`](/docs/api/yii/base/baseobject/index.md) |
| [`isNotNull()`](#method-isNotNull) | Returns the nullability state of the column as a tri-state value. | `ColumnSchemaBuilder` |
| [`isUnique()`](#method-isUnique) | Returns whether the column carries a `UNIQUE` constraint. | `ColumnSchemaBuilder` |
| [`notNull()`](#method-notNull) | Adds a `NOT NULL` constraint to the column. | `ColumnSchemaBuilder` |
| [`null()`](#method-null) | Adds a `NULL` constraint to the column. | `ColumnSchemaBuilder` |
| [`setCategoryMap()`](#method-setCategoryMap) |  | `ColumnSchemaBuilder` |
| [`unique()`](#method-unique) | Adds a `UNIQUE` constraint to the column. | `ColumnSchemaBuilder` |
| [`unsigned()`](#method-unsigned) | Marks column as unsigned. | `ColumnSchemaBuilder` |
| [`buildAfterString()`](#method-buildAfterString) protected | Builds the after constraint for the column. Defaults to unsupported. | `ColumnSchemaBuilder` |
| [`buildAppendString()`](#method-buildAppendString) protected | Builds the custom string that's appended to column definition. | `ColumnSchemaBuilder` |
| [`buildCheckString()`](#method-buildCheckString) protected | Builds the check constraint for the column. | `ColumnSchemaBuilder` |
| [`buildCommentString()`](#method-buildCommentString) protected | Builds the comment specification for the column. | `ColumnSchemaBuilder` |
| [`buildCompleteString()`](#method-buildCompleteString) protected | Returns the complete column definition from input format. | `ColumnSchemaBuilder` |
| [`buildDefaultString()`](#method-buildDefaultString) protected | Builds the default value specification for the column. | `ColumnSchemaBuilder` |
| [`buildDefaultValue()`](#method-buildDefaultValue) protected | Return the default value for the column. | `ColumnSchemaBuilder` |
| [`buildFirstString()`](#method-buildFirstString) protected | Builds the first constraint for the column. Defaults to unsupported. | `ColumnSchemaBuilder` |
| [`buildLengthString()`](#method-buildLengthString) protected | Builds the length/precision part of the column. | `ColumnSchemaBuilder` |
| [`buildNotNullString()`](#method-buildNotNullString) protected | Builds the not null constraint for the column. | `ColumnSchemaBuilder` |
| [`buildUniqueString()`](#method-buildUniqueString) protected | Builds the unique constraint for the column. | `ColumnSchemaBuilder` |
| [`buildUnsignedString()`](#method-buildUnsignedString) protected | Builds the unsigned string for column. Defaults to unsupported. | `ColumnSchemaBuilder` |
| [`getTypeCategory()`](#method-getTypeCategory) protected | Returns the category of the column type. | `ColumnSchemaBuilder` |

## Constants

| Constant | Value | Description | Defined by |
| --- | --- | --- | --- |
| <span id="const-CATEGORY_PK"></span>`CATEGORY_PK` | `'pk'` |  | `ColumnSchemaBuilder` |
| <span id="const-CATEGORY_STRING"></span>`CATEGORY_STRING` | `'string'` |  | `ColumnSchemaBuilder` |
| <span id="const-CATEGORY_NUMERIC"></span>`CATEGORY_NUMERIC` | `'numeric'` |  | `ColumnSchemaBuilder` |
| <span id="const-CATEGORY_TIME"></span>`CATEGORY_TIME` | `'time'` |  | `ColumnSchemaBuilder` |
| <span id="const-CATEGORY_OTHER"></span>`CATEGORY_OTHER` | `'other'` |  | `ColumnSchemaBuilder` |

## Property details

### $db <span id="property-db"></span>

```php
public yii\db\Connection $db = null
```

The current database connection.

It is used mainly to escape strings
safely when building the final column schema string.

**Since**

2.0.8

### $isNotNull <span id="property-isNotNull"></span>

```php
protected bool|null $isNotNull = null
```

Whether the column is or not nullable.

If this is `true`, a `NOT NULL` constraint will be added.
If this is `false`, a `NULL` constraint will be added.

### $isUnique <span id="property-isUnique"></span>

```php
protected bool $isUnique = false
```

Whether the column values should be unique.

If this is `true`, a `UNIQUE` constraint will be added.

### $isUnsigned <span id="property-isUnsigned"></span>

```php
protected bool $isUnsigned = false
```

Whether the column values should be unsigned.

If this is `true`, an `UNSIGNED` keyword will be added.

**Since**

2.0.7

### $length <span id="property-length"></span>

```php
protected int|string|array $length = null
```

Column size or precision definition.

This is what goes into the parenthesis after
the column type. This can be either a string, an integer or an array. If it is an array, the array values will
be joined into a string separated by comma.

## Method details

### __construct() <span id="method-__construct"></span>

```php
public function __construct(string $type, int|string|array|null $length = null, yii\db\Connection|null $db = null, array $config = [])
```

Create a column schema builder instance giving the type and value precision.

**Parameters**

| Parameter | Type | Description |
| --- | --- | --- |
| `$type` | `string` | Type of the column. See [`$type`](/docs/api/yii/db/columnschemabuilder/index.md#property-type). |
| `$length` | `int\|string\|array\|null` | Length or precision of the column. See [`$length`](/docs/api/yii/db/columnschemabuilder/index.md#property-length). |
| `$db` | [`Connection`](/docs/api/yii/db/connection/index.md)`\|null` | The current database connection. See [`$db`](/docs/api/yii/db/columnschemabuilder/index.md#property-db). |
| `$config` | `array` | Name-value pairs that will be used to initialize the object properties |

### __toString() <span id="method-__toString"></span>

```php
public function __toString(): string
```

Builds the full string for the column's schema.

**Returns**

`string`

### after() <span id="method-after"></span>

```php
public function after(string $after): $this
```

Adds an `AFTER` constraint to the column.

Note: MySQL and Oracle support only.

**Parameters**

| Parameter | Type | Description |
| --- | --- | --- |
| `$after` | `string` | The column after which $this column will be added. |

**Returns**

`$this`

**Since**

2.0.8

### append() <span id="method-append"></span>

```php
public function append(string $sql): $this
```

Specify additional SQL to be appended to column definition.

Position modifiers will be appended after column definition in databases that support them.

**Parameters**

| Parameter | Type | Description |
| --- | --- | --- |
| `$sql` | `string` | The SQL string to be appended. |

**Returns**

`$this`

**Since**

2.0.9

### check() <span id="method-check"></span>

```php
public function check(string $check): $this
```

Sets a `CHECK` constraint for the column.

**Parameters**

| Parameter | Type | Description |
| --- | --- | --- |
| `$check` | `string` | The SQL of the `CHECK` constraint to be added. |

**Returns**

`$this`

### comment() <span id="method-comment"></span>

```php
public function comment(string $comment): $this
```

Specifies the comment for column.

**Parameters**

| Parameter | Type | Description |
| --- | --- | --- |
| `$comment` | `string` | The comment |

**Returns**

`$this`

**Since**

2.0.8

### defaultExpression() <span id="method-defaultExpression"></span>

```php
public function defaultExpression(string $default): $this
```

Specify the default SQL expression for the column.

**Parameters**

| Parameter | Type | Description |
| --- | --- | --- |
| `$default` | `string` | The default value expression. |

**Returns**

`$this`

**Since**

2.0.7

### defaultValue() <span id="method-defaultValue"></span>

```php
public function defaultValue(mixed $default): $this
```

Specify the default value for the column.

**Parameters**

| Parameter | Type | Description |
| --- | --- | --- |
| `$default` | `mixed` | The default value. |

**Returns**

`$this`

### first() <span id="method-first"></span>

```php
public function first(): $this
```

Adds an `FIRST` constraint to the column.

Note: MySQL and Oracle support only.

**Returns**

`$this`

**Since**

2.0.8

### getAppend() <span id="method-getAppend"></span>

```php
public function getAppend(): string|null
```

Returns the raw SQL fragment appended to the column definition.

**Returns**

`string|null`: Appended SQL fragment, or `null` when none is set.

**Since**

22.0

### getCategoryMap() <span id="method-getCategoryMap"></span>

```php
public function getCategoryMap(): array
```

**Returns**

`array`: Mapping of abstract column types (keys) to type categories (values).

**Since**

2.0.43

### getCheck() <span id="method-getCheck"></span>

```php
public function getCheck(): string|null
```

Returns the raw `CHECK` constraint expression of the column.

**Returns**

`string|null`: `CHECK` expression, or `null` when no constraint is set.

**Since**

22.0

### getDefault() <span id="method-getDefault"></span>

```php
public function getDefault(): mixed
```

Returns the raw default value of the column.

**Returns**

`mixed`: Scalar value, an [`Expression`](/docs/api/yii/db/expression/index.md) when [`defaultExpression()`](/docs/api/yii/db/columnschemabuilder/index.md#method-defaultExpression) was used, or `null` when unset.

**Since**

22.0

### getTypeDefinition() <span id="method-getTypeDefinition"></span>

```php
public function getTypeDefinition(): string
```

Returns the abstract type together with its length or precision, without any constraint keywords.

The result is intended for [`QueryBuilder::getColumnType()`](/docs/api/yii/db/querybuilder/index.md#method-getColumnType) to resolve the physical column type.

**Returns**

`string`: Abstract type plus optional length, for example `string(255)`.

**Since**

22.0

### isNotNull() <span id="method-isNotNull"></span>

```php
public function isNotNull(): bool|null
```

Returns the nullability state of the column as a tri-state value.

**Returns**

`bool|null`: `true` for `NOT NULL`, `false` for `NULL`, or `null` when the nullability is unspecified.

**Since**

22.0

### isUnique() <span id="method-isUnique"></span>

```php
public function isUnique(): bool
```

Returns whether the column carries a `UNIQUE` constraint.

**Returns**

`bool`: `true` when a `UNIQUE` constraint is set; `false` otherwise.

**Since**

22.0

### notNull() <span id="method-notNull"></span>

```php
public function notNull(): $this
```

Adds a `NOT NULL` constraint to the column.

**Returns**

`$this`

### null() <span id="method-null"></span>

```php
public function null(): $this
```

Adds a `NULL` constraint to the column.

**Returns**

`$this`

**Since**

2.0.9

### setCategoryMap() <span id="method-setCategoryMap"></span>

```php
public function setCategoryMap(array $categoryMap): mixed
```

**Parameters**

| Parameter | Type | Description |
| --- | --- | --- |
| `$categoryMap` | `array` | Mapping of abstract column types (keys) to type categories (values). |

**Returns**

`mixed`

**Since**

2.0.43

### unique() <span id="method-unique"></span>

```php
public function unique(): $this
```

Adds a `UNIQUE` constraint to the column.

**Returns**

`$this`

### unsigned() <span id="method-unsigned"></span>

```php
public function unsigned(): $this
```

Marks column as unsigned.

**Returns**

`$this`

**Since**

2.0.7

### buildAfterString() <span id="method-buildAfterString"></span>

```php
protected function buildAfterString(): string
```

Builds the after constraint for the column. Defaults to unsupported.

**Returns**

`string`: A string containing the AFTER constraint.

**Since**

2.0.8

### buildAppendString() <span id="method-buildAppendString"></span>

```php
protected function buildAppendString(): string
```

Builds the custom string that's appended to column definition.

**Returns**

`string`: Custom string to append.

**Since**

2.0.9

### buildCheckString() <span id="method-buildCheckString"></span>

```php
protected function buildCheckString(): string
```

Builds the check constraint for the column.

**Returns**

`string`: A string containing the CHECK constraint.

### buildCommentString() <span id="method-buildCommentString"></span>

```php
protected function buildCommentString(): string
```

Builds the comment specification for the column.

**Returns**

`string`: A string containing the COMMENT keyword and the comment itself

**Since**

2.0.8

### buildCompleteString() <span id="method-buildCompleteString"></span>

```php
protected function buildCompleteString(string $format): string
```

Returns the complete column definition from input format.

**Parameters**

| Parameter | Type | Description |
| --- | --- | --- |
| `$format` | `string` | The format of the definition. |

**Returns**

`string`: A string containing the complete column definition.

**Since**

2.0.8

### buildDefaultString() <span id="method-buildDefaultString"></span>

```php
protected function buildDefaultString(): string
```

Builds the default value specification for the column.

**Returns**

`string`: String with default value of column.

### buildDefaultValue() <span id="method-buildDefaultValue"></span>

```php
protected function buildDefaultValue(): string|null
```

Return the default value for the column.

**Returns**

`string|null`: String with default value of column.

### buildFirstString() <span id="method-buildFirstString"></span>

```php
protected function buildFirstString(): string
```

Builds the first constraint for the column. Defaults to unsupported.

**Returns**

`string`: A string containing the FIRST constraint.

**Since**

2.0.8

### buildLengthString() <span id="method-buildLengthString"></span>

```php
protected function buildLengthString(): string
```

Builds the length/precision part of the column.

**Returns**

`string`

### buildNotNullString() <span id="method-buildNotNullString"></span>

```php
protected function buildNotNullString(): string
```

Builds the not null constraint for the column.

**Returns**

`string`: Returns 'NOT NULL' if [`isNotNull()`](/docs/api/yii/db/columnschemabuilder/index.md#method-isNotNull) is true, 'NULL' if [`isNotNull()`](/docs/api/yii/db/columnschemabuilder/index.md#method-isNotNull) is false or an empty string otherwise.

### buildUniqueString() <span id="method-buildUniqueString"></span>

```php
protected function buildUniqueString(): string
```

Builds the unique constraint for the column.

**Returns**

`string`: Returns string 'UNIQUE' if [`isUnique()`](/docs/api/yii/db/columnschemabuilder/index.md#method-isUnique) is true, otherwise it returns an empty string.

### buildUnsignedString() <span id="method-buildUnsignedString"></span>

```php
protected function buildUnsignedString(): string
```

Builds the unsigned string for column. Defaults to unsupported.

**Returns**

`string`: A string containing UNSIGNED keyword.

**Since**

2.0.7

### getTypeCategory() <span id="method-getTypeCategory"></span>

```php
protected function getTypeCategory(): string
```

Returns the category of the column type.

**Returns**

`string`: A string containing the column type category name.

**Since**

2.0.8