COMMENT — 객체의 주석 정의하거나 변경하기

COMMENT 명령은 데이터베이스 객체에 주석(comment)을 저장하거나, 교체하거나, 제거하는 명령이에요. 테이블, 컬럼, 함수, 인덱스, 스키마 등 거의 모든 종류의 객체에 설명을 붙여 문서화할 수 있어요.

출처: PostgreSQL 문서

본문

Synopsis

COMMENT ON
{
  ACCESS METHOD object_name |
  AGGREGATE aggregate_name ( aggregate_signature ) |
  CAST (source_type AS target_type) |
  COLLATION object_name |
  COLUMN relation_name.column_name |
  CONSTRAINT constraint_name ON table_name |
  CONSTRAINT constraint_name ON DOMAIN domain_name |
  CONVERSION object_name |
  DATABASE object_name |
  DOMAIN object_name |
  EXTENSION object_name |
  EVENT TRIGGER object_name |
  FOREIGN DATA WRAPPER object_name |
  FOREIGN TABLE object_name |
  FUNCTION function_name [ ( [ [ argmode ] [ argname ] argtype [, ...] ] ) ] |
  INDEX object_name |
  LARGE OBJECT large_object_oid |
  MATERIALIZED VIEW object_name |
  OPERATOR operator_name (left_type, right_type) |
  OPERATOR CLASS object_name USING index_method |
  OPERATOR FAMILY object_name USING index_method |
  POLICY policy_name ON table_name |
  [ PROCEDURAL ] LANGUAGE object_name |
  PROCEDURE procedure_name [ ( [ [ argmode ] [ argname ] argtype [, ...] ] ) ] |
  PUBLICATION object_name |
  ROLE object_name |
  ROUTINE routine_name [ ( [ [ argmode ] [ argname ] argtype [, ...] ] ) ] |
  RULE rule_name ON table_name |
  SCHEMA object_name |
  SEQUENCE object_name |
  SERVER object_name |
  STATISTICS object_name |
  SUBSCRIPTION object_name |
  TABLE object_name |
  TABLESPACE object_name |
  TEXT SEARCH CONFIGURATION object_name |
  TEXT SEARCH DICTIONARY object_name |
  TEXT SEARCH PARSER object_name |
  TEXT SEARCH TEMPLATE object_name |
  TRANSFORM FOR type_name LANGUAGE lang_name |
  TRIGGER trigger_name ON table_name |
  TYPE object_name |
  VIEW object_name
} IS { string_literal | NULL }

where aggregate_signature is:

* |
[ argmode ] [ argname ] argtype [ , ... ] |
[ [ argmode ] [ argname ] argtype [ , ... ] ] ORDER BY [ argmode ] [ argname ] argtype [ , ... ]

Description

COMMENT는 데이터베이스 객체에 대한 주석을 저장, 교체, 또는 제거해요.

각 객체에는 하나의 주석 문자열만 저장돼요. 같은 객체에 새 COMMENT 명령을 발행하면 기존 주석을 교체해요. NULL 또는 빈 문자열('')을 지정하면 주석을 제거해요. 객체가 삭제되면 주석도 자동으로 함께 삭제돼요.

주석을 달 객체에는 SHARE UPDATE EXCLUSIVE 잠금이 획득돼요.

대부분의 객체 종류에서는 객체의 소유자만 주석을 설정할 수 있어요. 역할(role)에는 소유자가 없으므로, COMMENT ON ROLE의 규칙은 슈퍼유저 역할에 주석을 달려면 슈퍼유저여야 하거나, CREATEROLE 권한을 가지고 대상 역할에 대해 ADMIN OPTION을 부여받아야 한다는 거예요. 마찬가지로 접근 메서드(access method)에도 소유자가 없어요. 접근 메서드에 주석을 달려면 슈퍼유저여야 해요. 물론 슈퍼유저는 무엇이든 주석을 달 수 있어요.

주석은 psql의 \d 계열 명령으로 볼 수 있어요. 주석을 검색하는 다른 사용자 인터페이스도 psql이 사용하는 동일한 내장 함수, 즉 obj_description, col_description, shobj_description을 기반으로 구축할 수 있어요 (표 9.82 참고).

Parameters

object_name, relation_name.column_name, aggregate_name, constraint_name, function_name, operator_name, policy_name, procedure_name, routine_name, rule_name, trigger_name

주석을 달 객체의 이름이에요. 스키마에 있는 객체(테이블, 함수 등)의 이름은 스키마 한정으로 지정할 수 있어요. 컬럼에 주석을 달 때 *relation_name*은 테이블, 뷰, 복합 타입, 또는 외부 테이블을 가리켜야 해요.

table_name, domain_name

제약 조건(constraint), 트리거, 규칙(rule), 또는 정책(policy)에 주석을 만들 때 이 매개변수들은 해당 객체가 정의된 테이블 또는 도메인의 이름을 지정해요.

source_type

캐스트(cast)의 소스 데이터 타입 이름이에요.

target_type

캐스트의 대상 데이터 타입 이름이에요.

argmode

함수, 프로시저, 또는 집계 함수 인자의 모드로, IN, OUT, INOUT, VARIADIC 중 하나예요. 생략하면 기본값은 IN이에요. 참고로 COMMENT는 OUT 인자를 실제로 신경 쓰지 않는데, 함수의 정체성을 결정하는 데는 입력 인자만 필요하기 때문이에요. 따라서 IN, INOUT, VARIADIC 인자만 나열하면 충분해요.

argname

함수, 프로시저, 또는 집계 함수 인자의 이름이에요. 참고로 COMMENT는 인자 이름을 실제로 신경 쓰지 않는데, 함수의 정체성을 결정하는 데는 인자 데이터 타입만 필요하기 때문이에요.

argtype

함수, 프로시저, 또는 집계 함수 인자의 데이터 타입이에요.

large_object_oid

대형 객체(large object)의 OID예요.

left_type, right_type

연산자 인자의 데이터 타입(들)이에요 (선택적으로 스키마 한정). 접두 연산자의 누락된 인자에는 NONE을 작성해요.

PROCEDURAL

의미 없는 말(noise word)이에요.

type_name

트랜스폼(transform)의 데이터 타입 이름이에요.

lang_name

트랜스폼의 언어 이름이에요.

string_literal

문자열 리터럴로 작성하는 새 주석 내용이에요. 빈 문자열('')은 주석을 제거해요.

NULL

주석을 제거하려면 NULL을 작성해요.

Notes

현재 주석을 보기 위한 보안 메커니즘은 없어요. 데이터베이스에 연결한 모든 사용자는 그 데이터베이스 안 객체의 모든 주석을 볼 수 있어요. 데이터베이스, 역할, 테이블스페이스 같은 공유 객체의 경우 주석은 전역적으로 저장되므로, 클러스터의 어떤 데이터베이스에든 연결한 모든 사용자가 공유 객체의 모든 주석을 볼 수 있어요. 따라서 보안에 중요한 정보를 주석에 넣지 마세요.

Examples

mytable 테이블에 주석을 달기:

COMMENT ON TABLE mytable IS 'This is my table.';

다시 제거하기:

COMMENT ON TABLE mytable IS NULL;

몇 가지 더 많은 예시:

COMMENT ON ACCESS METHOD gin IS 'GIN index access method';
COMMENT ON AGGREGATE my_aggregate (double precision) IS 'Computes sample variance';
COMMENT ON CAST (text AS int4) IS 'Allow casts from text to int4';
COMMENT ON COLLATION "fr_CA" IS 'Canadian French';
COMMENT ON COLUMN my_table.my_column IS 'Employee ID number';
COMMENT ON CONVERSION my_conv IS 'Conversion to UTF8';
COMMENT ON CONSTRAINT bar_col_cons ON bar IS 'Constrains column col';
COMMENT ON CONSTRAINT dom_col_constr ON DOMAIN dom IS 'Constrains col of domain';
COMMENT ON DATABASE my_database IS 'Development Database';
COMMENT ON DOMAIN my_domain IS 'Email Address Domain';
COMMENT ON EVENT TRIGGER abort_ddl IS 'Aborts all DDL commands';
COMMENT ON EXTENSION hstore IS 'implements the hstore data type';
COMMENT ON FOREIGN DATA WRAPPER mywrapper IS 'my foreign data wrapper';
COMMENT ON FOREIGN TABLE my_foreign_table IS 'Employee Information in other database';
COMMENT ON FUNCTION my_function (timestamp) IS 'Returns Roman Numeral';
COMMENT ON INDEX my_index IS 'Enforces uniqueness on employee ID';
COMMENT ON LANGUAGE plpython IS 'Python support for stored procedures';
COMMENT ON LARGE OBJECT 346344 IS 'Planning document';
COMMENT ON MATERIALIZED VIEW my_matview IS 'Summary of order history';
COMMENT ON OPERATOR ^ (text, text) IS 'Performs intersection of two texts';
COMMENT ON OPERATOR - (NONE, integer) IS 'Unary minus';
COMMENT ON OPERATOR CLASS int4ops USING btree IS '4 byte integer operators for btrees';
COMMENT ON OPERATOR FAMILY integer_ops USING btree IS 'all integer operators for btrees';
COMMENT ON POLICY my_policy ON mytable IS 'Filter rows by users';
COMMENT ON PROCEDURE my_proc (integer, integer) IS 'Runs a report';
COMMENT ON PUBLICATION alltables IS 'Publishes all operations on all tables';
COMMENT ON ROLE my_role IS 'Administration group for finance tables';
COMMENT ON ROUTINE my_routine (integer, integer) IS 'Runs a routine (which is a function or procedure)';
COMMENT ON RULE my_rule ON my_table IS 'Logs updates of employee records';
COMMENT ON SCHEMA my_schema IS 'Departmental data';
COMMENT ON SEQUENCE my_sequence IS 'Used to generate primary keys';
COMMENT ON SERVER myserver IS 'my foreign server';
COMMENT ON STATISTICS my_statistics IS 'Improves planner row estimations';
COMMENT ON SUBSCRIPTION alltables IS 'Subscription for all operations on all tables';
COMMENT ON TABLE my_schema.my_table IS 'Employee Information';
COMMENT ON TABLESPACE my_tablespace IS 'Tablespace for indexes';
COMMENT ON TEXT SEARCH CONFIGURATION my_config IS 'Special word filtering';
COMMENT ON TEXT SEARCH DICTIONARY swedish IS 'Snowball stemmer for Swedish language';
COMMENT ON TEXT SEARCH PARSER my_parser IS 'Splits text into words';
COMMENT ON TEXT SEARCH TEMPLATE snowball IS 'Snowball stemmer';
COMMENT ON TRANSFORM FOR hstore LANGUAGE plpython3u IS 'Transform between hstore and Python dict';
COMMENT ON TRIGGER my_trigger ON my_table IS 'Used for RI';
COMMENT ON TYPE complex IS 'Complex number data type';
COMMENT ON VIEW my_view IS 'View of departmental costs';
COMMENT ON VIEW my_view IS NULL;

Compatibility

SQL 표준에는 COMMENT 명령이 없어요.

COMMENT — 객체의 주석 정의하거나 변경하기