> ## Documentation Index > Fetch the complete documentation index at: https://docs.cockroachlabs.com/llms.txt > Use this file to discover all available pages before exploring further. # COMMENT ON The `COMMENT ON` [statement](/docs/stable/sql-statements.md) associates comments to [databases](/docs/stable/create-database.md), [tables](/docs/stable/create-table.md), [columns](/docs/stable/alter-table.md#add-column), [indexes](/docs/stable/indexes.md), or [types](/docs/stable/show-types.md). > [!NOTE] > > The `COMMENT ON` statement performs a schema change. For more information about how online schema changes work in CockroachDB, see [Online Schema Changes](/docs/stable/online-schema-changes.md). ## Required privileges The user must have the `CREATE` [privilege](/docs/stable/security-reference/authorization.md#managing-privileges) on the object they are commenting on. ## Synopsis ![comment syntax diagram](https://mintcdn.com/cockroachlabs/7gzGESYW_aT0XysP/images/sql-diagrams/v26.3/comment.svg?fit=max\&auto=format\&n=7gzGESYW_aT0XysP\&q=85\&s=2b9ceb687d64a0cfc3191395e848c25e) ## Parameters | Parameter | Description | | - | - | | `database_name` | The name of the [database](/docs/stable/create-database.md) on which you are commenting. | | `schema_name` | The name of the [schema](/docs/stable/create-schema.md) on which you are commenting. | | `type_name` | The name of the [type](/docs/stable/show-types.md) on which you are commenting. | | `table_name` | The name of the [table](/docs/stable/create-table.md) on which you are commenting. | | `column_name` | The name of the [column](/docs/stable/alter-table.md#add-column) on which you are commenting. | | `table_index_name` | The name of the [index](/docs/stable/indexes.md) on which you are commenting. | | `comment_text` | The comment ([`STRING`](/docs/stable/string)) you are associating to the object. You can remove a comment by replacing the string with `NULL`. | ## Examples #### Setup To follow along, run [`cockroach demo`](/docs/stable/cockroach-demo) to start a temporary, in-memory cluster with the [`movr`](/docs/stable/movr) 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 [`SHOW DATABASES`](/docs/stable/show-databases): ```sql theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}} > SHOW DATABASES WITH COMMENT; ``` ``` 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 [`SHOW TABLES`](/docs/stable/show-tables): ```sql theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}} > SHOW TABLES FROM movr WITH COMMENT; ``` ``` 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 [`SHOW CREATE`](/docs/stable/show-create): ```sql theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}} > SHOW CREATE TABLE vehicles; ``` ``` 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 [`SHOW COLUMNS`](/docs/stable/show-columns): ```sql theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}} > SHOW COLUMNS FROM users WITH COMMENT; ``` ``` 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 [create an index](/docs/stable/create-index.md) 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 [`SHOW INDEXES ... WITH COMMENT`](/docs/stable/show-index): ```sql theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}} > SHOW INDEXES FROM users WITH COMMENT; ``` ``` 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 [create a type](/docs/stable/create-type.md): ```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 [`SHOW TYPES`](/docs/stable/show-types): ```sql theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}} SHOW TYPES; ``` ``` 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 [selection query](/docs/stable/select-clause.md) against the `system.comments` table: ```sql theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}} SELECT * FROM system.comments; ``` ``` 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; ``` ``` 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 [`COMMENT ON`](/docs/stable/comment-on) 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 [`BACKUP`](/docs/stable/backup) 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 * [`CREATE DATABASE`](/docs/stable/create-database) * [`CREATE TABLE`](/docs/stable/create-table) * [`ADD COLUMN`](/docs/stable/alter-table#add-column) * [`CREATE INDEX`](/docs/stable/create-index) * [`SHOW TABLES`](/docs/stable/show-tables) * [SQL Statements](/docs/stable/sql-statements.md) * [dBeaver](/docs/stable/dbeaver.md) * [Online Schema Changes](/docs/stable/online-schema-changes.md)