Merge pull request #8022 from cockroachdb/alter-type

ALTER TYPE support

_includes/sidebar-data-v19.2.json

@@ -871,12 +871,6 @@
  "/${VERSION}/alter-table.html"
  ]
  },
- {
- "title": "<code>ALTER TYPE</code>",
- "urls": [
- "/${VERSION}/alter-type.html"
- ]
- },
  {
  "title": "<code>ALTER USER</code>",
  "urls": [

_includes/sidebar-data-v20.1.json

@@ -954,12 +954,6 @@
  "/${VERSION}/alter-table.html"
  ]
  },
- {
- "title": "<code>ALTER TYPE</code>",
- "urls": [
- "/${VERSION}/alter-type.html"
- ]
- },
  {
  "title": "<code>ALTER USER</code>",
  "urls": [

_includes/sidebar-data-v20.2.json

@@ -987,12 +987,6 @@
  "/${VERSION}/alter-table.html"
  ]
  },
- {
- "title": "<code>ALTER TYPE</code>",
- "urls": [
- "/${VERSION}/alter-type.html"
- ]
- },
  {
  "title": "<code>ALTER USER</code>",
  "urls": [

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.<br>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)

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

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.