Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -20,6 +20,8 @@ English | [Português (Brasil)](README.pt-BR.md)

See your schema the way you see it in SSMS. Add tables and their related tables, drag one column onto another to create a foreign key, change columns and primary keys inside the diagram, and let **Arrange Tables** lay everything out. Every change to the database is shown as a SQL script for review first. Diagrams are saved on the server, in a small `pgms` schema that PGMS asks permission to create.

Diagrams also show each table's **indexes** (GIN, GiST, BRIN and operator classes such as `gin_trgm_ops`, in a section closed by default) and warn about foreign keys that no index serves. Tables, columns and relationships can carry **descriptions**, stored as PostgreSQL `COMMENT ON`. **Export for AI…** writes the diagram as Markdown (columns, keys, relationships, indexes and descriptions) to give an AI agent before it writes SQL; an optional `pgms.diagram_markdown(name)` function returns the same text inside the database. See [Using diagrams with AI agents](docs/en/user-guide.md#using-diagrams-with-ai-agents).

### Visual query designer

![The Query Designer with the Diagram, Criteria and SQL panes](docs/assets/pgms-query-designer.png)
Expand Down
2 changes: 2 additions & 0 deletions README.pt-BR.md
Original file line number Diff line number Diff line change
Expand Up @@ -20,6 +20,8 @@

Veja o seu schema como no SSMS. Adicione tabelas e as tabelas relacionadas, arraste uma coluna sobre outra para criar uma chave estrangeira, altere colunas e chaves primárias dentro do diagrama e deixe o **Arrange Tables** organizar tudo. Toda alteração no banco aparece antes como script SQL para revisão. Os diagramas ficam salvos no servidor, num pequeno schema `pgms` que o PGMS pede permissão para criar.

O diagrama também mostra os **índices** de cada tabela (GIN, GiST, BRIN e classes de operadores como `gin_trgm_ops`, numa seção recolhida por padrão) e avisa das chaves estrangeiras sem índice. Tabelas, colunas e relações podem ter **descrições**, gravadas como `COMMENT ON` do PostgreSQL. **Export for AI…** gera o diagrama em Markdown (colunas, chaves, relações, índices e descrições) para entregar a um agente de IA antes de ele escrever SQL; a função opcional `pgms.diagram_markdown(nome)` devolve o mesmo texto dentro do banco. Veja [Usando diagramas com agentes de IA](docs/pt-BR/user-guide.md#usando-diagramas-com-agentes-de-ia).

### Query Designer visual

![O Query Designer com os painéis Diagram, Criteria e SQL](docs/assets/pgms-query-designer.png)
Expand Down
3 changes: 2 additions & 1 deletion docs/en/release-notes.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,8 @@ Fifth public pre-release of PGMS. It is an alpha for evaluation with synthetic/d

These changes are on `main` and will be part of the next pre-release; the downloads below are still v0.1.0-alpha.5.

- **Indexes in database diagrams.** Each table of a diagram has an **Indexes** section, closed by default, with one row per index when opened: method (GIN, GiST, SP-GiST, BRIN, Hash), key columns or expressions, operator class when not the default (such as `gin_trgm_ops`), `INCLUDE`, UNIQUE, EXCLUDE, partial and invalid, with the predicate and the full `CREATE INDEX` in the tooltip. A warning marks a table with a foreign key that no index serves and opens **Find Unindexed Foreign Keys…**, which also arrives in this change: on a database in Object Explorer it lists such keys from the catalog and creates the indexes from a reviewed script, concurrently or in one transaction. **Show Indexes** and **Refresh** are in the diagram menu. Each save writes the indexes of each table into the diagram definition (format 2) for tools and AI agents that read it; older diagrams open unchanged. Read only: indexes are still created in **Indexes/Keys…**. SSMS 22.11 shows no indexes in a diagram. Suggested by a PGMS user.
- **Indexes in database diagrams.** Each table of a diagram has an **Indexes** section, closed by default, with one row per index when opened: method (GIN, GiST, SP-GiST, BRIN, Hash), key columns or expressions, operator class when not the default (such as `gin_trgm_ops`), `INCLUDE`, UNIQUE, EXCLUDE, partial and invalid, with the predicate and the full `CREATE INDEX` in the tooltip. A warning marks a table with a foreign key that no index serves and opens **Find Unindexed Foreign Keys…**, which also arrives in this change: on a database in Object Explorer it lists such keys from the catalog and creates the indexes from a reviewed script, concurrently or in one transaction. **Show Indexes** and **Refresh** are in the diagram menu. Each save writes the indexes of each table into the diagram definition for tools and AI agents that read it; older diagrams open unchanged. Read only: indexes are still created in **Indexes/Keys…**. SSMS 22.11 shows no indexes in a diagram. Suggested by a PGMS user.
- **Descriptions in database diagrams and Export for AI.** A table, column or relationship of a diagram can have a description, which is its PostgreSQL `COMMENT ON`, so any tool that reads the catalog sees it. Edit it in **Description Property** from the table, column or relationship menu (or click the small page icon that marks a described item, with the text in its tooltip); **Save** applies it after the script review, like every change in a diagram. If you do not own the table, the description is kept in the diagram as not applied and PGMS shows the script to send to the owner. Each save keeps a copy of the descriptions in the diagram definition (format 3); when the database changed one since, the diagram shows the database text and an orange icon. **Export for AI…** writes the tables of the diagram as Markdown (columns, keys, relationships, indexes and descriptions, in a fixed order, with an instruction for the agent at the top) to copy or save, for a system prompt, a `CLAUDE.md` or an `AGENTS.md`. The optional function `pgms.diagram_markdown(name)`, created only after you review its script, returns the same text to an agent connected to the database. See [Using diagrams with AI agents](user-guide.md#using-diagrams-with-ai-agents). In SSMS 22.11 descriptions are edited in the Properties window; the icons, the copy and the export are PGMS additions. Suggested by a PGMS user.

## What changed since v0.1.0-alpha.4

Expand Down
20 changes: 19 additions & 1 deletion docs/en/user-guide.md
Original file line number Diff line number Diff line change
Expand Up @@ -20,7 +20,7 @@ Identity and sequence operations distinguish configured START from RESTART. A re

In Object Explorer, right-click **Database Diagrams** under a database and choose **New Database Diagram**. The first time, PGMS asks to create its support objects (schema `pgms`). Add tables with **Add Table** or **Add Related Tables**, drag a column onto another to create a foreign key, and use **Arrange Tables** to lay them out. Saving shows the SQL script of any change to the database for review.

**Indexes.** Each table shows an **Indexes** section below its columns, closed by default so diagrams laid out before keep their spacing: the header gives the count and the methods other than b-tree (for example `Indexes (3) · GIN`), and its tooltip lists every index. Click the header to show one row per index: name, method when it is not b-tree (Hash, GIN, GiST, SP-GiST, BRIN), key columns or expressions, the operator class when it is not the default (such as `gin_trgm_ops`, `jsonb_path_ops` or `text_pattern_ops`), `INCLUDE` columns, and UNIQUE, EXCLUDE, partial or invalid. The row tooltip has the predicate of a partial index and the full `CREATE INDEX`. A gold key marks the primary key, a silver key a unique or exclusion constraint, and a tree a plain index. A warning triangle in the title marks a table with a foreign key that no index serves, by the same rule as **Find Unindexed Foreign Keys…**; click it, or use the item of the table menu, to open that window. **Show Indexes** in the diagram menu turns the sections and the warning off and on for that diagram, and **Refresh** reads the tables and their indexes again. The section is read only: create or change indexes in **Indexes/Keys…** (double-click an index row) and the other dialogs. Every save writes the indexes of each table, read from the catalog inside the save transaction, into the diagram definition (`pgms.diagrams.definition`, format 2), so tools and AI agents that read the diagram see them; changes made only in the database do not mark the diagram as changed and reach the definition on its next save. Diagrams saved by earlier versions open as they were and are written in the new format by their next save. SSMS 22.11 shows no indexes in a diagram; this section is a PGMS addition.
**Indexes.** Each table shows an **Indexes** section below its columns, closed by default so diagrams laid out before keep their spacing: the header gives the count and the methods other than b-tree (for example `Indexes (3) · GIN`), and its tooltip lists every index. Click the header to show one row per index: name, method when it is not b-tree (Hash, GIN, GiST, SP-GiST, BRIN), key columns or expressions, the operator class when it is not the default (such as `gin_trgm_ops`, `jsonb_path_ops` or `text_pattern_ops`), `INCLUDE` columns, and UNIQUE, EXCLUDE, partial or invalid. The row tooltip has the predicate of a partial index and the full `CREATE INDEX`. A gold key marks the primary key, a silver key a unique or exclusion constraint, and a tree a plain index. A warning triangle in the title marks a table with a foreign key that no index serves, by the same rule as **Find Unindexed Foreign Keys…**; click it, or use the item of the table menu, to open that window. **Show Indexes** in the diagram menu turns the sections and the warning off and on for that diagram, and **Refresh** reads the tables and their indexes again. The section is read only: create or change indexes in **Indexes/Keys…** (double-click an index row) and the other dialogs. Every save writes the indexes of each table, read from the catalog inside the save transaction, into the diagram definition (`pgms.diagrams.definition`), so tools and AI agents that read the diagram see them; changes made only in the database do not mark the diagram as changed and reach the definition on its next save. Diagrams saved by earlier versions open as they were and are written in the new format by their next save. SSMS 22.11 shows no indexes in a diagram; this section is a PGMS addition.

## Query Designer

Expand Down Expand Up @@ -55,6 +55,24 @@ PGMS never loads, creates or configures the extension. The server needs `shared_

Filters (database, user, SQL text, minimum calls) and ordering run on the server before a 1,000-row limit. Clicking the Total, Mean, Max, Calls, Rows or metric headers reloads in that order; other headers sort only the loaded rows. **Window** shows cumulative values since the last reset, values since a saved baseline, or the last 5/15/60 minutes, computed by subtracting an earlier reading; sliding windows sample only while the window is open, and minimum/maximum are not available for a window. A top-N chart beside the grid follows the applied order. **Show Plan** opens the selected statement in a new query tab with `EXPLAIN (GENERIC_PLAN)`, without executing it or binding `$n` values. **Reset Selected** and **Reset All** call `pg_stat_statements_reset` after a confirmation whose default is No; the server decides whether the role may reset. Auto-refresh is optional and starts off. Filters, chart choices and baselines are stored per connection target in the PGMS state folder, without passwords or SQL results.

**Descriptions.** A table, a column or a relationship can have a description: it is the PostgreSQL `COMMENT ON` of that object, so every tool that reads the catalog sees it. A small page icon marks a described table (in its title), column (at the end of its row) and relationship (on its line), and its tooltip shows the text. Right-click and choose **Table Description…**, **Column Description…** or **Relationship Description…**, or click the icon, to open **Description Property**: free text of several lines, up to 4 KiB of UTF-8. The change stays in the diagram, the table shows `*`, and **Save** applies it with `COMMENT ON` after the script review, like every change made in a diagram; **Generate Change Script…** shows it before. A change that is only descriptions does not lock the table: PGMS checks that the table, column or key is still the one the diagram read (by OID and name) and that nobody changed that description in the meantime. PostgreSQL lets only the owner of a table change its descriptions. When you do not own it, Save keeps the description only in the diagram, marked as not applied (an orange icon), and then shows the script to send to the owner; **Script Unapplied Descriptions…** in the table menu shows it again, and once the owner runs it the mark goes away. **Description Property** can also put that text back in the box or discard it. Each save writes a copy of the descriptions into the diagram definition (format 3), with the time the catalog was read. When the diagram opens or you choose **Refresh**, the catalog wins: if a description changed in the database since the save, the diagram shows the new text with an orange icon whose tooltip has the old copy, and the next save updates the copy. In SSMS 22.11, descriptions are edited in the Properties window of the diagram and saved as `MS_Description`; the icons, the copy and the export below are PGMS additions.

## Using diagrams with AI agents

An AI agent that writes SQL without seeing the model guesses column names and misses the indexes. A diagram with descriptions is that model, in three forms:

- **The catalog.** Descriptions are `COMMENT ON`, so an agent connected to the database (through psql, an MCP server of your choice or any client) reads them with `obj_description` and `col_description`, or `\d+` in psql.
- **Export for AI…** in the diagram menu writes the tables of the diagram as Markdown: an instruction for the agent at the top, then each table with its description, columns (type, null, default, description), keys and checks, foreign keys (with a note when no index serves one), the tables that reference it, and its indexes with their full definition, including the method and operator class (such as `gin_trgm_ops`). Tables and items come in a fixed order, so the same database gives the same text. **Copy** puts it on the clipboard and **Save As…** writes a `.md` file, ready for a system prompt, a `CLAUDE.md` or an `AGENTS.md`. The export reads the database as it is now: unsaved changes of the diagram are not in it.
- **`pgms.diagram_markdown(name)`**, optional. **AI Export Function…** in the diagram menu, or the box in **Install Diagram Support** (unchecked by default), creates this function in the schema `pgms` after you review its script. `SELECT pgms.diagram_markdown('Sales');` returns the same Markdown as the export, read from the catalog, for the saved diagram with that name, or NULL when there is none. It is read only, runs with the privileges of the caller, who needs `SELECT` on `pgms.diagrams`, and the same dialog removes it.

The saved diagram itself is the JSON in `pgms.diagrams.definition`: tables, positions, indexes and the copy of the descriptions, with `"applied": false` on descriptions that are not applied in the database.

An example of an instruction for the system prompt of an agent:

> Before writing SQL for the Sales database, read `docs/database-model.md` (exported from PGMS) or run `SELECT pgms.diagram_markdown('Sales');`. Use only the tables and columns listed there, with the names as written. If something you need is not there, ask instead of guessing a name. Check the indexes before filtering, joining or sorting large tables.

PGMS has no MCP server of its own.

## Backup and restore

Choose compatible PostgreSQL tools and a new output file/directory. Custom, tar, plain SQL and directory formats support the documented content choices. Restore uses an existing target database; compatible objects/roles and permissions must already exist where required. Ownership and privileges are explicit choices. Directory backup supports parallel dump; restore remains serial. Global operations cover roles/memberships/tablespaces, not a physical cluster backup.
Expand Down
3 changes: 2 additions & 1 deletion docs/pt-BR/release-notes.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,8 @@ Quinta pré-release pública do PGMS. É uma alpha para avaliação com dados si

Estas mudanças estão no `main` e farão parte da próxima pré-release; os downloads abaixo continuam sendo da v0.1.0-alpha.5.

- **Índices nos diagramas de banco.** Cada tabela de um diagrama tem uma seção **Indexes**, recolhida por padrão, com uma linha por índice quando aberta: método (GIN, GiST, SP-GiST, BRIN, Hash), colunas ou expressões da chave, classe de operadores quando não é a padrão (como `gin_trgm_ops`), `INCLUDE`, UNIQUE, EXCLUDE, parcial e inválido, com o predicado e o `CREATE INDEX` completo na dica. Um aviso marca a tabela com chave estrangeira que nenhum índice atende e abre **Find Unindexed Foreign Keys…**, que também chega nesta mudança: num banco do Object Explorer, lista essas chaves pelo catálogo e cria os índices a partir de um script revisado, de forma concorrente ou em uma transação. **Show Indexes** e **Refresh** ficam no menu do diagrama. Cada gravação escreve os índices de cada tabela na definição do diagrama (formato 2) para ferramentas e agentes de IA que a leem; diagramas antigos abrem sem mudança. Só leitura: índices continuam sendo criados em **Indexes/Keys…**. O SSMS 22.11 não mostra índices no diagrama. Sugestão de um usuário do PGMS.
- **Índices nos diagramas de banco.** Cada tabela de um diagrama tem uma seção **Indexes**, recolhida por padrão, com uma linha por índice quando aberta: método (GIN, GiST, SP-GiST, BRIN, Hash), colunas ou expressões da chave, classe de operadores quando não é a padrão (como `gin_trgm_ops`), `INCLUDE`, UNIQUE, EXCLUDE, parcial e inválido, com o predicado e o `CREATE INDEX` completo na dica. Um aviso marca a tabela com chave estrangeira que nenhum índice atende e abre **Find Unindexed Foreign Keys…**, que também chega nesta mudança: num banco do Object Explorer, lista essas chaves pelo catálogo e cria os índices a partir de um script revisado, de forma concorrente ou em uma transação. **Show Indexes** e **Refresh** ficam no menu do diagrama. Cada gravação escreve os índices de cada tabela na definição do diagrama para ferramentas e agentes de IA que a leem; diagramas antigos abrem sem mudança. Só leitura: índices continuam sendo criados em **Indexes/Keys…**. O SSMS 22.11 não mostra índices no diagrama. Sugestão de um usuário do PGMS.
- **Descrições nos diagramas de banco e exportação para IA.** Tabela, coluna e relação de um diagrama podem ter descrição, que é o `COMMENT ON` do objeto no PostgreSQL, então qualquer ferramenta que lê o catálogo a enxerga. Edite em **Description Property** pelo menu da tabela, da coluna ou da relação (ou clique no pequeno ícone de página que marca o item descrito, com o texto na dica); **Save** aplica depois da revisão do script, como toda mudança do diagrama. Se você não é o dono da tabela, a descrição fica no diagrama como não aplicada e o PGMS mostra o script para enviar ao dono. Cada gravação guarda uma cópia das descrições na definição do diagrama (formato 3); quando o banco mudou alguma depois disso, o diagrama mostra o texto do banco e um ícone laranja. **Export for AI…** escreve as tabelas do diagrama em Markdown (colunas, chaves, relações, índices e descrições, em ordem fixa, com uma instrução para o agente no topo) para copiar ou salvar, para um system prompt, um `CLAUDE.md` ou um `AGENTS.md`. A função opcional `pgms.diagram_markdown(name)`, criada só depois de você revisar o script, devolve o mesmo texto a um agente conectado ao banco. Veja [Usando diagramas com agentes de IA](user-guide.md#usando-diagramas-com-agentes-de-ia). No SSMS 22.11 as descrições são editadas na janela Properties; os ícones, a cópia e a exportação são acréscimos do PGMS. Sugestão de um usuário do PGMS.

## O que mudou desde a v0.1.0-alpha.4

Expand Down
Loading