Uh oh!
There was an error while loading. Please reload this page.
feat(dsql): add EF Core / .NET ORM adapter guidance - #208
Merged
Conversation
praba2210force-pushed
the
feat/dsql-efcore-orm-docs-main
branch
from
June 29, 2026 23:03
e7175bf to
d25eebfComparepraba2210force-pushed
the
feat/dsql-efcore-orm-docs-main
branch
from
June 30, 2026 20:32
d25eebf to
2b66168Comparepraba2210
marked this pull request as ready for review
June 30, 2026 21:10
praba2210
requested review from
a team, krokoko, scottschreckengaust and theagenticguyJune 30, 2026 21:10
praba2210
requested review from
Benjscho, Morlej, anwesham-lab, gxjx-x, jaichabria, pkale and spencercorwinJune 30, 2026 21:10
anwesham-lab
commented
Jun 30, 2026
Member
upgrade the version pls |
praba2210force-pushed
the
feat/dsql-efcore-orm-docs-main
branch
from
June 30, 2026 22:08
2b66168 to
aacd913Comparepraba2210
commented
Jun 30, 2026
ContributorAuthor
Updated the version! |
spencercorwin
approved these changes
Jul 1, 2026
Uh oh!
There was an error while loading. Please reload this page.
anwesham-lab
approved these changes
Jul 2, 2026
Document the released Amazon.AuroraDsql.EntityFrameworkCore adapter in the DSQL skill: adapter names, .NET connection notes, and EF Core gotchas (Guid keys, OCC retry, app-layer FK integrity, isolation, migrations). Update SKILL.md routing and add trigger and functional eval coverage. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
praba2210force-pushed
the
feat/dsql-efcore-orm-docs-main
branch
from
July 2, 2026 19:41
aacd913 to
ee9c53fComparepraba2210
enabled auto-merge
July 2, 2026 19:43
Uh oh!
There was an error while loading. Please reload this page.
Uh oh!
There was an error while loading. Please reload this page.
Uh oh!
There was an error while loading. Please reload this page.
praba2210
disabled auto-merge
July 2, 2026 19:45
praba2210
enabled auto-merge
July 2, 2026 19:46
krokoko
approved these changes
Jul 7, 2026
Uh oh!
There was an error while loading. Please reload this page.
Morlej added a commit
to Morlej/agent-plugins
that referenced
this pull request
Jul 8, 2026
Resolves the 1.5.0 version collision with EF Core PR awslabs#208 (both this branch's system-diagnostics work and awslabs#208 independently claimed 1.5.0). Bumps to 1.6.0 across plugin.json, codex plugin.json, and marketplace.json. Adds eval coverage for Workflow 12 (system diagnostics), which previously had none: 3 triggering cases and 1 functional AAS-interpretation eval. Corrects stale eval README counts (37 trigger cases, 15 functional prompts / 54 assertions) and documents evals 13-15. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
DeepaliTandale pushed a commit
to DeepaliTandale/dt-agent-plugins
that referenced
this pull request
Jul 29, 2026
* feat(dsql): Add system diagnostics workflow (Workflow 12) Add CloudWatch AAS-based system diagnostics to the DSQL skill. Uses PromQL queries against db.active_sessions.avg to detect temporal anomalies in wait event distribution and identify regressed queries, then routes to Workflow 9 (Query Plan Explainability) for per-query investigation. OTel attribute names use the proposed naming convention: - db.wait.event, db.wait.class, db.session.state - db.query.id, db.query.normalized_text - aws.auroradsql.session.role.arn, application.name New files: - references/system-diagnostics/workflow.md — 6 diagnostic sub-workflows - references/system-diagnostics/wait-events.md — canonical wait event reference - references/system-diagnostics/promql-patterns.md — reusable PromQL templates Also: - Adds cloudwatch MCP server to .mcp.json (disabled by default) - Bumps plugin version to 1.5.0 * feat(dsql): Add performance routing table to prevent workflow bypass Add a decision table before Common Workflows that routes performance complaints to Workflow 12 (System Diagnostics) instead of allowing them to fall through to Workflow 9 (Query Plan Explainability) directly. Rule: when in doubt, start with Workflow 12 — it identifies specific queries and routes to Workflow 9 with context. * fix(dsql): Fix PromQL discovery patterns for system diagnostics - Use correct get_promql_label_values syntax with match parameter - Add note that calls without match filter return empty - Add PromQL syntax rules: quote labels with dots/@, use __name__ selector - Add explicit discovery step to Workflow 1 - Fix promql-patterns.md to show actual tool parameter names (label_name, match) * feat(dsql): Restructure diagnostics as mandatory full sweep Replace separate numbered workflows (1-6) with a single diagnostic procedure of 5 mandatory phases. The agent MUST execute ALL phases before presenting results — no stopping at the first finding. Phases: 1. Discovery and Baseline Comparison (distribution shifts) 2. Top-SQL Regression Detection (new/growing queries) 3. Workload Attribution (application/role changes) 4. Commit and OCC Analysis (volume vs conflicts) 5. Inflection Point Detection (when did it change) Adds 'Presenting Results' section mandating a unified report across all dimensions before handoff to Workflow 9. * fix(dsql): document CloudWatch MCP setup and fix Workflow 12 gaps Workflow 12 (System Diagnostics) required the CloudWatch MCP server but gave no way to enable it, and agents that hit unavailable PromQL tools had no recovery guidance. Address the observed failure modes: - Add a CloudWatch MCP Server section to mcp/mcp-setup.md: enabling the shipped-disabled server, AWS_REGION/AWS_PROFILE config, the PromQL-enabled region limitation, and the session restart needed for its tools to register (a mid-session enable shows "Connected" but exposes no callable tools until restart). - Add AWS_REGION/AWS_PROFILE placeholders to the disabled cloudwatch entry in .mcp.json so users see what to fill in. - workflow.md: add an explicit "If the PromQL tools are unavailable" callout in Prerequisites (enable + restart, no fabrication/CLI fallback) and a matching Error Handling row, so a blocked agent surfaces the fix rather than only reporting missing data. - Document the discovery-window gotcha: get_promql_label_values defaults to a window ending "now" and returns empty for older data; pass explicit start/end. An empty result means "no data in window," not "no such cluster." - Fix "6 diagnostic workflows/sub-workflows" -> "5 diagnostic phases" in SKILL.md (both the reference table and Workflow 12 section). Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * fix(dsql): bump databases-on-aws to 1.6.0, add Workflow 12 evals Resolves the 1.5.0 version collision with EF Core PR awslabs#208 (both this branch's system-diagnostics work and awslabs#208 independently claimed 1.5.0). Bumps to 1.6.0 across plugin.json, codex plugin.json, and marketplace.json. Adds eval coverage for Workflow 12 (system diagnostics), which previously had none: 3 triggering cases and 1 functional AAS-interpretation eval. Corrects stale eval README counts (37 trigger cases, 15 functional prompts / 54 assertions) and documents evals 13-15. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * fix(dsql): enforce observe-only boundary in Workflow 12 diagnostics Workflow 12 (system diagnostics) must observe via CloudWatch and defer all per-query root cause to Workflow 9. In practice it was easy to restate a db.wait.event label as an EXPLAIN diagnosis — e.g. calling SequentialScanRead a "full table scan" or inferring a missing/building index — which a live investigation disproved (the top SequentialScanRead query was a 1.78ms Index Only Scan on the primary key). - workflow.md: add an explicit principle that a wait-event label is not an EXPLAIN node type; MUST NOT infer scan type, index state, or root cause from it. Constrain the Workflow 9 handoff to describe only the observation, never a hypothesized cause. - wait-events.md: add an observe-only guardrail banner; reframe the read/IO event sections (SequentialScanRead, ScatteredBatchRead, SingleRead) from "Root causes/Remediation" to "Possible causes (confirm in Workflow 9)" + "Observe-only steps". - evals.json: add regression eval 16 (asserts no full-scan/missing-index claim, routes to Workflow 9); realign eval 15 so it rewards observing the concentrated wait-event shift rather than diagnosing a "plan regression" from CloudWatch data alone. Functional evals 15 and 16: 5/5 each. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * fix(dsql): address Workflow 12 review (namespace, PromQL quoting, docs) Applies review feedback from praba2210 on PR awslabs#207. Blocking: - Phase 4 Commit/OCC analysis used the wrong CloudWatch namespace ("AuroraDSQL"), which returns no datapoints. Corrected to "AWS/AuroraDSQL" in workflow.md, promql-patterns.md, and wait-events.md. - Quoted the dotted metric name as {__name__="db.active_sessions.avg", ...} in all 11 bare-form PromQL templates in promql-patterns.md, per the CloudWatch/Prometheus 3.0 spec and the file set's own rule. Fixes: - README eval counts: 15/54 -> 16/59, plus a "What it checks" row for eval 16. - mcp-setup.md: list cloudwatch:GetMetricData + cloudwatch:ListMetrics as the required permissions (dropped the incorrect aps reference — that is Amazon Managed Prometheus, a different service). - wait-events.md ClientWrite: route the result-size question (LIMIT / pagination is a query rewrite) to Workflow 9; keep client-side steps. Style/nits: - Consolidated the per-section observe-only caveat to defer to the file-level guardrail banner. - MUST on the 7-day range limit; de-duplicated the >30% trigger; aligned the 900s step guidance (6-24h) across both files. Functional evals 15 and 16: 5/5 each. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * fix(dsql): normalize illustrative PromQL snippets in wait-events.md Follow-up to the Workflow 12 review: apply the same __name__ / dotted-label quoting to the 9 illustrative "Identify query" snippets in wait-events.md that the review scoped to the promql-patterns.md templates. Uses the {__name__="db.active_sessions.avg", "db.wait.event"=...} form and quotes the bare db.query.normalized_text group-by labels, so every PromQL example in the system-diagnostics reference set is copy-paste-correct and internally consistent. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * fix(dsql): resolve self-review findings for Workflow 12 diagnostics Multi-agent self-review (validated against a live DSQL cluster + AWS docs) surfaced 15 confirmed findings; this fixes all of them. Functional bugs (verified live): - Wrong CloudWatch namespace in wait-events.md and promql-patterns.md ("AuroraDSQL" returns 0 metrics; "AWS/AuroraDSQL" returns all 19). The earlier fix only reached workflow.md. - promql-patterns.md Phase-4 get_metric_data omitted statistic="Sum" (TotalTransactions/OccConflicts are counters — default AVG reports ~1.0) and start_time/end_time (defaults to last 3h, misaligning with baselines). - Non-RFC3339 relative times (NOW-1h etc.) in workflow.md and promql-patterns.md examples — the API rejects these; contradicted the file's own "MUST ... RFC 3339" rule. Replaced with placeholder timestamps and a compute-the-window note. - Discovery get_promql_label_values templates now document the required start/end for non-recent data. Observe-only doctrine (the hardening pass had reached only 4 of 10 sections): - Reframed OnCpu, ClientRead, ClientWrite, FkExistenceCheck, UniqueConstraintCheck, Commit, PgSleep from "Root causes"/"Remediation" to "Possible causes (confirm in Workflow 9)"/"Observe-only steps". - Removed prescriptive fixes (remove pg_sleep(), set GUCs, audit pool) — now surfaced as candidate causes for the owner to confirm. - Unified handoff wording to "hand off to Workflow 9". - Added db.query.id to the Fk/Unique/Single/OnCpu grouping queries (workflow.md:139 MUST). - Added a snippet convention note explaining the "..." cluster-filter placeholder. Docs: - README grader-modes: LLM judge is evals 6-16 (was "6-9"). - SKILL.md description: restored "EF Core" to the ORM list. - eval 15: corrected the derivable shares to ~19%->~47% (89/478 vs 336/709) and made the percentage non-mandatory; kept the correct 3.7x. - Aligned step-size guidance as SHOULD across both files. Refuted (no change): mcp-setup.md IAM permissions — GetMetricData + ListMetrics is complete per AWS PromQL docs. Build clean; functional evals 15 and 16 pass 5/5. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * docs(dsql): prefer CLI/psql when the aurora-dsql MCP targets another cluster The aurora-dsql MCP server binds a single cluster at startup (--cluster_endpoint is a launch flag; the db tools take no per-call endpoint), so using it against a different cluster means editing .mcp.json and restarting the session. Guide the skill to only use the MCP tools when the server already targets the intended cluster, and otherwise prefer the CLI + psql path (scripts/psql-connect.sh) rather than silently reconfiguring. - SKILL.md: new concise "Choosing How to Connect: MCP vs CLI/psql" decision rule, plus a Quick Start step 0 pointing to it. Kept SKILL.md under the 300-line target by keeping the section brief and linking to the reference. - references/auth/connectivity-tools.md: full "Ad-hoc Queries: MCP vs CLI/psql" subsection with the decision rule and psql-connect.sh examples. - mcp-setup.md: note that --cluster_endpoint is a per-instance startup flag and to prefer CLI/psql over reconfiguring; contrasts with the per-call CloudWatch MCP. Doc-only change; build + cross-ref lint clean. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * fix(dsql): resolve round-2 self-review findings (connectivity accuracy, doctrine) Second multi-agent self-review pass (validated against the live cluster and the actual psql-connect.sh source). 9 confirmed findings fixed. Connectivity guidance (bugs introduced by the prior connectivity commit): - connectivity-tools.md: removed the false "read-only credentials by default" claim. psql-connect.sh connects as the `admin` DB user by default (full read/write/DDL); --admin only changes the IAM token action, not SQL privileges. Now states this explicitly and points to --user for least privilege. Verified against the script + scripts/README.md. - Reconciled the CloudWatch "one config serves any cluster" wording across SKILL.md, connectivity-tools.md, and mcp-setup.md with the existing "Region matters" note: the per-call `region` arg IS honored (verified live — querying an us-east-1 cluster with region=us-west-2 returns empty), so one server can query any PromQL-enabled region by passing the region per call; AWS_REGION only sets the default. - development-guide.md: the unconditional "PREFER MCP tools for ad-hoc queries" and "MUST ALWAYS Execute DIRECTLY using MCP" now cross-reference the conditional "only when the MCP targets the intended cluster" rule. Observe-only doctrine: - workflow.md opening sentence no longer says the skill does "root cause analysis" via db tools — it observes and hands off to Workflow 9. - Clarified the aurora-dsql MCP prerequisite is for the Workflow 9 handoff, not this workflow; unified "defer to" -> "hand off to Workflow 9". PromQL/CloudWatch: - Added start/end to the 3 remaining discovery get_promql_label_values templates (only the first had it). - Phase 5 example: replaced stale 2024 dates + exactly-7-day span with placeholder window + a note to keep the span under the 7-day (incl. lookback) limit. - FkExistenceCheck: added the AWS/AuroraDSQL + statistic="Sum" reminder to the TotalTransactions reference. - Added a "must be concrete RFC3339" note to the Range Queries section. Refuted / left intentional: unquoted dimensions pseudocode; "~3.7x" (grader tolerates); ClientRead/PgSleep client-side guardrail phrasing. Build + cross-ref lint clean; functional evals 15 and 16 pass 5/5. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> --------- Signed-off-by: James Morle <7480305+Morlej@users.noreply.github.com> Co-authored-by: Alain Krok <alkrok@amazon.com> Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for freeto join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What
Documents the released
Amazon.AuroraDsql.EntityFrameworkCoreadapter in the Aurora DSQL skill, and adds eval coverage for the .NET / EF Core path.Changes
skills/dsql/SKILL.mdskills/dsql/references/language.mdC# / .NETsection (Npgsql connector) with anEF Coresubsectionskills/dsql/references/orm-guides/overview.mdEF Core (.NET)gotchas table (setup, Guid keys, OCC retry, app-layer FK integrity, isolation, migrations)skills/dsql/references/auth/connectivity-tools.mdskills/dsql/references/onboarding.mdtools/evals/databases-on-aws/dsql/evals.jsontools/evals/databases-on-aws/dsql/trigger_evals.jsonNotes
aac1f4c,08bbd67).aurora-dsql-ormsREADME; all added links HTTP-checked (200).mise run buildpasses (markdownlint, cross-refs, dprint, security scans all clean).Generated with Claude Code
By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of the project license.