COMMENT

COMMENT
Anterior	Acima	Comandos SQL	Principal	Próxima

COMMENT — define ou modifica o comentário de um objeto

Sinopse

COMMENT ON
{
  ACCESS METHOD nome_do_objeto |
  AGGREGATE nome_da_agregação ( assinatura_da_agregação ) |
  CAST (tipo_de_dados_origem AS tipo_de_dados_destino) |
  COLLATION nome_do_objeto |
  COLUMN nome_da_relação.nome_da_coluna |
  CONSTRAINT nome_da_restrição ON nome_da_tabela |
  CONSTRAINT nome_da_restrição ON DOMAIN nome_do_domínio |
  CONVERSION nome_do_objeto |
  DATABASE nome_do_objeto |
  DOMAIN nome_do_objeto |
  EXTENSION nome_do_objeto |
  EVENT TRIGGER nome_do_objeto |
  FOREIGN DATA WRAPPER nome_do_objeto |
  FOREIGN TABLE nome_do_objeto |
  FUNCTION nome_da_função
      [ ( [ [ modo_do_argumento ]
      [ nome_do_argumento ] tipo_de_dados_do_argumento
      [, ...] ] ) ] |
  INDEX nome_do_objeto |
  LARGE OBJECT oid_de_objeto_grande |
  MATERIALIZED VIEW nome_do_objeto |
  OPERATOR nome_do_operador (tipo_esquerdo, tipo_direito) |
  OPERATOR CLASS nome_do_objeto USING método_de_índice |
  OPERATOR FAMILY nome_do_objeto USING método_de_índice |
  POLICY nome_da_política ON nome_da_tabela |
  [ PROCEDURAL ] LANGUAGE nome_do_objeto |
  PROCEDURE nome_do_procedimento
      [ ( [ [ modo_do_argumento ]
      [ nome_do_argumento ] tipo_de_dados_do_argumento
      [, ...] ] ) ] |
  PUBLICATION nome_do_objeto |
  ROLE nome_do_objeto |
  ROUTINE nome_da_rotina
      [ ( [ [ modo_do_argumento ]
      [ nome_do_argumento ] tipo_de_dados_do_argumento
      [, ...] ] ) ] |
  RULE nome_da_regra ON nome_da_tabela |
  SCHEMA nome_do_objeto |
  SEQUENCE nome_do_objeto |
  SERVER nome_do_objeto |
  STATISTICS nome_do_objeto |
  SUBSCRIPTION nome_do_objeto |
  TABLE nome_do_objeto |
  TABLESPACE nome_do_objeto |
  TEXT SEARCH CONFIGURATION nome_do_objeto |
  TEXT SEARCH DICTIONARY nome_do_objeto |
  TEXT SEARCH PARSER nome_do_objeto |
  TEXT SEARCH TEMPLATE nome_do_objeto |
  TRANSFORM FOR nome_do_tipo_de_dados LANGUAGE nome_da_linguagem |
  TRIGGER nome_do_gatilho ON nome_da_tabela |
  TYPE nome_do_objeto |
  VIEW nome_do_objeto
} IS { literal_de_cadeia_de_caracteres | NULL }

onde assinatura_da_agregação é:

* |
[ modo_do_argumento ] [ nome_do_argumento ] tipo_de_dados_do_argumento
    [ , ... ] |
[ [ modo_do_argumento ] [ nome_do_argumento ] tipo_de_dados_do_argumento
    [ , ... ] ]
    ORDER BY [ modo_do_argumento ] [ nome_do_argumento ] tipo_de_dados_do_argumento
    [ , ... ]

Descrição

O comando COMMENT armazena comentário sobre o objeto de banco de dados.

Apenas uma cadeia de caracteres de comentário é armazenada para cada objeto, portanto, para modificar um comentário, deve ser executado um novo comando COMMENT para o mesmo objeto. Para remover um comentário, deve ser escrito NULL no lugar da cadeia de caracteres de texto. Os comentários são excluídos automaticamente quando seu objeto é excluído.

É adquirido um bloqueio SHARE UPDATE EXCLUSIVE no objeto recebendo o comentário.

Para a maioria dos tipos de objeto, apenas o dono do objeto pode definir um comentário. As funções de banco de dados (roles) não têm dono, portanto a regra para COMMENT ON ROLE é que é necessário ser um superusuário para definir um comentário sobre uma função de banco de dados de superusuário, ou ter o privilégio CREATEROLE e ter recebido o privilégio ADMIN OPTION na função de banco de dados alvo. Da mesma forma, os métodos de acesso também não possuem donos; então é necessário ser um superusuário para definir um comentário sobre um método de acesso. É claro que um superusuário pode definir um comentário sobre qualquer coisa.

Os comentários podem ser vistos usando a família de comandos \d do psql. Outras interfaces de usuário para recuperar comentários podem ser construídas sobre as mesmas funções internas que o psql usa, ou seja, obj_description, col_description, e shobj_description (veja Tabela 9.82).

Parâmetros

nome_do_objeto nome_da_relação.nome_da_coluna nome_da_agregação nome_da_restrição nome_da_função nome_do_operador nome_da_política nome_do_procedimento nome_da_rotina nome_da_regra nome_do_gatilho: O nome do objeto recebendo o comentário. Nomes de objetos que residem em esquemas (tabelas, funções, etc.) podem ser qualificados pelo esquema. Ao definir o comentário para uma coluna, o nome_da_relação deve referir-se a uma tabela, visão, tipo de dados composto, ou tabela estrangeira.
nome_da_tabela nome_do_domínio: Ao definir um comentário sobre restrição, gatilho, regra, ou política, estes parâmetros especificam o nome da tabela ou do domínio onde o objeto está definido.
tipo_de_dados_origem: O nome do tipo de dados de origem da conversão.
tipo_de_dados_destino: O nome do tipo de dados de destino da conversão.
modo_do_argumento: O modo do argumento de uma função, procedimento, ou agregação: IN, OUT, INOUT, ou VARIADIC. Se omitido, o padrão é IN. Note que o comando COMMENT não presta atenção aos argumentos OUT, porque apenas os argumentos de entrada são necessários para determinar a identidade da função. Portanto, basta listar os argumentos IN, INOUT, e VARIADIC.
nome_do_argumento: O nome do argumento. Note que o comando COMMENT, na verdade, não presta atenção aos nomes dos argumentos, porque apenas os tipos de dados dos argumentos são necessários para determinar a identidade da função.
tipo_de_dados_do_argumento: O tipo de dados do argumento de uma função, procedimento ou agregação.
oid_de_objeto_grande: O OID do objeto grande.
tipo_esquerdo tipo_direito: Os tipos de dados dos argumentos do operador (opcionalmente qualificados pelo esquema). Deve ser escrito NONE para o argumento ausente de um operador de prefixo.
PROCEDURAL: Esta é uma palavra ruído.
nome_do_tipo_de_dados: O nome do tipo de dados da transformação.
nome_da_linguagem: O nome da linguagem da transformação.
literal_de_cadeia_de_caracteres: O novo conteúdo do comentário, escrito como um literal de cadeia de caracteres. ^[115].
NULL: Deve ser escrito NULL para remover o comentário.

Notas

Não há no momento nenhum mecanismo de segurança para visualização de comentários: qualquer usuário conectado a um banco de dados pode ver todos os comentários dos objetos neste banco de dados. Para objetos compartilhados, como bancos de dados, funções de banco de dados e espaços de tabelas, os comentários são armazenados globalmente para que qualquer usuário conectado a qualquer banco de dados da instância possa ver todos os comentários para os objetos compartilhados. Portanto, não devem ser colocadas informações críticas de segurança nos comentários.

Exemplos

Anexar um comentário à tabela minha_tabela:

COMMENT ON TABLE minha_tabela IS 'Esta é a minha tabela.';

Remoção do comentário:

COMMENT ON TABLE minha_tabela IS NULL;

Alguns outros exemplos:

COMMENT ON ACCESS METHOD gin
    IS 'Método de acesso a índice GIN';
COMMENT ON AGGREGATE minha_agregação (double precision)
    IS 'Calcula a variância da amostra';
COMMENT ON CAST (text AS int4)
    IS 'Permitir conversões de text para int4';
COMMENT ON COLLATION "fr_CA"
    IS 'Francês canadense';
COMMENT ON COLUMN minha_tabela.minha_coluna
    IS 'Número de identificação do funcionário';
COMMENT ON CONVERSION my_conv
    IS 'Conversão para UTF8';
COMMENT ON CONSTRAINT bar_col_cons ON bar
    IS 'Restrição da coluna bar';
COMMENT ON CONSTRAINT dom_col_constr ON DOMAIN dom
    IS 'Restrição da coluna de domínio';
COMMENT ON DATABASE meu_banco_de_dados
    IS 'Banco de dados de desenvolvimento';
COMMENT ON DOMAIN meu_domínio
    IS 'Domínio de endereço de e-mail';
COMMENT ON EVENT TRIGGER abort_ddl
    IS 'Aborta todos os comandos de DDL';
COMMENT ON EXTENSION hstore
    IS 'Implementa o tipo de dados hstore';
COMMENT ON FOREIGN DATA WRAPPER meu_empacotador
    IS 'Meu empacotador de dados estrangeiros';
COMMENT ON FOREIGN TABLE minha_tabela_estrangeira
    IS 'Informações de funcionário em outro banco de dados';
COMMENT ON FUNCTION minha_função (timestamp)
    IS 'Retorna algarismo romano';
COMMENT ON INDEX meu_índice
    IS 'Obriga a unicidade do ID de funcionário';
COMMENT ON LANGUAGE plpython
    IS 'Linguagem procedural Python para procedimentos armazenados';
COMMENT ON LARGE OBJECT 346344
    IS 'Documento de planejamento';
COMMENT ON MATERIALIZED VIEW minha_visão_mat
    IS 'Resumo do histórico de pedidos';
COMMENT ON OPERATOR ^ (text, text)
    IS 'Realiza a interseção de dois textos';
COMMENT ON OPERATOR - (NONE, integer)
    IS 'Menos unário';
COMMENT ON OPERATOR CLASS int4ops USING btree
    IS 'Operadores inteiros de 4 bytes para Árvores-B';
COMMENT ON OPERATOR FAMILY integer_ops USING btree
    IS 'Todos os operadores inteiros para Árvores-B';
COMMENT ON POLICY minha_política ON minha_tabela
    IS 'Filtra linhas por usuários';
COMMENT ON PROCEDURE meu_procedimento (integer, integer)
    IS 'Executa um relatório';
COMMENT ON PUBLICATION todas_as_tabelas
    IS 'Publica todas as operações em todas as tabelas';
COMMENT ON ROLE minha_função_bd
    IS 'Grupo de administração para tabelas financeiras';
COMMENT ON ROUTINE minha_rotina (integer, integer)
    IS 'Executa uma rotina (que é uma função ou procedimento)';
COMMENT ON RULE minha_regra ON minha_tabela
    IS 'Registra atualizações de registros de funcionários';
COMMENT ON SCHEMA meu_esquema
    IS 'Dados departamentais';
COMMENT ON SEQUENCE minha_sequência
    IS 'Usado para gerar chaves primárias';
COMMENT ON SERVER meu_servidor
    IS 'Meu servidor estrangeiro';
COMMENT ON STATISTICS minhas_estatísticas
    IS 'Melhora as estimativas de linha do planejador';
COMMENT ON SUBSCRIPTION todas_as_tabelas
    IS 'Subscrição para todas as operações em todas as tabelas';
COMMENT ON TABLE meu_esquema.minha_tabela
    IS 'Informação sobre empregado';
COMMENT ON TABLESPACE meu_espaço_de_tabelas
    IS 'Espaço de tabelas para índices';
COMMENT ON TEXT SEARCH CONFIGURATION minha_configuração
    IS 'Filtragem de palavras especiais';
COMMENT ON TEXT SEARCH DICTIONARY swedish
    IS 'Lematizador Snowball para o idioma da Suécia';
COMMENT ON TEXT SEARCH PARSER meu_analisador
    IS 'Divide o texto em palavras';
COMMENT ON TEXT SEARCH TEMPLATE snowball
    IS 'Lematizador Snowball';
COMMENT ON TRANSFORM FOR hstore LANGUAGE plpython3u
    IS 'Transforma entre hstore e Python dict';
COMMENT ON TRIGGER meu_gatilho ON minha_tabela
    IS 'Usado para integridade referencial';
COMMENT ON TYPE complex
    IS 'Tipo de dados de número complexo';
COMMENT ON VIEW minha_visão
    IS 'Visão dos custos departamentais';

Conformidade

Não existe o comando COMMENT no padrão SQL.

^[115] Um literal de cadeia de caracteres (string literal) é uma sequência fixa de caracteres delimitada, interpretada exatamente como escrita na programação. (N. T.)