alchemy 2.0.0-beta.76 → 2.0.0-beta.78

package/lib/AWS/RDS/DBInstance.js

@@ -1,4 +1,6 @@
+import * as ec2 from "@distilled.cloud/aws/ec2";
 import * as rds from "@distilled.cloud/aws/rds";
+import * as Data from "effect/Data";
 import * as Effect from "effect/Effect";
 import * as Redacted from "effect/Redacted";
 import * as Schedule from "effect/Schedule";
@@ -35,6 +37,95 @@ import { sha256 } from "../../Util/sha256.js";
  * });
  * ```
  *
+ * ### Storage Defaults
+ * Omitted storage settings describe desired defaults, including on existing
+ * instances: gp3 storage, a minimum allocation of 20 GiB, and the engine's
+ * baseline performance. RDS Custom defaults to 40 GiB; io1/io2 default to
+ * 100 GiB and at least 1000 IOPS. Only allocated capacity is a floor because
+ * RDS cannot shrink a database. Storage type and performance are reconciled
+ * even when the program is unchanged and the cloud settings have drifted.
+ *
+ * **Example:** PostgreSQL with default storage and autoscaling disabled
+ * ```typescript
+ * const db = yield* DBInstance("Db", {
+ *   engine: "postgres",
+ *   dbInstanceClass: "db.t3.micro",
+ *   masterUsername: "admin",
+ *   manageMasterUserPassword: true,
+ * });
+ * ```
+ *
+ * This starts with 20 GiB of gp3 storage, 3000 IOPS, and 125 MiBps. For small
+ * non-SQL Server gp3 volumes, these performance values are fixed and Alchemy
+ * omits the unsupported performance fields from AWS requests.
+ *
+ * ### Resetting Storage Performance
+ * Removing performance settings restores the baseline for the desired
+ * storage type, effective allocation, engine, and autoscaling limit. AWS
+ * requires coupled storage fields together on modifications; Alchemy sends
+ * the resolved allocation, type, supported performance fields, and ceiling
+ * in the same request. Existing database contents are retained.
+ *
+ * **Example:** Restore the PostgreSQL gp3 baseline at 400 GiB
+ * ```diff lang="typescript"
+ * const db = yield* DBInstance("Db", {
+ *   engine: "postgres",
+ *   dbInstanceClass: "db.t3.micro",
+ *   masterUsername: "admin",
+ *   manageMasterUserPassword: true,
+ *   allocatedStorage: 400,
+ * -  iops: 16000,
+ * -  storageThroughput: 750,
+ * });
+ * ```
+ *
+ * At this allocation PostgreSQL uses striped gp3 storage, so removal requests
+ * 12000 IOPS and 500 MiBps. Removing `storageType: "gp2"` instead selects gp3
+ * without shrinking the allocation. Changes remain subject to AWS's storage
+ * optimization cooldown; redeploying cannot bypass that restriction.
+ *
+ * ### Storage Autoscaling
+ * `allocatedStorage` is a minimum, not a shrink target. RDS can increase the
+ * allocation but cannot reduce it in place. `maxAllocatedStorage` controls
+ * future automatic growth; omitting it or setting it to `0` disables autoscaling.
+ *
+ * **Example:** Start with 20 GiB and allow automatic growth to 100 GiB
+ * ```typescript
+ * const db = yield* DBInstance("Db", {
+ *   engine: "postgres",
+ *   dbInstanceClass: "db.t3.micro",
+ *   masterUsername: "admin",
+ *   manageMasterUserPassword: true,
+ *   storageType: "gp2",
+ *   allocatedStorage: 20,
+ *   maxAllocatedStorage: 100,
+ * });
+ * ```
+ *
+ * If RDS grows this database to 30 GiB, redeploying keeps that capacity and the
+ * 100 GiB autoscaling limit. It does not attempt to shrink the database to 20 GiB.
+ * An externally changed autoscaling limit is reset to the declared value.
+ *
+ * ### Disabling Storage Autoscaling
+ * Removing `maxAllocatedStorage` resets autoscaling to its disabled default.
+ * Existing allocated storage and database contents remain intact.
+ *
+ * **Example:** Remove the autoscaling limit to disable future automatic growth
+ * ```diff lang="typescript"
+ * const db = yield* DBInstance("Db", {
+ *   engine: "postgres",
+ *   dbInstanceClass: "db.t3.micro",
+ *   masterUsername: "admin",
+ *   manageMasterUserPassword: true,
+ *   storageType: "gp2",
+ *   allocatedStorage: 20,
+ * -  maxAllocatedStorage: 100,
+ * });
+ * ```
+ *
+ * `maxAllocatedStorage: 0` has the same behavior. Redeploying with either form
+ * also disables autoscaling if it was enabled outside Alchemy.
+ *
  * ### Cluster Member
  * **Example:** An Aurora writer instance
  * ```typescript
@@ -45,6 +136,88 @@ import { sha256 } from "../../Util/sha256.js";
  * });
  * ```
  *
+ * ### Listener Port Defaults
+ * Omitted listener ports select the database engine's default: PostgreSQL
+ * 5432, MySQL/MariaDB 3306, Oracle 1521, SQL Server 1433, and Db2 50000.
+ * Alchemy compares the actual endpoint port, including pending changes,
+ * rather than the separate `DbInstancePort` field returned by AWS.
+ *
+ * **Example:** PostgreSQL listening on its default port
+ * ```typescript
+ * const db = yield* DBInstance("Db", {
+ *   engine: "postgres",
+ *   dbInstanceClass: "db.t3.micro",
+ *   masterUsername: "admin",
+ *   manageMasterUserPassword: true,
+ * });
+ * ```
+ *
+ * ### Resetting the Listener Port
+ * Removing a custom port restores the engine default. Unchanged programs
+ * also detect and repair external listener changes. Port changes restart
+ * the database, including when restoring defaults after adoption.
+ *
+ * **Example:** Restore PostgreSQL's port 5432
+ * ```diff lang="typescript"
+ * const db = yield* DBInstance("Db", {
+ *   engine: "postgres",
+ *   dbInstanceClass: "db.t3.micro",
+ *   masterUsername: "admin",
+ *   manageMasterUserPassword: true,
+ * -  port: 5433,
+ * });
+ * ```
+ *
+ * Aurora and other cluster members inherit their listener from `DBCluster`;
+ * instance `port` declarations are ignored. RDS Custom creation accepts a
+ * port, but an existing Custom instance that needs a listener change fails
+ * explicitly instead of silently retaining the wrong port or replacing data.
+ *
+ * ### Association Defaults
+ * Parameter and security-group associations are desired configuration.
+ * Omission selects a compatible engine default parameter group and the
+ * effective VPC's default security group, including during adoption.
+ * Existing database versions and VPC placement constrain those defaults;
+ * the currently attached groups are never used as fallback desired values.
+ *
+ * **Example:** Use default associations in a declared network
+ * ```typescript
+ * const db = yield* DBInstance("Db", {
+ *   engine: "postgres",
+ *   dbInstanceClass: "db.t3.micro",
+ *   masterUsername: "admin",
+ *   manageMasterUserPassword: true,
+ *   dbSubnetGroupName: subnetGroup.dbSubnetGroupName,
+ * });
+ * ```
+ *
+ * ### Resetting Associations
+ * Removing declarations restores defaults. Unchanged programs also repair
+ * external attachment drift. Reordering or duplicating security-group IDs
+ * does not resend the association request.
+ *
+ * **Example:** Restore the engine and VPC default groups
+ * ```diff lang="typescript"
+ * const db = yield* DBInstance("Db", {
+ *   engine: "postgres",
+ *   dbInstanceClass: "db.t3.micro",
+ *   masterUsername: "admin",
+ *   manageMasterUserPassword: true,
+ *   dbSubnetGroupName: subnetGroup.dbSubnetGroupName,
+ * -  dbParameterGroupName: customParameters.dbParameterGroupName,
+ * -  vpcSecurityGroupIds: [applicationGroup.groupId],
+ * });
+ * ```
+ *
+ * The default security group's rules determine network access after reset.
+ * Detached group resources remain intact. Parameter changes can require a
+ * reboot; `dbParameterGroupApplyStatuses` reports `pending-reboot` without
+ * automatically restarting the database. Aurora instance parameter groups
+ * remain instance-managed, while security groups belong to its cluster.
+ * Multi-AZ DB cluster associations are cluster-managed. RDS Custom cannot
+ * manage parameter groups or modify existing security-group attachments;
+ * Db2 BYOL requires an explicit parameter group with IBM licensing IDs.
+ *
  * ### Monitoring & Logs
  * **Example:** Enhanced monitoring + log export
  * ```typescript
@@ -89,6 +262,10 @@ const toAttrs = ({ instance, tags, skipFinalSnapshot, finalDBSnapshotIdentifier,
     publiclyAccessible: instance.PubliclyAccessible,
     dbSubnetGroupName: instance.DBSubnetGroup?.DBSubnetGroupName,
     dbParameterGroupNames: (instance.DBParameterGroups ?? []).flatMap((group) => group.DBParameterGroupName ? [group.DBParameterGroupName] : []),
+    dbParameterGroupApplyStatuses: Object.fromEntries((instance.DBParameterGroups ?? []).flatMap((group) => group.DBParameterGroupName
+        ? [[group.DBParameterGroupName, group.ParameterApplyStatus]]
+        : [])),
+    vpcSecurityGroupIds: (instance.VpcSecurityGroups ?? []).flatMap((group) => group.VpcSecurityGroupId ? [group.VpcSecurityGroupId] : []),
     allocatedStorage: instance.AllocatedStorage,
     maxAllocatedStorage: instance.MaxAllocatedStorage,
     storageType: instance.StorageType,
@@ -138,6 +315,317 @@ const logExportDelta = (observed, desired) => {
         ...(DisableLogTypes.length > 0 ? { DisableLogTypes } : {}),
     };
 };
+const sameMembers = (desired, observed) => {
+    const want = new Set(desired);
+    const have = new Set(observed);
+    return want.size === have.size && [...want].every((value) => have.has(value));
+};
+class InvalidDBInstanceAssociations extends Data.TaggedError("InvalidDBInstanceAssociations") {
+}
+const resolveAssociations = Effect.fn(function* (props, observed) {
+    const clusterIdentifier = props.dbClusterIdentifier ?? observed?.DBClusterIdentifier;
+    const clusterOwned = clusterIdentifier !== undefined || props.engine.startsWith("aurora");
+    const custom = props.engine.startsWith("custom-");
+    if (clusterOwned && !props.engine.startsWith("aurora")) {
+        if (props.dbParameterGroupName !== undefined) {
+            return yield* new InvalidDBInstanceAssociations({
+                message: "Multi-AZ DB cluster associations are managed on the cluster",
+            });
+        }
+        return { dbParameterGroupName: undefined, vpcSecurityGroupIds: undefined };
+    }
+    if (props.engine.startsWith("db2-") &&
+        props.dbParameterGroupName === undefined &&
+        (props.licenseModel ??
+            observed?.LicenseModel ??
+            "bring-your-own-license") === "bring-your-own-license") {
+        return yield* new InvalidDBInstanceAssociations({
+            message: "Db2 BYOL requires an explicit parameter group with IBM licensing IDs",
+        });
+    }
+    let dbParameterGroupName = props.dbParameterGroupName;
+    if (custom && dbParameterGroupName !== undefined) {
+        return yield* new InvalidDBInstanceAssociations({
+            message: "RDS Custom does not support DB parameter-group associations",
+        });
+    }
+    if (!custom && dbParameterGroupName === undefined) {
+        let engineVersion = props.engineVersion ?? observed?.EngineVersion;
+        if (clusterIdentifier !== undefined) {
+            engineVersion = (yield* rds.describeDBClusters({
+                DBClusterIdentifier: clusterIdentifier,
+            })).DBClusters?.[0]?.EngineVersion;
+            if (!engineVersion) {
+                return yield* new InvalidDBInstanceAssociations({
+                    message: "The DB cluster did not return an engine version",
+                });
+            }
+        }
+        const pages = yield* rds.describeDBEngineVersions
+            .pages({
+            Engine: props.engine,
+            EngineVersion: engineVersion,
+            DefaultOnly: engineVersion === undefined ? true : undefined,
+            IncludeAll: engineVersion !== undefined ? true : undefined,
+        })
+            .pipe(Stream.runCollect);
+        const families = new Set(pages.flatMap((page) => (page.DBEngineVersions ?? []).map((version) => version.DBParameterGroupFamily)));
+        const family = [...families][0];
+        if (families.size !== 1 || !family) {
+            return yield* new InvalidDBInstanceAssociations({
+                message: "No unambiguous DB parameter group family; declare engineVersion or dbParameterGroupName",
+            });
+        }
+        dbParameterGroupName = `default.${family}`;
+    }
+    if (clusterOwned)
+        return { dbParameterGroupName, vpcSecurityGroupIds: undefined };
+    let vpcSecurityGroupIds = props.vpcSecurityGroupIds;
+    if (vpcSecurityGroupIds === undefined) {
+        const vpcId = props.dbSubnetGroupName !== undefined
+            ? (yield* rds.describeDBSubnetGroups({
+                DBSubnetGroupName: props.dbSubnetGroupName,
+            })).DBSubnetGroups?.[0]?.VpcId
+            : (observed?.DBSubnetGroup?.VpcId ??
+                (yield* ec2.describeVpcs({
+                    Filters: [{ Name: "is-default", Values: ["true"] }],
+                })).Vpcs?.[0]?.VpcId);
+        if (!vpcId) {
+            return yield* new InvalidDBInstanceAssociations({
+                message: "No VPC found for the DB instance; declare dbSubnetGroupName or provide a default VPC",
+            });
+        }
+        const groups = yield* ec2.describeSecurityGroups({
+            Filters: [
+                { Name: "vpc-id", Values: [vpcId] },
+                { Name: "group-name", Values: ["default"] },
+            ],
+        });
+        vpcSecurityGroupIds = (groups.SecurityGroups ?? []).flatMap((group) => group.GroupId ? [group.GroupId] : []);
+        if (vpcSecurityGroupIds.length !== 1) {
+            return yield* new InvalidDBInstanceAssociations({
+                message: `Expected one default security group in VPC '${vpcId}'`,
+            });
+        }
+    }
+    if (vpcSecurityGroupIds.length === 0) {
+        return yield* new InvalidDBInstanceAssociations({
+            message: "At least one VPC security group is required; omit vpcSecurityGroupIds to select the VPC default group",
+        });
+    }
+    return {
+        dbParameterGroupName,
+        vpcSecurityGroupIds: [...new Set(vpcSecurityGroupIds)],
+    };
+});
+const parameterGroupMatches = (desired, instance) => desired.dbParameterGroupName === undefined ||
+    sameMembers([desired.dbParameterGroupName], (instance.DBParameterGroups ?? []).map((group) => group.DBParameterGroupName));
+const securityGroupsMatch = (desired, instance) => desired.vpcSecurityGroupIds === undefined ||
+    sameMembers(desired.vpcSecurityGroupIds, (instance.VpcSecurityGroups ?? []).map((group) => group.VpcSecurityGroupId));
+const associationsConverged = (desired, instance) => parameterGroupMatches(desired, instance) &&
+    (desired.dbParameterGroupName === undefined ||
+        (instance.DBParameterGroups ?? []).every((group) => group.ParameterApplyStatus === "in-sync" ||
+            group.ParameterApplyStatus === "pending-reboot")) &&
+    securityGroupsMatch(desired, instance) &&
+    (desired.vpcSecurityGroupIds === undefined ||
+        (instance.VpcSecurityGroups ?? []).every((group) => group.Status === "active"));
+class InvalidDBInstancePort extends Data.TaggedError("InvalidDBInstancePort") {
+}
+const desiredInstancePort = Effect.fn(function* (props, observed) {
+    if (props.dbClusterIdentifier !== undefined ||
+        observed?.DBClusterIdentifier !== undefined ||
+        props.engine.startsWith("aurora")) {
+        return undefined;
+    }
+    if (props.port !== undefined) {
+        if (!Number.isInteger(props.port) ||
+            props.port < 1150 ||
+            props.port > 65535) {
+            return yield* new InvalidDBInstancePort({
+                message: "port must be an integer between 1150 and 65535",
+            });
+        }
+        return props.port;
+    }
+    if (props.engine === "postgres")
+        return 5432;
+    if (props.engine === "mysql" || props.engine === "mariadb")
+        return 3306;
+    if (props.engine.startsWith("oracle-") ||
+        props.engine.startsWith("custom-oracle-"))
+        return 1521;
+    if (props.engine.startsWith("sqlserver-") ||
+        props.engine.startsWith("custom-sqlserver-"))
+        return 1433;
+    if (props.engine.startsWith("db2-"))
+        return 50000;
+    return yield* new InvalidDBInstancePort({
+        message: `Declare port explicitly for engine '${props.engine}'`,
+    });
+});
+const portConverged = (instance, port) => port === undefined ||
+    (instance.Endpoint?.Port === port &&
+        instance.PendingModifiedValues?.Port === undefined);
+class InvalidDBInstanceStorage extends Data.TaggedError("InvalidDBInstanceStorage") {
+}
+const resolveStorage = Effect.fn(function* (props, allocatedFloor = 0) {
+    if (props.dbClusterIdentifier || props.engine.startsWith("aurora")) {
+        if (props.allocatedStorage !== undefined ||
+            props.storageType !== undefined ||
+            props.iops !== undefined ||
+            props.storageThroughput !== undefined) {
+            return yield* new InvalidDBInstanceStorage({
+                message: "Configure cluster-owned storage on DBCluster, not DBInstance",
+            });
+        }
+        return undefined;
+    }
+    const sqlServer = props.engine.includes("sqlserver-");
+    const oracle = props.engine.includes("oracle-");
+    const storageType = props.storageType ?? "gp3";
+    const provisioned = storageType === "io1" || storageType === "io2";
+    if (!["standard", "gp2", "gp3", "io1", "io2"].includes(storageType) ||
+        (storageType === "standard" && allocatedFloor === 0) ||
+        (storageType === "gp2" && props.engine.startsWith("db2-"))) {
+        return yield* new InvalidDBInstanceStorage({
+            message: `Storage type '${storageType}' is not supported for '${props.engine}'`,
+        });
+    }
+    const custom = props.engine.startsWith("custom-");
+    const minimum = custom
+        ? 40
+        : sqlServer
+            ? 20
+            : provisioned
+                ? 100
+                : storageType === "standard"
+                    ? 5
+                    : 20;
+    const requested = props.allocatedStorage ?? (provisioned ? 100 : custom ? 40 : 20);
+    if (!Number.isInteger(requested) || requested <= 0) {
+        return yield* new InvalidDBInstanceStorage({
+            message: "allocatedStorage must be a positive integer",
+        });
+    }
+    // An in-place increase must be at least ten percent of the current allocation.
+    const allocation = requested > allocatedFloor && allocatedFloor > 0
+        ? Math.max(requested, Math.ceil((allocatedFloor * 11) / 10))
+        : Math.max(requested, allocatedFloor);
+    if (allocation < minimum) {
+        return yield* new InvalidDBInstanceStorage({
+            message: `Effective allocated storage must be at least ${minimum} GiB for ${storageType}`,
+        });
+    }
+    const ratioCapacity = Math.max(allocation, props.maxAllocatedStorage ?? 0);
+    if (storageType !== "gp3") {
+        if (props.storageThroughput !== undefined ||
+            (!provisioned && props.iops !== undefined)) {
+            return yield* new InvalidDBInstanceStorage({
+                message: `${storageType} does not support the declared IOPS/throughput settings`,
+            });
+        }
+        const minimumIops = provisioned
+            ? Math.max(1000, Math.ceil(ratioCapacity * (sqlServer && storageType === "io1" ? 1 : 0.5)))
+            : 0;
+        const iops = props.iops ?? minimumIops;
+        const maximumIops = allocation * (storageType === "io1" ? 50 : 1000);
+        if (provisioned &&
+            (!Number.isInteger(iops) || iops < minimumIops || iops > maximumIops)) {
+            return yield* new InvalidDBInstanceStorage({
+                message: `The allocation and autoscaling limit require ${storageType} IOPS between ${minimumIops} and ${maximumIops}`,
+            });
+        }
+        return {
+            request: {
+                AllocatedStorage: allocation,
+                StorageType: storageType,
+                Iops: provisioned ? iops : undefined,
+            },
+            iops,
+            throughput: 0,
+        };
+    }
+    const striped = !sqlServer && allocation >= (oracle ? 200 : 400);
+    const configurable = sqlServer || striped;
+    const baselineIops = striped ? 12000 : 3000;
+    const baselineThroughput = striped ? 500 : 125;
+    const minimumIops = Math.max(baselineIops, sqlServer ? Math.ceil(ratioCapacity * 0.5) : 0, (props.storageThroughput ?? baselineThroughput) * 4);
+    const iops = props.iops ?? minimumIops;
+    const minimumThroughput = Math.max(baselineThroughput, ["mysql", "mariadb"].includes(props.engine) ? Math.ceil(iops / 64) : 0);
+    const throughput = props.storageThroughput ?? minimumThroughput;
+    if (!Number.isInteger(iops) ||
+        iops < minimumIops ||
+        !Number.isInteger(throughput) ||
+        throughput < minimumThroughput ||
+        throughput > iops * 0.25 ||
+        (!configurable &&
+            (iops !== baselineIops || throughput !== baselineThroughput))) {
+        return yield* new InvalidDBInstanceStorage({
+            message: configurable
+                ? `gp3 requires at least ${minimumIops} IOPS and ${minimumThroughput} MiBps, with throughput <= IOPS / 4`
+                : `Small ${props.engine} gp3 storage has fixed 3000 IOPS and 125 MiBps`,
+        });
+    }
+    return {
+        request: {
+            AllocatedStorage: allocation,
+            StorageType: storageType,
+            Iops: configurable ? iops : undefined,
+            StorageThroughput: configurable ? throughput : undefined,
+        },
+        iops,
+        throughput,
+    };
+});
+const hasPendingStorage = (instance) => instance.PendingModifiedValues?.AllocatedStorage !== undefined ||
+    instance.PendingModifiedValues?.StorageType !== undefined ||
+    instance.PendingModifiedValues?.Iops !== undefined ||
+    instance.PendingModifiedValues?.StorageThroughput !== undefined;
+const storageConverged = (observed, desired) => desired === undefined ||
+    ((observed.AllocatedStorage ?? 0) >= desired.request.AllocatedStorage &&
+        observed.StorageType === desired.request.StorageType &&
+        (observed.Iops ?? 0) === desired.iops &&
+        (observed.StorageThroughput ?? 0) === desired.throughput &&
+        !hasPendingStorage(observed));
+const toStorageConfiguration = Effect.fn(function* (props) {
+    const supportsAutoscaling = props.dbClusterIdentifier === undefined &&
+        !props.engine.startsWith("aurora") &&
+        !props.engine.startsWith("custom-");
+    if (!supportsAutoscaling && props.maxAllocatedStorage !== undefined) {
+        return yield* new InvalidDBInstanceStorage({
+            message: "maxAllocatedStorage is not supported for cluster members or RDS Custom",
+        });
+    }
+    const maxAllocatedStorage = supportsAutoscaling
+        ? (props.maxAllocatedStorage ?? 0)
+        : undefined;
+    if (maxAllocatedStorage !== undefined &&
+        (!Number.isInteger(maxAllocatedStorage) || maxAllocatedStorage < 0)) {
+        return yield* new InvalidDBInstanceStorage({
+            message: "maxAllocatedStorage must be a nonnegative integer in GiB",
+        });
+    }
+    return {
+        allocatedStorage: props.dbClusterIdentifier === undefined
+            ? props.allocatedStorage
+            : undefined,
+        maxAllocatedStorage,
+    };
+});
+const allocationConverged = (desired, observed) => desired.allocatedStorage === undefined ||
+    (observed.AllocatedStorage !== undefined &&
+        observed.AllocatedStorage >= desired.allocatedStorage);
+const autoscalingConverged = (desired, observed) => {
+    const ceiling = desired.maxAllocatedStorage;
+    if (ceiling === undefined)
+        return true;
+    // RDS reports disabled autoscaling as zero; equality also prevents growth.
+    if (ceiling === 0 || ceiling === observed.AllocatedStorage) {
+        return ((observed.MaxAllocatedStorage ?? 0) === 0 ||
+            observed.MaxAllocatedStorage === observed.AllocatedStorage);
+    }
+    return ceiling === observed.MaxAllocatedStorage;
+};
 export const DBInstanceProvider = () => Provider.effect(DBInstance, Effect.gen(function* () {
     const toIdentifier = (id, props) => props.dbInstanceIdentifier
         ? Effect.succeed(props.dbInstanceIdentifier)
@@ -150,9 +638,7 @@ export const DBInstanceProvider = () => Provider.effect(DBInstance, Effect.gen(f
             .pipe(Effect.catchTag("DBInstanceNotFoundFault", () => Effect.succeed(undefined)));
         return response?.DBInstances?.[0];
     });
-    // Bounded readiness wait. Gate on `DBInstanceStatus === "available"` so a
-    // follow-on `modifyDBInstance` doesn't hit `InvalidDBInstanceStateFault`.
-    // `waitForAvailable` budgets ~10 min (60 * 10s) for slow provisioning;
+    // Storage optimization is online and can continue for hours after a resize.
     // `requireAvailable: false` only waits for the ARN to appear.
     const waitForInstance = Effect.fn(function* (instanceId, { requireAvailable = true } = {}) {
         const readinessPolicy = Schedule.max([
@@ -168,6 +654,7 @@ export const DBInstanceProvider = () => Provider.effect(DBInstance, Effect.gen(f
             const status = instance.DBInstanceStatus;
             if (requireAvailable &&
                 status !== "available" &&
+                status !== "storage-optimization" &&
                 status !== "incompatible-parameters" &&
                 status !== "incompatible-restore") {
                 return Effect.fail(new Error(`DB instance '${instanceId}' not available (status: ${status})`));
@@ -175,6 +662,69 @@ export const DBInstanceProvider = () => Provider.effect(DBInstance, Effect.gen(f
             return Effect.succeed(instance);
         }), Effect.retry({ schedule: readinessPolicy }));
     });
+    const waitForAssociations = Effect.fn(function* (instanceId, desired) {
+        const instance = yield* readInstance(instanceId).pipe(Effect.flatMap((instance) => instance?.DBParameterGroups?.some((group) => group.ParameterApplyStatus === "failed-to-apply")
+            ? Effect.fail(new InvalidDBInstanceAssociations({
+                message: `DB instance '${instanceId}' parameter group failed to apply`,
+            }))
+            : Effect.succeed(instance)), Effect.repeat({
+            schedule: Schedule.min([
+                Schedule.exponential("5 seconds"),
+                Schedule.spaced("1 minute"),
+            ]),
+            times: 10,
+            until: (instance) => instance !== undefined &&
+                (instance.DBInstanceStatus === "available" ||
+                    instance.DBInstanceStatus === "storage-optimization") &&
+                associationsConverged(desired, instance),
+        }));
+        if (!instance?.DBInstanceArn ||
+            !["available", "storage-optimization"].includes(instance.DBInstanceStatus ?? "") ||
+            !associationsConverged(desired, instance)) {
+            return yield* new InvalidDBInstanceAssociations({
+                message: `DB instance '${instanceId}' associations did not converge`,
+            });
+        }
+        return instance;
+    });
+    const waitForPort = Effect.fn(function* (instanceId, port) {
+        const instance = yield* readInstance(instanceId).pipe(Effect.repeat({
+            schedule: Schedule.min([
+                Schedule.exponential("5 seconds"),
+                Schedule.spaced("1 minute"),
+            ]),
+            times: 10,
+            until: (instance) => instance !== undefined &&
+                (instance.DBInstanceStatus === "available" ||
+                    instance.DBInstanceStatus === "storage-optimization") &&
+                portConverged(instance, port),
+        }));
+        if (!instance?.DBInstanceArn ||
+            !["available", "storage-optimization"].includes(instance.DBInstanceStatus ?? "") ||
+            !portConverged(instance, port)) {
+            return yield* new InvalidDBInstancePort({
+                message: `DB instance '${instanceId}' listener did not converge (status: ${instance?.DBInstanceStatus}, desired: ${port}, observed: ${instance?.Endpoint?.Port}, pending: ${instance?.PendingModifiedValues?.Port})`,
+            });
+        }
+        return instance;
+    });
+    const waitForStorage = Effect.fn(function* (instanceId, converged) {
+        // RDS can remain available while an accepted storage resize is pending.
+        const instance = yield* readInstance(instanceId).pipe(Effect.repeat({
+            schedule: Schedule.min([
+                Schedule.exponential("5 seconds"),
+                Schedule.spaced("1 minute"),
+            ]),
+            times: 10,
+            until: (instance) => instance !== undefined && converged(instance),
+        }));
+        if (!instance?.DBInstanceArn || !converged(instance)) {
+            return yield* new InvalidDBInstanceStorage({
+                message: `DB instance '${instanceId}' storage did not converge (status: ${instance?.DBInstanceStatus}, allocated: ${instance?.AllocatedStorage}, maximum: ${instance?.MaxAllocatedStorage}, pending allocation: ${instance?.PendingModifiedValues?.AllocatedStorage})`,
+            });
+        }
+        return instance;
+    });
     return {
         stables: ["dbInstanceArn", "dbInstanceIdentifier"],
         // Pattern (a) AWS account/region collection: `describeDBInstances` is
@@ -189,7 +739,7 @@ export const DBInstanceProvider = () => Provider.effect(DBInstance, Effect.gen(f
             instance,
             tags: toTagRecord(instance.TagList),
         })))), Effect.catchTag("DBInstanceNotFoundFault", () => Effect.succeed([]))),
-        diff: Effect.fn(function* ({ id, olds, news }) {
+        diff: Effect.fn(function* ({ id, olds, news, output }) {
             if (!isResolved(news))
                 return undefined;
             if ((yield* toIdentifier(id, olds ?? {})) !==
@@ -207,6 +757,22 @@ export const DBInstanceProvider = () => Provider.effect(DBInstance, Effect.gen(f
                     olds.dbSubnetGroupName !== news.dbSubnetGroupName)) {
                 return { action: "replace" };
             }
+            const storage = yield* toStorageConfiguration(news);
+            if (output !== undefined) {
+                const instance = yield* readInstance(output.dbInstanceIdentifier);
+                if (!instance?.DBInstanceArn) {
+                    return { action: "update", stables: [] };
+                }
+                const port = yield* desiredInstancePort(news, instance);
+                const associations = yield* resolveAssociations(news, instance);
+                const desiredStorage = yield* resolveStorage(news, instance.AllocatedStorage);
+                if (!storageConverged(instance, desiredStorage) ||
+                    !autoscalingConverged(storage, instance) ||
+                    !portConverged(instance, port) ||
+                    !associationsConverged(associations, instance)) {
+                    return { action: "update" };
+                }
+            }
         }),
         read: Effect.fn(function* ({ id, olds, output }) {
             const identifier = output?.dbInstanceIdentifier ??
@@ -244,12 +810,17 @@ export const DBInstanceProvider = () => Provider.effect(DBInstance, Effect.gen(f
             const backupRetentionDays = toWireDays(news.backupRetentionPeriod);
             const performanceInsightsRetentionDays = toWireDays(news.performanceInsightsRetentionPeriod);
             const monitoringIntervalSeconds = toWireSeconds(news.monitoringInterval);
+            const storage = yield* toStorageConfiguration(news);
             // Observe — fetch live instance state.
             let observed = yield* readInstance(identifier);
+            let port = yield* desiredInstancePort(news, observed);
+            let associations = yield* resolveAssociations(news, observed);
+            let desiredStorage = yield* resolveStorage(news, observed?.AllocatedStorage);
             // Ensure — create if missing. Tolerate
             // `DBInstanceAlreadyExistsFault` as a race with a peer reconciler.
+            let created = false;
             if (!observed?.DBInstanceArn) {
-                yield* rds
+                created = yield* rds
                     .createDBInstance({
                     DBInstanceIdentifier: identifier,
                     DBClusterIdentifier: news.dbClusterIdentifier,
@@ -257,23 +828,21 @@ export const DBInstanceProvider = () => Provider.effect(DBInstance, Effect.gen(f
                     Engine: news.engine,
                     EngineVersion: news.engineVersion,
                     DBName: news.dbName,
-                    AllocatedStorage: news.allocatedStorage,
-                    MaxAllocatedStorage: news.maxAllocatedStorage,
-                    StorageType: news.storageType,
-                    Iops: news.iops,
-                    StorageThroughput: news.storageThroughput,
+                    ...desiredStorage?.request,
+                    // Omission at creation leaves autoscaling disabled.
+                    MaxAllocatedStorage: storage.maxAllocatedStorage || undefined,
                     MasterUsername: news.masterUsername,
                     MasterUserPassword: news.masterUserPassword,
                     ManageMasterUserPassword: news.manageMasterUserPassword,
                     MasterUserSecretKmsKeyId: news.masterUserSecretKmsKeyId,
-                    Port: news.port,
+                    Port: port,
                     MultiAZ: news.multiAZ,
                     AvailabilityZone: news.availabilityZone,
                     BackupRetentionPeriod: backupRetentionDays,
                     PreferredBackupWindow: news.preferredBackupWindow,
                     PreferredMaintenanceWindow: news.preferredMaintenanceWindow,
                     DBSubnetGroupName: news.dbSubnetGroupName,
-                    DBParameterGroupName: news.dbParameterGroupName,
+                    DBParameterGroupName: associations.dbParameterGroupName,
                     OptionGroupName: news.optionGroupName,
                     LicenseModel: news.licenseModel,
                     StorageEncrypted: news.storageEncrypted,
@@ -288,12 +857,7 @@ export const DBInstanceProvider = () => Provider.effect(DBInstance, Effect.gen(f
                     EnableCloudwatchLogsExports: news.enableCloudwatchLogsExports,
                     DeletionProtection: news.deletionProtection,
                     NetworkType: news.networkType,
-                    // Cluster members inherit VPC security groups from the DB
-                    // cluster; passing them fails with InvalidParameterCombination
-                    // ("Set vpc security group for the DB Cluster").
-                    VpcSecurityGroupIds: news.dbClusterIdentifier
-                        ? undefined
-                        : news.vpcSecurityGroupIds,
+                    VpcSecurityGroupIds: associations.vpcSecurityGroupIds,
                     PubliclyAccessible: news.publiclyAccessible,
                     PromotionTier: news.promotionTier,
                     AutoMinorVersionUpgrade: news.autoMinorVersionUpgrade,
@@ -303,17 +867,22 @@ export const DBInstanceProvider = () => Provider.effect(DBInstance, Effect.gen(f
                         Value,
                     })),
                 })
-                    .pipe(Effect.catchTag("DBInstanceAlreadyExistsFault", () => Effect.void));
+                    .pipe(Effect.as(true), Effect.catchTag("DBInstanceAlreadyExistsFault", () => Effect.succeed(false)));
                 observed = yield* waitForInstance(identifier);
             }
-            else {
+            if (!created) {
                 // Wait for the instance to settle before any modify so the call
                 // doesn't hit `InvalidDBInstanceStateFault`.
                 observed = yield* waitForInstance(identifier);
+                if (hasPendingStorage(observed)) {
+                    observed = yield* waitForStorage(identifier, (instance) => !hasPendingStorage(instance));
+                }
+                desiredStorage = yield* resolveStorage(news, observed.AllocatedStorage);
+                associations = yield* resolveAssociations(news, observed);
                 // syncCoreSettings — single `modifyDBInstance` carrying scalar
                 // in-place fields. Only emit a field when the desired value differs
                 // from the observed cloud state, to avoid spurious
-                // `PendingModifiedValues`. `Port` maps to `DBPortNumber` on modify.
+                // `PendingModifiedValues`. The listener port is synchronized below.
                 const core = {
                     DBInstanceIdentifier: identifier,
                     ApplyImmediately: true,
@@ -327,16 +896,18 @@ export const DBInstanceProvider = () => Provider.effect(DBInstance, Effect.gen(f
                 };
                 setIf("DBInstanceClass", news.dbInstanceClass, observed.DBInstanceClass); // prettier-ignore
                 setIf("EngineVersion", news.engineVersion, observed.EngineVersion);
-                setIf("AllocatedStorage", news.allocatedStorage, observed.AllocatedStorage); // prettier-ignore
-                setIf("MaxAllocatedStorage", news.maxAllocatedStorage, observed.MaxAllocatedStorage); // prettier-ignore
-                setIf("StorageType", news.storageType, observed.StorageType);
-                setIf("Iops", news.iops, observed.Iops);
-                setIf("StorageThroughput", news.storageThroughput, observed.StorageThroughput); // prettier-ignore
+                if (desiredStorage && !storageConverged(observed, desiredStorage)) {
+                    Object.assign(core, desiredStorage.request);
+                    core.MaxAllocatedStorage =
+                        storage.maxAllocatedStorage === 0
+                            ? desiredStorage.request.AllocatedStorage
+                            : storage.maxAllocatedStorage;
+                    coreDirty = true;
+                }
                 setIf("MultiAZ", news.multiAZ, observed.MultiAZ);
                 setIf("BackupRetentionPeriod", backupRetentionDays, observed.BackupRetentionPeriod); // prettier-ignore
                 setIf("PreferredBackupWindow", news.preferredBackupWindow, observed.PreferredBackupWindow); // prettier-ignore
                 setIf("PreferredMaintenanceWindow", news.preferredMaintenanceWindow, observed.PreferredMaintenanceWindow); // prettier-ignore
-                setIf("DBPortNumber", news.port, observed.DbInstancePort);
                 setIf("OptionGroupName", news.optionGroupName, undefined);
                 setIf("LicenseModel", news.licenseModel, observed.LicenseModel);
                 setIf("CACertificateIdentifier", news.caCertificateIdentifier, observed.CACertificateIdentifier); // prettier-ignore
@@ -348,17 +919,21 @@ export const DBInstanceProvider = () => Provider.effect(DBInstance, Effect.gen(f
                 setIf("MonitoringRoleArn", news.monitoringRoleArn, observed.MonitoringRoleArn); // prettier-ignore
                 setIf("DeletionProtection", news.deletionProtection, observed.DeletionProtection); // prettier-ignore
                 setIf("NetworkType", news.networkType, observed.NetworkType);
-                setIf("DBParameterGroupName", news.dbParameterGroupName, undefined);
+                if (!parameterGroupMatches(associations, observed)) {
+                    core.DBParameterGroupName = associations.dbParameterGroupName;
+                    coreDirty = true;
+                }
                 setIf("PubliclyAccessible", news.publiclyAccessible, observed.PubliclyAccessible); // prettier-ignore
                 setIf("PromotionTier", news.promotionTier, observed.PromotionTier);
                 setIf("AutoMinorVersionUpgrade", news.autoMinorVersionUpgrade, observed.AutoMinorVersionUpgrade); // prettier-ignore
                 setIf("CopyTagsToSnapshot", news.copyTagsToSnapshot, observed.CopyTagsToSnapshot); // prettier-ignore
-                // Security groups on Aurora cluster members are managed by the DB
-                // cluster (ModifyDBCluster), so only sync them for standalone
-                // instances.
-                if (news.vpcSecurityGroupIds !== undefined &&
-                    news.dbClusterIdentifier === undefined) {
-                    core.VpcSecurityGroupIds = news.vpcSecurityGroupIds;
+                if (!securityGroupsMatch(associations, observed)) {
+                    if (news.engine.startsWith("custom-")) {
+                        return yield* new InvalidDBInstanceAssociations({
+                            message: "Changing existing RDS Custom security-group associations through ModifyDBInstance is not supported",
+                        });
+                    }
+                    core.VpcSecurityGroupIds = associations.vpcSecurityGroupIds;
                     coreDirty = true;
                 }
                 if (news.allowMajorVersionUpgrade) {
@@ -381,6 +956,13 @@ export const DBInstanceProvider = () => Provider.effect(DBInstance, Effect.gen(f
                 if (coreDirty) {
                     yield* rds.modifyDBInstance(core);
                     observed = yield* waitForInstance(identifier);
+                    if (core.DBParameterGroupName !== undefined ||
+                        core.VpcSecurityGroupIds !== undefined) {
+                        observed = yield* waitForAssociations(identifier, associations);
+                    }
+                    if (core.AllocatedStorage !== undefined) {
+                        observed = yield* waitForStorage(identifier, (instance) => storageConverged(instance, desiredStorage));
+                    }
                 }
                 // syncCloudwatchLogsExports — delta-shaped; separate call so it
                 // never mixes the full-set fields above.
@@ -394,6 +976,80 @@ export const DBInstanceProvider = () => Provider.effect(DBInstance, Effect.gen(f
                     observed = yield* waitForInstance(identifier);
                 }
             }
+            if (hasPendingStorage(observed)) {
+                observed = yield* waitForStorage(identifier, (instance) => !hasPendingStorage(instance));
+            }
+            desiredStorage = yield* resolveStorage(news, observed.AllocatedStorage);
+            if (desiredStorage && !storageConverged(observed, desiredStorage)) {
+                yield* rds.modifyDBInstance({
+                    DBInstanceIdentifier: identifier,
+                    ...desiredStorage.request,
+                    MaxAllocatedStorage: storage.maxAllocatedStorage === 0
+                        ? desiredStorage.request.AllocatedStorage
+                        : storage.maxAllocatedStorage,
+                    ApplyImmediately: true,
+                });
+                observed = yield* waitForInstance(identifier);
+                observed = yield* waitForStorage(identifier, (instance) => storageConverged(instance, desiredStorage));
+            }
+            if (!autoscalingConverged(storage, observed)) {
+                const ceiling = storage.maxAllocatedStorage === 0
+                    ? observed.AllocatedStorage
+                    : storage.maxAllocatedStorage;
+                if (ceiling === undefined) {
+                    return yield* new InvalidDBInstanceStorage({
+                        message: "RDS did not return the allocated storage needed to disable autoscaling",
+                    });
+                }
+                // AWS disables autoscaling when the ceiling equals live allocation.
+                yield* rds.modifyDBInstance({
+                    DBInstanceIdentifier: identifier,
+                    MaxAllocatedStorage: ceiling,
+                    ApplyImmediately: true,
+                });
+                observed = yield* waitForStorage(identifier, (instance) => allocationConverged(storage, instance) &&
+                    autoscalingConverged(storage, instance));
+            }
+            port = yield* desiredInstancePort(news, observed);
+            if (port !== undefined && !portConverged(observed, port)) {
+                if (observed.PendingModifiedValues?.Port !== port) {
+                    if (news.engine.startsWith("custom-")) {
+                        return yield* new InvalidDBInstancePort({
+                            message: "Changing an existing RDS Custom listener through ModifyDBInstance is not supported",
+                        });
+                    }
+                    // Port changes restart immediately without applying unrelated pending settings.
+                    yield* rds.modifyDBInstance({
+                        DBInstanceIdentifier: identifier,
+                        DBPortNumber: port,
+                        ApplyImmediately: false,
+                    });
+                }
+                observed = yield* waitForPort(identifier, port);
+            }
+            associations = yield* resolveAssociations(news, observed);
+            if (!associationsConverged(associations, observed)) {
+                const parameterChanged = !parameterGroupMatches(associations, observed);
+                const securityChanged = !securityGroupsMatch(associations, observed);
+                if (securityChanged && news.engine.startsWith("custom-")) {
+                    return yield* new InvalidDBInstanceAssociations({
+                        message: "Changing existing RDS Custom security-group associations through ModifyDBInstance is not supported",
+                    });
+                }
+                if (parameterChanged || securityChanged) {
+                    yield* rds.modifyDBInstance({
+                        DBInstanceIdentifier: identifier,
+                        DBParameterGroupName: parameterChanged
+                            ? associations.dbParameterGroupName
+                            : undefined,
+                        VpcSecurityGroupIds: securityChanged
+                            ? associations.vpcSecurityGroupIds
+                            : undefined,
+                        ApplyImmediately: true,
+                    });
+                }
+                observed = yield* waitForAssociations(identifier, associations);
+            }
             const dbInstanceArn = observed.DBInstanceArn ?? "";
             // Sync tags — diff observed cloud tags against desired.
             const observedTags = toTagRecord(observed.TagList);
@@ -428,10 +1084,10 @@ export const DBInstanceProvider = () => Provider.effect(DBInstance, Effect.gen(f
             const finalDBSnapshotIdentifier = skipFinalSnapshot
                 ? undefined
                 : (output.finalDBSnapshotIdentifier ??
-                    `${output.dbInstanceIdentifier}-final-${new Date()
+                    (yield* Effect.sync(() => `${output.dbInstanceIdentifier}-final-${new Date()
                         .toISOString()
                         .replaceAll(/[:.]/g, "-")
-                        .toLowerCase()}`);
+                        .toLowerCase()}`)));
             yield* rds
                 .deleteDBInstance({
                 DBInstanceIdentifier: output.dbInstanceIdentifier,