feat(dsql): add EF Core / .NET ORM adapter guidance

Prabakaran Annadurai · claude · Prabakaran Annadurai · commit aacd913ed4bf · 2026-06-30T15:06:59.000-07:00
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) &lt;noreply@anthropic.com&gt;
diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json
@@ -164,7 +164,7 @@
       "name": "databases-on-aws",
       "source": "./plugins/databases-on-aws",
       "tags": ["aws", "database", "aurora", "dsql", "serverless", "postgresql"],
-      "version": "1.4.0"
+      "version": "1.5.0"
     },
     {
       "category": "deployment",
diff --git a/plugins/databases-on-aws/.claude-plugin/plugin.json b/plugins/databases-on-aws/.claude-plugin/plugin.json
@@ -22,5 +22,5 @@
   "license": "Apache-2.0",
   "name": "databases-on-aws",
   "repository": "https://github.com/awslabs/agent-plugins",
-  "version": "1.4.0"
+  "version": "1.5.0"
 }
diff --git a/plugins/databases-on-aws/.codex-plugin/plugin.json b/plugins/databases-on-aws/.codex-plugin/plugin.json
@@ -1,6 +1,6 @@
 {
   "name": "databases-on-aws",
-  "version": "1.4.0",
+  "version": "1.5.0",
   "description": "Expert database guidance for the AWS database portfolio. Design schemas, execute queries, handle migrations, and choose the right database for your workload.",
   "author": {
     "name": "Amazon Web Services",
diff --git a/plugins/databases-on-aws/skills/dsql/SKILL.md b/plugins/databases-on-aws/skills/dsql/SKILL.md
@@ -1,9 +1,9 @@
 ---
 name: dsql
-description: "Build with Aurora DSQL — manage schemas, execute queries, handle migrations, diagnose query plans, load data, and develop applications with a serverless, distributed SQL database. Covers IAM auth, multi-tenant patterns, MySQL-to-DSQL and PostgreSQL-to-DSQL schema conversion, FK replacement code generation, OCC retry patterns, ORM migration (Django/Hibernate/Rails), DDL operations, query plan explainability, SQL compatibility validation, and bulk data loading. Triggers on phrases like: DSQL, Aurora DSQL, distributed SQL database, serverless PostgreSQL-compatible database, migrate to DSQL, DSQL query plan, DSQL EXPLAIN ANALYZE, DSQL ENUM, DSQL foreign key, DSQL OCC retry, DSQL multi-region, DSQL JSONB, DSQL GIN index, load into DSQL, load CSV into DSQL, bulk load DSQL, aurora-dsql-loader."
+description: "Build with Aurora DSQL — manage schemas, execute queries, handle migrations, diagnose query plans, load data, and develop applications with a serverless, distributed SQL database. Covers IAM auth, multi-tenant patterns, MySQL-to-DSQL and PostgreSQL-to-DSQL schema conversion, FK replacement code generation, OCC retry patterns, ORM migration (Django/EF Core/Hibernate/Rails), DDL operations, query plan explainability, SQL compatibility validation, and bulk data loading. Triggers on phrases like: DSQL, Aurora DSQL, distributed SQL database, serverless PostgreSQL-compatible database, migrate to DSQL, DSQL query plan, DSQL EXPLAIN ANALYZE, DSQL ENUM, DSQL foreign key, DSQL OCC retry, DSQL multi-region, DSQL JSONB, DSQL GIN index, load into DSQL, load CSV into DSQL, bulk load DSQL, aurora-dsql-loader."
 license: Apache-2.0
 metadata:
-  tags: aws, aurora, dsql, distributed-sql, distributed, distributed-database, database, serverless, serverless-database, postgresql, postgres, sql, schema, migration, multi-tenant, iam-auth, aurora-dsql, mcp, orm, enum, foreign-key, occ-retry, django, hibernate, rails, multi-region, schema-conversion, type-mapping, data-loading
+  tags: aws, aurora, dsql, distributed-sql, distributed, distributed-database, database, serverless, serverless-database, postgresql, postgres, sql, schema, migration, multi-tenant, iam-auth, aurora-dsql, mcp, orm, enum, foreign-key, occ-retry, django, ef-core, dotnet, csharp, hibernate, rails, multi-region, schema-conversion, type-mapping, data-loading
 ---
 
 # Amazon Aurora DSQL Skill
@@ -65,9 +65,9 @@ Load these files as needed for detailed guidance:
 
 ### ORM Guides:
 
-| Reference                                                   | When to Load              | Contains                                                         |
-| ----------------------------------------------------------- | ------------------------- | ---------------------------------------------------------------- |
-| [orm-guides/overview.md](references/orm-guides/overview.md) | Migrating any ORM to DSQL | Adapter names, key gotchas for Django/Hibernate/Rails/SQLAlchemy |
+| Reference                                                   | When to Load              | Contains                                                                 |
+| ----------------------------------------------------------- | ------------------------- | ------------------------------------------------------------------------ |
+| [orm-guides/overview.md](references/orm-guides/overview.md) | Migrating any ORM to DSQL | Adapter names, key gotchas for Django/EF Core/Hibernate/Rails/SQLAlchemy |
 
 ### Data Loading:
 
@@ -231,7 +231,7 @@ MUST load [query-plan/workflow.md](references/query-plan/workflow.md) at entry 
 
 MUST load [pg-migrations/type-mapping.md](references/pg-migrations/type-mapping.md) and [pg-migrations/schema-objects.md](references/pg-migrations/schema-objects.md). Run `dsql_lint(fix=true)` first for mechanical fixes, then apply semantic conversions from the pg-migrations references for unfixable diagnostics and patterns the linter cannot handle. Re-lint the final output before deploying.
 
-### Workflow 11: ORM Migration (Django/Hibernate/Rails)
+### Workflow 11: ORM Migration (Django/EF Core/Hibernate/Rails)
 
 Load [orm-guides/overview.md](references/orm-guides/overview.md) for adapter names and framework-specific gotchas.
 
diff --git a/plugins/databases-on-aws/skills/dsql/references/auth/connectivity-tools.md b/plugins/databases-on-aws/skills/dsql/references/auth/connectivity-tools.md
@@ -6,7 +6,7 @@ Part of [DSQL Development Guide](../development-guide.md).
 
 ## Database Connectivity Tools
 
-DSQL has many tools for connecting including 10 database drivers, 4, ORM libraries, and 3 specialized adapters
+DSQL has many tools for connecting including 12 database drivers, 4 ORM libraries, and 4 specialized adapters
 across various languages as listed in the [programming guide](https://docs.aws.amazon.com/aurora-dsql/latest/userguide/aws-sdks.html). PREFER using connectors, drivers, ORM libraries, and adapters.
 
 ### Database Drivers
@@ -43,11 +43,12 @@ Standalone libraries that provide object-relational mapping functionality:
 
 Specific extensions that make existing ORMs work with Aurora DSQL:
 
-| Programming Language | ORM/Framework | Repository                                                                           |
-| -------------------- | ------------- | ------------------------------------------------------------------------------------ |
-| **Java**             | Hibernate     | [Aurora DSQL Hibernate Adapter](https://github.com/awslabs/aurora-dsql-hibernate/)   |
-| **Python**           | Django        | [Aurora DSQL Django Adapter](https://github.com/awslabs/aurora-dsql-django/)         |
-| **Python**           | SQLAlchemy    | [Aurora DSQL SQLAlchemy Adapter](https://github.com/awslabs/aurora-dsql-sqlalchemy/) |
+| Programming Language | ORM/Framework | Repository                                                                                          |
+| -------------------- | ------------- | --------------------------------------------------------------------------------------------------- |
+| **C# (.NET)**        | EF Core       | [Aurora DSQL EF Core Adapter](https://github.com/awslabs/aurora-dsql-orms/tree/main/dotnet/ef-core) |
+| **Java**             | Hibernate     | [Aurora DSQL Hibernate Adapter](https://github.com/awslabs/aurora-dsql-hibernate/)                  |
+| **Python**           | Django        | [Aurora DSQL Django Adapter](https://github.com/awslabs/aurora-dsql-django/)                        |
+| **Python**           | SQLAlchemy    | [Aurora DSQL SQLAlchemy Adapter](https://github.com/awslabs/aurora-dsql-sqlalchemy/)                |
 
 ---
 
diff --git a/plugins/databases-on-aws/skills/dsql/references/language.md b/plugins/databases-on-aws/skills/dsql/references/language.md
@@ -142,6 +142,19 @@ PREFER using JDBC with the [DSQL JDBC Connector](https://docs.aws.amazon.com/aur
 - Wrap JDBC connection, configure max lifetime < 1 hour
 - See [aurora-dsql-samples/java/pgjdbc_hikaricp](https://github.com/aws-samples/aurora-dsql-samples/tree/main/java/pgjdbc_hikaricp)
 
+### C# / .NET
+
+PREFER using the [Amazon.AuroraDsql.Npgsql](https://github.com/awslabs/aurora-dsql-orms/tree/main/dotnet) connector for automatic IAM auth:
+
+- Wraps Npgsql with IAM token generation and refresh
+- Register via `AddDsqlDataSource(host)`
+
+#### EF Core
+
+- Adapter: [Amazon.AuroraDsql.EntityFrameworkCore](https://github.com/awslabs/aurora-dsql-orms/tree/main/dotnet/ef-core) (requires .NET 8.0+, EF Core 9.0.7+, `Amazon.AuroraDsql.Npgsql` 1.1.0+)
+- Configure with `options.UseDsql(sp)` in `AddDbContext`
+- Use `Guid` keys (store-generated `gen_random_uuid()`) and `DsqlExecutionStrategy` for OCC retry — see [orm-guides/overview.md](orm-guides/overview.md) for framework gotchas
+
 ### Rust
 
 **SQLx** (async)
diff --git a/plugins/databases-on-aws/skills/dsql/references/onboarding.md b/plugins/databases-on-aws/skills/dsql/references/onboarding.md
@@ -366,7 +366,7 @@ Let them know you're ready to help with more:
 2. **Distributed:** Active-active writes across multiple regions
 3. **Strong Consistency:** Immediate read-your-writes across all regions
 4. **IAM Authentication:** No password management, automatic token rotation
-5. **PostgreSQL Compatible:** Supports 12 [Database Drivers](./auth/connectivity-tools.md#database-drivers), 4 [ORMs](./auth/connectivity-tools.md#object-relational-mapping-orm-libraries), and 3 [Adapters/Dialects](./auth/connectivity-tools.md#aurora-dsql-adapters-and-dialects) as listed.
+5. **PostgreSQL Compatible:** Supports 12 [Database Drivers](./auth/connectivity-tools.md#database-drivers), 4 [ORMs](./auth/connectivity-tools.md#object-relational-mapping-orm-libraries), and 4 [Adapters/Dialects](./auth/connectivity-tools.md#aurora-dsql-adapters-and-dialects) as listed.
 
 **For detailed patterns, see [`./development-guide.md`](./development-guide.md)**
 
diff --git a/plugins/databases-on-aws/skills/dsql/references/orm-guides/overview.md b/plugins/databases-on-aws/skills/dsql/references/orm-guides/overview.md
@@ -5,12 +5,13 @@ names and configuration not available in general documentation.
 
 ## Adapters
 
-| Framework  | Adapter                            | Install                                                      |
-| ---------- | ---------------------------------- | ------------------------------------------------------------ |
-| Django     | `aurora_dsql_django`               | `pip install aurora-dsql-django boto3`                       |
-| Hibernate  | `aurora-dsql-hibernate-dialect`    | `software.amazon.dsql:aurora-dsql-hibernate-dialect` (Maven) |
-| Rails      | Standard `pg` gem + `aws-sdk-dsql` | `gem 'pg'` + `gem 'aws-sdk-dsql'`                            |
-| SQLAlchemy | `aurora_dsql_sqlalchemy`           | `pip install aurora-dsql-sqlalchemy boto3`                   |
+| Framework  | Adapter                                 | Install                                                      |
+| ---------- | --------------------------------------- | ------------------------------------------------------------ |
+| Django     | `aurora_dsql_django`                    | `pip install aurora-dsql-django boto3`                       |
+| EF Core    | `Amazon.AuroraDsql.EntityFrameworkCore` | `dotnet add package Amazon.AuroraDsql.EntityFrameworkCore`   |
+| Hibernate  | `aurora-dsql-hibernate-dialect`         | `software.amazon.dsql:aurora-dsql-hibernate-dialect` (Maven) |
+| Rails      | Standard `pg` gem + `aws-sdk-dsql`      | `gem 'pg'` + `gem 'aws-sdk-dsql'`                            |
+| SQLAlchemy | `aurora_dsql_sqlalchemy`                | `pip install aurora-dsql-sqlalchemy boto3`                   |
 
 ## Key Gotchas Per Framework
 
@@ -25,6 +26,20 @@ names and configuration not available in general documentation.
 | AutoField         | Replace with `UUIDField(primary_key=True, default=uuid.uuid4)`    |
 | ForeignKey        | Add `db_constraint=False`                                         |
 
+### EF Core (.NET)
+
+Requires .NET 8.0+, EF Core 9.0.7+, and `Amazon.AuroraDsql.Npgsql` 1.1.0+.
+
+| Issue          | Fix                                                                                                                                                                                                                                                |
+| -------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Setup          | `AddDsqlDataSource(host)` then `UseDsql(sp)` in `AddDbContext` (IAM auth via `Amazon.AuroraDsql.Npgsql`)                                                                                                                                           |
+| PKs            | `Guid` keys with a store-generated `gen_random_uuid()` default — leave `Id` unset on insert                                                                                                                                                        |
+| Auto-increment | `long` keys via `dsql.EnableIdentityColumns()` — `cacheSize: 1` for near-strict ordering, larger (default ≥ 65536) for throughput                                                                                                                  |
+| OCC retry      | `DsqlExecutionStrategy` auto-retries `SaveChangesAsync` in implicit transactions. Inside an explicit transaction it does NOT retry — use `ExecuteInTransactionAsync` and call `ChangeTracker.Clear()` first so retries don't replay stale entities |
+| FK constraints | Not enforced — navigations/`Include`/joins work, but enforce referential integrity in the application layer                                                                                                                                        |
+| Isolation      | Requested isolation levels are ignored; `SET TRANSACTION ISOLATION LEVEL`, `SAVEPOINT`, and `LOCK TABLE` are filtered at the ADO.NET layer                                                                                                         |
+| Migrations     | dsql-lint rewrites EF Core DDL for DSQL (e.g. `CREATE INDEX` → `CREATE INDEX ASYNC`) and makes it idempotent so failed migrations re-run safely                                                                                                    |
+
 ### Hibernate
 
 | Issue          | Fix                                                                                                                                                                                                                                                                                         |
diff --git a/tools/evals/databases-on-aws/dsql/evals.json b/tools/evals/databases-on-aws/dsql/evals.json
@@ -145,6 +145,31 @@
         "Recommends adding --header to the loader invocation"
       ],
       "llm_judge": true
+    },
+    {
+      "id": 13,
+      "prompt": "I'm building a new .NET web API with Entity Framework Core and want to use Aurora DSQL as the database. Help me get the data layer set up correctly.",
+      "expected_output": "Recommends the Amazon.AuroraDsql.EntityFrameworkCore adapter with AddDsqlDataSource/UseDsql, and guides toward DSQL-friendly patterns: Guid keys with gen_random_uuid(), application-layer referential integrity, and DsqlExecutionStrategy for OCC retry.",
+      "files": [],
+      "expectations": [
+        "Recommends the Amazon.AuroraDsql.EntityFrameworkCore adapter and AddDsqlDataSource/UseDsql setup",
+        "Recommends Guid primary keys with a gen_random_uuid() default (or EnableIdentityColumns for long keys)",
+        "Recommends enforcing referential integrity in the application layer",
+        "Recommends DsqlExecutionStrategy for OCC retry to handle concurrency conflicts"
+      ],
+      "llm_judge": true
+    },
+    {
+      "id": 14,
+      "prompt": "Can I use Aurora DSQL with a C# / .NET application? What's the recommended setup?",
+      "expected_output": "Confirms .NET support, recommends the Amazon.AuroraDsql.Npgsql connector for IAM auth and the Amazon.AuroraDsql.EntityFrameworkCore adapter for EF Core, and notes the .NET 8.0+/EF Core 9.0.7+ requirements.",
+      "files": [],
+      "expectations": [
+        "Confirms Aurora DSQL works with .NET / C#",
+        "Recommends the Amazon.AuroraDsql.Npgsql connector for automatic IAM authentication",
+        "Recommends the Amazon.AuroraDsql.EntityFrameworkCore adapter for EF Core users"
+      ],
+      "llm_judge": true
     }
   ]
 }
diff --git a/tools/evals/databases-on-aws/dsql/trigger_evals.json b/tools/evals/databases-on-aws/dsql/trigger_evals.json
@@ -63,6 +63,18 @@
     "query": "bulk load parquet data from S3 into DSQL — about 200 million rows across 50 files",
     "should_trigger": true
   },
+  {
+    "query": "I'm migrating a .NET app with Entity Framework Core over to Aurora DSQL",
+    "should_trigger": true
+  },
+  {
+    "query": "I'm building a .NET app with Entity Framework Core and want to use Aurora DSQL as the database",
+    "should_trigger": true
+  },
+  {
+    "query": "Can I use Aurora DSQL from a C# / .NET application? Looking for the recommended setup",
+    "should_trigger": true
+  },
   {
     "query": "I need to set up an Aurora Serverless v2 PostgreSQL cluster with read replicas for my analytics workload",
     "should_trigger": false

Original file line number	Diff line number	Diff line change
`@@ -164,7 +164,7 @@`
`164`	`164`	`"name": "databases-on-aws",`
`165`	`165`	`"source": "./plugins/databases-on-aws",`
`166`	`166`	`"tags": ["aws", "database", "aurora", "dsql", "serverless", "postgresql"],`
`167`		`- "version": "1.4.0"`
	`167`	`+ "version": "1.5.0"`
`168`	`168`	`},`
`169`	`169`	`{`
`170`	`170`	`"category": "deployment",`
Original file line number	Diff line number	Diff line change
`@@ -22,5 +22,5 @@`
`22`	`22`	`"license": "Apache-2.0",`
`23`	`23`	`"name": "databases-on-aws",`
`24`	`24`	`"repository": "https://github.com/awslabs/agent-plugins",`
`25`		`- "version": "1.4.0"`
	`25`	`+ "version": "1.5.0"`
`26`	`26`	`}`
Original file line number	Diff line number	Diff line change
`@@ -1,6 +1,6 @@`
`1`	`1`	`{`
`2`	`2`	`"name": "databases-on-aws",`
`3`		`- "version": "1.4.0",`
	`3`	`+ "version": "1.5.0",`
`4`	`4`	`"description": "Expert database guidance for the AWS database portfolio. Design schemas, execute queries, handle migrations, and choose the right database for your workload.",`
`5`	`5`	`"author": {`
`6`	`6`	`"name": "Amazon Web Services",`