Os exemplos de SQL utilizam PostgreSQL, a menos que outro dialeto seja mencionado. Excertos curtos pressupõem que as suas tabelas referenciadas já existem. Valide o DDL na sua base de dados de destino antes de o aplicar.
Por que razão a documentação da base de dados falha
A documentação da base de dados torna-se frequentemente obsoleta porque é escrita separadamente do esquema. Alguém cria um diagrama durante o primeiro sprint de design, a base de dados muda durante seis meses e a documentação torna-se silenciosamente enganadora.
Uma abordagem melhor é manter a documentação próxima da fonte SQL. Gere diagramas a partir de DDL, adicione explicações curtas para tabelas e relacionamentos e atualize os documentos sempre que o esquema mudar.
O que incluir na documentação do esquema
A documentação útil de bases de dados responde às perguntas que os programadores realmente fazem enquanto constroem funcionalidades e depuram dados de produção.
- Um ERD. Mostrar tabelas, chaves primárias, chaves estrangeiras e os principais caminhos de relacionamento.
- Notas sobre o propósito da tabela. Explique por que razão cada tabela principal existe e qual a funcionalidade que a detém.
- Regras de relacionamento. Destaque a cardinalidade, relações opcionais e ações em cascata.
- Restrições importantes. Documente chaves únicas, verificações, valores de enumeração e regras de negócio impostas pelo SQL.
- Contexto de migração. Ligar alterações de esquema à funcionalidade, correção de erro ou motivo operacional por trás delas.
Bloco de Documentação de Exemplo
Uma entrada de documentação leve pode emparelhar SQL com notas em linguagem simples:
CREATE TABLE accounts (
id BIGINT GENERATED ALWAYS AS IDENTITY PRIMARY KEY,
name TEXT NOT NULL
);
CREATE TABLE invoices (
id BIGINT GENERATED ALWAYS AS IDENTITY PRIMARY KEY,
account_id BIGINT NOT NULL REFERENCES accounts (id),
status VARCHAR(30) NOT NULL DEFAULT 'draft',
total NUMERIC(12, 2) NOT NULL CHECK (total >= 0),
due_date DATE,
created_at TIMESTAMPTZ NOT NULL DEFAULT now()
);
CREATE TABLE invoice_payments (
id BIGINT GENERATED ALWAYS AS IDENTITY PRIMARY KEY,
invoice_id BIGINT NOT NULL REFERENCES invoices (id) ON DELETE CASCADE,
amount NUMERIC(12, 2) NOT NULL CHECK (amount > 0),
paid_at TIMESTAMPTZ NOT NULL DEFAULT now()
);As notas de documentação podem dizer: uma conta tem muitas faturas, as faturas têm muitos registos de pagamento e as linhas de pagamento são eliminadas se uma fatura de teste for eliminada. Em sistemas de produção com requisitos de auditoria, poderá substituir eliminações em cascata por eliminações restritas e registos de arquivo.
Um Fluxo de Trabalho de Documentação Prático
Aqui está um fluxo de trabalho que mantém os documentos úteis sem transformar a documentação num trabalho a tempo inteiro.
- Comece com o esquema SQL e gere um ERD no Editor do Erd Go.
- Exportar o diagrama ou iniciar sessão, salvar, e partilhar uma ligação pública de apenas leitura quando o esquema for apropriado para acesso público. Utilize exportações de imagem para documentação privada.
- Adicione um parágrafo curto para cada agrupamento de tabelas importante: auth, billing, orders, content, audit ou reporting.
- Regere o ERD a partir do SQL atualizado durante as migrações para que a documentação reflita o que mudou.
- Mantenha os exemplos de sintaxe em sincronia com o Documentação DDL do Erd Go para que futuros colaboradores possam reproduzir o diagrama.
O objetivo não é uma enciclopédia perfeita. O objetivo é um mapa vivo que ajude as pessoas a compreender rapidamente a base de dados e a confiar no que estão a ler.



