Skip to content

[Claude] Descrições no diagrama e exportação para IA - #17

Merged
leoars merged 3 commits into
mainfrom
pgms-045-diagram-descriptions
Nov 13, 2026
Merged

leoars merged 3 commits into
mainfrom
pgms-045-diagram-descriptions

Conversation

@leoars

@leoars leoars commented Nov 12, 2026

Copy link
Copy Markdown
Owner

What changed / O que mudou

Descrições no diagrama e exportação para IA (PGMS-045, build M1062 da fonte de desenvolvimento). Empilhado sobre o PR #16 (pgms-044-diagram-indexes): faça o merge do #16 primeiro. Sugestão de um usuário: o que mais ajudou o agente de IA dele foi documentar a modelagem e fazer o agente ler esse documento antes de escrever SQL.

  • Ícone de descrição (uma pequena página) na tabela, na coluna e na relação que têm COMMENT ON, com o texto na dica. Clicar no ícone abre a descrição.
  • Description Property, como o diálogo que o SSMS 22.11 abre pelo "…" da janela Properties. Abre por Table Description…, Column Description…, Relationship Description… ou pelo ícone. Limite de 4 KiB em UTF-8.
  • Aplicação no Save do diagrama, como as outras mudanças: a tabela ganha *, e o COMMENT ON entra no script revisado e na transação do Save. Quando uma tabela só tem descrições alteradas, o Save não pede ACCESS EXCLUSIVE. Antes de gravar, ele confere a tabela pelo OID, a coluna pelo attnum e pelo nome, a FK pelo nome, e que a descrição não mudou no banco desde a leitura.
  • Tabelas de outro dono: as descrições delas saem da transação e o resto do Save continua. Elas ficam no JSON como não aplicadas ("applied": false), e o script vai para o dono. Script Unapplied Descriptions… mostra esse script de novo.
  • JSON do diagrama, formato 3: cada Save grava uma cópia das descrições lida do catálogo. Quando o banco muda depois, o ícone fica laranja e mostra os dois textos, sem marcar o diagrama como alterado.
  • Export for AI… (menu da área vazia): Markdown em inglês com as tabelas do diagrama, colunas, chaves, checks, FKs, quem referencia cada tabela, índices e descrições. Tem Copy e Save As.
  • pgms.diagram_markdown(diagram_name), opcional: roda a mesma consulta SQL do Export for AI, então o texto sai idêntico. É STABLE, SECURITY INVOKER e tem search_path fixo. Pode ser instalada pelo menu AI Export Function… ou pela caixa, desmarcada por padrão, de Install Diagram Support.
  • Guia "Using diagrams with AI agents" EN/pt-BR e notas de versão em "em desenvolvimento".

Why / Por quê

O SSMS 22.11 foi pilotado antes, numa instância própria e num banco descartável do LocalDB:

  • O diagrama não marca nada que tenha descrição.
  • A descrição fica na janela Properties; o "…" abre Description Property, a tabela ganha *, e o save usa sp_updateextendedproperty.
  • Não há exportação para IA.

O diálogo e o fluxo "pendente até o Save" seguem o SSMS. São acréscimos do PGMS, sem alegação de paridade:

  • o ícone e as dicas;
  • a cópia no JSON e o aviso de divergência;
  • o tratamento das tabelas de outro dono;
  • o Export for AI e a função.

Validation actually run / Validação realmente executada

Nesta pilha de branches, no PostgreSQL 17.11, em cluster isolado em loopback:

  • Test-Integration.ps1 -DiagramsOnly: 282 integração + 449 WPF, antes das correções do PR seguinte. Cobre:
    • COMMENT ON de tabela, coluna e constraint, com escape;
    • o limite de 4 KiB;
    • as guardas (descrição alterada no banco, coluna renomeada, tabela recriada com o mesmo nome);
    • tabela de outro dono com um papel que não é superusuário;
    • o JSON formato 3;
    • o Markdown, comparado com um snapshot;
    • a função igual ao Export for AI;
    • a interface: ícones, Description Property, divergência, Export for AI, AI Export Function, Install Diagram Support.
  • Test-PublicDocumentation.ps1: válido.

Na fonte de desenvolvimento, com o mesmo código, a regressão completa no PG 17.11 deu 3.018 de integração + 4.560 WPF = 7.578, na primeira rodada.

Não executado:

  • regressão completa nesta branch;
  • PostgreSQL 16 e 18;
  • mouse e teclado reais;
  • leitura do Markdown por um agente de IA real.

Limites conhecidos:

  • Não guarda o OID da constraint: uma FK apagada e recriada com o mesmo nome passa pela guarda.
  • No Markdown, crase em nome de objeto não é escapada.
  • O tamanho do Markdown num banco grande não foi medido.
  • Criar a função exige CREATE no schema pgms, e quem a chama precisa de SELECT em pgms.diagrams.

🤖 Generated with Claude Code

@leoars
leoars changed the base branch from pgms-044-diagram-indexes to main November 13, 2026 02:44
leoars and others added 2 commits November 12, 2026 23:44
Tabela, coluna e relação do diagrama ganham descrição (COMMENT ON),
editada em Description Property e aplicada no Save depois da revisão do
script, com ícone e texto na dica. Tabela de outro dono: a descrição fica
no diagrama como não aplicada, com o script para o dono. Cópia das
descrições no JSON (formato 3), com aviso quando o banco mudou. Export for
AI… em Markdown e função opcional pgms.diagram_markdown com a mesma
consulta. Guias e notas EN/pt-BR. Sugestão de um usuário.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@leoars
leoars force-pushed the pgms-045-diagram-descriptions branch from ab428fa to 2463d54 Compare November 13, 2026 02:44
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@leoars
leoars merged commit e975dd9 into main Nov 13, 2026
1 check passed
@leoars
leoars deleted the pgms-045-diagram-descriptions branch November 13, 2026 02:51
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant