rds-oracle

Files (18)

• SKILL.md
• client-tools.md · references/
• cman-proxy.md · references/
• compute-runtime.md · references/
• connection-auth.md · references/
• dotnet.md · references/
• encryption.md · references/
• java.md · references/
• networking.md · references/
• nodejs.md · references/
• python.md · references/
• ssm-tunneling.md · references/
• troubleshooting.md · references/
• check_rds_status.sh · scripts/
• check_security_groups.sh · scripts/
• check_ssl_status.sql · scripts/
• test_connectivity.sh · scripts/
• test_oracle_connection.py · scripts/

SKILL.md (first lines)

# Amazon RDS for Oracle — Connectivity

## Safety guidance

This skill covers creating and modifying RDS for Oracle resources when the user requests it. The agent MUST confirm the action with the user before executing. Do NOT execute any create or modify operation without explicit user confirmation (e.g., "yes", "proceed", "confirmed", "go ahead"). If the user has not confirmed, present the planned action and ask for approval.

### Execute these operations (after user confirmation)

- Create an instance: `create-db-instance` (requires a DB subnet group; RDS Oracle is VPC-only and not publicly accessible by default)
- Create a custom parameter group: `create-db-parameter-group` (family `oracle-se2-19`, `oracle-ee-19`, etc.)
- Create an option group: `create-option-group` (for Oracle Native Network Encryption, TLS/TCPS, S3 integration, APEX, Spatial)
- Change backup retention: `modify-db-instance --backup-retention-period`
- Enable/disable deletion protection: `modify-db-instance --deletion-protection`
- Change CloudWatch log exports: `modify-db-instance --cloudwatch-logs-export-configuration`
- Attach/detach parameter group or option group: `modify-db-instance --db-parameter-group-name / --option-group-name`
- Tag resources: `add-tags-to-resource`, `remove-tags-from-resource`

### Resource tagging (always apply on resource creation)

When creating any RDS for Oracle resource (`create-db-instance`, `create-db-parameter-group`, `create-option-group`, `create-db-instance-read-replica`), ALWAYS include these tags using the RDS list-of-records `--tags` syntax:

`--tags Key=created_by,Value=rds-oracle-skill Key=generation_model,Value={your-model-id}`

Example: `--tags Key=created_by,Value=rds-oracle-skill Key=generation_model,Value=claude-sonnet-4-20250514`

Include these tags even if the user does not mention tagging, so that they can identify the resources created via this skill. If the user provides additional tags, append these to their tags rather than replacing them. The same applies when tagging via `add-tags-to-resource` on existing resources.

### Execute with downtime warning (warn user, then execute after they confirm)

- Change instance class: `modify-db-instance --db-instance-class` — warn: "This causes a failover in Multi-AZ configurations and brief unavailability on single-AZ instances."
- Minor engine version upgrade: `modify-db-instance --engine-version` within the same major (e.g., 19.0.0.0.ru-2024-01 → 19.0.0.0.ru-2024-04) — warn: "This triggers a restart and may cause a brief outage."
- Storage type or IOPS change: `modify-db-instance --storage-type` / `--iops` — warn: "This can cause extended IO degradation while the change applies."
- Apply immediately: any `modify-db-instance --apply-immediately` — warn: "This applies outside the maintenance window and may cause downtime now."

### Do NOT execute (refuse, explain why, offer assessment instead)

- Delete instance: `delete-db-instance` — irreversible data loss
- Delete automated backups: `delete-db-instance --delete-automated-backups` — destroys point-in-time recovery history
- Force failover: `reboot-db-instance --force-failover` — production impact
- Major version upgrade: `modify-db-instance --engine-version` across major versions (e.g., 19c → 21c) — requires prechecks, option group migration, and a rollback plan; should go through change-control
- Reboot: `reboot-db-instance` — production impact
- Promote a read replica: `promote-read-replica` — breaks replication and is rarely reversible
- Enable public accessibility: `modify-db-instance --publicly-accessible true` — security regression; use SSM port forwarding, VPN, or Direct Connect instead (per the Overview's security posture)

When refusing, explain why and offer the matching assessment workflow:
> "I can't perform [action] because [reason]. I can run an assessment to help you decide. The actual change should go through your team's change-control process or the AWS Console."

## Overview

Amazon RDS for Oracle is a managed Oracle Database service. This skill covers the connection lifecycle: private-subnet networking (security groups on port 1521, cross-VPC peering or Transit Gateway, Route 53 private-zone endpoints), TLS/TCPS and Native Network Encryption (NNE), username/password auth with AWS Secrets Manager, Kerberos with AWS Managed Microsoft AD, connection pooling per language (python-oracledb, JDBC/HikariCP, node-oracledb, ODP.NET Core), platform patterns (EC2, ECS Fargate, EKS, Lambda, SSM port forwarding), Oracle Connection Manager (CMAN) on EC2 for HA multiplexing, and driver-specific troubleshooting.

Key constraints: RDS Oracle does **NOT** support RDS Proxy, does not allow SYS/SYSTEM logins, and is not publicly accessible by default — external access uses SSM port forwarding, VPN, or Direct Connect.

Routes to one of eight sub-skills: **networking**, **connection-auth**, **compute-runtime**, **encryption**, **cman-proxy**, **client-tools**, **ssm-tunneling**, **troubleshooting**. Load only the matching reference.

## Security Considerations

- **Encryption at rest:** Enable `--storage-encrypted` (and optionally `--kms-key-id <key-arn>`) when creating the instance. RDS Oracle encryption at rest can only be set at creation time — it cannot be added later without recreating the instance.
- **Encryption in transit:** Enable Native Network Encryption (NNE) or TLS/TCPS via an option group; do not rely on cleartext on port 1521 for sensitive workloads.
- **Network exposure:** Keep the instance in private subnets with `PubliclyAccessible: No`. Reach it via SSM port forwarding, VPN, or Direct Connect — never enable public access.
- **Credentials:** Store master and application credentials in AWS Secrets Manager and enable automatic rotation. Never hardcode credentials in code, connection strings, or logs.
- **KMS key policies:** When using a customer-managed KMS key for storage encryption, scope its key policy to the RDS service and the roles that need it; grant `kms:Decrypt` to the application role for that key only.
- **Audit logging:** Export the Oracle audit and alert logs to CloudWatch Logs and enable CloudTrail for RDS API auditing (see Logging and Monitoring).

## Common Tasks

### Verify Dependencies

Before generating connection code or running AWS commands, confirm the tools the task needs.

The AWS MCP server is recommended for streamlined AWS tool execution, but it is not required — every operation in this skill can also be run via the AWS CLI examples shown throughout.

- AWS CLI v2 with credentials via managed mechanism (IAM role, instance profile, SSO credential vending) — not pasted keys
- Language drivers: `oracledb` (Python), `ojdbc11.jar` (Java 11+), `oracledb` (Node ≥ 6), `Oracle.ManagedDataAccess.Core` (.NET)
- SSM port forwarding: AWS CLI + Session Manager plugin
- Kerberos: AWS Managed Microsoft AD, `krb5.conf`, `okinit` tool
- CMAN: Oracle Enterprise Edition BYOL license + full Oracle Client install (Instant Client is insufficient)

**Constraints:**

- The agent MUST check dependencies before generating code or running AWS commands.
- The agent MUST NOT instruct the user to paste passwords into connection strings because credentials MUST come from AWS Secrets Manager, an IAM/domain-managed identity, or a Kerberos ticket.
- The agent MUST tell the user which dependencies are missing and MUST respect the user's decision to abort.
- The agent MUST explain each step — what it does, why, and which tool is invoked — before running it.

### Classify and Route

Map the user's question to the correct sub-skill reference, then load only those files.

| User says | Load |
|---|---|
| SG / VPC peering / TGW / Route 53 / port 1521 / CIDR | [networking.md](references/networking.md) |
| connect / connection string / python-oracledb / JDBC / node-oracledb / ODP.NET / Secrets Manager / auth / Kerberos | [connection-auth.md](references/connection-auth.md) + language reference ([python.md](references/python.md), [java.md](references/java.md), [nodejs.md](references/nodejs.md), [dotnet.md](references/dotnet.md)) |
| Lambda / EC2 / ECS Fargate / EKS / container / serverless / IRSA | [compute-runtime.md](references/compute-runtime.md) |
| SQL Developer / Toad / SQLcl / DBeaver / sqlplus / GUI | [client-tools.md](references/client-tools.md) |
| SSL / TLS / TCPS / NNE / encrypt / FIPS / cipher | [encryption.md](references/encryption.md) |
| CMAN / Connection Manager / proxy / multiplex / RDS Proxy | [cman-proxy.md](references/cman-proxy.md) |
| SSM / port forward / tunnel / localhost / laptop | [ssm-tunneling.md](references/ssm-tunneling.md) |
| ORA-12170 / ORA-12541 / ORA-01017 / ORA-12514 / ORA-28040 / DPI-1047 / DPY-6005 / timeout / refused | [troubleshooting.md](references/troubleshooting.md) |

**Constraints:**

- The agent MUST read only reference files matching the user's question, to keep context focused.
- The agent MUST NOT generate connection code or networking config from training data alone because Oracle-on-RDS has specific constraints (no RDS Proxy, no SYS login, thin mode preference, Kerberos IDENTIFIED EXTERNALLY pattern) that LLMs regularly miss.
- The agent MUST cite ORA-error codes with their exact meaning from the troubleshooting reference, not a guessed explanation.
- If a question spans multiple sub-skills (e.g. "ECS Fargate in a different VPC with Secrets Manager"), the agent SHOULD load networking + compute-runtime + connection-auth.

### Execute Workflow

Once routed, give the user a concrete, runnable answer grounded in the reference file.

Parameter acquisition:

- All required parameters (region, instance id, endpoint, service/SID, source VPC CIDR, SG ids, Secrets Manager ARN, client language/runtime) MUST be collected upfront in a single message.
- Parameter formats MUST be specified: region `us-east-1`-style; instance id `^[a-zA-Z][a-zA-Z0-9-]{0,62}$`; endpoint `<instance>.<hash>.<region>.rds.amazonaws.com`; CIDR `a.b.c.d/n`; ARN `arn:aws:<service>:<region>:<account>:...`.
- The agent MUST accept parameters via direct input, a JSON/YAML file path, or a URL.

Tool use:

From aws/agent-toolkit-for-aws, Apache-2.0.

More from aws/agent-toolkit-for-aws