## Summary
Make the README answer what Postgres Skills is, who it is for, and how
it works before asking developers to install it.
- Lead with the plugin identity, supported agents, PostgreSQL-anywhere
coverage, and the distinction from a database extension or standalone
assistant.
- Add audience, workload, current-friction, architecture, and honest
non-goals sections.
- Explain the agent, skill instructions, local PostgreSQL MCP server,
optional Azure CLI, permissions, and approval boundaries with an
architecture diagram and a concrete walkthrough.
- Add a short read-only quick start. Preserve the full example
collection and 33-reference catalog in expandable sections, and
distinguish full-plugin from skills-only installation.
- Move first-time agent setup to the existing setup guide, make privacy
and permissions language agent-neutral, and provide single-line
connection commands usable in PowerShell and macOS/Linux shells.
- Align the Codex installation command with the repository's
compatibility workflow (`codex plugin add`). Clarify that SQL-driven
embedding calls can send text to a model provider and incur charges.
## Scope
Only `README.md` and `plugin/SETUP.md`. No skill behavior, MCP
configuration, dependency, or database changes.
README word counts (whitespace-delimited, including code and tables):
initially visible content decreases from 2,479 to 1,454 words (about
41%). The full source increases from 2,479 to 2,911 words to retain the
detailed reference material and add the missing explanations. The setup
guide increases from 449 to 926 words, mainly from relocated onboarding
instructions.
## Validation
- Focused repository structure, security/content contracts, and
terminology checks: 69 passed.
- Existing external-link checker scoped to changed documentation: 16
unique URLs passed.
- Relative links, section anchors, code fences, expandable sections, and
`git diff --check` passed.
- Fresh-reader comprehension review covered product identity, audience,
prerequisites, execution boundaries, installation modes, permissions,
and non-goals. Addressed its Windows onboarding, database-readiness, and
external-inference clarity findings.
- No database/model calls or live cloud operations performed. Full
live-agent installation and database integration checks were not run
locally; existing CI remains responsible for those checks.
Co-authored-by: Aditi Gupta <adig@microsoft.com>
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Copilot-Session: ba611893-3f35-446b-a650-1e7bf57fa186
Closes#37
## Summary
Adds an Azure reference for recovering a **deleted** Azure Database for
PostgreSQL Flexible Server. Until now that question routed to the HA/DR
reference, whose PITR guidance assumes the source server still exists.
## What's in the reference
- **Recovery window:** backups are kept for 5 days after deletion.
Recovery is best-effort, in the same subscription and original region
only.
- **Procedure:**
- Look up the `resourceId` and `submissionTimestamp` of the delete event
in the activity log.
- Call `Servers - Create Or Update` with `createMode: "ReviveDropped"`
and api-version `2025-08-01`, via `az rest`. There's no dedicated `az
postgres flexible-server` subcommand for this.
- Prefer a new server name.
- The revive request needs user confirmation because it creates a
billable server.
- **VNet-integrated servers:** the request also needs
`network.delegatedSubnetResourceId` and
`network.privateDnsZoneArmResourceId`.
- **After the 5-day window:** restore from an Azure Backup vault if
long-term retention (LTR) was configured. The vault restores dump files
to a storage account, which you then load with `pg_restore`.
- **Post-restore checklist** for the new server.
- **Prevention:** a `CanNotDelete` lock. Locks don't block `DROP
DATABASE`.
- **HorizonDB:** deleted clusters can't be restored; recommend a Delete
lock.
## Other changes
- **Routing:** new row in `SKILL.md`, plus an entry in
`tests/.skills.json`.
- **Token budget:** `SKILL.md` was already at 3,991 of 4,000 tokens. I
compacted some wording (graph-workloads paragraph, a duplicate graph
bullet, one CLI-policy sentence) without removing any routing rules.
It's now exactly 4,000.
- **Tests:**
- 3 activation-precision cases, including a gating negative.
- 4 routing challenges (`route-del-01..03`, `route-hz-12`).
- 5 eval challenges (`az-del-01..04`, `hz-del-01`).
- **Docs:** README catalog and counts, CONTRIBUTING counts, CHANGELOG.
## Validation
- `python -m pytest tests -m "not pg and not integration and not
azure"`: 187 passed.
- `tests/evals/routing_eval.py --check`: PASS. All new challenges route
correctly on copilot-cli, claude-code and codex-cli.
- `tests/evals/lint_challenges.py`: 331 challenges, no schema issues.
## Sources
- [Restore a deleted
server](https://learn.microsoft.com/azure/postgresql/backup-restore/how-to-restore-deleted-server)
- [Servers - Create Or Update
(2025-08-01)](https://learn.microsoft.com/rest/api/postgresql/servers/create-or-update?view=rest-postgresql-2025-08-01)
- [Resource
locks](https://learn.microsoft.com/azure/postgresql/configure-maintain/how-to-enable-deletion-protection)
- [HorizonDB business
continuity](https://learn.microsoft.com/azure/horizondb/backup-restore/concepts-business-continuity)
---------
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
## Summary
- rename the human-facing product name from "PostgreSQL Skills" to
"Postgres Skills"
- preserve the stable `postgres-skills` plugin ID, marketplace name,
namespace, and installation commands
- add a regression test separating the display name from the machine
identifier
## Validation
- `claude plugin validate .\plugin`
- 62 repository structure, link, and terminology tests pass
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Copilot-Session: d602e64b-556b-4b04-b723-fca569cfb2e6
## Summary
Fixes the 5 skills-only bugs (BUG-1 through BUG-5) from the 2026-09-04
postgres-skills bug-bash report. MCP-only bugs (BUG-7/8/9/10) and the
CLI-only bug (BUG-6) are out of scope, since they require changes
outside `SKILL.md`.
- **BUG-1** (unrequested billable resource/identity creation) &
**BUG-4** (MCP unavailable -> credential guessing) & part of **BUG-5**
(Docker denied -> initdb escalation): added a shared **Escalation
policy** under Key Constraints - a blocked/denied path must surface the
blocker and ask, never silently substitute a different
method/resource/target.
- **BUG-2** (unrequested Entra auth change, no confirmation): extended
the existing destructive-az-CLI confirmation gate to also cover toggling
Entra ID auth, creating/removing an Entra administrator, and toggling
password auth (irreversible actions only; SSL/firewall left ungated as
cheaply reversible).
- **BUG-3a** (unreliable skill activation): rewrote the `description`
frontmatter field with concrete operational/lifecycle keywords, and
removed the `tags`/`activation` YAML block, which the GitHub Copilot SDK
does not read for activation (only `name`/`description` are honored).
- **BUG-3b** (guardrails not applied cross-platform): widened the
OS/service command guardrail beyond Linux-only commands to include
Windows (`Restart-Service`, `services.msc`), macOS (`brew services`),
and Docker (`docker restart`).
- **BUG-5** (create a server -> insecure local server): routed "create a
new server" to `azure-postgresql-provisioning`, and added guidance there
to default to `az postgres flexible-server create` when Azure-connected
and the target is unspecified, and to never use `trust` auth for
locally-spawned dev servers.
## Validation
- `pytest tests/test_activation_precision.py tests/test_skill_routing.py
tests/test_repo_structure.py tests/test_skill_size.py
tests/test_terminology.py tests/test_licenses.py tests/test_links.py` -
150 passed; 2 pre-existing/unrelated failures (`test_json_is_parseable`
for symlinked marketplace.json files, confirmed to fail identically on
unmodified `main`).
- Confirmed the new "create a new server" routing keyword does not
collide with any existing `test_activation_precision.py` test case.
Co-authored-by: Aditi Gupta <adig@microsoft.com>
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 8647d648-c7fb-45f2-ad96-3e52b9290144
## Summary
- upgrade `@microsoft/postgres-mcp` from `0.1.0-rc.8` to the current
`latest` release, `0.1.0-rc.9`
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Copied the header from the table further below. This probably doesn't
matter to AI, but greatly improves human readability.
Verified by visually confirming the fix using the markdown's GitHub
preview.
Co-authored-by: aditivgupta <86393637+aditivgupta@users.noreply.github.com>
## Summary
Adds **Azure HorizonDB (Preview)** coverage to the
`postgresql-best-practices` skill so that when the connected instance is
a HorizonDB cluster, the agent routes to HorizonDB-specific guidance
instead of falling back to Flexible Server steps.
## Changes
- **SKILL.md** — HorizonDB flavor detection + routing guardrails.
- **11 `references/azure-postgresql-*.md`** — added "On Azure HorizonDB
(Preview)" **delta** sections that lean on the shared Flexible Server
body (no duplicated content).
- **Redundancy pass** — rewrote concept-heavy HorizonDB sections as pure
deltas so common Flexible Server / HorizonDB info is not duplicated.
- **README.md** — HorizonDB example + flavor-routing note.
- **Challenges** — 13 HorizonDB challenges (`hz-*`) in `challenges.yaml`
and 11 deterministic routing challenges (`route-hz-01..11`) in
`routing_challenges.yaml`.
## Validation
- Authoring/content suite: full no-DB pytest passes (excluding known
Windows-only symlink + local `npx` env artifacts, which resolve on Linux
CI).
- Challenge lint: 326 challenges validated.
- Routing gate (`routing_eval.py --check`): copilot-cli + codex-cli both
100% (0 misroutes).
---------
Co-authored-by: Aditi Gupta <adig@microsoft.com>
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
Copilot-Session: 3c05a95f-29ac-44a8-a365-8236a4636f6e
The `Routing eval gate` step of the "Tests: pytest suite" job failed
with 1 misroute on both `copilot-cli` and `codex-cli`: routing challenge
`route-61` (VS Code AGE graph visualization) activated
`opencypher-age-patterns` instead of `text-to-cypher`. The pytest step
itself passed — the gate is a separate step in the same job.
**Root cause:** the visualization routing row was added to
`plugin/skills/pg-graph/SKILL.md`, but the corresponding keywords were
never mirrored into `tests/.skills.json` — the manifest the
deterministic host adapters route with. With no visualization keyword in
the manifest, the only match in the challenge query was the literal
"Apache AGE", which belongs to `opencypher-age-patterns`.
### Changes
- **`tests/.skills.json`** — added visualization activation keywords to
the `graph-text-to-cypher` entry so the manifest matches the SKILL.md
routing table:
```json
"activation_keywords": [
"text to cypher", "natural language to cypher", "english to cypher",
"generate cypher", "nl to cypher",
"visualize graph", "visualize my graph", "vs code graph", "graph explorer",
"render the graph", "renders as nodes and edges", "ms-ossdata.vscode-pgsql"
]
```
- **`tests/evals/challenges/routing_challenges.yaml`** — dropped the
"Apache AGE" literal from the `route-61` query. That phrase is an exact
`opencypher-age-patterns` trigger, so it would co-activate regardless of
the manifest fix, and the challenge asserts a single expected skill. The
query still carries unambiguous visualization intent ("visualize my
graph", "renders as nodes and edges").
The remaining diff on this branch (pg-graph HorizonDB/VS Code docs,
`challenges.yaml`, README) is PR #19 content unchanged.
---------
Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
Co-authored-by: aditivgupta <86393637+aditivgupta@users.noreply.github.com>
Updates the README to cover the newly merged pg-graph skill (PR #17).
- Reference count 22 to 32
- Graph lifecycle noted in the intro and How it works
- New Building and querying graphs examples (ontology from
documents/tables, text-to-Cypher, explainability)
- New Graph on PostgreSQL - Apache AGE (pg-graph) reference catalog
section listing all 10 references
---------
Co-authored-by: Aditi Gupta <adig@microsoft.com>
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
## What
Adds a new **pg-graph** skill to the plugin, covering the full
knowledge-graph lifecycle on PostgreSQL with Apache AGE. It is a sibling
to `postgresql-best-practices`, which now points here for anything
involving Apache AGE, openCypher, `ag_catalog`, knowledge graphs, or
ontology.
**Hard constraint:** everything uses capabilities available **today** —
agent-driven extraction over the MCP query tools, the `azure_ai`
extension, pgvector, and Apache AGE. It does **not** depend on
unreleased `ai.*` pipeline primitives.
## Lifecycle covered
1. **Derive an ontology** from structured or unstructured data —
taxonomy learning, confidence/quality scores, and a reader-friendly
human feedback loop before finalizing (`ontology-derivation`).
2. **Build the graph** — idempotent `MERGE` load, context-aware
deduplication, jargon/taxonomy learning (`extract-to-graph`,
`context-dedup`).
3. **Consume the graph** — openCypher/AGE patterns,
natural-language-to-Cypher, schema introspection, worked examples
(`opencypher-age-patterns`, `text-to-cypher`,
`graph-schema-introspection`, `examples`).
4. **Retrieve and explain** — pgvector seed + AGE traversal + rerank,
`azure_ai` embeddings, and explainability/traceability with provenance,
a returned reasoning path, weakest-link path confidence, and a
reproducible reasoning-trace log (`graph-augmented-rag`,
`azure-ai-semantic-search`, `graph-explainability`).
## Key AGE-on-managed-Azure caveats baked in
- `age` is in `shared_preload_libraries` on managed Azure, so `LOAD
'age'` is unnecessary and blocked for non-superusers.
- `ag_catalog.cypher()` requires the graph name as a **literal**, not a
bind parameter.
- `search_path = public, ag_catalog` (ag_catalog not first).
## Evals
- Added **11 quality** + **10 routing** challenges for pg-graph, in line
with the existing evals framework.
- Narrowed the pg-graph container `.skills.json` keywords to meta/help
phrases (matching `postgres-skills`) so the SKILL root no longer
co-fires on every graph query.
- Routing eval: **100% precision/recall/F1** for pg-graph on the
copilot-cli and codex-cli hosts; overall routing precision 97.9%.
- Deterministic test suite passes (pre-existing marketplace.json symlink
failures unrelated).
## Validation
Ontology derivation, dedup jargon-mining, NL→Cypher incident traversal,
`azure_ai` embeddings (1536-dim), confidence scoring, and the
explainability path/trace patterns were all validated live against an
Azure Database for PostgreSQL Flexible Server with Apache AGE.
---------
Co-authored-by: Aditi Gupta <adig@microsoft.com>
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
## Summary
Point the plugin's MCP integration at the renamed **`postgres-mcp`**
distribution (formerly `pgsql-tools`), move to its `~/.postgres-mcp`
base folder, and align with its `PGSQL_MCP_` env-var normalization.
## Changes
- **Launcher (`run_mcp.js`)** — pin the CLI to the `postgres-mcp`
releases: release tag `cli-v*` → `mcp-v*`, asset `pgsql-tools-cli-*` →
`postgres-mcp-*`, binary `pgsql-tools` → `postgres-mcp`, start command
`mcp run` → `run`.
- **Base folder** — install/cache directory, PATH entry, and marker
moved from `~/.pgsql-tools-cli` to `~/.postgres-mcp` (co-located with
the binary's own config root).
- **Server registration** — the MCP server key in `.mcp.json` renamed to
`postgres-mcp`.
- **Env vars** — `PGSQL_TOOLS_QUERY_TIMEOUT_MS` →
`PGSQL_MCP_QUERY_TIMEOUT_MS`, and the test fixtures' connection-string
var → `PGSQL_MCP_CONNECTION_STRING`, matching the upstream env-var
normalization.
- **Version pin file** — `PGSQL_TOOLS_CLI_VERSION` →
`POSTGRES_MCP_CLI_VERSION`.
- **Plugin version** — bumped `0.0.1` → `0.1.0` (marketplace + Codex
manifests).
- **Docs / keywords / branding** — remaining `pgsql-tools` references
updated to `postgres-mcp`.
Retained intentionally: the `microsoft/pgsql-tools` GitHub release repo.
## Testing
- End-to-end launcher run: downloads the pinned asset, verifies the
SHA-256 checksum, installs to `~/.postgres-mcp/bin`, and the server
responds as `postgres-mcp`.
- Integration MCP e2e suite (8 tests) green against a real Postgres; 35
non-DB tests pass.
---------
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
This PR applies targeted fixes to the PostgreSQL skills reference files,
driven by a knowledge audit and post-audit factual verification. Changes
fall into two buckets:
Generic skill trimming — Five generic PostgreSQL reference files were
reduced to gotchas-only format based on audit results showing models
already know this content well (93–100% known rate). SQL examples and
section headers are retained as test contract anchors.
Azure skill hallucination corrections — Eight Azure reference files were
corrected against Microsoft Learn documentation to fix factual errors
introduced during the initial audit or caught in review.
What changed
Generic references (trimmed, -370 net lines)
- postgresql-advanced-indexing.md
- postgresql-jsonb-patterns.md
- postgresql-query-performance.md — also adds n_mod_since_analyze
stale-stats detection
- postgresql-row-level-security.md
- postgresql-table-partitioning.md
Azure references (corrected, +101 net lines)
<img width="779" height="298" alt="image"
src="https://github.com/user-attachments/assets/abcbea78-c1af-4170-bd7b-7d5b3e22c133"
/>
---------
Co-authored-by: Aditi Gupta <adig@microsoft.com>
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
- Block SHOW config_file/hba_file/data_directory on Azure (revealed
internal paths)
- Clarify ALTER DATABASE SET vs az CLI for server-wide parameter changes
- Add broader activation keywords for schema/table inspection prompts
- Add pgsql_ and pgsql-tools to technical keywords for better routing
Bugs fixed:
- B1: Agent used ALTER DATABASE SET for work_mem instead of az CLI
- B2: Agent revealed /datadrive/pg/data/postgresql.conf path on Azure
- B3: Ambiguous 'show tables' prompt didn't trigger PostgreSQL skill
---------
Co-authored-by: Aditi Gupta <adig@microsoft.com>
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
## Summary
- Map Windows arm64 to the published `win-x64` asset (runs via Windows
x64 emulation), so Windows-on-ARM no longer fails platform detection.
- Retry the install promote renames to survive transient Windows file
locks (EPERM/EACCES/EBUSY/ENOTEMPTY).
- Rename the plugin and marketplace to `postgres-skills` and update all
references (README, CONTRIBUTING, CI, manifests, tests).
- CI: verify the plugin shows as installed via `plugin list` for each
CLI.
## Testing
- Re-installed plugin in mac and windows. Tested with a few basic DB
operations using MCP server.
---------
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
## Overview
Bootstraps the **PostgreSQL Agent Skills** repository: a PostgreSQL
best-practices skill plus a distributable plugin for agent hosts, with a
supporting test and evaluation harness.
## What's included
- **Skill** — PostgreSQL best-practices guidance (generic + Azure
Database for PostgreSQL), organized as a lightweight routing table that
loads focused reference topics on demand.
- **Plugin** — multi-host packaging and an MCP launcher that installs
and runs the pinned `pgsql-tools` CLI.
- **Tests & evals** — a pytest suite plus an evaluation pipeline that
measures skill activation accuracy and content quality.
- **Project docs & CI** — README, contributing/support/security docs,
and a CI workflow.
---------
Co-authored-by: Aditi Gupta <adig@microsoft.com>
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
Co-authored-by: github-actions[bot] <github-actions[bot]@users.noreply.github.com>
Co-authored-by: Alperen Cetin <hcetin@microsoft.com>
Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
Alperen Cetin
Prashant ChinnamandCopilot App
Dev-iLandaditivgupta
Copilotandaditivgupta
