agent-skillsCAUTION

From the repository's own README, as read at the audited commit. Badges and raw HTML are left out.

The instruction file, verbatim from the audited commit — this is the text the model reads, and the surface the audit's instruction layer examines. Quoted here so you can judge it without cloning anything.

---
name: yugabytedb-app-dev
description: >
  Build production-grade applications that connect to YugabyteDB across any language runtime or framework.
  Covers JDBC/Spring Boot, Spring Boot Reactive (WebFlux + R2DBC), Quarkus (SmallRye Fault Tolerance + Agroal), Python, Node.js, Go, .NET, and more — with correct driver config, pool tuning (HikariCP/Agroal/Npgsql),
  transaction retry logic, Flyway migrations, and topology-aware
  load balancing. Use this skill whenever the user is writing NEW application code that talks to YugabyteDB,
  integrating a framework (Spring, Quarkus, Micronaut, FastAPI, Express, etc.) with YugabyteDB, asking how to
  handle transaction retries or serialization errors with YugabyteDB, configuring a connection pool for YugabyteDB,
  Trigger even when the user just says
  "connect my app to YugabyteDB" or "YugabyteDB Spring Boot" or "YugabyteDB retry".
---

# YugabyteDB Application Development Skill

A reference skill for building applications on top of YugabyteDB, covering connection config,
transaction retries, and language/framework-specific best practices.

---

## Overview

YugabyteDB is a distributed SQL database compatible with PostgreSQL. Writing applications for it
requires attention to three areas standard Postgres apps often skip:

1. **Driver** — Use the YugabyteDB JDBC driver (`jdbc-yugabytedb`) or the standard Postgres driver.
   YB's driver adds cluster-aware load balancing and topology routing.
2. **Retries** — Distributed transactions can fail with transient errors (serialization failures `40001`,
   deadlocks `40P01`, connection resets). Applications MUST retry these rather than surface them to users.
---

## Quick Reference by Runtime

| Runtime | Driver / Library | Retry Mechanism |
|---|---|---|
| Java / Spring Boot | `jdbc-yugabytedb` + HikariCP | Spring core `RetryPolicy` + `ExponentialBackOff` (built-in, no extra dep) + AOP aspect |
| Java / Spring Boot Reactive | `r2dbc-postgresql` + r2dbc-pool | Reactor `.retryWhen(YbRetry.spec())` inline in pipeline |
| Java / Quarkus | `jdbc-yugabytedb` + Agroal | SmallRye `@Retry` + CDI interceptor for exception translation |
| Python | `psycopg2` / `asyncpg` | Custom decorator wrapping `psycopg2.errors.SerializationFailure` | Two connection pools |
| Node.js | `@yugabytedb/pg` (smart driver) | `withRetry` loop catching `40001`/`40P01`/`XX000` | `EndpointPoolManager` (multi-endpoint probe + failover) |
| Go | `pgx` | `pgx` retry loop | Two `pgxpool.Pool` instances |
| .NET / ASP.NET Core | `Npgsql` + EF Core | Polly `AsyncRetryPolicy` | Two `DbContext` registrations (rw + ro) |

---

## Instructions
- Use the latest stable version of the YugabyteDB driver for your language
- Use the latest stable version of the application framework for your language

---

## Core Concepts

### Transaction Error Codes to Retry

```
40001  — serialization_failure (optimistic concurrency)
40P01  — deadlock_detected
57P01  — admin_shutdown (node restart / kill -15)
08006  — connection_failure (socket timeout, kill -9)
XX000  — internal_error — ONLY retry conditionally
```

Also retry on these Java exception types for JPA/JDBC:
- `SQLRecoverableException`
- `SQLTransientConnectionException`
- `TransientDataAccessException`
- Hibernate `TransactionException` (begin/commit/rollback failures)

---

## Java References

### Spring Boot

For full details read → [`references/java-spring.md`](references/java-spring.md)

Key files in the reference implementation:

| File | Purpose |
|---|---|
| `KVRetryPolicy.java` | Implements `RetryPolicy` — classifies retryable exceptions; owns `ExponentialBackOff` |
| `DataSourceAspect.java` | AOP aspect wrapping all `@Service` methods with `RetryTemplate` |
| `YbDataApplication.java` | Wires `RetryTemplate` with exponential backoff from config |
| `KVService.java` | Service using `@Transactional` and `@Transactional(readOnly = true)` |
| `application.yaml` | Full driver + pool + retry config |

### Spring Boot Reactive (WebFlux + R2DBC)

For full details read → [`references/java-spring-reactive.md`](references/java-spring-reactive.md)

Key differences from Spring Boot (blocking):

| Topic | Reactive behaviour |
|---|---|
| Driver | `com.yugabyte:r2dbc-postgresql` (YugabyteDB fork) — URL scheme `r2dbc:postgresql://` |
| Retry | `RetryConfigSpec` bean provides `Retry`; controller applies `.retryWhen(retrySpec)` on each pipeline |
| Transactions | `@Transactional` in service; retry wraps outside via controller pipeline |
| Migrations | Flyway still runs over JDBC at startup (add `jdbc-yugabytedb` as a side-car dep) |

### Quarkus

For full details read → [`references/java-quarkus.md`](references/java-quarkus.md)

Key differences from Spring Boot:

| Topic | Quarkus behaviour |
|---|---|
| Connection pool | Agroal (not HikariCP); config via `quarkus.datasource.jdbc.*` |
| Retry mechanism | SmallRye Fault Tolerance `@Retry` + custom CDI interceptor for SQL-state translation |
| **Interceptor ordering** | **CRITICAL**: set `mp.fault.tolerance.interceptor.priority=100` so `@Retry` wraps outside `@Transactional`, giving each retry a fresh transaction |
| Native image | YugabyteDB driver is JVM-mode only — not compatible with GraalVM native compilation |

---

## Python Reference

For full details read → [`references/python.md`](references/python.md)

---

## Node.js Reference

For full details read → [`references/nodejs.md`](references/nodejs.md)

---

## Go Reference

For full details read → [`references/go.md`](references/go.md)

---

## .NET Reference

For full details read → [`references/dotnet.md`](references/dotnet.md)

---

## Step-by-Step: New Application Setup

### 1. Add Dependencies

**Maven (Java):**
```xml
<dependency>
  <groupId>com.yugabyte</groupId>
  <artifactId>jdbc-yugabytedb</artifactId>
  <version>42.7.3-yb-4</version>
</dependency>
<dependency>
  <groupId>org.springframework.retry</groupId>
  <artifactId>spring-retry</artifactId>
  <version>2.0.12</version>
</dependency>
```

**

CAUTIONgrade C · trust 79/100 Install with care. The audit found things worth knowing before you trust its output.

What the source does

Filesystem

none-observed

Network

declared (1 observation(s))

Shell

none-observed

Dependencies

pinned

Secrets in source

found

Findings (5)

"postgresql://yugabyte:[email protected]:5433/yugabyte" +

DSN = "postgresql://yugabyte:[email protected]:5433/yugabyte?load_balance=true"

dsn="postgresql://yugabyte:[email protected]:5433/yugabyte"

dsn="postgresql://yugabyte:[email protected]:5433/yugabyte",

Gates applied: no_behavioural_pass, no_license.