Skip to main content
skill CX Codex

aws-aurora — Claude Code skill: what it does, how to install

Guides AWS Aurora database architecture, RDS Proxy setup, connection pooling, and Data API queries in serverless setups.

MIT 288 installs ★ 713 updated 2026-10-13

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add alinaqi/maggy --skill aws-aurora -a claude-code
Open on GitHub

What aws-aurora does

The skill triggers on paths matching **/rds*, **/aurora*, serverless.*, or template.yaml. It guides the assistant to avoid direct database connections from Lambda functions, routing queries through RDS Proxy or the HTTP Data API instead.

It includes production-ready snippets for AWS CDK proxy deployment, IAM token generation via @aws-sdk/rds-signer, and transactional operations using data-api-client in TypeScript or boto3 in Python.

Direct database connections belong only on persistent compute like EC2 or ECS. Opening raw client pools inside short-lived Lambda instances will quickly exhaust database connection limits.

What it helps with

  • configure RDS Proxy in AWS CDK with connection pooling rules
  • authenticate Lambda functions against PostgreSQL using IAM tokens
  • run HTTP queries and transactions via Aurora Data API using Python or TypeScript
  • calculate safe connection pool timeouts for serverless workloads

Example prompts for the agent

  • Configure an AWS Lambda connection to Aurora PostgreSQL using RDS Proxy
  • Write a balance transfer transaction using Aurora Data API in Python boto3
  • Generate a CDK stack with DatabaseProxy for an Aurora Serverless v2 cluster

How to install aws-aurora

1Skills CLI (Vercel)

npx skills add alinaqi/maggy --skill aws-aurora -a claude-code

2Manually: put the files in place

~/.claude/skills/aws-aurora/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/aws-aurora/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about aws-aurora

How do I install aws-aurora in Claude Code?

Run npx skills add alinaqi/maggy --skill aws-aurora -a claude-code. The file will be placed into ~/.claude/skills/aws-aurora/SKILL.md.

What does the aws-aurora skill do?

It provides patterns and snippets for building on Amazon Aurora Serverless v2 and RDS. It covers connection pooling strategies, proxy tuning, and Data API usage.

When should Data API be used instead of RDS Proxy?

Data API needs no VPC setup and simplifies HTTP query calls, but incurs higher per-query latency and only works with Aurora Serverless. RDS Proxy requires a VPC while supporting standard SQL clients under heavy traffic.

Source text

SKILL.md · MIT
---
name: aws-aurora
description: AWS Aurora Serverless v2, RDS Proxy, Data API, connection pooling
when-to-use: When working with AWS Aurora/RDS databases
user-invocable: false
paths: ["**/rds*", "**/aurora*", "serverless.*", "template.yaml"]
effort: medium
---

# AWS Aurora Skill


Amazon Aurora is a MySQL/PostgreSQL-compatible relational database with serverless scaling, high availability, and enterprise features.

**Sources:** [Aurora Docs](https://docs.aws.amazon.com/AmazonRDS/latest/AuroraUserGuide/) | [Serverless v2](https://docs.aws.amazon.com/AmazonRDS/latest/AuroraUserGuide/aurora-serverless-v2.html) | [RDS Proxy](https://docs.aws.amazon.com/AmazonRDS/latest/AuroraUserGuide/rds-proxy.html)

---

## Core Principle

**Use RDS Proxy for serverless, Data API for simplicity, connection pooling always.**

Aurora excels at ACID-compliant workloads. For serverless architectures (Lambda), always use RDS Proxy or Data API to handle connection management. Never open raw connections from Lambda functions.

---

## Aurora Options

| Option | Best For |
|--------|----------|
| **Aurora Serverless v2** | Variable workloads, auto-scaling (0.5-128 ACUs) |
| **Aurora Provisioned** | Predictable workloads, maximum performance |
| **Aurora Global** | Multi-region, disaster recovery |
| **Data API** | Serverless without VPC, simple HTTP access |
| **RDS Proxy** | Connection pooling for Lambda, high concurrency |

---

## Connection Strategies

### Strategy 1: RDS Proxy (Recommended for Lambda)
```
Lambda → RDS Proxy → Aurora
         (pool)
```
- Connection pooling and reuse
- Automatic failover handling
- IAM authentication support
- Works with existing SQL clients

### Strategy 2: Data API (Simplest for Serverless)
```
Lambda → Data API (HTTP) → Aurora
```
- No VPC required
- No connection management
- Higher latency per query
- Limited to Aurora Serverless

### Strategy 3: Direct Connection (Not for Lambda)
```
App Server → Aurora
(persistent connection)
```
- Only for long-running servers (ECS, EC2)
- Manage connection pool yourself
- Not suitable for serverless

---

## RDS Proxy Setup

### Create Proxy (AWS Console/CDK)
```typescript
// CDK example
import * as rds from 'aws-cdk-lib/aws-rds';

const proxy = new rds.DatabaseProxy(this, 'Proxy', {
  proxyTarget: rds.ProxyTarget.fromCluster(cluster),
  secrets: [cluster.secret!],
  vpc,
  securityGroups: [proxySecurityGroup],
  requireTLS: true,
  idleClientTimeout: cdk.Duration.minutes(30),
  maxConnectionsPercent: 90,
  maxIdleConnectionsPercent: 10,
  borrowTimeout: cdk.Duration.seconds(30)
});
```

### Connect via Proxy (TypeScript/Node.js)
```typescript
// lib/db.ts
import { Pool } from 'pg';
import { Signer } from '@aws-sdk/rds-signer';

const signer = new Signer({
  hostname: process.env.RDS_PROXY_ENDPOINT!,
  port: 5432,
  username: process.env.DB_USER!,
  region: process.env.AWS_REGION!
});

// IAM authentication
async function getPool(): Promise<Pool> {
  const token = await signer.getAuthToken();

  return new Pool({
    host: process.env.RDS_PROXY_ENDPOINT,
    port: 5432,
    database: process.env.DB_NAME,
    user: process.env.DB_USER,
    password: token,
    ssl: { rejectUnauthorized: true },
    max: 1,  // Single connection for Lambda
    idleTimeoutMillis: 120000,
    connectionTimeoutMillis: 10000
  });
}

// Usage in Lambda
let pool: Pool | null = null;

export async function handler(event: any) {
  if (!pool) {
    pool = await getPool();
  }

  const result = await pool.query('SELECT * FROM users WHERE id = $1', [event.userId]);
  return result.rows[0];
}
```

### Proxy Configuration Best Practices
```bash
# Key settings for Lambda workloads
MaxConnectionsPercent: 90        # Use most of DB connections
MaxIdleConnectionsPercent: 10    # Keep some idle for bursts
ConnectionBorrowTimeout: 30s     # Wait for available connection
IdleClientTimeout: 30min         # Close idle proxy connections

# Monitor these CloudWatch metrics:
# - DatabaseConnectionsCurrentlyBorrowed
# - DatabaseConnectionsCurrentlySessionPinned
# - QueryDatabaseResponseLatency
```

---

## Data API (HTTP-based)

### Enable Data API
```bash
# Must be Aurora Serverless
aws rds modify-db-cluster \
  --db-cluster-identifier my-cluster \
  --enable-http-endpoint
```

### TypeScript with Data API Client v2
```bash
npm install data-api-client
```

```typescript
// lib/db.ts
import DataAPIClient from 'data-api-client';

const db = DataAPIClient({
  secretArn: process.env.DB_SECRET_ARN!,
  resourceArn: process.env.DB_CLUSTER_ARN!,
  database: process.env.DB_NAME!,
  region: process.env.AWS_REGION!
});

// Simple query
const users = await db.query('SELECT * FROM users WHERE active = :active', {
  active: true
});

// Insert with returning
const result = await db.query(
  'INSERT INTO users (email, name) VALUES (:email, :name) RETURNING *',
  { email: '[email protected]', name: 'Test User' }
);

// Transaction
const transaction = await db.transaction();
try {
  await transaction.query('UPDATE accounts SET balance = balance - :amount WHERE id = :from', {
    amount: 100, from: 1
  });
  await transaction.query('UPDATE accounts SET balance = balance + :amount WHERE id = :to', {
    amount: 100, to: 2
  });
  await transaction.commit();
} catch (error) {
  await transaction.rollback();
  throw error;
}
```

### Python with boto3
```python
# requirements.txt
boto3>=1.34.0

# db.py
import boto3
import os

rds_data = boto3.client('rds-data')

CLUSTER_ARN = os.environ['DB_CLUSTER_ARN']
SECRET_ARN = os.environ['DB_SECRET_ARN']
DATABASE = os.environ['DB_NAME']


def execute_sql(sql: str, parameters: list = None):
    """Execute SQL via Data API."""
    params = {
        'resourceArn': CLUSTER_ARN,
        'secretArn': SECRET_ARN,
        'database': DATABASE,
        'sql': sql
    }

    if parameters:
        params['parameters'] = parameters

    return rds_data.execute_statement(**params)


def get_user(user_id: int):
    result = execute_sql(
        'SELECT * FROM users WHERE id = :id',
        [{'name': 'id', 'value': {'longValue': user_id}}]
    )
    return result.get('records', [])


def create_user(email: str, name: str):
    result = execute_sql(
        'INSERT INTO users (email, name) VALUES (:email, :name) RETURNING *',
        [
            {'name': 'email', 'value': {'stringValue': email}},
            {'name': 'name', 'value': {'stringValue': name}}
        ]
    )
    return result.get('generatedFields')


# Transaction
def transfer_funds(from_id: int, to_id: int, amount: float):
    transaction = rds_data.begin_transaction(
        resourceArn=CLUSTER_ARN,
        secretArn=SECRET_ARN,
        database=DATABASE
    )
    transaction_id = transaction['transactionId']

    try:
        execute_sql(
            'UPDATE accounts SET balance = balance - :amount WHERE id = :id',
            [
                {'name': 'amount', 'value': {'doubleValue': amount}},
                {'name': 'id', 'value': {'longValue': from_id}}
            ]
        )

        execute_sql(
            'UPDATE accounts SET balance = balance + :amount WHERE id = :id',
            [
                {'name': 'amount', 'value': {'doubleValue': amount}},
                {'name': 'id', 'value': {'longValue': to_id}}
            ]
        )

        rds_data.commit_transaction(
            resourceArn=CLUSTER_ARN,
            secretArn=SECRET_ARN,
            transactionId=transaction_id
        )
    except Exception as e:
        rds_data.rollback_transaction(
            resourceArn=CLUSTER_ARN,
            secretArn=SECRET_ARN,
            transactionId=transaction_id
        )
        raise e
```

---

## Prisma with Aurora

### Setup (VPC Connection via RDS Proxy)
```bash
npm install prisma @prisma/client
npx prisma init
```

```prisma
// prisma/schema.prisma
generator client {
  provider = "prisma-client-js"
}

datasource db {
  provider = "postgresql"
  url      = env("DATABASE_URL")
}

model User {
  id        Int      @id @default(autoincrement())
  email     String   @unique
  name      String
  posts     Post[]
  createdAt DateTime @default(now())
  updatedAt DateTime @updatedAt
}

model Post {
  id        Int      @id @default(autoincrement())
  title     String
  content   String?
  published Boolean  @default(false)
  author    User     @relation(fields: [authorId], references: [id])
  authorId  Int
  createdAt DateTime @default(now())
}
```

### Environment
```bash
# Use RDS Proxy endpoint
DATABASE_URL="postgresql://user:[email protected]:5432/mydb?schema=public&connection_limit=1"
```

### Lambda Handler with Prisma
```typescript
// handlers/users.ts
import { PrismaClient } from '@prisma/client';

// Reuse client across invocations
let prisma: PrismaClient | null = null;

function getPrisma(): PrismaClient {
  if (!prisma) {
    prisma = new PrismaClient({
      datasources: {
        db: { url: process.env.DATABASE_URL }
      }
    });
  }
  return prisma;
}

export async function handler(event: any) {
  const db = getPrisma();

  const users = await db.user.findMany({
    include: { posts: true },
    take: 10
  });

  return {
    statusCode: 200,
    body: JSON.stringify(users)
  };
}
```

---

## Aurora Serverless v2

### Capacity Configuration
```typescript
// CDK
const cluster = new rds.DatabaseCluster(this, 'Cluster', {
  engine: rds.DatabaseClusterEngine.auroraPostgres({
    version: rds.AuroraPostgresEngineVersion.VER_15_4
  }),
  serverlessV2MinCapacity: 0.5,  // Minimum ACUs
  serverlessV2MaxCapacity: 16,   // Maximum ACUs
  writer: rds.ClusterInstance.serverlessV2('writer'),
  readers: [
    rds.ClusterInstance.serverlessV2('reader', { scaleWithWriter: true })
  ],
  vpc,
  vpcSubnets: { subnetType: ec2.SubnetType.PRIVATE_WITH_EGRESS }
});
```

### Capacity Guidelines

| Workload | Min ACUs | Max ACUs |
|----------|----------|----------|
| Dev/Test | 0.5 | 2 |
| Small Production | 2 | 8 |
| Medium Production | 4 | 32 |
| Large Production | 8 | 128 |

### Handle Scale-to-Zero Wake-up
```typescript
// Data API Client v2 handles this automatically
// For direct connections, implement retry logic:

import { Pool } from 'pg';

async function queryWithRetry(
  pool: Pool,
  sql: string,
  params: any[],
  maxRetries = 3
): Promise<any> {
  for (let attempt = 1; attempt <= maxRetries; attempt++) {
    try {
      return await pool.query(sql, params);
    } catch (error: any) {
      // Aurora Serverless waking up
      if (error.code === 'ETIMEDOUT' || error.message?.includes('Communications link failure')) {
        if (attempt === maxRetries) throw error;
        // Exponential backoff
        await new Promise(resolve => setTimeout(resolve, Math.pow(2, attempt) * 1000));
        continue;
      }
      throw error;
    }
  }
}
```

---

## Migrations

### Using Prisma Migrate
```bash
# Development (creates migration)
npx prisma migrate dev --name add_users_table

# Production (apply migrations)
npx prisma migrate deploy

# Generate client
npx prisma generate
```

### CI/CD Migration Script
```yaml
# .github/workflows/deploy.yml
- name: Run migrations
  run: |
    # Connect via bastion or use a migration Lambda
    npx prisma migrate deploy
  env:
    DATABASE_URL: ${{ secrets.DATABASE_URL }}
```

### Migration Lambda
```typescript
// lambdas/migrate.ts
import { execSync } from 'child_process';

export async function handler() {
  try {
    execSync('npx prisma migrate deploy', {
      env: {
        ...process.env,
        DATABASE_URL: process.env.DATABASE_URL
      },
      stdio: 'inherit'
    });
    return { statusCode: 200, body: 'Migrations applied' };
  } catch (error) {
    console.error('Migration failed:', error);
    throw error;
  }
}
```

---

## Connection Pooling (Non-Lambda)

### PgBouncer Sidecar (ECS/EKS)
```yaml
# docker-compose.yml
services:
  app:
    build: .
    environment:
      DATABASE_URL: postgresql://user:pass@pgbouncer:6432/mydb

  pgbouncer:
    image: edoburu/pgbouncer
    environment:
      DATABASE_URL: postgresql://user:pass@aurora-endpoint:5432/mydb
      POOL_MODE: transaction
      MAX_CLIENT_CONN: 1000
      DEFAULT_POOL_SIZE: 20
```

### Application-Level Pooling
```typescript
// For long-running servers (not Lambda)
import { Pool } from 'pg';

const pool = new Pool({
  host: process.env.DB_HOST,
  port: 5432,
  database: process.env.DB_NAME,
  user: process.env.DB_USER,
  password: process.env.DB_PASSWORD,
  max: 20,                  // Max connections
  idleTimeoutMillis: 30000, // Close idle after 30s
  connectionTimeoutMillis: 10000
});

// Use pool for all queries
export async function query(sql: string, params?: any[]) {
  const client = await pool.connect();
  try {
    return await client.query(sql, params);
  } finally {
    client.release();
  }
}
```

---

## Monitoring

### Key CloudWatch Metrics
```
# Aurora
- CPUUtilization
- DatabaseConnections
- FreeableMemory
- ServerlessDatabaseCapacity (ACUs)
- AuroraReplicaLag

# RDS Proxy
- DatabaseConnectionsCurrentlyBorrowed
- DatabaseConnectionsCurrentlySessionPinned
- QueryDatabaseResponseLatency
- ClientConnectionsReceived
```

### Performance Insights
```bash
# Enable via console or CLI
aws rds modify-db-cluster \
  --db-cluster-identifier my-cluster \
  --enable-performance-insights \
  --performance-insights-retention-period 7
```

---

## Security

### IAM Database Authentication
```typescript
import { Signer } from '@aws-sdk/rds-signer';

const signer = new Signer({
  hostname: process.env.DB_HOST!,
  port: 5432,
  username: 'iam_user',
  region: 'us-east-1'
});

const token = await signer.getAuthToken();

// Use token as password (valid for 15 minutes)
const pool = new Pool({
  host: process.env.DB_HOST,
  user: 'iam_user',
  password: token,
  ssl: true
});
```

### Secrets Manager Rotation
```typescript
import { SecretsManagerClient, GetSecretValueCommand } from '@aws-sdk/client-secrets-manager';

const client = new SecretsManagerClient({ region: 'us-east-1' });

async function getDbCredentials() {
  const response = await client.send(
    new GetSecretValueCommand({ SecretId: process.env.DB_SECRET_ARN })
  );
  return JSON.parse(response.SecretString!);
}
```

---

## CLI Quick Reference

```bash
# Cluster operations
aws rds describe-db-clusters
aws rds create-db-cluster --engine aurora-postgresql --db-cluster-identifier my-cluster
aws rds delete-db-cluster --db-cluster-identifier my-cluster --skip-final-snapshot

# Serverless v2
aws rds modify-db-cluster \
  --db-cluster-identifier my-cluster \
  --serverless-v2-scaling-configuration MinCapacity=0.5,MaxCapacity=16

# Data API
aws rds-data execute-statement \
  --resource-arn $CLUSTER_ARN \
  --secret-arn $SECRET_ARN \
  --database mydb \
  --sql "SELECT * FROM users"

# Proxy
aws rds describe-db-proxies
aws rds create-db-proxy --db-proxy-name my-proxy --engine-family POSTGRESQL ...

# Snapshots
aws rds create-db-cluster-snapshot --db-cluster-identifier my-cluster --db-cluster-snapshot-identifier backup-1
aws rds restore-db-cluster-from-snapshot --db-cluster-identifier restored --snapshot-identifier backup-1
```

---

## Anti-Patterns

- **Direct Lambda→Aurora connections** - Always use RDS Proxy or Data API
- **No connection limits** - Set `max: 1` for Lambda, use pooling for servers
- **Ignoring cold starts** - Serverless v2 needs time to scale; keep minimum ACUs for production
- **No read replicas** - Offload reads to replicas for heavy workloads
- **Missing IAM auth** - Use IAM over static passwords when possible
- **No retry logic** - Handle transient errors from scaling/failover
- **Over-provisioned capacity** - Use Serverless v2 for variable workloads
- **Skipping Secrets Manager** - Never hardcode credentials

© alinaqi · MIT · alinaqi/maggy

Similar skills

All skills for Cloud: AWS, Azure, GCP →
creating-amazon-aurora-db-cluster-with-instances aws creating-amazon-aurora-db-cluster-with-instances creates Aurora cluster with instances, sets up password via Secrets Manager, and monitors status with retry logic. Supports MySQL and PostgreSQL. CX Codex +1 6,800installs amazon-aurora-postgresql aws amazon-aurora-postgresql — a skill that runs Aurora PostgreSQL chores from the chat: cluster creation, ACU sizing, commitment pricing, upgrades. Built for teams whose Postgres already lives in AWS. CX Codex +1 6,500installs aws-cloudformation-rds Giuseppe Trisciuoglio aws-cloudformation-rds guides Claude Code through AWS CloudFormation templates for Amazon RDS, Aurora, multi-AZ setups, and related network resources. Use it when shaping database infrastructure. CX Codex +1 ★ 372repo stars aws-rds-spring-boot-integration giuseppe-trisciuoglio aws-rds-spring-boot-integration is a Claude Code skill for wiring Spring Boot applications to AWS RDS. It covers Aurora, MySQL and PostgreSQL setups. CX Codex +1 3,900installs aws-solution-architect Alireza Rezvani aws-solution-architect designs AWS architectures, produces IaC templates, and reviews cloud costs. Use it for serverless builds, AWS migration work, or CI/CD planning. CX Codex +1 1,586installs aws-serverless-eda zxkane aws-serverless-eda guides serverless and event-driven architecture design on AWS following Well-Architected principles. Handy when setting up Lambda, Step Functions, DynamoDB, and EventBridge. CX Codex +1 755installs

From the same set61

The whole set →
agent-teams agent-teams coordinates AI agents around a required TDD pipeline. Use it when feature work needs ordered checks, security review, and pull request creation. CX Codex +1 300installs supabase-python supabase-python guides FastAPI application setup using Supabase for authentication and SQLAlchemy or SQLModel for database queries. CX Codex +1 298installs supabase-node supabase-node — a skill for Node.js backends built with Express or Hono, using Supabase Auth and Drizzle ORM for API and database patterns. CX Codex +1 293installs existing-repo A skill to quickly understand an existing repository: detects project structure, finds already-configured tools, and sets up missing guardrails without breaking anything. CX Codex +1 292installs reddit-ads Guides code generation for the Reddit Ads API, covering campaign hierarchies, OAuth 2.0 flows, and rate limits. CX Codex +1 287installs credentials This skill finds API keys in a central access file and maps them to environment variables. Use it when setting up a project that needs service credentials. CX Codex +1 287installs iterative-development iterative-development is a Claude Code skill that runs tests after each response, feeds failures back to the model, and continues the TDD loop until tests pass. CX Codex +1 286installs code-graph code-graph — a skill that indexes your project as a symbol and dependency graph. Query the graph instead of reading files sequentially: get function signatures, call chains, and blast radius in milliseconds. CX Codex +1 285installs

Project sponsors

Companies that keep this analytics open