import {
diffMigrations,
migrationsAttrs,
migrationsInputOf,
stampedOf,
type MigrationsInput,
} from "@alchemy.run/sql/Migrations";
import * as ec2 from "@distilled.cloud/aws/ec2";
import * as rds from "@distilled.cloud/aws/rds";
import * as secretsmanager from "@distilled.cloud/aws/secrets-manager";
import { isResolved } from "alchemy/Diff";
import { createPhysicalName } from "alchemy/PhysicalName";
import * as Provider from "alchemy/Provider";
import { Resource } from "alchemy/Resource";
import { createInternalTags, diffTags } from "alchemy/Tags";
import { toWireDays, toWireSeconds } from "alchemy/Util/Duration";
import { sha256 } from "alchemy/Util/sha256";
import * as Data from "effect/Data";
import type * as Duration from "effect/Duration";
import * as Effect from "effect/Effect";
import * as Redacted from "effect/Redacted";
import * as Schedule from "effect/Schedule";
import * as Stream from "effect/Stream";
import {
normalizePolicyDocument,
stringifyPolicyDocument,
type PolicyDocument,
} from "../IAM/Policy.ts";
import { reapLogGroupsByPrefix } from "../Logs/reapLogGroups.ts";
import type { Providers } from "../Providers.ts";
import { runDBInstanceMigrations, type MigrationsTransport } from "./Migrations.ts";
export interface DBInstanceProps {
/**
* Instance identifier. If omitted, Alchemy generates one.
*/
dbInstanceIdentifier?: string;
/**
* Aurora cluster the instance belongs to. When set, the instance is a
* cluster member and most storage/backup props are managed by the cluster.
* Replacing this forces a new instance.
*/
dbClusterIdentifier?: string;
/**
* Instance class such as `db.serverless` or `db.t3.micro`.
*/
dbInstanceClass: string;
/**
* Database engine, e.g. `mysql`, `postgres`, `aurora-postgresql`.
* Changing the engine forces replacement.
*/
engine: string;
/**
* Optional engine version. Changed in place via `modifyDBInstance`.
*/
engineVersion?: string;
/**
* Standalone (non-Aurora) database name created with the instance.
* Immutable — forces replacement.
*/
dbName?: string;
/**
* Minimum allocated storage in GiB (standalone instances). RDS cannot
* shrink storage; omission/removal retains any larger existing allocation.
* Defaults to 100 GiB for io1/io2, 40 GiB for other RDS Custom storage,
* and 20 GiB otherwise. In-place increases request at least 10% growth.
* Cluster members inherit storage from their cluster.
*/
allocatedStorage?: number;
/**
* Upper limit (GiB) for storage autoscaling on standalone instances.
* Omission or `0` disables autoscaling, including after adoption or drift.
* Disabling never shrinks allocated storage. RDS requires the current
* allocation as the modify request's reset value, not a zero ceiling.
* Not supported for cluster members or RDS Custom.
* @default 0
*/
maxAllocatedStorage?: number;
/**
* Storage type: `gp2` | `gp3` | `io1` | `io2` | `standard`. Omission/removal
* selects gp3, including for existing instances. Magnetic (`standard`)
* storage is accepted only for existing instances; Db2 does not support gp2.
* AWS engine, instance-class, and regional restrictions still apply.
* Cluster members inherit storage from their cluster.
* @default "gp3"
*/
storageType?: string;
/**
* Provisioned IOPS (io1/io2/gp3). Omission/removal selects a deterministic
* baseline, not the observed setting: gp3 uses 3000 IOPS, or 12000 for
* striped storage; io1/io2 use at least 1000. Allocation, autoscaling,
* engine, and declared throughput can raise that baseline.
* Small non-SQL Server gp3 volumes have fixed performance. AWS rate-limits
* changes and may require a storage-optimization cooldown.
*/
iops?: number;
/**
* Storage throughput in MiBps (gp3 only). Omission/removal selects 125,
* or 500 for striped storage. MySQL/MariaDB IOPS can raise the baseline.
* gp3 is striped at 200 GiB for Oracle and 400 GiB for other engines,
* except SQL Server, which does not use the striped baseline.
*/
storageThroughput?: number;
/**
* Master username (standalone instances). Immutable — forces replacement.
*/
masterUsername?: string;
/**
* Master password (standalone instances). In-place modify.
*/
masterUserPassword?: Redacted.Redacted<string>;
/**
* Let RDS manage the master user password in Secrets Manager.
*/
manageMasterUserPassword?: boolean;
/**
* Rotate the managed master user password on the next reconcile.
*/
rotateMasterUserPassword?: boolean;
/**
* KMS key used to encrypt the managed master user secret.
*/
masterUserSecretKmsKeyId?: string;
/**
* Resource policy for this instance's RDS-managed master secret. Omission or
* removal deletes an existing policy, including after adoption or drift.
* RDS retains ownership of the secret value, rotation, and deletion.
* Requires Secrets Manager GetResourcePolicy, ValidateResourcePolicy,
* PutResourcePolicy, and DeleteResourcePolicy permissions. Declared policies
* are validated even on no-op plans; writes also use BlockPublicPolicy.
* Cluster-owned secrets and RDS Custom are not supported by this property.
*/
masterUserSecretResourcePolicy?: PolicyDocument;
/**
* Standalone listener port. Omission/removal restores the engine default:
* PostgreSQL 5432, MySQL/MariaDB 3306, Oracle 1521, SQL Server 1433, Db2 50000.
* Unknown engines require an explicit port. RDS Custom supports creation
* with a port, but changing an existing Custom listener is not supported here.
* Ignored for Aurora and cluster members: configure the DBCluster port.
* Changes restart the database and are sent as `DBPortNumber` on modify.
*/
port?: number;
/**
* Multi-AZ deployment (standalone instances). In-place modify.
*/
multiAZ?: boolean;
/**
* Availability zone (standalone single-AZ). Immutable — forces replacement.
*/
availabilityZone?: string;
/**
* Backup retention period (e.g. `"7 days"` or `Duration.days(7)`).
* Sent to the API in whole days. In-place modify.
*/
backupRetentionPeriod?: Duration.Input;
/**
* Daily backup window, e.g. `07:00-09:00`. In-place modify.
*/
preferredBackupWindow?: string;
/**
* Weekly maintenance window, e.g. `Mon:00:00-Mon:03:00`. In-place modify.
*/
preferredMaintenanceWindow?: string;
/**
* Optional DB subnet group. Effectively immutable for an in-VPC instance.
*/
dbSubnetGroupName?: string;
/**
* DB parameter group. Omission/removal restores `default.<engine-family>`.
* The family follows the requested version, otherwise the existing engine
* version, otherwise the regional default for a new instance. Aurora uses
* its cluster's version. Pending-reboot associations are returned without
* automatically rebooting. Unsupported on RDS Custom; Db2 BYOL requires
* an explicit group with IBM licensing IDs.
*/
dbParameterGroupName?: string;
/**
* VPC security groups attached to the instance, compared as a set.
* Omission/removal restores the default group in the effective instance VPC:
* the declared subnet group's VPC, the existing instance VPC, or the regional
* default VPC for a new instance. An empty array is invalid.
* Resetting changes network access according to the default group's rules;
* it does not delete detached group resources. Ignored for cluster members,
* whose security groups are managed on DBCluster. Existing RDS Custom
* attachments cannot be changed through this provider.
*/
vpcSecurityGroupIds?: string[];
/**
* Option group (MySQL/Oracle/SQL Server). In-place modify.
*/
optionGroupName?: string;
/**
* License model, e.g. `license-included` | `bring-your-own-license`.
*/
licenseModel?: string;
/**
* Whether storage is encrypted. Immutable — forces replacement.
*/
storageEncrypted?: boolean;
/**
* KMS key for storage encryption. Immutable — forces replacement.
*/
kmsKeyId?: string;
/**
* CA certificate identifier. In-place modify.
*/
caCertificateIdentifier?: string;
/**
* Enable IAM database authentication. Omission/removal disables it, including
* after adoption or drift. Cluster members inherit their cluster's setting.
* Applying a change or a queued IAM change uses ApplyImmediately, which also
* applies unrelated pending RDS modifications. Supported on standalone
* PostgreSQL, MySQL, and MariaDB; unsupported on RDS Custom.
* @default false
*/
enableIAMDatabaseAuthentication?: boolean;
/**
* Enable Performance Insights. In-place modify.
*/
enablePerformanceInsights?: boolean;
/**
* KMS key for Performance Insights. In-place modify.
*/
performanceInsightsKMSKeyId?: string;
/**
* Performance Insights retention (e.g. `"7 days"`). Sent to the API in
* whole days (valid: 7, 731, or month multiples).
*/
performanceInsightsRetentionPeriod?: Duration.Input;
/**
* Enhanced-monitoring granularity (e.g. `"60 seconds"`). Sent to the API
* in whole seconds (valid: 0, 1, 5, 10, 15, 30, 60).
*/
monitoringInterval?: Duration.Input;
/**
* IAM role ARN for enhanced monitoring. In-place modify.
*/
monitoringRoleArn?: string;
/**
* Log types to export to CloudWatch Logs, compared as a set. Omission/removal
* disables all exports. Changes apply immediately without flushing unrelated
* pending modifications. Cluster members inherit their cluster's exports.
* Unsupported on RDS Custom.
* @default []
*/
enableCloudwatchLogsExports?: string[];
/**
* Block accidental deletion. Omission/removal disables protection, including
* after adoption or drift. Ignored for cluster members: configure DBCluster.
* Aurora cluster protection does not prevent deleting individual instances.
* @default false
*/
deletionProtection?: boolean;
/**
* Network type: `IPV4` | `DUAL`. Omission/removal restores IPv4. DUAL requires
* IPv6-enabled subnets. Ignored for cluster members: configure DBCluster.
* Changes apply immediately and can also apply unrelated pending RDS changes.
* @default "IPV4"
*/
networkType?: string;
/**
* Allow a major engine-version upgrade during a modify. Modify-only flag.
*/
allowMajorVersionUpgrade?: boolean;
/**
* Whether the instance has a public address. Omission/removal restores private
* access, including after adoption or drift. Also managed on Aurora instances;
* non-Aurora Multi-AZ cluster members inherit their cluster's configuration.
* Changes apply immediately without flushing unrelated pending modifications.
* @default false
*/
publiclyAccessible?: boolean;
/**
* Promotion tier inside the cluster.
*/
promotionTier?: number;
/**
* Auto minor version upgrades.
*/
autoMinorVersionUpgrade?: boolean;
/**
* Copy tags to snapshots.
*/
copyTagsToSnapshot?: boolean;
/**
* User-defined tags.
*/
tags?: Record<string, string>;
/**
* Skip the final snapshot when the instance is deleted. Set `false` to
* have RDS take a final snapshot on teardown — belt-and-suspenders beyond
* `deletionProtection` for databases whose data must survive a deliberate
* destroy. Persisted into state so `delete` honors it without props.
* @default true
*/
skipFinalSnapshot?: boolean;
/**
* Identifier for the final snapshot taken when `skipFinalSnapshot` is
* `false`. Defaults to `<instance-identifier>-final-<timestamp>` so
* repeated destroy/create cycles never collide on snapshot names.
*/
finalDBSnapshotIdentifier?: string;
/**
* SQL migrations to apply on deploy, once this instance is available.
* Accepts a directory path, a `Drizzle.Schema` resource, or
* `{ dir, table? }`. Supports PostgreSQL, MySQL and MariaDB engines. On
* an Aurora cluster member the migrations target the cluster's database;
* declare them on one instance per cluster (the writer).
*
* Bookkeeping always lives in Alchemy's `__alchemy_migrations` table. A
* database previously migrated by drizzle-kit or Prisma is adopted by a
* one-way conversion on first deploy. Each migration commits with its
* bookkeeping row in one transaction; MySQL and MariaDB commit DDL
* implicitly, so their DDL is not rolled back if a later statement fails.
* Deleting the instance never touches the database.
*/
migrations?: MigrationsInput;
/**
* How `migrations` reach the database: `"data-api"` (Aurora clusters with
* `enableHttpEndpoint: true`; the Data API runs one statement per call, so
* separate statements with `--> statement-breakpoint`), `"direct"` (a
* connection from the deploying machine, which needs a network route to
* the endpoint), or an `AWS.RDS.MigrationRunner` Lambda inside the VPC.
* @default "data-api" when the instance's Aurora cluster has the Data API enabled, otherwise "direct"
*/
migrationsTransport?: MigrationsTransport;
/**
* ARN of the Secrets Manager secret (JSON with `username` and `password`)
* that `migrations` authenticate with.
* @default `masterUsername` + `masterUserPassword` when set (direct and Lambda transports), otherwise the RDS-managed master user secret
*/
migrationsSecretArn?: string;
}
export interface DBInstance extends Resource<
"AWS.RDS.DBInstance",
DBInstanceProps,
{
/**
* Identifier of the instance.
*/
dbInstanceIdentifier: string;
/**
* ARN of the instance.
*/
dbInstanceArn: string;
/**
* Aurora cluster the instance belongs to, if any.
*/
dbClusterIdentifier: string | undefined;
/**
* DNS address of the instance endpoint.
*/
endpointAddress: string | undefined;
/**
* Port of the instance endpoint.
*/
endpointPort: number | undefined;
/**
* Instance class (e.g. `db.serverless`, `db.t3.micro`).
*/
dbInstanceClass: string | undefined;
/**
* Database engine.
*/
engine: string | undefined;
/**
* Engine version in use.
*/
engineVersion: string | undefined;
/**
* Status of the instance (e.g. `available`).
*/
status: string | undefined;
/**
* Failover promotion tier inside the cluster.
*/
promotionTier: number | undefined;
/**
* Whether the instance has a public address.
*/
publiclyAccessible: boolean | undefined;
/**
* Subnet group the instance is placed in.
*/
dbSubnetGroupName: string | undefined;
/**
* Parameter groups applied to the instance.
*/
dbParameterGroupNames: string[];
/**
* Observed parameter-group apply statuses, including pending-reboot.
*/
dbParameterGroupApplyStatuses: Record<string, string | undefined>;
/**
* Observed VPC security-group attachments, including cluster-owned groups.
*/
vpcSecurityGroupIds: string[];
/**
* Observed VPC security-group application states, such as `active`.
*/
vpcSecurityGroupStatuses: Record<string, string | undefined>;
/**
* Allocated storage in GiB.
*/
allocatedStorage: number | undefined;
/**
* Storage autoscaling ceiling in GiB.
*/
maxAllocatedStorage: number | undefined;
/**
* Storage type (e.g. `gp3`, `io1`, `aurora`).
*/
storageType: string | undefined;
/**
* Provisioned IOPS.
*/
iops: number | undefined;
/**
* Storage throughput in MiBps (gp3).
*/
storageThroughput: number | undefined;
/**
* Whether the instance is Multi-AZ.
*/
multiAZ: boolean | undefined;
/**
* Availability Zone of the instance.
*/
availabilityZone: string | undefined;
/**
* Standby AZ for Multi-AZ deployments.
*/
secondaryAvailabilityZone: string | undefined;
/**
* Backup retention period in days.
*/
backupRetentionPeriod: number | undefined;
/**
* Daily backup window (`hh:mm-hh:mm` UTC).
*/
preferredBackupWindow: string | undefined;
/**
* Weekly maintenance window.
*/
preferredMaintenanceWindow: string | undefined;
/**
* KMS key used for storage encryption.
*/
kmsKeyId: string | undefined;
/**
* Whether storage is encrypted.
*/
storageEncrypted: boolean | undefined;
/**
* CA certificate identifier.
*/
caCertificateIdentifier: string | undefined;
/**
* Whether IAM database authentication is enabled.
*/
iamDatabaseAuthenticationEnabled: boolean | undefined;
/**
* Observed IAM authentication change awaiting application. A pending value
* is not evidence that authentication has changed on the database.
*/
pendingIamDatabaseAuthenticationEnabled: boolean | undefined;
/**
* Whether Performance Insights is enabled.
*/
performanceInsightsEnabled: boolean | undefined;
/**
* Enhanced-monitoring granularity in seconds.
*/
monitoringInterval: number | undefined;
/**
* ARN of the enhanced-monitoring CloudWatch Logs stream.
*/
enhancedMonitoringResourceArn: string | undefined;
/**
* Log types exported to CloudWatch Logs.
*/
enabledCloudwatchLogsExports: string[];
/**
* Whether deletion protection is enabled.
*/
deletionProtection: boolean | undefined;
/**
* Whether minor engine upgrades are applied automatically, as observed.
* Lets `alchemy drift` detect out-of-band changes.
*/
autoMinorVersionUpgrade?: boolean;
/**
* Immutable region-unique instance resource ID (used in IAM auth ARNs).
*/
dbiResourceId: string | undefined;
/**
* Master username.
*/
masterUsername: string | undefined;
/**
* Whether the final snapshot is skipped on delete, persisted from the
* prop of the same name. `delete` receives only the stored attributes,
* never live props, so the snapshot decision must ride in state;
* `undefined` (older state without this attr) is treated as skip.
*/
skipFinalSnapshot: boolean | undefined;
/**
* Identifier used for the final snapshot when `skipFinalSnapshot` is
* `false`, persisted from props so `delete` can name the snapshot without
* live props. `undefined` means `delete` falls back to the default
* `<instance-identifier>-final-<timestamp>` naming scheme.
*/
finalDBSnapshotIdentifier: string | undefined;
/**
* Salted SHA-256 fingerprint of the last `masterUserPassword` this
* provider sent to RDS — `sha256(`${dbInstanceIdentifier}:${password}`)`,
* never the secret itself. Lets reconcile skip the `MasterUserPassword`
* modify (and the `resetting-master-credentials` cycle it triggers) when
* the configured password has not changed.
*
* Persisted `Redacted` because a password hash is still sensitive: an
* unsalted digest is vulnerable to rainbow-table lookup, so the state
* store must not surface it in plaintext (logs, `stringify`, dumps). The
* per-resource identifier salt additionally defeats precomputed tables;
* it is stable across a resource's life, so the fingerprint stays
* comparable across reconciles.
*/
masterUserPasswordFingerprint: Redacted.Redacted<string> | undefined;
/**
* ARN of the Secrets Manager secret holding master credentials.
*/
masterUserSecretArn: string | undefined;
/**
* Canonical policy observed during read or reconciliation. Undefined when
* there is no instance-managed secret or no resource policy. Inventory
* listing does not load policy metadata and leaves this attribute undefined.
*/
masterUserSecretResourcePolicy: string | undefined;
/**
* Option group memberships.
*/
optionGroupMemberships: string[];
/**
* License model.
*/
licenseModel: string | undefined;
/**
* Configured database port.
*/
dbInstancePort: number | undefined;
/**
* Network type (`IPV4` or `DUAL`).
*/
networkType: string | undefined;
/**
* Tags on the instance.
*/
tags: Record<string, string>;
/** Directory of the applied SQL migrations. */
migrationsDir: string | undefined;
/** Migration bookkeeping table. */
migrationsTable: string | undefined;
/** Applied migration content hashes. */
migrationsHashes: Record<string, string>;
},
never,
Providers
> {}
/**
* An RDS database instance — either a standalone (non-Aurora) database or a
* member of an Aurora `DBCluster`.
*
* Exposes the full storage, backup, monitoring, performance-insights,
* encryption, networking, and log-export surface of `createDBInstance` /
* `modifyDBInstance`. Mutable fields are reconciled in place against the
* observed cloud state; immutable fields (`engine`, `dbName`,
* `masterUsername`, `availabilityZone`, `storageEncrypted`, `kmsKeyId`,
* `dbSubnetGroupName`) force a replacement.
* ### Standalone Instance
* **Example:** A gp3 MySQL instance
* ```typescript
* const db = yield* DBInstance("Db", {
* engine: "mysql",
* dbInstanceClass: "db.t3.micro",
* allocatedStorage: 20,
* storageType: "gp3",
* masterUsername: "admin",
* masterUserPassword: Redacted.make("supersecret"),
* backupRetentionPeriod: "7 days",
* deletionProtection: false,
* });
* ```
*
* ### 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
* const writer = yield* DBInstance("Writer", {
* dbClusterIdentifier: cluster.dbClusterIdentifier,
* dbInstanceClass: "db.serverless",
* engine: "aurora-postgresql",
* });
* ```
*
* ### 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.
*
* ### Security Defaults
* Omission is desired configuration, not permission to retain external state:
* IAM authentication, public access, and deletion protection default to false,
* network type to IPV4, and log exports to an empty set. Removal and unchanged
* declarations repair these settings after drift or adoption.
*
* **Example:** Enable IAM authentication and PostgreSQL log exports
* ```typescript
* const db = yield* DBInstance("Db", {
* engine: "postgres",
* dbInstanceClass: "db.t3.micro",
* masterUsername: "admin",
* manageMasterUserPassword: true,
* dbSubnetGroupName: subnetGroup.dbSubnetGroupName,
* enableIAMDatabaseAuthentication: true,
* enableCloudwatchLogsExports: ["postgresql"],
* });
* ```
*
* Removing the last two properties disables IAM authentication and log exports.
* Public access remains instance-managed for Aurora, while IAM authentication,
* deletion protection, network type, and exports belong to DBCluster. Requested
* or observed cluster membership suppresses instance writes to those settings.
* Non-Aurora Multi-AZ cluster members also inherit public accessibility.
*
* ### Pending Security Changes
* **Example:** Inspect applied and pending IAM authentication separately
* ```typescript
* return {
* enabled: db.iamDatabaseAuthenticationEnabled,
* pending: db.pendingIamDatabaseAuthenticationEnabled,
* securityGroupStatuses: db.vpcSecurityGroupStatuses,
* };
* ```
*
* Deployment waits for applied security settings and an operational instance.
* A matching queued IAM value is promoted with ApplyImmediately without
* resending the IAM field; an incompatible queued value is overwritten even
* when the applied value already matches. AWS has no selective queue flush:
* applying IAM or network-type changes immediately can apply unrelated pending
* modifications and cause downtime. Alchemy does not wait until maintenance.
* Network type has no field in AWS PendingModifiedValues, so an externally
* queued network change cannot be detected until it starts applying.
* Public access, deletion protection, and log exports use ApplyImmediately:false
* because AWS applies these immediately regardless of that flag. They do not
* flush the maintenance queue. Other declared updates retain their existing
* immediate-application behavior. Static parameter changes remain pending-reboot;
* Alchemy never calls RebootDBInstance automatically.
*
* ### Managed Master Secret Policy
* **Example:** Allow a role to read the RDS-managed master secret
* ```typescript
* const db = yield* DBInstance("Db", {
* engine: "postgres",
* dbInstanceClass: "db.t3.micro",
* masterUsername: "admin",
* manageMasterUserPassword: true,
* masterUserSecretResourcePolicy: {
* Version: "2012-10-17",
* Statement: [{
* Effect: "Allow",
* Principal: { AWS: reader.roleArn },
* Action: ["secretsmanager:GetSecretValue"],
* Resource: "*",
* }],
* },
* });
* ```
*
* Declared policies are checked with `ValidateResourcePolicy`, including
* unchanged plans, and writes additionally use `BlockPublicPolicy`. Once the
* managed secret exists, validation names it, so deployment requires
* `secretsmanager:ValidateResourcePolicy` and `secretsmanager:PutResourcePolicy`
* on that secret rather than on `*`. Before the first create, with no secret
* yet, validation runs without a target. Alchemy compares
* live policy metadata without reading secret values. RDS owns credential
* generation, rotation, and secret deletion. Only instance-managed secrets are
* supported; an Aurora or Multi-AZ cluster owns its own secret, and RDS Custom
* does not support managed credentials. Explicit denies can still obstruct the
* deployer's access or RDS rotation; policy validation is not a guarantee that
* every declared permission is operationally safe.
*
* ### Removing a Managed Secret Policy
* **Example:** Restore the default of no resource policy
* ```diff lang="typescript"
* const db = yield* DBInstance("Db", {
* engine: "postgres",
* dbInstanceClass: "db.t3.micro",
* masterUsername: "admin",
* manageMasterUserPassword: true,
* - masterUserSecretResourcePolicy: readerPolicy,
* });
* ```
*
* Omission or removal deletes the resource policy, including external policies
* discovered during adoption or unchanged-input drift detection. Identity-based
* IAM permissions still apply. The secret, its credentials, and RDS rotation
* remain intact. Deployment waits for policy readback before returning; managing
* an existing secret also requires `secretsmanager:GetResourcePolicy` and, when
* resetting a policy, `secretsmanager:DeleteResourcePolicy`.
*
* ### Readiness
* Deployment waits for an instance ARN and an operational status: `available`
* or `storage-optimization`. Storage optimization remains online and can
* continue for hours. Missing or pending observations retain the ten-minute
* provisioning budget; SDK failures keep their original typed errors rather
* than being retried by the readiness loop. Unknown statuses and blue/green
* `storage-initialization` remain bounded pending observations, never ready.
*
* **Example:** Return the ready database's status from a stack
* ```typescript
* const db = yield* DBInstance("Db", {
* engine: "postgres",
* dbInstanceClass: "db.t3.micro",
* masterUsername: "admin",
* manageMasterUserPassword: true,
* });
* return { status: db.status };
* ```
*
* States requiring intervention, including `stopped`, `storage-full`, and
* incompatible or failed configurations, fail with `DBInstanceReadinessBlocked`.
* Alchemy does not automatically start a stopped instance. Restore its
* operational state and deploy again. Unchanged declarations also check
* readiness, while storage, port, and association updates wait for both their
* requested values and an operational instance before returning.
*
* ### Migrations
* **Example:** Apply migrations from an Aurora cluster's writer
* ```typescript
* const cluster = yield* DBCluster("Cluster", {
* engine: "aurora-postgresql",
* databaseName: "app",
* enableHttpEndpoint: true,
* manageMasterUserPassword: true,
* masterUsername: "app",
* });
* const writer = yield* DBInstance("Writer", {
* dbClusterIdentifier: cluster.dbClusterIdentifier,
* dbInstanceClass: "db.serverless",
* engine: "aurora-postgresql",
* migrations: "./migrations",
* });
* ```
*
* Migrations run over the cluster's Data API once the instance is
* available, so the deploying machine needs no VPC access. Declare them on
* one instance per cluster.
*
* **Example:** Migrate a publicly reachable instance directly
* ```typescript
* const db = yield* DBInstance("Db", {
* engine: "postgres",
* dbInstanceClass: "db.t4g.micro",
* allocatedStorage: 20,
* dbName: "app",
* masterUsername: "app",
* manageMasterUserPassword: true,
* publiclyAccessible: true,
* migrations: "./migrations",
* migrationsTransport: "direct",
* });
* ```
*
* **Example:** Migrate a private instance through an in-VPC runner
* ```typescript
* const runner = yield* AWS.RDS.MigrationRunner("MigrationRunner", {
* subnetIds: network.privateSubnetIds,
* securityGroupIds: [runnerSecurityGroup.groupId],
* });
* const db = yield* DBInstance("Db", {
* engine: "mysql",
* dbInstanceClass: "db.t4g.micro",
* allocatedStorage: 20,
* dbName: "app",
* masterUsername: "app",
* manageMasterUserPassword: true,
* dbSubnetGroupName: subnetGroup.dbSubnetGroupName,
* vpcSecurityGroupIds: [databaseSecurityGroup.groupId],
* migrations: "./migrations",
* migrationsTransport: runner,
* });
* ```
*
* ### Monitoring & Logs
* **Example:** Enhanced monitoring + log export
* ```typescript
* const db = yield* DBInstance("Db", {
* engine: "postgres",
* dbInstanceClass: "db.t3.micro",
* allocatedStorage: 20,
* monitoringInterval: "60 seconds",
* monitoringRoleArn: monitoringRole.roleArn,
* enablePerformanceInsights: true,
* enableCloudwatchLogsExports: ["postgresql", "upgrade"],
* });
* ```
*
* @resource
*/
export const DBInstance = Resource<DBInstance>("AWS.RDS.DBInstance");
const toTagRecord = (
tags: Array<{ Key?: string; Value?: string }> | undefined,
): Record<string, string> =>
Object.fromEntries(
(tags ?? [])
.filter(
(tag): tag is { Key: string; Value: string } =>
typeof tag.Key === "string" && typeof tag.Value === "string",
)
.map((tag) => [tag.Key, tag.Value]),
);
/**
* Whether two optional master-password fingerprints match, compared by their
* underlying (`Redacted`-unwrapped) digest. A missing stored fingerprint
* counts as "does not match" so a pre-existing instance sends its password
* once, then records the fingerprint for subsequent reconciles.
*/
const sameFingerprint = (
a: Redacted.Redacted<string> | undefined,
b: Redacted.Redacted<string> | undefined,
): boolean => a !== undefined && b !== undefined && Redacted.value(a) === Redacted.value(b);
const toAttrs = ({
instance,
tags,
skipFinalSnapshot,
finalDBSnapshotIdentifier,
masterUserPasswordFingerprint,
masterUserSecretResourcePolicy,
migrations,
}: {
instance: rds.DBInstance;
tags: Record<string, string>;
skipFinalSnapshot?: boolean | undefined;
finalDBSnapshotIdentifier?: string | undefined;
masterUserPasswordFingerprint?: Redacted.Redacted<string> | undefined;
masterUserSecretResourcePolicy?: string | undefined;
migrations?: Pick<
DBInstance["Attributes"],
"migrationsDir" | "migrationsTable" | "migrationsHashes"
>;
}): DBInstance["Attributes"] => ({
migrationsDir: migrations?.migrationsDir,
migrationsTable: migrations?.migrationsTable,
migrationsHashes: migrations?.migrationsHashes ?? {},
skipFinalSnapshot,
finalDBSnapshotIdentifier,
masterUserPasswordFingerprint,
dbInstanceIdentifier: instance.DBInstanceIdentifier ?? "",
dbInstanceArn: instance.DBInstanceArn ?? "",
dbClusterIdentifier: instance.DBClusterIdentifier,
endpointAddress: instance.Endpoint?.Address,
endpointPort: instance.Endpoint?.Port,
dbInstanceClass: instance.DBInstanceClass,
engine: instance.Engine,
engineVersion: instance.EngineVersion,
status: instance.DBInstanceStatus,
promotionTier: instance.PromotionTier,
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] : [],
),
vpcSecurityGroupStatuses: Object.fromEntries(
(instance.VpcSecurityGroups ?? []).flatMap((group) =>
group.VpcSecurityGroupId ? [[group.VpcSecurityGroupId, group.Status]] : [],
),
),
allocatedStorage: instance.AllocatedStorage,
maxAllocatedStorage: instance.MaxAllocatedStorage,
storageType: instance.StorageType,
iops: instance.Iops,
storageThroughput: instance.StorageThroughput,
multiAZ: instance.MultiAZ,
availabilityZone: instance.AvailabilityZone,
secondaryAvailabilityZone: instance.SecondaryAvailabilityZone,
backupRetentionPeriod: instance.BackupRetentionPeriod,
preferredBackupWindow: instance.PreferredBackupWindow,
preferredMaintenanceWindow: instance.PreferredMaintenanceWindow,
kmsKeyId: instance.KmsKeyId,
storageEncrypted: instance.StorageEncrypted,
caCertificateIdentifier: instance.CACertificateIdentifier,
iamDatabaseAuthenticationEnabled: instance.IAMDatabaseAuthenticationEnabled,
pendingIamDatabaseAuthenticationEnabled:
instance.PendingModifiedValues?.IAMDatabaseAuthenticationEnabled,
performanceInsightsEnabled: instance.PerformanceInsightsEnabled,
monitoringInterval: instance.MonitoringInterval,
enhancedMonitoringResourceArn: instance.EnhancedMonitoringResourceArn,
enabledCloudwatchLogsExports: instance.EnabledCloudwatchLogsExports ?? [],
deletionProtection: instance.DeletionProtection,
autoMinorVersionUpgrade: instance.AutoMinorVersionUpgrade,
dbiResourceId: instance.DbiResourceId,
masterUsername: instance.MasterUsername,
masterUserSecretArn: instance.MasterUserSecret?.SecretArn,
masterUserSecretResourcePolicy,
optionGroupMemberships: (instance.OptionGroupMemberships ?? []).flatMap((membership) =>
membership.OptionGroupName ? [membership.OptionGroupName] : [],
),
licenseModel: instance.LicenseModel,
dbInstancePort: instance.DbInstancePort,
networkType: instance.NetworkType,
tags,
});
/**
* Compute the CloudWatch Logs export delta. The modify API is delta-shaped
* (`EnableLogTypes`/`DisableLogTypes`), so it must NOT carry the full set.
* Returns `undefined` when there is no change.
*/
const logExportDelta = (
observed: string[] | undefined,
desired: string[] | undefined,
): rds.CloudwatchLogsExportConfiguration | undefined => {
if (desired === undefined) return undefined;
const have = new Set(observed ?? []);
const want = new Set(desired);
const EnableLogTypes = [...want].filter((t) => !have.has(t));
const DisableLogTypes = [...have].filter((t) => !want.has(t));
if (EnableLogTypes.length === 0 && DisableLogTypes.length === 0) {
return undefined;
}
return {
...(EnableLogTypes.length > 0 ? { EnableLogTypes } : {}),
...(DisableLogTypes.length > 0 ? { DisableLogTypes } : {}),
};
};
const sameMembers = (desired: readonly string[], observed: readonly (string | undefined)[]) => {
const want = new Set(desired);
const have = new Set(observed);
return want.size === have.size && [...want].every((value) => have.has(value));
};
const clusterOwnsConfiguration = (props: DBInstanceProps, observed?: rds.DBInstance) =>
props.dbClusterIdentifier !== undefined ||
observed?.DBClusterIdentifier !== undefined ||
props.engine.startsWith("aurora") ||
observed?.Engine?.startsWith("aurora") === true;
const securityConfiguration = (props: DBInstanceProps, observed?: rds.DBInstance) => {
const clusterOwned = clusterOwnsConfiguration(props, observed);
const custom =
props.engine.startsWith("custom-") || observed?.Engine?.startsWith("custom-") === true;
const supportsIam = ["postgres", "mysql", "mariadb"].includes(observed?.Engine ?? props.engine);
return {
publiclyAccessible:
clusterOwned && !props.engine.startsWith("aurora") && !observed?.Engine?.startsWith("aurora")
? undefined
: (props.publiclyAccessible ?? false),
iamAuthentication: clusterOwned
? undefined
: (props.enableIAMDatabaseAuthentication ?? (supportsIam ? false : undefined)),
deletionProtection: clusterOwned ? undefined : (props.deletionProtection ?? false),
networkType: clusterOwned ? undefined : (props.networkType ?? "IPV4"),
logExports: clusterOwned
? undefined
: (props.enableCloudwatchLogsExports ?? (custom ? undefined : [])),
};
};
type SecurityConfiguration = ReturnType<typeof securityConfiguration>;
const pendingLogExports = (instance: rds.DBInstance) =>
instance.PendingModifiedValues?.PendingCloudwatchLogsExports;
const effectiveLogExports = (instance: rds.DBInstance) => {
const exports = new Set(instance.EnabledCloudwatchLogsExports ?? []);
for (const log of pendingLogExports(instance)?.LogTypesToDisable ?? []) {
exports.delete(log);
}
for (const log of pendingLogExports(instance)?.LogTypesToEnable ?? []) {
exports.add(log);
}
return [...exports];
};
const iamConverged = (desired: SecurityConfiguration, instance: rds.DBInstance) =>
desired.iamAuthentication === undefined ||
(desired.iamAuthentication === instance.IAMDatabaseAuthenticationEnabled &&
instance.PendingModifiedValues?.IAMDatabaseAuthenticationEnabled === undefined);
const securityConverged = (desired: SecurityConfiguration, instance: rds.DBInstance) =>
iamConverged(desired, instance) &&
(desired.publiclyAccessible === undefined ||
desired.publiclyAccessible === instance.PubliclyAccessible) &&
(desired.deletionProtection === undefined ||
desired.deletionProtection === instance.DeletionProtection) &&
(desired.networkType === undefined || desired.networkType === instance.NetworkType) &&
(desired.logExports === undefined ||
(sameMembers(desired.logExports, instance.EnabledCloudwatchLogsExports ?? []) &&
(pendingLogExports(instance)?.LogTypesToEnable?.length ?? 0) === 0 &&
(pendingLogExports(instance)?.LogTypesToDisable?.length ?? 0) === 0));
class DBInstanceSecurityPending extends Data.TaggedError("DBInstanceSecurityPending")<{
instanceId: string;
}> {
override get message() {
return `DB instance '${this.instanceId}' security configuration did not converge`;
}
}
class InvalidDBInstanceAssociations extends Data.TaggedError("InvalidDBInstanceAssociations")<{
message: string;
}> {}
const resolveAssociations = Effect.fn(function* (
props: DBInstanceProps,
observed?: rds.DBInstance,
) {
const clusterIdentifier = props.dbClusterIdentifier ?? observed?.DBClusterIdentifier;
const clusterOwned = clusterOwnsConfiguration(props, observed);
const aurora =
props.engine.startsWith("aurora") || observed?.Engine?.startsWith("aurora") === true;
const custom = props.engine.startsWith("custom-");
if (clusterOwned && !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)],
};
});
type Associations = Effect.Success<ReturnType<typeof resolveAssociations>>;
const parameterGroupMatches = (desired: Associations, instance: rds.DBInstance) =>
desired.dbParameterGroupName === undefined ||
sameMembers(
[desired.dbParameterGroupName],
(instance.DBParameterGroups ?? []).map((group) => group.DBParameterGroupName),
);
const securityGroupsMatch = (desired: Associations, instance: rds.DBInstance) =>
desired.vpcSecurityGroupIds === undefined ||
sameMembers(
desired.vpcSecurityGroupIds,
(instance.VpcSecurityGroups ?? []).map((group) => group.VpcSecurityGroupId),
);
const associationsConverged = (desired: Associations, instance: rds.DBInstance) =>
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")<{
message: string;
}> {}
const desiredInstancePort = Effect.fn(function* (
props: DBInstanceProps,
observed?: rds.DBInstance,
) {
if (clusterOwnsConfiguration(props, observed)) {
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: rds.DBInstance, port: number | undefined) =>
port === undefined ||
(instance.Endpoint?.Port === port && instance.PendingModifiedValues?.Port === undefined);
class InvalidDBInstanceStorage extends Data.TaggedError("InvalidDBInstanceStorage")<{
message: string;
}> {}
type StorageRequest = Required<
Pick<rds.CreateDBInstanceMessage, "AllocatedStorage" | "StorageType">
> &
Pick<rds.CreateDBInstanceMessage, "Iops" | "StorageThroughput">;
interface DesiredStorage {
request: StorageRequest;
iops: number;
throughput: number;
}
const resolveStorage = Effect.fn(function* (props: DBInstanceProps, 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,
} satisfies DesiredStorage;
}
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,
} satisfies DesiredStorage;
});
const hasPendingStorage = (instance: rds.DBInstance) =>
instance.PendingModifiedValues?.AllocatedStorage !== undefined ||
instance.PendingModifiedValues?.StorageType !== undefined ||
instance.PendingModifiedValues?.Iops !== undefined ||
instance.PendingModifiedValues?.StorageThroughput !== undefined;
const storageConverged = (observed: rds.DBInstance, desired: DesiredStorage | undefined): boolean =>
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: DBInstanceProps) {
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,
};
});
type StorageConfiguration = Effect.Success<ReturnType<typeof toStorageConfiguration>>;
const allocationConverged = (desired: StorageConfiguration, observed: rds.DBInstance) =>
desired.allocatedStorage === undefined ||
(observed.AllocatedStorage !== undefined &&
observed.AllocatedStorage >= desired.allocatedStorage);
const autoscalingConverged = (desired: StorageConfiguration, observed: rds.DBInstance) => {
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;
};
class InvalidDBInstanceSecretPolicy extends Data.TaggedError("InvalidDBInstanceSecretPolicy")<{
message: string;
}> {}
class DBInstanceManagedSecretMissing extends Data.TaggedError("DBInstanceManagedSecretMissing")<{
instanceId: string;
}> {
override get message() {
return `DB instance '${this.instanceId}' has no RDS-managed master secret for its resource policy`;
}
}
class DBInstanceSecretPolicyPending extends Data.TaggedError("DBInstanceSecretPolicyPending")<{
instanceId: string;
}> {
override get message() {
return `DB instance '${this.instanceId}' managed-secret resource policy has not propagated`;
}
}
class DBInstancePending extends Data.TaggedError("DBInstancePending")<{
instanceId: string;
status: string | undefined;
}> {
override get message() {
return `DB instance '${this.instanceId}' is not ready (status: ${this.status ?? "not yet visible"})`;
}
}
class DBInstanceReadinessBlocked extends Data.TaggedError("DBInstanceReadinessBlocked")<{
instanceId: string;
status: string;
}> {
override get message() {
return `DB instance '${this.instanceId}' requires intervention (status: ${this.status})`;
}
}
const blockedStatuses = new Set([
"automation-paused",
"delete-precheck",
"deleted",
"deleting",
"failed",
"inaccessible-encryption-credentials",
"inaccessible-encryption-credentials-recoverable",
"incompatible-create",
"incompatible-network",
"incompatible-option-group",
"incompatible-parameters",
"incompatible-restore",
"insufficient-capacity",
"restore-error",
"stopped",
"stopping",
"storage-full",
"unsupported-configuration",
"upgrade-failed",
]);
const instanceReady = (
instance: rds.DBInstance | undefined,
): instance is rds.DBInstance & { DBInstanceArn: string } =>
!!instance?.DBInstanceArn &&
(instance.DBInstanceStatus === "available" ||
instance.DBInstanceStatus === "storage-optimization");
export const DBInstanceProvider = () =>
Provider.effect(
DBInstance,
Effect.gen(function* () {
const toIdentifier = (id: string, props: DBInstanceProps) =>
props.dbInstanceIdentifier
? Effect.succeed(props.dbInstanceIdentifier)
: createPhysicalName({ id, maxLength: 63 });
const readInstance = Effect.fn(function* (instanceId: string) {
const response = yield* rds
.describeDBInstances({
DBInstanceIdentifier: instanceId,
})
.pipe(Effect.catchTag("DBInstanceNotFoundFault", () => Effect.undefined));
return response?.DBInstances?.[0];
});
const observeReadiness = Effect.fn(function* (instanceId: string) {
const instance = yield* readInstance(instanceId);
const status = instance?.DBInstanceStatus;
if (status !== undefined && blockedStatuses.has(status)) {
return yield* new DBInstanceReadinessBlocked({ instanceId, status });
}
return instance;
});
// Storage optimization is online; provisioning retains its ten-minute budget.
const waitForInstance = Effect.fn(function* (instanceId: string) {
return yield* observeReadiness(instanceId).pipe(
Effect.flatMap((instance) =>
instanceReady(instance)
? Effect.succeed(instance)
: Effect.fail(
new DBInstancePending({
instanceId,
status: instance?.DBInstanceStatus,
}),
),
),
Effect.retry({
while: (error) => error._tag === "DBInstancePending",
schedule: Schedule.max([Schedule.fixed("10 seconds"), Schedule.recurs(60)]),
}),
);
});
// RDS can keep reporting `available` for a few seconds after accepting
// a modify, so `waitForInstance` may return before the previous change
// starts and the next modify reaches a busy instance. Wait it out and
// resend.
const modifyInstance = Effect.fn(function* (
instanceId: string,
request: rds.ModifyDBInstanceMessage,
) {
return yield* rds.modifyDBInstance(request).pipe(
Effect.catchTag("InvalidDBInstanceStateFault", (error) =>
waitForInstance(instanceId).pipe(Effect.andThen(Effect.fail(error))),
),
Effect.retry({
while: (error) => error._tag === "InvalidDBInstanceStateFault",
schedule: Schedule.spaced("5 seconds"),
times: 8,
}),
);
});
const waitForSecurity = Effect.fn(function* (
instanceId: string,
desired: SecurityConfiguration,
) {
const instance = yield* observeReadiness(instanceId).pipe(
Effect.repeat({
schedule: Schedule.min([
Schedule.exponential("5 seconds"),
Schedule.spaced("1 minute"),
]),
times: 10,
until: (instance) => instanceReady(instance) && securityConverged(desired, instance),
}),
);
if (!instanceReady(instance) || !securityConverged(desired, instance)) {