ON UPDATE expressions

v20.2/add-column.md

@@ -224,7 +224,7 @@ $ cockroach demo bank
 
 {% include copy-clipboard.html %}
 ~~~ sql
-> SHOW CREATE TABLE FROM bank;
+> SHOW CREATE TABLE bank;
 ~~~
 ~~~
   table_name |                                                          create_statement
@@ -259,7 +259,7 @@ $ cockroach demo bank
 
 {% include copy-clipboard.html %}
 ~~~ sql
-> SHOW CREATE TABLE FROM bank;
+> SHOW CREATE TABLE bank;
 ~~~
 ~~~
   table_name |                                                          create_statement
@@ -295,7 +295,7 @@ $ cockroach demo bank
 
 {% include copy-clipboard.html %}
 ~~~ sql
-> SHOW CREATE TABLE FROM bank;
+> SHOW CREATE TABLE bank;
 ~~~
 ~~~
   table_name |                                                          create_statement

v21.1/add-column.md

@@ -224,7 +224,7 @@ $ cockroach demo bank
 
 {% include copy-clipboard.html %}
 ~~~ sql
-> SHOW CREATE TABLE FROM bank;
+> SHOW CREATE TABLE bank;
 ~~~
 ~~~
   table_name |                                                          create_statement
@@ -259,7 +259,7 @@ $ cockroach demo bank
 
 {% include copy-clipboard.html %}
 ~~~ sql
-> SHOW CREATE TABLE FROM bank;
+> SHOW CREATE TABLE bank;
 ~~~
 ~~~
   table_name |                                                          create_statement
@@ -295,7 +295,7 @@ $ cockroach demo bank
 
 {% include copy-clipboard.html %}
 ~~~ sql
-> SHOW CREATE TABLE FROM bank;
+> SHOW CREATE TABLE bank;
 ~~~
 ~~~
   table_name |                                                          create_statement

v21.1/default-value.md

@@ -20,7 +20,9 @@ You can only apply the `DEFAULT` value constraint to individual columns.
 You can also add the `DEFAULT` value constraint to an existing table through [`ALTER COLUMN`](alter-column.html#set-or-change-a-default-value).
 {{site.data.alerts.end}}
 
-<div>{% include {{ page.version.version }}/sql/generated/diagrams/default_value_column_level.html %} </section>
+<div>
+{% include {{ page.version.version }}/sql/generated/diagrams/default_value_column_level.html %}
+</div>
 
  Parameter | Description
 -----------|-------------

v21.2/add-column.md

@@ -4,7 +4,7 @@ summary: Use the ADD COLUMN statement to add columns to tables.
 toc: true
 ---
 
-The `ADD COLUMN` [statement](sql-statements.html) is part of `ALTER TABLE` and adds columns to tables.
+`ADD COLUMN` is a subcommand of [`ALTER TABLE`](alter-table.html). Use `ADD COLUMN` to add columns to existing tables.
 
 {% include {{ page.version.version }}/sql/combine-alter-table-commands.md %}
 
@@ -26,7 +26,37 @@ The user must have the `CREATE` [privilege](authorization.html#assign-privileges
  `table_name` | The name of the table to which you want to add the column.
  `column_name` | The name of the column you want to add. The column name must follow these [identifier rules](keywords-and-identifiers.html#identifiers) and must be unique within the table but can have the same name as indexes or constraints.
  `typename` | The [data type](data-types.html) of the new column.
- `col_qualification` | An optional list of column definitions, which may include [column-level constraints](constraints.html), [collation](collate.html), or [column family assignments](column-families.html).<br><br>If the column family is not specified, the column will be added to the first column family. For more information about how column families are assigned, see [Column Families](column-families.html#assign-column-families-when-adding-columns).
+ `col_qualification` | An optional list of [column qualifications](#column-qualifications).
+
+## Column qualifications
+
+CockroachDB supports the following column qualifications:
+
+- [Column-level constraints](constraints.html)
+- [Collations](collate.html)
+- [Column family assignments](column-families.html)
+- [`DEFAULT` expressions](default-value.html)
+- <span class="version-tag">New in v21.2</span>: [`ON UPDATE` expressions](#on-update-expressions)
+
+### ON UPDATE expressions
+
+<span class="version-tag">New in v21.2</span>: `ON UPDATE` expressions update column values in the following cases:
+
+- An [`UPDATE`](update.html) or [`UPSERT`](upsert.html) statement modifies a different column value in the same row.
+- An `ON UPDATE CASCADE` expression on a different column modifies an existing value in the same row.
+
+`ON UPDATE` expressions **do not** update column values in the following cases:
+
+- An `UPDATE` or `UPSERT` statement directly modifies the value of a column with an `ON UPDATE` expression.
+- An `UPSERT` statement creates a new row.
+- A new column is backfilled with values (e.g., by a `DEFAULT` expression).
+
+Note the following limitations of `ON UPDATE` expressions:
+
+- `ON UPDATE` expressions allow context-dependent expressions, but not expressions that reference other columns. For example, the `current_timestamp()` [built-in function](functions-and-operators.html) is allowed, but `CONCAT(<column_one>, <column_two>)` is not.
+- You cannot add a [foreign key constraint](foreign-key.html) and an `ON UPDATE` expression to the same column.
+
+For an example of `ON UPDATE`, see [Add a column with an `ON UPDATE` expression](#add-a-column-with-an-on-update-expression).
 
 ## Viewing schema changes
 
@@ -225,7 +255,7 @@ $ cockroach demo bank
 
 {% include copy-clipboard.html %}
 ~~~ sql
-> SHOW CREATE TABLE FROM bank;
+> SHOW CREATE TABLE bank;
 ~~~
 ~~~
   table_name |                                                          create_statement
@@ -260,7 +290,7 @@ $ cockroach demo bank
 
 {% include copy-clipboard.html %}
 ~~~ sql
-> SHOW CREATE TABLE FROM bank;
+> SHOW CREATE TABLE bank;
 ~~~
 ~~~
   table_name |                                                          create_statement
@@ -296,7 +326,7 @@ $ cockroach demo bank
 
 {% include copy-clipboard.html %}
 ~~~ sql
-> SHOW CREATE TABLE FROM bank;
+> SHOW CREATE TABLE bank;
 ~~~
 ~~~
   table_name |                                                          create_statement
@@ -325,6 +355,56 @@ $ cockroach demo bank
 (1 row)
 ~~~
 
+### Add a column with an `ON UPDATE` expression
+
+<span class="version-tag">New in v21.2</span>: `ON UPDATE` expressions set the value for a column when other values in a row are updated.
+
+For example, suppose you add a new column to the `bank` table:
+
+{% include copy-clipboard.html %}
+~~~ sql
+> ALTER TABLE bank ADD COLUMN last_updated TIMESTAMPTZ DEFAULT now() ON UPDATE now();
+~~~
+
+{% include copy-clipboard.html %}
+~~~ sql
+> SELECT id, balance, last_updated FROM bank LIMIT 5;
+~~~
+
+~~~
+  id | balance |         last_updated
+-----+---------+--------------------------------
+   0 |       0 | 2021-10-21 17:03:41.213557+00
+   1 |       0 | 2021-10-21 17:03:41.213557+00
+   2 |       0 | 2021-10-21 17:03:41.213557+00
+   3 |       0 | 2021-10-21 17:03:41.213557+00
+   4 |       0 | 2021-10-21 17:03:41.213557+00
+(5 rows)
+~~~
+
+When any value in any row of the `bank` table is updated, CockroachDB re-evaluates the `ON UPDATE` expression and updates the `last_updated` column with the result.
+
+{% include copy-clipboard.html %}
+~~~ sql
+> UPDATE bank SET balance = 500 WHERE id = 0;
+~~~
+
+{% include copy-clipboard.html %}
+~~~ sql
+> SELECT id, balance, last_updated FROM bank LIMIT 5;
+~~~
+
+~~~
+  id | balance |         last_updated
+-----+---------+--------------------------------
+   0 |     500 | 2021-10-21 17:06:42.211261+00
+   1 |       0 | 2021-10-21 17:03:41.213557+00
+   2 |       0 | 2021-10-21 17:03:41.213557+00
+   3 |       0 | 2021-10-21 17:03:41.213557+00
+   4 |       0 | 2021-10-21 17:03:41.213557+00
+(5 rows)
+~~~
+
 ## See also
 
 - [`ALTER TABLE`](alter-table.html)

v21.2/alter-column.md

@@ -4,10 +4,11 @@ summary: Use the ALTER COLUMN statement to set, change, or drop a column's DEFAU
 toc: true
 ---
 
-The `ALTER COLUMN` [statement](sql-statements.html) is part of `ALTER TABLE` and can be used to:
+`ALTER COLUMN` is a subcommand of [`ALTER TABLE`](alter-table.html). You can use `ALTER COLUMN` to do the following:
 
 - Set, change, or drop a column's [`DEFAULT` constraint](default-value.html).
 - Set or drop a column's [`NOT NULL` constraint](not-null.html).
+- <span class="version-tag">New in v21.2</span>: Set, change, or drop an [`ON UPDATE` expression](add-column.html#on-update-expressions).
 - Change a column's [data type](data-types.html).
 
 {{site.data.alerts.callout_info}}

v21.2/computed-columns.md

@@ -21,7 +21,7 @@ Computed columns:
 - Cannot be used to generate other computed columns.
 - Cannot reference a [foreign key](foreign-key.html).
 - Behave like any other column, with the exception that they cannot be written to directly.
-- Are mutually exclusive with [`DEFAULT`](default-value.html).
+- Are mutually exclusive with [`DEFAULT`](default-value.html) and [`ON UPDATE`](add-column.html#on-update-expressions) expressions.
 
 Virtual computed columns:
 

v21.2/create-table.md

@@ -99,7 +99,7 @@ Parameter | Description
 `opt_persistence_temp_table` |  Defines the table as a session-scoped temporary table. For more information, see [Temporary Tables](temporary-tables.html).<br><br>Note that the `LOCAL`, `GLOBAL`, and `UNLOGGED` options are no-ops, allowed by the parser for PostgresSQL compatibility.<br><br>**Support for temporary tables is [experimental](experimental-features.html#temporary-objects)**.
 `IF NOT EXISTS` | Create a new table only if a table of the same name does not already exist in the database; if one does exist, do not return an error.<br><br>Note that `IF NOT EXISTS` checks the table name only; it does not check if an existing table has the same columns, indexes, constraints, etc., of the new table.
 `table_name` | The name of the table to create, which must be unique within its database and follow these [identifier rules](keywords-and-identifiers.html#identifiers). When the parent database is not set as the default, the name must be formatted as `database.name`.<br><br>The [`UPSERT`](upsert.html) and [`INSERT ON CONFLICT`](insert.html) statements use a temporary table called `excluded` to handle uniqueness conflicts during execution. It's therefore not recommended to use the name `excluded` for any of your tables.
-`column_def` | A comma-separated list of column definitions. Each column requires a [name/identifier](keywords-and-identifiers.html#identifiers) and [data type](data-types.html); optionally, a [column-level constraint](constraints.html) or other column qualification (e.g., [computed columns](computed-columns.html)) can be specified. Column names must be unique within the table but can have the same name as indexes or constraints.<br><br>Any `PRIMARY KEY`, `UNIQUE`, and `CHECK` [constraints](constraints.html) defined at the column level are moved to the table-level as part of the table's creation. Use the [`SHOW CREATE`](show-create.html) statement to view them at the table level.
+`column_def` | A comma-separated list of column definitions. Each column requires a [name/identifier](keywords-and-identifiers.html#identifiers) and [data type](data-types.html). Column names must be unique within the table but can have the same name as indexes or constraints.<br><br>You can optionally specify a [column qualification](add-column.html#column-qualifications) (e.g., a [column-level constraint](constraints.html)). Any `PRIMARY KEY`, `UNIQUE`, and `CHECK` [constraints](constraints.html) defined at the column level are moved to the table-level as part of the table's creation. Use the [`SHOW CREATE`](show-create.html) statement to view them at the table level.
 `index_def` | An optional, comma-separated list of [index definitions](indexes.html). For each index, the column(s) to index must be specified; optionally, a name can be specified. Index names must be unique within the table and follow these [identifier rules](keywords-and-identifiers.html#identifiers). See the [Create a Table with Secondary Indexes and Inverted Indexes](#create-a-table-with-secondary-and-inverted-indexes) example below.<br><br> To enable [hash-sharded indexes](hash-sharded-indexes.html), set the `experimental_enable_hash_sharded_indexes` [session variable](set-vars.html) to `on`. For examples, see [Create a table with hash-sharded indexes](#create-a-table-with-a-hash-sharded-primary-index) below.<br><br>The [`CREATE INDEX`](create-index.html) statement can be used to create an index separate from table creation.
 `family_def` | An optional, comma-separated list of [column family definitions](column-families.html). Column family names must be unique within the table but can have the same name as columns, constraints, or indexes.<br><br>A column family is a group of columns that are stored as a single key-value pair in the underlying key-value store. CockroachDB automatically groups columns into families to ensure efficient storage and performance. However, there are cases when you may want to manually assign columns to families. For more details, see [Column Families](column-families.html).
 `table_constraint` | An optional, comma-separated list of [table-level constraints](constraints.html). Constraint names must be unique within the table but can have the same name as columns, column families, or indexes.