Documentando Objetos no PostgreSQL

Onde guardar a documentação sobre os objetos do seu banco de dados? A importância a e grande quantidade de informação sobre tabelas, seus campos, índices e outros objetos faz com que essa questão ganhe importância. Um bom lugar para fazer esse registro é justamente o próprio banco de dados. No PostgreSQL é possível se comentar os objetos armazenados no banco, atualizar, remover e consultar essas informações, através do comando COMMENT.

O comando COMMENT armazena um comentário textual associado a um objeto do banco de dados. Sua sintaxe é relativamente simples:

COMMENT ON
{
 TABLE object_name |
 COLUMN table_name.column_name |
 AGGREGATE agg_name (agg_type [, ...] ) |
 CAST (sourcetype AS targettype) |
 CONSTRAINT constraint_name ON table_name |
 CONVERSION object_name |
 DATABASE object_name |
 DOMAIN object_name |
 FUNCTION func_name ( [ [ argmode ] [ argname ] argtype [, ...] ] ) |
 INDEX object_name |
 LARGE OBJECT large_object_oid |
 OPERATOR op (leftoperand_type, rightoperand_type) |
 OPERATOR CLASS object_name USING index_method |
 OPERATOR FAMILY object_name USING index_method |
 [ PROCEDURAL ] LANGUAGE object_name |
 ROLE object_name |
 RULE rule_name ON table_name |
 SCHEMA object_name |
 SEQUENCE 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 |
 TRIGGER trigger_name ON table_name |
 TYPE object_name |
 VIEW object_name
} IS 'text'

A grande lista de tipos de objetos para os quais o comando pode criar comentários é bastante abrangente. Compreende tabelas, campos de tabelas, índices, tablespaces, esquemas, databases, tipos, funções, etc. Os comentários são armazenados em campos TEXT, que permitem documentações largamente detalhadas.

Os comentários são consultados por meio do utilitário PSQL e de algumas funções disponibilizadas pelo PostgreSQL (obj_description, col_description, and shobj_description).

• Exemplos de Código - Criação de Comentário
  

1 - Criação de Objetos do Tipo Tabela.

create table starttest (col int);
create table starttest2 (col int);

2 - Definição de Comentários

COMMENT ON TABLE starttest IS 'Tabela do sistema SITP';
COMMENT ON TABLE starttest2 IS 'SITP - Modulo II';

3 - Remoção de Comentários

COMMENT ON TABLE starttest IS NULL;

• Exemplos de Código - Consulta de Comentários

1 - Recuperação de OID de objeto em PG_CLASS.

SELECT relname, relfilenode
FROM PG_CLASS
WHERE relname LIKE 'starttest%';

2 - Consulta dos commentários associados pelo OID.

SELECT obj_description(17173);

3 - Consulta dos comentários de todos os objetos de PG_CLASS.

SELECT obj_description(p.relfilenode), * from pg_class p;

4 - Consulta dos comentários de todos os objetos de PG_TYPE.

SELECT obj_description(p.typrelid), * from PG_TYPE p;

• Utilizaçao Prática
  

O uso do comando COMMENT para documentar objetos do banco é pouco difundido em parte pelo fato do mesmo ser pouco conhecido, não apresentar similares em alguns SGBDs e por não ser gerado por muitas das ferramentas do mercado, que armazenam estas informações em formato próprio, sem transferi-las ao SGBD.

Também existem questões de segurança, pois um usuário malicioso que tenha acesso ao banco pode recuperar os comentários sobre os seus objetos. No entanto, o interesse real dos invasores de bancos de dados se refere às informações armazenadas, e não à documentação dos bancos de dados.

Deve ser evitado armazenar qualquer informação crítica para a segurança com o comando COMMENT, tais como senhas, informações sobre criptografia e política de acesso utilizados, uma vez que não existem restrições de segurança para os comentários armazenados, isto é, qualquer usuário criado no SGBD visualiza todas as informações.

Os comentários são exportados ao se fazer um backup do banco com os utilitários do PostgreSQL.