SQL COMMENT

What is SQL COMMENT and how do I use it?

Adds or modifies a descriptive comment attached to a database object.

Welcome to the Galaxy, Guardian!
You'll be receiving a confirmation email

Follow us on twitter :)

Oops! Something went wrong while submitting the form.

Compatible dialects for SQL COMMENT: PostgreSQL, Oracle, MySQL (via COMMENT ON or inline COMMENT), Snowflake, Redshift. Not directly supported in SQLite; SQL Server uses sp_addextendedproperty instead.

SQL COMMENT Full Explanation

COMMENT (formally COMMENT ON) attaches human-readable text to database objects such as tables, columns, views, indexes, schemas, and functions. The comment is stored in the system catalog so anyone querying metadata can see the description. It does not affect query execution, permissions, or storage size. Most modern engines persist the comment until it is explicitly changed or the object is dropped. Some dialects allow comments to be set inline during CREATE or ALTER statements (e.g., MySQL), while others use a dedicated COMMENT ON command (PostgreSQL, Oracle, Standard SQL). Comments can be queried through catalog views or information_schema. Because comments are metadata, they are included in logical backups but not always in physical dumps unless specified.

SQL COMMENT Syntax

COMMENT ON object_type object_name IS 'comment_text';

SQL COMMENT Parameters

object_type (keyword) - The kind of object to annotate (TABLE, COLUMN, VIEW, INDEX, SCHEMA, FUNCTION, etc.)
object_name (identifier) - Qualified name of the object being commented on. For columns use table_name.column_name.
comment_text (string) - The text of the comment. Use NULL to remove an existing comment.

Example Queries Using SQL COMMENT

-- Add a table comment
COMMENT ON TABLE public.users IS 'Stores registered application users';

-- Add a column comment
COMMENT ON COLUMN public.users.email IS 'Primary email address, must be unique';

-- Remove a comment
COMMENT ON TABLE public.users IS NULL;

Expected Output Using SQL COMMENT

The statement returns OK/COMMAND COMPLETED and the comment is stored in system metadata
Subsequent DESCRIBE or catalog queries show the new comment

Use Cases with SQL COMMENT

Document schema objects for future developers.
Expose field descriptions to BI tools that read metadata.
Store business definitions close to data for data cataloging.
Mark deprecated tables or columns without affecting production queries.

Common Mistakes with SQL COMMENT

Forgetting the ON keyword (e.g., COMMENT TABLE ...).
Omitting quotes around comment_text, causing a syntax error.
Using COMMENT where the dialect only supports inline COMMENT clauses (e.g., MySQL column definition).
Expecting comments to replicate automatically across replicas in engines that require separate metadata sync.

First Introduced In

SQL-92 standard (COMMENT ON); earliest vendor implementation in Oracle 7

Frequently Asked Questions

What objects can be annotated?

Most engines allow comments on tables and columns. PostgreSQL and Oracle also support schemas, views, indexes, sequences, materialized views, and functions.

Does SQL COMMENT impact performance?

No. Comments are purely metadata and have zero effect on query planning or execution speed.

How can I view existing comments?

Use catalog queries such as `SELECT obj_description('public.users'::regclass)` in PostgreSQL or query `information_schema.columns` in MySQL.

How do I delete a comment?

Set the comment text to NULL: `COMMENT ON TABLE public.users IS NULL;`