Find Idle RDS Instances With No Connections

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "ReadRdsInstancesAndMetrics",
      "Effect": "Allow",
      "Action": [
        "rds:DescribeDBInstances",
        "cloudwatch:GetMetricData"
      ],
      "Resource": "*"
    }
  ]
}

// find-idle-rds-instances.ts
// Reports RDS DB instances in one region whose DatabaseConnections metric stayed at zero
// (or under --max-conns) for the last --days days, with an estimate of the instance-hour cost. Read-only.
// Usage: npx tsx find-idle-rds-instances.ts [--days 14] [--max-conns 0]
import { RDSClient, paginateDescribeDBInstances, type DBInstance } from "@aws-sdk/client-rds";
import { CloudWatchClient, GetMetricDataCommand } from "@aws-sdk/client-cloudwatch";

// On-Demand USD per hour, Single-AZ, us-east-1, as of September 2026. Multi-AZ is roughly double.
// Add your own classes and engines; unknown ones print "-".
const PER_HOUR: Record<string, Record<string, number>> = {
  mysql: { "db.t4g.micro": 0.016, "db.t3.micro": 0.017, "db.t4g.medium": 0.065, "db.t3.medium": 0.068, "db.m6g.large": 0.152, "db.m7g.large": 0.168, "db.m5.large": 0.171, "db.r6g.large": 0.215 },
  postgres: { "db.t4g.micro": 0.016, "db.t3.micro": 0.018, "db.t4g.medium": 0.065, "db.t3.medium": 0.072, "db.m6g.large": 0.159, "db.m7g.large": 0.168, "db.m5.large": 0.178, "db.r6g.large": 0.225 },
};
const HOURS_PER_MONTH = 730;

function arg(name: string): string | undefined {
  const i = process.argv.indexOf(name);
  return i === -1 ? undefined : process.argv[i + 1];
}

const rds = new RDSClient({}); // region from AWS_REGION or your profile
const cw = new CloudWatchClient({});

// Daily maximum connections and average CPU for up to 250 instances per request (500 queries max).
async function metrics(ids: string[], days: number) {
  const out = new Map<string, { maxConns: number; avgCpu: number; points: number }>();
  const end = new Date();
  const start = new Date(end.getTime() - days * 86_400_000);
  const q = (id: string, n: number, metric: string, stat: string) => ({
    Id: `${metric === "DatabaseConnections" ? "c" : "u"}${n}`,
    MetricStat: {
      Metric: { Namespace: "AWS/RDS", MetricName: metric, Dimensions: [{ Name: "DBInstanceIdentifier", Value: id }] },
      Period: 86_400,
      Stat: stat,
    },
  });
  for (let i = 0; i < ids.length; i += 250) {
    const batch = ids.slice(i, i + 250);
    const queries = batch.flatMap((id, n) => [q(id, n, "DatabaseConnections", "Maximum"), q(id, n, "CPUUtilization", "Average")]);
    let NextToken: string | undefined;
    const values = new Map<string, number[]>();
    do {
      const res = await cw.send(new GetMetricDataCommand({ StartTime: start, EndTime: end, MetricDataQueries: queries, NextToken }));
      for (const r of res.MetricDataResults ?? []) values.set(r.Id ?? "", [...(values.get(r.Id ?? "") ?? []), ...(r.Values ?? [])]);
      NextToken = res.NextToken;
    } while (NextToken);
    batch.forEach((id, n) => {
      const conns = values.get(`c${n}`) ?? [];
      const cpu = values.get(`u${n}`) ?? [];
      out.set(id, {
        maxConns: Math.max(0, ...conns),
        avgCpu: cpu.length ? cpu.reduce((s, x) => s + x, 0) / cpu.length : 0,
        points: conns.length,
      });
    });
  }
  return out;
}

async function main(): Promise<void> {
  const days = Number(arg("--days") ?? 14);
  const maxConns = Number(arg("--max-conns") ?? 0);

  const instances: DBInstance[] = [];
  for await (const page of paginateDescribeDBInstances({ client: rds }, {})) {
    instances.push(...(page.DBInstances ?? []).filter((d) => d.DBInstanceStatus === "available"));
  }
  if (instances.length === 0) {
    console.log("No available DB instances in this region.");
    return;
  }

  const m = await metrics(instances.map((d) => d.DBInstanceIdentifier ?? ""), days);
  const rows = [];
  let idleCost = 0;
  for (const db of instances) {
    const id = db.DBInstanceIdentifier ?? "";
    const stats = m.get(id) ?? { maxConns: 0, avgCpu: 0, points: 0 };
    const ageDays = db.InstanceCreateTime ? (Date.now() - db.InstanceCreateTime.getTime()) / 86_400_000 : days;
    const rate = PER_HOUR[db.Engine ?? ""]?.[db.DBInstanceClass ?? ""];
    const monthly = rate === undefined ? undefined : rate * (db.MultiAZ ? 2 : 1) * HOURS_PER_MONTH;
    const verdict =
      ageDays < days ? "too new"
      : stats.points === 0 ? "no data"
      : stats.maxConns <= maxConns ? "IDLE"
      : "in use";
    if (verdict === "IDLE" && monthly !== undefined) idleCost += monthly;
    rows.push({
      Instance: id,
      Engine: db.Engine ?? "",
      Class: db.DBInstanceClass ?? "",
      "Multi-AZ": db.MultiAZ ? "yes" : "no",
      Cluster: db.DBClusterIdentifier ?? "",
      Replica: db.ReadReplicaSourceDBInstanceIdentifier ? "replica" : (db.ReadReplicaDBInstanceIdentifiers ?? []).length ? "has replicas" : "",
      [`Max conns (${days}d)`]: stats.maxConns,
      "Avg CPU %": stats.avgCpu.toFixed(1),
      "Instance $/mo": monthly === undefined ? "-" : monthly.toFixed(2),
      Verdict: verdict,
    });
  }
  console.table(rows);
  console.log(`Idle instances with a known price: about $${idleCost.toFixed(2)}/month in instance hours (storage and backups extra).`);
  console.log("Report only: nothing was stopped or deleted.");
}

main().catch((err) => {
  console.error(err);
  process.exit(1);
});

npm install @aws-sdk/client-rds @aws-sdk/client-cloudwatch
npm install --save-dev tsx typescript

# No client connections in 14 days
AWS_PROFILE=readonly AWS_REGION=us-east-1 npx tsx find-idle-rds-instances.ts

# 30 days, treating a single health-check connection as idle
AWS_PROFILE=readonly AWS_REGION=us-east-1 npx tsx find-idle-rds-instances.ts --days 30 --max-conns 1

┌─────────┬─────────────────┬─────────────────────┬─────────────────┬──────────┬─────────────┬─────────┬─────────────────┬───────────┬───────────────┬──────────┐
│ (index) │ Instance        │ Engine              │ Class           │ Multi-AZ │ Cluster     │ Replica │ Max conns (14d) │ Avg CPU % │ Instance $/mo │ Verdict  │
├─────────┼─────────────────┼─────────────────────┼─────────────────┼──────────┼─────────────┼─────────┼─────────────────┼───────────┼───────────────┼──────────┤
│ 0       │ 'orders-prod'   │ 'postgres'          │ 'db.m6g.large'  │ 'yes'    │ ''          │ ''      │ 212             │ '23.4'    │ '232.14'      │ 'in use' │
│ 1       │ 'reporting-old' │ 'mysql'             │ 'db.m5.large'   │ 'no'     │ ''          │ ''      │ 0               │ '2.1'     │ '124.83'      │ 'IDLE'   │
│ 2       │ 'qa-db'         │ 'postgres'          │ 'db.t4g.medium' │ 'no'     │ ''          │ ''      │ 0               │ '3.8'     │ '47.45'       │ 'IDLE'   │
│ 3       │ 'analytics-1'   │ 'aurora-postgresql' │ 'db.r6g.large'  │ 'no'     │ 'analytics' │ ''      │ 0               │ '4.9'     │ '-'           │ 'IDLE'   │
└─────────┴─────────────────┴─────────────────────┴─────────────────┴──────────┴─────────────┴─────────┴─────────────────┴───────────┴───────────────┴──────────┘
Idle instances with a known price: about $172.28/month in instance hours (storage and backups extra).
Report only: nothing was stopped or deleted.