diff --git a/_includes/sidebar-data-v19.2.json b/_includes/sidebar-data-v19.2.json index d6739bca660..3d1f3a5998c 100644 --- a/_includes/sidebar-data-v19.2.json +++ b/_includes/sidebar-data-v19.2.json @@ -871,12 +871,6 @@ "/${VERSION}/alter-table.html" ] }, - { - "title": "ALTER TYPE", - "urls": [ - "/${VERSION}/alter-type.html" - ] - }, { "title": "ALTER USER", "urls": [ diff --git a/_includes/sidebar-data-v20.1.json b/_includes/sidebar-data-v20.1.json index c62b4fb9151..d8243ac0656 100644 --- a/_includes/sidebar-data-v20.1.json +++ b/_includes/sidebar-data-v20.1.json @@ -954,12 +954,6 @@ "/${VERSION}/alter-table.html" ] }, - { - "title": "ALTER TYPE", - "urls": [ - "/${VERSION}/alter-type.html" - ] - }, { "title": "ALTER USER", "urls": [ diff --git a/_includes/sidebar-data-v20.2.json b/_includes/sidebar-data-v20.2.json index 82237e7f872..a6f59d54f7e 100644 --- a/_includes/sidebar-data-v20.2.json +++ b/_includes/sidebar-data-v20.2.json @@ -987,12 +987,6 @@ "/${VERSION}/alter-table.html" ] }, - { - "title": "ALTER TYPE", - "urls": [ - "/${VERSION}/alter-type.html" - ] - }, { "title": "ALTER USER", "urls": [ diff --git a/_includes/v19.2/sql/diagrams/alter_column.html b/_includes/v19.2/sql/diagrams/alter_column.html index 538c7895cd9..2a211a311b3 100644 --- a/_includes/v19.2/sql/diagrams/alter_column.html +++ b/_includes/v19.2/sql/diagrams/alter_column.html @@ -1,90 +1,80 @@ -
- - - - -ALTER - - -TABLE - - -IF - - -EXISTS - - -table_name - -ALTER - - -COLUMN - - -column_name - -SET - - -DEFAULT - - -a_expr - -NOT - - -NULL - - -DATA - - -TYPE - - -typename - -COLLATE - - -collation_name - -USING - - -a_expr - -DROP - - -DEFAULT - - -NOT - - -NULL - - -STORED - - -TYPE - - -typename - -COLLATE - - -collation_name - -USING - - -a_expr - -
+
+ + + + +ALTER + + +TABLE + + +IF + + +EXISTS + + +table_name + +ALTER + + +COLUMN + + +column_name + +SET + + +DEFAULT + + +a_expr + +NOT + + +NULL + + +DATA + + +TYPE + + +typename + +COLLATE + + +collation_name + +DROP + + +DEFAULT + + +NOT + + +NULL + + +STORED + + +TYPE + + +typename + +COLLATE + + +collation_name + +
diff --git a/_includes/v19.2/sql/diagrams/alter_type.html b/_includes/v19.2/sql/diagrams/alter_type.html deleted file mode 100644 index ace962f3b99..00000000000 --- a/_includes/v19.2/sql/diagrams/alter_type.html +++ /dev/null @@ -1,45 +0,0 @@ -
- - - - -ALTER - - -TABLE - - -IF - - -EXISTS - - -table_name - - -ALTER - - -COLUMN - - -column_name - - -SET - - -DATA - - -TYPE - - - -typename - - - - -
diff --git a/_includes/v20.1/sql/diagrams/alter_column.html b/_includes/v20.1/sql/diagrams/alter_column.html index 538c7895cd9..2a211a311b3 100644 --- a/_includes/v20.1/sql/diagrams/alter_column.html +++ b/_includes/v20.1/sql/diagrams/alter_column.html @@ -1,90 +1,80 @@ -
- - - - -ALTER - - -TABLE - - -IF - - -EXISTS - - -table_name - -ALTER - - -COLUMN - - -column_name - -SET - - -DEFAULT - - -a_expr - -NOT - - -NULL - - -DATA - - -TYPE - - -typename - -COLLATE - - -collation_name - -USING - - -a_expr - -DROP - - -DEFAULT - - -NOT - - -NULL - - -STORED - - -TYPE - - -typename - -COLLATE - - -collation_name - -USING - - -a_expr - -
+
+ + + + +ALTER + + +TABLE + + +IF + + +EXISTS + + +table_name + +ALTER + + +COLUMN + + +column_name + +SET + + +DEFAULT + + +a_expr + +NOT + + +NULL + + +DATA + + +TYPE + + +typename + +COLLATE + + +collation_name + +DROP + + +DEFAULT + + +NOT + + +NULL + + +STORED + + +TYPE + + +typename + +COLLATE + + +collation_name + +
diff --git a/_includes/v20.1/sql/diagrams/alter_type.html b/_includes/v20.1/sql/diagrams/alter_type.html deleted file mode 100644 index ace962f3b99..00000000000 --- a/_includes/v20.1/sql/diagrams/alter_type.html +++ /dev/null @@ -1,45 +0,0 @@ -
- - - - -ALTER - - -TABLE - - -IF - - -EXISTS - - -table_name - - -ALTER - - -COLUMN - - -column_name - - -SET - - -DATA - - -TYPE - - - -typename - - - - -
diff --git a/_includes/v20.2/sql/diagrams/alter_type.html b/_includes/v20.2/sql/diagrams/alter_type.html deleted file mode 100644 index ace962f3b99..00000000000 --- a/_includes/v20.2/sql/diagrams/alter_type.html +++ /dev/null @@ -1,45 +0,0 @@ -
- - - - -ALTER - - -TABLE - - -IF - - -EXISTS - - -table_name - - -ALTER - - -COLUMN - - -column_name - - -SET - - -DATA - - -TYPE - - - -typename - - - - -
diff --git a/v19.2/alter-column.md b/v19.2/alter-column.md index fd99936dc5b..549cdf59f30 100644 --- a/v19.2/alter-column.md +++ b/v19.2/alter-column.md @@ -5,8 +5,10 @@ toc: true --- The `ALTER COLUMN` [statement](sql-statements.html) is part of `ALTER TABLE` and can be used to: + - Set, change, or drop a column's [`DEFAULT` constraint](default-value.html) - Set or drop a column's [`NOT NULL` constraint](not-null.html) +- Increase the precision of the column's [data type](data-types.html) {{site.data.alerts.callout_info}} To manage other constraints, see [`ADD CONSTRAINT`](add-constraint.html) and [`DROP CONSTRAINT`](drop-constraint.html). @@ -30,12 +32,30 @@ The user must have the `CREATE` [privilege](authorization.html#assign-privileges |-----------|-------------| | `table_name` | The name of the table with the column you want to modify. | | `column_name` | The name of the column you want to modify. | -| `a_expr` | The new [Default Value](default-value.html) you want to use. | +| `SET DEFAULT a_expr` | The new [Default Value](default-value.html) you want to use. | +| `typename` | The new, altered type you want to use.
In CockroachDB versions < v20.2, support for altering column types is limited to increasing the precision of the current column type. For details, see [Altering column types](#altering-column-types).| ## Viewing schema changes {% include {{ page.version.version }}/misc/schema-change-view-job.md %} +## Altering column types + +In CockroachDB versions < v20.2, support for altering column types is limited to increasing the precision of the current type of a column. You cannot convert the column type to another data type, or decrease the precision of the column type. Changing the column type from its current type to the same type and precision will result in a no-op, with no error. + +You can use `ALTER COLUMN TYPE` if the following conditions are met: + +- The on-disk representation of the column remains unchanged. For example, you cannot change the column data type from `STRING` to an `INT`. +- The existing data remains valid. For example, you can change the column data type from `STRING[10]` to `STRING[20]`, but not to `STRING [5]` since that will invalidate the existing data. + +The following are equivalent in CockroachDB: + +- `ALTER TABLE ... ALTER ... TYPE` +- `ALTER TABLE ... ALTER COLUMN TYPE` +- `ALTER TABLE ... ALTER COLUMN SET DATA TYPE` + +For an example of `ALTER COLUMN TYPE`, see [Increase a column type's precision](#increase-a-column-types-precision). + ## Examples ### Set or change a `DEFAULT` value @@ -80,6 +100,21 @@ If the column has the [`NOT NULL` constraint](not-null.html) applied to it, you {% include {{ page.version.version }}/computed-columns/convert-computed-column.md %} +### Increase a column type's precision + +The [TPC-C](performance-benchmarking-with-tpc-c-1k-warehouses.html) database contains a `customer` table with a column `c_credit_lim` of type [`DECIMAL(10,2)`](decimal.html). Suppose you want to increase the precision of the column's data type to `DECIMAL (12,2)`: + +{% include copy-clipboard.html %} +~~~ sql +> ALTER TABLE customer ALTER c_credit_lim type DECIMAL (12,2); +~~~ + +~~~ +ALTER TABLE + +Time: 80.814044ms +~~~ + ## See also - [Constraints](constraints.html) diff --git a/v19.2/alter-table.md b/v19.2/alter-table.md index 6fc918b1508..cf71dae3f89 100644 --- a/v19.2/alter-table.md +++ b/v19.2/alter-table.md @@ -19,7 +19,6 @@ Subcommand | Description | Can combine with other subcommands? [`ADD COLUMN`](add-column.html) | Add columns to tables. | Yes [`ADD CONSTRAINT`](add-constraint.html) | Add constraints to columns. | Yes [`ALTER COLUMN`](alter-column.html) | Change or drop a column's [`DEFAULT` constraint](default-value.html) or [`NOT NULL` constraint](not-null.html). | Yes -[`ALTER TYPE`](alter-type.html) | Change a column's [data type](data-types.html). | Yes [`CONFIGURE ZONE`](configure-zone.html) | [Configure replication zones](configure-replication-zones.html) for a table. | No [`DROP COLUMN`](drop-column.html) | Remove columns from tables. | Yes [`DROP CONSTRAINT`](drop-constraint.html) | Remove constraints from columns. | Yes diff --git a/v19.2/alter-type.md b/v19.2/alter-type.md deleted file mode 100644 index b8ddfbd7eef..00000000000 --- a/v19.2/alter-type.md +++ /dev/null @@ -1,85 +0,0 @@ ---- -title: ALTER TYPE -summary: Use the ALTER TYPE statement to change a column's data type. -toc: true ---- - -The `ALTER TYPE` [statement](sql-statements.html) is part of [`ALTER TABLE`](alter-table.html) and changes a column's [data type](data-types.html). - -{% include {{ page.version.version }}/sql/combine-alter-table-commands.md %} - -## Considerations - -You can use the `ALTER TYPE` subcommand if the following conditions are met: - -- On-disk representation of the column remains unchanged. For example, you cannot change the column data type from `STRING` to an `INT`, even if the string is just a number. -- The existing data remains valid. For example, you can change the column data type from `STRING[10]` to `STRING[20]`, but not to `STRING [5]` since that will invalidate the existing data. - -## Synopsis - -
-{% include {{ page.version.version }}/sql/diagrams/alter_type.html %} -
- -## Required privileges - -The user must have the `CREATE` [privilege](authorization.html#assign-privileges) on the table. - -## Parameters - -| Parameter | Description -|-----------|------------- -| `table_name` | The name of the table with the column whose data type you want to change. -| `column_name` | The name of the column whose data type you want to change. -| `typename` | The new [data type](data-types.html) you want to use. - -## Viewing schema changes - -{% include {{ page.version.version }}/misc/schema-change-view-job.md %} - -## Examples - -### Success scenario - -The [TPC-C](performance-benchmarking-with-tpc-c-1k-warehouses.html) database has a `customer` table with a column `c_credit_lim DECIMAL (10,2)`. Suppose you want to change the data type to `DECIMAL (12,2)`: - -{% include copy-clipboard.html %} -~~~ sql -> ALTER TABLE customer ALTER c_credit_lim type DECIMAL (12,2); -~~~ - -~~~ -ALTER TABLE - -Time: 80.814044ms -~~~ - -### Error scenarios - -Changing a column data type from `DECIMAL` to `INT` would change the on-disk representation of the column. Therefore, attempting to do so results in an error: - -{% include copy-clipboard.html %} -~~~ sql -> ALTER TABLE customer ALTER c_credit_lim type INT; -~~~ - -~~~ -pq: type conversion not yet implemented -~~~ - -Changing a column data type from `DECIMAL(12,2)` to `DECIMAL (8,2)` would invalidate the existing data. Therefore, attempting to do so results in an error: - -{% include copy-clipboard.html %} -~~~ sql -> ALTER TABLE customer ALTER c_credit_lim type DECIMAL (8,2); -~~~ - -~~~ -pq: type conversion not yet implemented -~~~ - -## See also - -- [`ALTER TABLE`](alter-table.html) -- [Other SQL Statements](sql-statements.html) -- [`SHOW JOBS`](show-jobs.html) diff --git a/v19.2/sql-statements.md b/v19.2/sql-statements.md index aae185e04e3..8fe13b4d7bf 100644 --- a/v19.2/sql-statements.md +++ b/v19.2/sql-statements.md @@ -40,7 +40,6 @@ Statement | Usage [`ALTER RANGE`](alter-range.html) | Configure the replication zone for a system range. [`ALTER SEQUENCE`](alter-sequence.html) | Apply a schema change to a sequence. [`ALTER TABLE`](alter-table.html) | Apply a schema change to a table. -[`ALTER TYPE`](alter-type.html) | Change a column's [data type](data-types.html). [`ALTER USER`](alter-user.html) | Add or change a user's password. [`ALTER VIEW`](alter-view.html) | Rename a view. [`COMMENT ON`](comment-on.html) | Associate a comment to a database, table, or column. diff --git a/v20.1/alter-column.md b/v20.1/alter-column.md index f44c1707ae9..262273b1d1c 100644 --- a/v20.1/alter-column.md +++ b/v20.1/alter-column.md @@ -5,8 +5,10 @@ toc: true --- The `ALTER COLUMN` [statement](sql-statements.html) is part of `ALTER TABLE` and can be used to: + - Set, change, or drop a column's [`DEFAULT` constraint](default-value.html) - Set or drop a column's [`NOT NULL` constraint](not-null.html) +- Increase the precision of the column's [data type](data-types.html) {{site.data.alerts.callout_info}} To manage other constraints, see [`ADD CONSTRAINT`](add-constraint.html) and [`DROP CONSTRAINT`](drop-constraint.html). @@ -30,12 +32,30 @@ The user must have the `CREATE` [privilege](authorization.html#assign-privileges |-----------|-------------| | `table_name` | The name of the table with the column you want to modify. | | `column_name` | The name of the column you want to modify. | -| `a_expr` | The new [Default Value](default-value.html) you want to use. | +| `SET DEFAULT a_expr` | The new [Default Value](default-value.html) you want to use. | +| `typename` | The new, altered type you want to use.
In CockroachDB versions < v20.2, support for altering column types is limited to increasing the precision of the current column type. For details, see [Altering column types](#altering-column-types).| ## Viewing schema changes {% include {{ page.version.version }}/misc/schema-change-view-job.md %} +## Altering column types + +In CockroachDB versions < v20.2, support for altering column types is limited to increasing the precision of the current type of a column. You cannot convert the column type to another data type, or decrease the precision of the column type. Changing the column type from its current type to the same type and precision will result in a no-op, with no error. + +You can use `ALTER COLUMN TYPE` if the following conditions are met: + +- The on-disk representation of the column remains unchanged. For example, you cannot change the column data type from `STRING` to an `INT`. +- The existing data remains valid. For example, you can change the column data type from `STRING[10]` to `STRING[20]`, but not to `STRING [5]` since that will invalidate the existing data. + +The following are equivalent in CockroachDB: + +- `ALTER TABLE ... ALTER ... TYPE` +- `ALTER TABLE ... ALTER COLUMN TYPE` +- `ALTER TABLE ... ALTER COLUMN SET DATA TYPE` + +For an example of `ALTER COLUMN TYPE`, see [Increase a column type's precision](#increase-a-column-types-precision). + ## Examples ### Set or change a `DEFAULT` value @@ -80,6 +100,21 @@ If the column has the [`NOT NULL` constraint](not-null.html) applied to it, you {% include {{ page.version.version }}/computed-columns/convert-computed-column.md %} +### Increase a column type's precision + +The [TPC-C](performance-benchmarking-with-tpc-c-1k-warehouses.html) database contains a `customer` table with a column `c_credit_lim` of type [`DECIMAL(10,2)`](decimal.html). Suppose you want to increase the precision of the column's data type to `DECIMAL (12,2)`: + +{% include copy-clipboard.html %} +~~~ sql +> ALTER TABLE customer ALTER c_credit_lim type DECIMAL (12,2); +~~~ + +~~~ +ALTER TABLE + +Time: 80.814044ms +~~~ + ## See also - [Constraints](constraints.html) diff --git a/v20.1/alter-table.md b/v20.1/alter-table.md index f144430355c..6f8ca435a7c 100644 --- a/v20.1/alter-table.md +++ b/v20.1/alter-table.md @@ -20,7 +20,6 @@ Subcommand | Description | Can combine with other subcommands? [`ADD CONSTRAINT`](add-constraint.html) | Add constraints to columns. | Yes [`ALTER COLUMN`](alter-column.html) | Change or drop a column's [`DEFAULT` constraint](default-value.html) or [`NOT NULL` constraint](not-null.html). | Yes [`ALTER PRIMARY KEY`](alter-primary-key.html) | New in v20.1: Change the [primary key](primary-key.html) of a table. | Yes -[`ALTER TYPE`](alter-type.html) | Change a column's [data type](data-types.html). | Yes [`CONFIGURE ZONE`](configure-zone.html) | [Configure replication zones](configure-replication-zones.html) for a table. | No [`DROP COLUMN`](drop-column.html) | Remove columns from tables. | Yes [`DROP CONSTRAINT`](drop-constraint.html) | Remove constraints from columns. | Yes diff --git a/v20.1/alter-type.md b/v20.1/alter-type.md deleted file mode 100644 index b8ddfbd7eef..00000000000 --- a/v20.1/alter-type.md +++ /dev/null @@ -1,85 +0,0 @@ ---- -title: ALTER TYPE -summary: Use the ALTER TYPE statement to change a column's data type. -toc: true ---- - -The `ALTER TYPE` [statement](sql-statements.html) is part of [`ALTER TABLE`](alter-table.html) and changes a column's [data type](data-types.html). - -{% include {{ page.version.version }}/sql/combine-alter-table-commands.md %} - -## Considerations - -You can use the `ALTER TYPE` subcommand if the following conditions are met: - -- On-disk representation of the column remains unchanged. For example, you cannot change the column data type from `STRING` to an `INT`, even if the string is just a number. -- The existing data remains valid. For example, you can change the column data type from `STRING[10]` to `STRING[20]`, but not to `STRING [5]` since that will invalidate the existing data. - -## Synopsis - -
-{% include {{ page.version.version }}/sql/diagrams/alter_type.html %} -
- -## Required privileges - -The user must have the `CREATE` [privilege](authorization.html#assign-privileges) on the table. - -## Parameters - -| Parameter | Description -|-----------|------------- -| `table_name` | The name of the table with the column whose data type you want to change. -| `column_name` | The name of the column whose data type you want to change. -| `typename` | The new [data type](data-types.html) you want to use. - -## Viewing schema changes - -{% include {{ page.version.version }}/misc/schema-change-view-job.md %} - -## Examples - -### Success scenario - -The [TPC-C](performance-benchmarking-with-tpc-c-1k-warehouses.html) database has a `customer` table with a column `c_credit_lim DECIMAL (10,2)`. Suppose you want to change the data type to `DECIMAL (12,2)`: - -{% include copy-clipboard.html %} -~~~ sql -> ALTER TABLE customer ALTER c_credit_lim type DECIMAL (12,2); -~~~ - -~~~ -ALTER TABLE - -Time: 80.814044ms -~~~ - -### Error scenarios - -Changing a column data type from `DECIMAL` to `INT` would change the on-disk representation of the column. Therefore, attempting to do so results in an error: - -{% include copy-clipboard.html %} -~~~ sql -> ALTER TABLE customer ALTER c_credit_lim type INT; -~~~ - -~~~ -pq: type conversion not yet implemented -~~~ - -Changing a column data type from `DECIMAL(12,2)` to `DECIMAL (8,2)` would invalidate the existing data. Therefore, attempting to do so results in an error: - -{% include copy-clipboard.html %} -~~~ sql -> ALTER TABLE customer ALTER c_credit_lim type DECIMAL (8,2); -~~~ - -~~~ -pq: type conversion not yet implemented -~~~ - -## See also - -- [`ALTER TABLE`](alter-table.html) -- [Other SQL Statements](sql-statements.html) -- [`SHOW JOBS`](show-jobs.html) diff --git a/v20.1/sql-statements.md b/v20.1/sql-statements.md index 566d9f1cbc4..7bbac911ad8 100644 --- a/v20.1/sql-statements.md +++ b/v20.1/sql-statements.md @@ -42,7 +42,6 @@ Statement | Usage [`ALTER RANGE`](alter-range.html) | Configure the replication zone for a system range. [`ALTER SEQUENCE`](alter-sequence.html) | Apply a schema change to a sequence. [`ALTER TABLE`](alter-table.html) | Apply a schema change to a table. -[`ALTER TYPE`](alter-type.html) | Change a column's [data type](data-types.html). [`ALTER USER`](alter-user.html) | add, change, or remove a user's password and to change the login privileges for a role. [`ALTER ROLE`](alter-role.html) | Add, change, or remove a [role's](create-role.html) password and to change the login privileges for a role. [`ALTER VIEW`](alter-view.html) | Rename a view. diff --git a/v20.2/alter-column.md b/v20.2/alter-column.md index f44c1707ae9..1054fa258ce 100644 --- a/v20.2/alter-column.md +++ b/v20.2/alter-column.md @@ -5,13 +5,19 @@ toc: true --- The `ALTER COLUMN` [statement](sql-statements.html) is part of `ALTER TABLE` and can be used to: + - Set, change, or drop a column's [`DEFAULT` constraint](default-value.html) - Set or drop a column's [`NOT NULL` constraint](not-null.html) +- New in v20.2: Change a column's [data type](data-types.html) {{site.data.alerts.callout_info}} To manage other constraints, see [`ADD CONSTRAINT`](add-constraint.html) and [`DROP CONSTRAINT`](drop-constraint.html). {{site.data.alerts.end}} +{{site.data.alerts.callout_info}} +Support for altering column types is [experimental](experimental-features.html) in CockroachDB versions v20.2, with certain limitations. For details, see [Altering column data types](#altering-column-data-types). +{{site.data.alerts.end}} + {% include {{ page.version.version }}/sql/combine-alter-table-commands.md %} ## Synopsis @@ -30,12 +36,40 @@ The user must have the `CREATE` [privilege](authorization.html#assign-privileges |-----------|-------------| | `table_name` | The name of the table with the column you want to modify. | | `column_name` | The name of the column you want to modify. | -| `a_expr` | The new [Default Value](default-value.html) you want to use. | +| `SET DEFAULT a_expr` | The new [Default Value](default-value.html) you want to use. | +| `typename` | The new [data type](data-types.html) you want to use.
New in v20.2: Support for altering column types is expanded in CockroachDB v20.2, but still [experimental](experimental-features.html), and with certain limitations. For details, see [Altering column data types](#altering-column-data-types). | +| `USING a_expr` | New in v20.2: Specifies how to compute a new column value from the old column value. | ## Viewing schema changes {% include {{ page.version.version }}/misc/schema-change-view-job.md %} +## Altering column data types + +New in v20.2: Support for altering column data types is [experimental](experimental-features.html) in CockroachDB versions v20.2, with [certain limitations](#limitations-on-altering-data-types). To enable column type altering, set the `enable_experimental_alter_column_type_general` [session variable](set-vars.html) to `true`. + +The following are equivalent in CockroachDB: + +- `ALTER TABLE ... ALTER ... TYPE` +- `ALTER TABLE ... ALTER COLUMN TYPE` +- `ALTER TABLE ... ALTER COLUMN SET DATA TYPE` + +For examples of `ALTER COLUMN TYPE`, [Examples](#convert-to-a-different-data-type). + +### Limitations on altering data types + +You can alter the data type of a column if: + +- The column is not part of an [index](indexes.html). +- The column does not have [`CHECK` constraints](check.html). +- The column does not own a [sequence](create-sequence.html). +- The `ALTER COLUMN TYPE` statement is not part of a [combined `ALTER TABLE` statement](alter-table.html#subcommands). +- The `ALTER COLUMN TYPE` statement is not inside an [explicit transaction](begin-transaction.html). + +{{site.data.alerts.callout_info}} +Most `ALTER COLUMN TYPE` changes are finalized asynchronously. Schema changes on the table with the altered column may be restricted, and writes to the altered column may be rejected until the schema change is finalized. +{{site.data.alerts.end}} + ## Examples ### Set or change a `DEFAULT` value @@ -80,6 +114,170 @@ If the column has the [`NOT NULL` constraint](not-null.html) applied to it, you {% include {{ page.version.version }}/computed-columns/convert-computed-column.md %} + +### Convert to a different data type + +The [TPC-C](performance-benchmarking-with-tpc-c-1k-warehouses.html) database has a `customer` table with a column `c_credit_lim` of type [`DECIMAL(10,2)`](decimal.html): + +{% include copy-clipboard.html %} +~~~ sql +> SELECT column_name, data_type FROM [SHOW COLUMNS FROM customer] WHERE column_name='c_credit_lim'; +~~~ + +~~~ + column_name | data_type +---------------+---------------- + c_credit_lim | DECIMAL(10,2) +(1 row) +~~~ + +Suppose you want to change the data type from `DECIMAL` to [`STRING`](string.html). + +First, set the `enable_experimental_alter_column_type_general` [session variable](set-vars.html) to `true`: + +{% include copy-clipboard.html %} +~~~ sql +> SET enable_experimental_alter_column_type_general = true; +~~~ + +Then, alter the column type: + +{% include copy-clipboard.html %} +~~~ sql +> ALTER TABLE customer ALTER c_credit_lim TYPE STRING; +~~~ + +~~~ +NOTICE: ALTER COLUMN TYPE changes are finalized asynchronously; further schema changes on this table may be restricted until the job completes; some writes to the altered column may be rejected until the schema change is finalized +~~~ + +{% include copy-clipboard.html %} +~~~ sql +> SELECT column_name, data_type FROM [SHOW COLUMNS FROM customer] WHERE column_name='c_credit_lim'; +~~~ + +~~~ + column_name | data_type +---------------+------------ + c_credit_lim | STRING +(1 row) +~~~ + + +### Change a column type's precision + +The [TPC-C](performance-benchmarking-with-tpc-c-1k-warehouses.html) `customer` table contains a column `c_balance` of type [`DECIMAL(12,2)`](decimal.html): + +{% include copy-clipboard.html %} +~~~ sql +> SELECT column_name, data_type FROM [SHOW COLUMNS FROM customer] WHERE column_name='c_balance'; +~~~ + +~~~ + column_name | data_type +--------------+---------------- + c_balance | DECIMAL(12,2) +(1 row) +~~~ + +Suppose you want to increase the precision of the `c_balance` column from `DECIMAL(12,2)` to `DECIMAL(14,2)`: + +{% include copy-clipboard.html %} +~~~ sql +> ALTER TABLE customer ALTER c_balance TYPE DECIMAL(14,2); +~~~ + +{% include copy-clipboard.html %} +~~~ sql +> SELECT column_name, data_type FROM [SHOW COLUMNS FROM customer] WHERE column_name='c_balance'; +~~~ + +~~~ + column_name | data_type +--------------+---------------- + c_balance | DECIMAL(14,2) +(1 row) +~~~ + +### Change a column's type using an expression + +You can change the data type of a column and create a new, computed value from the old column values, with a [`USING` clause](#parameters). For example: + +{% include copy-clipboard.html %} +~~~ sql +> SELECT column_name, data_type FROM [SHOW COLUMNS FROM customer] WHERE column_name='c_discount'; +~~~ + +~~~ + column_name | data_type +--------------+--------------- + c_discount | DECIMAL(4,4) +(1 row) +~~~ + +{% include copy-clipboard.html %} +~~~ sql +> SELECT c_discount FROM customer LIMIT 10; +~~~ + +~~~ + c_discount +-------------- + 0.1569 + 0.4629 + 0.2932 + 0.0518 + 0.3922 + 0.1106 + 0.0622 + 0.4916 + 0.3072 + 0.0316 +(10 rows) +~~~ + +{% include copy-clipboard.html %} +~~~ sql +> ALTER TABLE customer ALTER c_discount TYPE STRING USING ((c_discount*100)::DECIMAL(4,2)::STRING || ' percent'); +~~~ + +~~~ +NOTICE: ALTER COLUMN TYPE changes are finalized asynchronously; further schema changes on this table may be restricted until the job completes; some writes to the altered column may be rejected until the schema change is finalized +~~~ + +{% include copy-clipboard.html %} +~~~ sql +> SELECT column_name, data_type FROM [SHOW COLUMNS FROM customer] WHERE column_name='c_discount'; +~~~ + +~~~ + column_name | data_type +--------------+------------ + c_discount | STRING +(1 row) +~~~ + +{% include copy-clipboard.html %} +~~~ sql +> SELECT c_discount FROM customer LIMIT 10; +~~~ + +~~~ + c_discount +----------------- + 15.69 percent + 46.29 percent + 29.32 percent + 5.18 percent + 39.22 percent + 11.06 percent + 6.22 percent + 49.16 percent + 30.72 percent + 3.16 percent +(10 rows) +~~~ + ## See also - [Constraints](constraints.html) diff --git a/v20.2/alter-table.md b/v20.2/alter-table.md index fa0bc97ebd2..0667f5f6c8c 100644 --- a/v20.2/alter-table.md +++ b/v20.2/alter-table.md @@ -18,10 +18,8 @@ Subcommand | Description | Can combine with other subcommands? -----------|-------------|------------------------------------ [`ADD COLUMN`](add-column.html) | Add columns to tables. | Yes [`ADD CONSTRAINT`](add-constraint.html) | Add constraints to columns. | Yes -[`ALTER COLUMN`](alter-column.html) | Change or drop a column's [`DEFAULT` constraint](default-value.html) or [`NOT NULL` constraint](not-null.html). | Yes -[`ALTER PRIMARY KEY`](alter-primary-key.html) | Change the [primary key](primary-key.html) of a table. | Yes -[`ALTER TYPE`](alter-type.html) | Change a column's [data type](data-types.html). | Yes -[`CONFIGURE ZONE`](configure-zone.html) | [Configure replication zones](configure-replication-zones.html) for a table. | No +[`ALTER COLUMN`](alter-column.html) | Change an existing column. | Yes +[`ALTER PRIMARY KEY`](alter-primary-key.html) | Change the [primary key](primary-key.html) of a table. | Yesnes.html) for a table. | No [`DROP COLUMN`](drop-column.html) | Remove columns from tables. | Yes [`DROP CONSTRAINT`](drop-constraint.html) | Remove constraints from columns. | Yes [`EXPERIMENTAL_AUDIT`](experimental-audit.html) | Enable per-table audit logs. | Yes diff --git a/v20.2/alter-type.md b/v20.2/alter-type.md deleted file mode 100644 index b8ddfbd7eef..00000000000 --- a/v20.2/alter-type.md +++ /dev/null @@ -1,85 +0,0 @@ ---- -title: ALTER TYPE -summary: Use the ALTER TYPE statement to change a column's data type. -toc: true ---- - -The `ALTER TYPE` [statement](sql-statements.html) is part of [`ALTER TABLE`](alter-table.html) and changes a column's [data type](data-types.html). - -{% include {{ page.version.version }}/sql/combine-alter-table-commands.md %} - -## Considerations - -You can use the `ALTER TYPE` subcommand if the following conditions are met: - -- On-disk representation of the column remains unchanged. For example, you cannot change the column data type from `STRING` to an `INT`, even if the string is just a number. -- The existing data remains valid. For example, you can change the column data type from `STRING[10]` to `STRING[20]`, but not to `STRING [5]` since that will invalidate the existing data. - -## Synopsis - -
-{% include {{ page.version.version }}/sql/diagrams/alter_type.html %} -
- -## Required privileges - -The user must have the `CREATE` [privilege](authorization.html#assign-privileges) on the table. - -## Parameters - -| Parameter | Description -|-----------|------------- -| `table_name` | The name of the table with the column whose data type you want to change. -| `column_name` | The name of the column whose data type you want to change. -| `typename` | The new [data type](data-types.html) you want to use. - -## Viewing schema changes - -{% include {{ page.version.version }}/misc/schema-change-view-job.md %} - -## Examples - -### Success scenario - -The [TPC-C](performance-benchmarking-with-tpc-c-1k-warehouses.html) database has a `customer` table with a column `c_credit_lim DECIMAL (10,2)`. Suppose you want to change the data type to `DECIMAL (12,2)`: - -{% include copy-clipboard.html %} -~~~ sql -> ALTER TABLE customer ALTER c_credit_lim type DECIMAL (12,2); -~~~ - -~~~ -ALTER TABLE - -Time: 80.814044ms -~~~ - -### Error scenarios - -Changing a column data type from `DECIMAL` to `INT` would change the on-disk representation of the column. Therefore, attempting to do so results in an error: - -{% include copy-clipboard.html %} -~~~ sql -> ALTER TABLE customer ALTER c_credit_lim type INT; -~~~ - -~~~ -pq: type conversion not yet implemented -~~~ - -Changing a column data type from `DECIMAL(12,2)` to `DECIMAL (8,2)` would invalidate the existing data. Therefore, attempting to do so results in an error: - -{% include copy-clipboard.html %} -~~~ sql -> ALTER TABLE customer ALTER c_credit_lim type DECIMAL (8,2); -~~~ - -~~~ -pq: type conversion not yet implemented -~~~ - -## See also - -- [`ALTER TABLE`](alter-table.html) -- [Other SQL Statements](sql-statements.html) -- [`SHOW JOBS`](show-jobs.html) diff --git a/v20.2/experimental-features.md b/v20.2/experimental-features.md index 10c7aab1cf6..3bf03e863d7 100644 --- a/v20.2/experimental-features.md +++ b/v20.2/experimental-features.md @@ -19,6 +19,7 @@ The table below lists the experimental session settings that are available. For | Variable | Default Value | Description | |-------------------------------------+---------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `enable_experimental_alter_column_type_general` | `'false'` | If set to `'true'`, enables [column type altering](#alter-column-types) for general cases, with some limitations. | | `experimental_enable_hash_sharded_indexes` | `'off'` | If set to `'on'`, enables [hash-sharded indexes](#hash-sharded-indexes) with `USING HASH`. | | `experimental_enable_temp_tables` | `'off'` | If set to `'on'`, enables [temporary objects](#temporary-objects), including [temporary tables](temporary-tables.html), [temporary views](views.html#temporary-views), and [temporary sequences](create-sequence.html#temporary-sequences). | @@ -134,6 +135,9 @@ The table below lists the experimental SQL functions and operators available in | [`experimental_strptime`](functions-and-operators.html#date-and-time-functions) | Format time using standard `strptime` notation. | | [`experimental_uuid_v4()`](functions-and-operators.html#id-generation-functions) | Return a UUID. | +## Alter column types + +New in v20.2: CockroachDB supports altering the column types of existing tables, with certain limitations. For more information, see [Altering column data types](alter-column.html#altering-column-data-types). ## Temporary objects diff --git a/v20.2/sql-statements.md b/v20.2/sql-statements.md index 6594af41e3b..185f546fb88 100644 --- a/v20.2/sql-statements.md +++ b/v20.2/sql-statements.md @@ -42,7 +42,6 @@ Statement | Usage [`ALTER RANGE`](alter-range.html) | Configure the replication zone for a system range. [`ALTER SEQUENCE`](alter-sequence.html) | Apply a schema change to a sequence. [`ALTER TABLE`](alter-table.html) | Apply a schema change to a table. -[`ALTER TYPE`](alter-type.html) | Change a column's [data type](data-types.html). [`ALTER USER`](alter-user.html) | add, change, or remove a user's password and to change the login privileges for a role. [`ALTER ROLE`](alter-role.html) | Add, change, or remove a [role's](create-role.html) password and to change the login privileges for a role. [`ALTER VIEW`](alter-view.html) | Rename a view.