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.

1. 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

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

Key files in the reference implementation:

Spring Boot Reactive (WebFlux + R2DBC)

For full details read → references/java-spring-reactive.md

Key differences from Spring Boot (blocking):

Quarkus

For full details read → references/java-quarkus.md

Key differences from Spring Boot:

Python Reference

For full details read → references/python.md

Node.js Reference

For full details read → references/nodejs.md

Go Reference

For full details read → references/go.md

.NET Reference

For full details read → references/dotnet.md

Step-by-Step: New Application Setup

1. Add Dependencies

Maven (Java):

<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>

Python:

pip install psycopg2-binary  # or asyncpg for async

Node.js:

npm install @yugabytedb/pg    # YugabyteDB smart driver (fork of node-postgres)

Go:

go get github.com/jackc/pgx/v5

2. Configure Datasource

Always set:

• auto-commit: false — YugabyteDB works best with explicit transaction management
• connection-init-sql with prepare warmup; execute warmup; commit; — validates and warms the connection
• socketTimeout — prevents hanging connections on node failure
• yb-servers-refresh-interval — refreshes cluster topology periodically

3. Implement Retry Logic

Never skip retries. YugabyteDB distributed transactions can fail with 40001 under normal operation (two concurrent writers hitting the same row). Without retries, these surface as errors to end users.

Use the reference KVRetryPolicy pattern — read references/java-spring.md for the full annotated implementation with all retry-worthy SQL states.

4. Schema Migrations

Use Flyway (Java) or Alembic (Python) for schema management. YugabyteDB supports all standard PostgreSQL DDL.

-- Example migration: V1_0_0__create.sql
CREATE EXTENSION IF NOT EXISTS "uuid-ossp";
CREATE TABLE IF NOT EXISTS kvinfo (
    key   uuid PRIMARY KEY,
    value text
);   -- tune tablet count to expected data size

Common Pitfalls

Sample Prompts

These are example prompts that should trigger this skill.

Java / Spring Boot

• "I'm building a Spring Boot app and need to connect it to YugabyteDB. Show me the Maven dependencies, application.yaml config, and how to set up the connection pool correctly."
• "My Spring Boot app talking to YugabyteDB keeps getting '40001 serialization failure' errors under load. How do I handle this properly?"
• "I have an existing Spring Boot app connected to PostgreSQL. What do I need to change to migrate it to YugabyteDB?"

Java / Spring Boot Reactive

• "How do I build a reactive Spring Boot application using WebFlux and R2DBC that connects to YugabyteDB with retry support?"

Java / Quarkus

• "I want to build a Quarkus REST API backed by YugabyteDB. Walk me through the setup including retry handling."
• "My Quarkus app has @Retry on the service but transactions still fail without retrying. What's wrong?"

Python

• "How do I write a Python service that connects to YugabyteDB and handles transaction retries correctly? I need create, read, and delete operations."
• "Show me how to use asyncpg with FastAPI and YugabyteDB with proper retry handling."

Node.js

• "Show me how to connect a Node.js Express app to YugabyteDB with proper retry logic for distributed transaction errors."

Go

• "I'm using Go with pgx and need to connect to YugabyteDB and retry on transaction conflicts. Show me a complete example."

.NET

• "How do I set up a .NET ASP.NET Core app with Entity Framework Core to use YugabyteDB, including handling serialization failures?"

General / Cross-runtime

• "What SQL error codes do I need to retry on when using YugabyteDB, and why?"
• "How should I configure my connection pool for YugabyteDB?"
• "Connect my app to YugabyteDB"
• "YugabyteDB retry"
• "YugabyteDB Spring Boot setup"