Como documentar objetos de banco de dados com anotações

Todo banco de dados os possui. Um conjunto de colunas — ou mesmo tabelas inteiras — que ninguém consegue explicar por que eles existem. Qualquer documentação sobre eles (se alguma vez existiu) está perdida há muito tempo em seu wiki corporativo.

Para ajudá-lo a entender seu esquema, seria melhor registrar notas dentro do banco de dados, de preferência ao lado das colunas e tabelas. Isso permitiria que você visualizasse esses detalhes em suas ferramentas ou consultando o dicionário de dados.

A maioria dos sistemas de banco de dados permite fazer isso com comentários de objetos. Por exemplo, no Oracle Database, você pode fazer isso com o comando COMMENT comando:

Essas informações aparecem nas visualizações do dicionário de comentários do objeto correspondente:

Essa é uma ótima maneira de ajudar outros desenvolvedores e administradores de banco de dados (DBAs) a entender seus esquemas.

Mas os comentários são apenas uma string. Isso os torna difíceis de usar se você deseja armazenar muitas propriedades sobre um objeto.

Por exemplo, é comum que as tabelas do banco de dados incluam um INSERT_DATETIME coluna. Todas essas colunas devem ser:

• Gerado pelo sistema: O banco de dados deve fornecer os valores usando padrões de coluna.
• Obrigatório: Não são permitidos valores nulos.
• Insira apenas: Esses valores nunca devem ser atualizados.

Estas informações estão relacionadas à sua intenção de usar os dados: não se trata apenas de por que essas colunas existem, mas de como interagir com elas. O registro desses detalhes ajuda os futuros mantenedores a entender como usar esses dados em aplicativos.

Você pode armazenar essas propriedades junto com outras notas nos comentários. A questão é qual formato você usa? JSON? XML? Pares de valores-chave delimitados?

Seja qual for sua escolha, você precisa que todos os futuros mantenedores sigam o mesmo formato. Isso se torna um desafio para sistemas de longa vida. Seria melhor se o próprio banco de dados impusesse alguma estrutura aos comentários.

O Oracle Database 23c resolveu isso adicionando anotações de uso.

Melhor documentação de banco de dados com anotações

As anotações são chaves com valores opcionais. Você pode usá-los para registrar quaisquer metadados que desejar sobre o objeto em questão.

Por exemplo, isso anota o INSERT_DATETIME coluna com as propriedades listadas acima:

Você pode estar se perguntando por que Allow_writes usa um array JSON, mesmo que haja apenas um valor. Por que não usar apenas a string “insert”?

Você provavelmente desejará aplicar esta anotação a muitas colunas. Eles também podem oferecer suporte a atualizações ou exclusões. Torná-los todos arrays torna-os mais fáceis de processar em comparação com uma mistura de arrays e strings simples.

Depois de adicionar as anotações, você poderá visualizá-las no *_usage_annotations Visualizações:

Essas visualizações mostram anotações para todos os tipos de objetos. Isso significa que todos eles estão acessíveis em um único local, o que simplifica o acesso programático às anotações para gerar documentação separada, se desejar.

A estrutura de valores-chave das anotações as torna mais poderosas que os comentários.

Mas ainda há um desafio quando você os usa para valores comuns. A maioria ou todas as tabelas em um esquema terão um INSERT_DATETIME coluna. Todos devem ter anotações idênticas. Tentar manter tudo isso sincronizado ao longo do tempo é difícil!

Em vez de copiar as anotações para cada INSERT_DATETIME coluna, seria melhor defini-los uma vez em um objeto compartilhado. Em seguida, aplique este objeto a todas as colunas que precisam dele. Isso garante que todos tenham as mesmas propriedades.

A questão é: como?

Padronize anotações com domínios

O Oracle Database 23c resolveu isso adicionando domínios de uso. Eles se baseiam em domínios no padrão SQL. Eles estendem os tipos de dados existentes com propriedades opcionais, incluindo:

• Restrições
• Padrões
• Anotações
• …

Use o CREATE DOMAIN declaração para fazer uma. Isto cria um INSERT_DATETIME domínio com as anotações acima:

Você pode então aplicar esse domínio a colunas ao criar ou alterar tabelas. Faça isso especificando o domínio em vez do tipo de dados ou usando a cláusula domain após o tipo de dados. Isso copia as anotações do domínio para as colunas da tabela:

Para vincular um domínio a uma coluna, ambos devem ter o mesmo tipo de dados base. Você só pode associar o INSERT_DATETIME domínio com timestamp colunas, não date, number, varchar2etc.

Com essa definição centralizada, você pode ter certeza de que todas as colunas que usam um domínio terão as mesmas anotações. Isto se aplica mesmo se você quiser alterá-los no futuro.

Por exemplo, você pode querer especificar que permite operações de filtragem e classificação em carimbos de data/hora de inserção, o que significa que é seguro usar essas colunas no WHERE e ORDER BY cláusulas.

Você pode alterar o domínio para adicionar estas anotações:

O banco de dados aplica-os automaticamente às colunas correspondentes do banco de dados:

Intenção dos dados do documento

Os esquemas de banco de dados podem ser complexos. Compreender o propósito de cada parte pode ser complicado. Ao documentar isso no próprio esquema, você ajuda todos a saber como e por que cada bit.

Os comentários são uma forma amplamente utilizada de registrar esses detalhes. A sua natureza não estruturada limita a sua utilidade. A estrutura de valores-chave das anotações no Oracle Database 23c oferece mais poder.

No Oracle Database 23c, você também pode definir domínios. Eles fornecem um único ponto de definição para valores de dados comuns, como a inserção de carimbos de data/hora.

A combinação de domínios e anotações oferece uma maneira simples de descrever dados. Juntos, eles formam uma nova classe de instruções SQL: linguagem de intenção de dados (DIL).

À medida que os esquemas crescem, o uso dessas instruções DIL será fundamental para ajudar outros desenvolvedores a entender por que e como usá-las.

Ajude seus colegas desenvolvedores e DBAs: Documente seu banco de dados com domínios e anotações!

A postagem Como documentar objetos de banco de dados com anotações apareceu pela primeira vez em The New Stack.