> ## Documentation Index
> Fetch the complete documentation index at: https://cockroachlabs.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# COMMENT ON

export const InternalLink = ({version, path = "", children, ...props}) => {
  let detectedVersion = version || "stable";
  if (typeof window !== 'undefined' && !version) {
    const match = window.location.pathname.match(/\/docs\/([^/]+)/);
    if (match) {
      detectedVersion = match[1];
    }
  }
  const normalizedPath = path.startsWith("/") ? path.slice(1) : path;
  return <a href={`/docs/${detectedVersion}/${normalizedPath}`} {...props}>
      {children}
    </a>;
};

The `COMMENT ON` <InternalLink path="sql-statements">statement</InternalLink> associates comments to <InternalLink path="create-database">databases</InternalLink>, <InternalLink path="create-table">tables</InternalLink>, <InternalLink path="alter-table#add-column">columns</InternalLink>, <InternalLink path="indexes">indexes</InternalLink>, or <InternalLink path="show-types">types</InternalLink>.

The `COMMENT ON` statement performs a schema change. For more information about how online schema changes work in CockroachDB, see <InternalLink path="online-schema-changes">Online Schema Changes</InternalLink>.

## Required privileges

The user must have the `CREATE` <InternalLink path="security-reference/authorization#managing-privileges">privilege</InternalLink> on the object they are commenting on.

## Synopsis

<img src="https://mintcdn.com/cockroachlabs/N8jqu5GnKPMC09TX/images/sql-diagrams/v25.4/comment.svg?fit=max&auto=format&n=N8jqu5GnKPMC09TX&q=85&s=bc010496c97a5b12f6f796b13df1a514" alt="comment syntax diagram" style={{maxWidth: "100%", overflowX: "auto"}} width="733" height="367" data-path="images/sql-diagrams/v25.4/comment.svg" />

## Parameters

| Parameter            | Description                                                                                                                                                        |
| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `database\_name`     | The name of the <InternalLink path="create-database">database</InternalLink> on which you are commenting.                                                          |
| `schema\_name`       | The name of the <InternalLink path="create-schema">schema</InternalLink> on which you are commenting.                                                              |
| `type\_name`         | The name of the <InternalLink path="show-types">type</InternalLink> on which you are commenting.                                                                   |
| `table\_name`        | The name of the <InternalLink path="create-table">table</InternalLink> on which you are commenting.                                                                |
| `column\_name`       | The name of the <InternalLink path="alter-table#add-column">column</InternalLink> on which you are commenting.                                                     |
| `table\_index\_name` | The name of the <InternalLink path="indexes">index</InternalLink> on which you are commenting.                                                                     |
| `comment\_text`      | The comment (<InternalLink path="string">`STRING`</InternalLink>) you are associating to the object. You can remove a comment by replacing the string with `NULL`. |

## Examples

#### Setup

To follow along, run <InternalLink path="cockroach-demo">`cockroach demo`</InternalLink> to start a temporary, in-memory cluster with the <InternalLink path="movr">`movr`</InternalLink> sample dataset preloaded:

```shell theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
$ cockroach demo
```

### Add a comment to a database

To add a comment to a database:

```sql theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
> COMMENT ON DATABASE movr IS 'This database contains information about users, vehicles, and rides.';
```

To view database comments, use <InternalLink path="show-databases">`SHOW DATABASES`</InternalLink>:

```sql theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
> SHOW DATABASES WITH COMMENT;
```

```text theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
  database_name | owner | primary_region | regions | survival_goal |                               comment
----------------+-------+----------------+---------+---------------+-----------------------------------------------------------------------
  defaultdb     | root  | NULL           | {}      | NULL          | NULL
  movr          | demo  | NULL           | {}      | NULL          | This database contains information about users, vehicles, and rides.
  postgres      | root  | NULL           | {}      | NULL          | NULL
  system        | node  | NULL           | {}      | NULL          | NULL
(4 rows)
```

### Add a comment to a table

To add a comment to a table:

```sql theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
> COMMENT ON TABLE vehicles IS 'This table contains information about vehicles registered with MovR.';
```

To view table comments, use <InternalLink path="show-tables">`SHOW TABLES`</InternalLink>:

```sql theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
> SHOW TABLES FROM movr WITH COMMENT;
```

```text theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
          table_name         |                               comment
+----------------------------+----------------------------------------------------------------------+
  users                      |
  vehicles                   | This table contains information about vehicles registered with MovR.
  rides                      |
  vehicle_location_histories |
  promo_codes                |
  user_promo_codes           |
(6 rows)
```

You can also view comments on a table with <InternalLink path="show-create">`SHOW CREATE`</InternalLink>:

```sql theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
> SHOW CREATE TABLE vehicles;
```

```text theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
  table_name |                                          create_statement
-------------+------------------------------------------------------------------------------------------------------
  vehicles   | CREATE TABLE vehicles (
             |     id UUID NOT NULL,
             |     city VARCHAR NOT NULL,
             |     type VARCHAR NULL,
             |     owner_id UUID NULL,
             |     creation_time TIMESTAMP NULL,
             |     status VARCHAR NULL,
             |     current_location VARCHAR NULL,
             |     ext JSONB NULL,
             |     CONSTRAINT "primary" PRIMARY KEY (city ASC, id ASC),
             |     CONSTRAINT fk_city_ref_users FOREIGN KEY (city, owner_id) REFERENCES users(city, id),
             |     INDEX vehicles_auto_index_fk_city_ref_users (city ASC, owner_id ASC),
             |     FAMILY "primary" (id, city, type, owner_id, creation_time, status, current_location, ext)
             | );
             | COMMENT ON TABLE vehicles IS 'This table contains information about vehicles registered with MovR.'
(1 row)
```

### Add a comment to a column

To add a comment to a column:

```sql theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
> COMMENT ON COLUMN users.credit_card IS 'This column contains user payment information.';
```

To view column comments, use <InternalLink path="show-columns">`SHOW COLUMNS`</InternalLink>:

```sql theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
> SHOW COLUMNS FROM users WITH COMMENT;
```

```text theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
  column_name | data_type | is_nullable | column_default | generation_expression |   indices    | is_hidden |                    comment
--------------+-----------+-------------+----------------+-----------------------+--------------+-----------+-------------------------------------------------
  id          | UUID      |      f      | NULL           |                       | {users_pkey} |     f     | NULL
  city        | VARCHAR   |      f      | NULL           |                       | {users_pkey} |     f     | NULL
  name        | VARCHAR   |      t      | NULL           |                       | {users_pkey} |     f     | NULL
  address     | VARCHAR   |      t      | NULL           |                       | {users_pkey} |     f     | NULL
  credit_card | VARCHAR   |      t      | NULL           |                       | {users_pkey} |     f     | This column contains user payment information.
(5 rows)
```

### Add a comment to an index

Suppose we <InternalLink path="create-index">create an index</InternalLink> on the `name` column of the `users` table:

```sql theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
> CREATE INDEX ON users(name);
```

To add a comment to the index:

```sql theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
> COMMENT ON INDEX users_name_idx IS 'This index improves performance on queries that filter by name.';
```

To view column comments, use <InternalLink path="show-index">`SHOW INDEXES... WITH COMMENT`</InternalLink>:

```sql theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
> SHOW INDEXES FROM users WITH COMMENT;
```

```text theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
  table_name |   index_name   | non_unique | seq_in_index | column_name | direction | storing | implicit | visible |                             comment
-------------+----------------+------------+--------------+-------------+-----------+---------+----------+---------+------------------------------------------------------------------
  users      | users_name_idx |     t      |            1 | name        | ASC       |    f    |    f     |    t    | This index improves performance on queries that filter by name.
  users      | users_name_idx |     t      |            2 | city        | ASC       |    f    |    t     |    t    | This index improves performance on queries that filter by name.
  users      | users_name_idx |     t      |            3 | id          | ASC       |    f    |    t     |    t    | This index improves performance on queries that filter by name.
  users      | users_pkey     |     f      |            1 | city        | ASC       |    f    |    f     |    t    | NULL
  users      | users_pkey     |     f      |            2 | id          | ASC       |    f    |    f     |    t    | NULL
  users      | users_pkey     |     f      |            3 | name        | N/A       |    t    |    f     |    t    | NULL
  users      | users_pkey     |     f      |            4 | address     | N/A       |    t    |    f     |    t    | NULL
  users      | users_pkey     |     f      |            5 | credit_card | N/A       |    t    |    f     |    t    | NULL
(8 rows)
```

### Add a comment to a type

Issue a SQL statement to <InternalLink path="create-type">create a type</InternalLink>:

```sql theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
CREATE TYPE IF NOT EXISTS my_point AS (x FLOAT, y FLOAT, z FLOAT);
```

To view the type you just created, use <InternalLink path="show-types">`SHOW TYPES`</InternalLink>:

```sql theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
SHOW TYPES;
```

```text theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
  schema |   name   | owner
---------+----------+--------
  public | my_point | root
(1 row)
```

To add a comment on the type, use a statement like the following:

```sql theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
COMMENT ON TYPE my_point IS '3D point';
```

To view all comments on types, make a <InternalLink path="select-clause">selection query</InternalLink> against the `system.comments` table:

```sql theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
SELECT * FROM system.comments;
```

```text theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
  type | object_id | sub_id | comment
-------+-----------+--------+-----------
     7 |       112 |      0 | 3D POINT
(1 row)
```

### Remove a comment from a database

To remove a comment from a database:

```sql theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
> COMMENT ON DATABASE movr IS NULL;
```

```sql theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
> SHOW DATABASES WITH COMMENT;
```

```text theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
  database_name | owner | primary_region | regions | survival_goal | comment
----------------+-------+----------------+---------+---------------+----------
  defaultdb     | root  | NULL           | {}      | NULL          | NULL
  movr          | demo  | NULL           | {}      | NULL          | NULL
  postgres      | root  | NULL           | {}      | NULL          | NULL
  system        | node  | NULL           | {}      | NULL          | NULL
(4 rows)
```

### Remove a comment from a type

To remove the comment from the type you created in the [preceding example](#add-a-comment-to-a-type), add a `NULL` comment:

```sql theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
COMMENT ON TYPE my_point IS NULL;
```

## Known limitations

* The <InternalLink path="comment-on">`COMMENT ON`</InternalLink> statement associates comments to databases, tables, or columns. However, the internal table ( `system.comments` ) in which these comments are stored is not captured by a <InternalLink path="backup">`BACKUP`</InternalLink> of an individual table or database. As a workaround, take a cluster backup instead, as the `system.comments` table is included in cluster backups.

## See also

* <InternalLink path="create-database">`CREATE DATABASE`</InternalLink>
* <InternalLink path="create-table">`CREATE TABLE`</InternalLink>
* <InternalLink path="alter-table#add-column">`ADD COLUMN`</InternalLink>
* <InternalLink path="create-index">`CREATE INDEX`</InternalLink>
* <InternalLink path="show-tables">`SHOW TABLES`</InternalLink>
* <InternalLink path="sql-statements">SQL Statements</InternalLink>
* <InternalLink path="dbeaver">dBeaver</InternalLink>
* <InternalLink path="online-schema-changes">Online Schema Changes</InternalLink>