Voltar a todos os guias
Projeto de bancos de dados··3 min de leitura

Documentação de bases de dados: explique o esquema SQL com diagramas ERD

Documente esquemas de bases de dados com ERDs, exemplos de SQL, notas de relação e contexto de migração para que as equipas possam compreender os modelos de Dados mais rapidamente.

Um diagrama de cliente-para-encomenda ao lado de notas que explicam a chave estrangeira e a regra de negócio
Neste guia
  1. Por que razão a documentação da base de dados falha
  2. O que incluir na documentação do esquema
  3. Bloco de Documentação de Exemplo
  4. Um Fluxo de Trabalho de Documentação Prático
  5. Referências e leitura adicional

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.

Esquema SQL, diagrama ERD, notas de relação e contexto de migração combinados em documentação
Uma documentação de base de dados robusta associa a fonte SQL a um ERD e a breves notas sobre relações, para que a documentação se mantenha prática.

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.

Referências e leitura adicional

Mais publicações