feat(rds): add support for database instances

packages/@aws-cdk/aws-rds/README.md

@@ -45,33 +45,85 @@ By default, the master password will be generated and stored in AWS Secrets Mana
 Your cluster will be empty by default. To add a default database upon construction, specify the
 `defaultDatabaseName` attribute.
 
+### Starting an Instance Database
+To set up a instance database, create an instance of `DatabaseInstance`. You must
+always launch a database in a VPC. Use the `vpcSubnets` attribute to control whether
+your instances will be launched privately or publicly:
+
+```ts
+const instance = new DatabaseInstance(stack, 'Instance', {
+    engine: rds.DatabaseInstanceEngine.OracleSE1,
+    instanceClass: new ec2.InstanceTypePair(ec2.InstanceClass.Burstable2, ec2.InstanceSize.Small),
+    masterUsername: 'syscdk',
+    vpc
+});
+```
+By default, the master password will be generated and stored in AWS Secrets Manager.
+
+Use `DatabaseInstanceFromSnapshot` and `DatabaseInstanceReadReplica` to create an instance from snapshot or
+a source database respectively:
+
+```ts
+new DatabaseInstanceFromSnapshot(stack, 'Instance', {
+    snapshotIdentifier: 'my-snapshot',
+    engine: rds.DatabaseInstanceEngine.Postgres,
+    instanceClass: new ec2.InstanceTypePair(ec2.InstanceClass.Burstable2, ec2.InstanceSize.Large),
+    vpc
+});
+
+new DatabaseInstanceReadReplica(stack, 'ReadReplica', {
+    sourceDatabaseInstance: sourceInstance,
+    engine: rds.DatabaseInstanceEngine.Postgres,
+    instanceClass: new ec2.InstanceTypePair(ec2.InstanceClass.Burstable2, ec2.InstanceSize.Large),
+    vpc
+});
+```
+Creating a "production" Oracle database instance with option and parameter groups:
+
+[example of setting up a production oracle instance](test/integ.instance.lit.ts)
+
+
+### Instance events
+To define Amazon CloudWatch event rules for database instances, use the `onEvent`
+method:
+
+```ts
+const rule = instance.onEvent('InstanceEvent');
+rule.addTarget(lambdaFunction);
+```
+
 ### Connecting
 
-To control who can access the cluster, use the `.connections` attribute. RDS database have
+To control who can access the cluster/instance, use the `.connections` attribute. RDS database have
 a default port, so you don't need to specify the port:
 
 ```ts
 cluster.connections.allowFromAnyIpv4('Open to the world');
 ```
 
-The endpoints to access your database will be available as the `.clusterEndpoint` and `.readerEndpoint`
+The endpoints to access your cluster database will be available as the `.clusterEndpoint` and `.readerEndpoint`
 attributes:
 
 ```ts
 const writeAddress = cluster.clusterEndpoint.socketAddress;   // "HOSTNAME:PORT"
 ```
 
+For an instance database:
+```ts
+const address = instance.instanceEndpoint.socketAddress;   // "HOSTNAME:PORT"
+```
+
 ### Rotating master password
-When the master password is generated and stored in AWS Secrets Manager, it can be rotated automatically:
+When the master password is generated and stored in AWS Secrets Manager, it can be rotated automatically both for a cluster and an instance:
 
-[example of setting up master password rotation](test/integ.cluster-rotation.lit.ts)
+[example of setting up master password rotation for a cluster](test/integ.cluster-rotation.lit.ts)
 
 Rotation of the master password is also supported for an existing cluster:
 ```ts
 new RotationSingleUser(stack, 'Rotation', {
     secret: importedSecret,
     engine: DatabaseEngine.Oracle,
-    target: importedCluster,
+    target: importedCluster, // or importedInstance
     vpc: importedVpc,
 })
 ```
@@ -87,3 +139,13 @@ The `importedSecret` must be a JSON string with the following format:
   "port": "<optional: if not specified, default port will be used>"
 }
 ```
+
+### Metrics
+Database instances expose [metrics (cloudwatch.Metric)](https://github.com/awslabs/aws-cdk/blob/master/packages/%40aws-cdk/aws-cloudwatch/README.md):
+```ts
+// The number of database connections in use (average over 5 minutes)
+const dbConnections = instance.metricDatabaseConnections();
+
+// The average amount of time taken per disk I/O operation (average over 1 minute)
+const readLatency = instance.metric('ReadLatency', { statistic: 'Average', periodSec: 60 });
+```

packages/@aws-cdk/aws-rds/lib/cluster-ref.ts

@@ -1,6 +1,7 @@
 import ec2 = require('@aws-cdk/aws-ec2');
 import secretsmanager = require('@aws-cdk/aws-secretsmanager');
 import cdk = require('@aws-cdk/cdk');
+import { Endpoint } from './endpoint';
 
 /**
  * Create a clustered database with a given number of instances.
@@ -82,31 +83,3 @@ export interface DatabaseClusterImportProps {
    */
   readonly instanceEndpointAddresses: string[];
 }
-
-/**
- * Connection endpoint of a database cluster or instance
- *
- * Consists of a combination of hostname and port.
- */
-export class Endpoint {
-  /**
-   * The hostname of the endpoint
-   */
-  public readonly hostname: string;
-
-  /**
-   * The port of the endpoint
-   */
-  public readonly port: string;
-
-  /**
-   * The combination of "HOSTNAME:PORT" for this endpoint
-   */
-  public readonly socketAddress: string;
-
-  constructor(address: string, port: string) {
-    this.hostname = address;
-    this.port = port;
-    this.socketAddress = `${address}:${port}`;
-  }
-}

packages/@aws-cdk/aws-rds/lib/cluster.ts

@@ -2,9 +2,10 @@ import ec2 = require('@aws-cdk/aws-ec2');
 import kms = require('@aws-cdk/aws-kms');
 import secretsmanager = require('@aws-cdk/aws-secretsmanager');
 import cdk = require('@aws-cdk/cdk');
-import { IClusterParameterGroup } from './cluster-parameter-group';
-import { DatabaseClusterImportProps, Endpoint, IDatabaseCluster } from './cluster-ref';
+import { DatabaseClusterImportProps, IDatabaseCluster } from './cluster-ref';
 import { DatabaseSecret } from './database-secret';
+import { Endpoint } from './endpoint';
+import { IParameterGroup } from './parameter-group';
 import { BackupProps, DatabaseClusterEngine, InstanceProps, Login } from './props';
 import { CfnDBCluster, CfnDBInstance, CfnDBSubnetGroup } from './rds.generated';
 import { DatabaseEngine, RotationSingleUser, RotationSingleUserOptions } from './rotation-single-user';
@@ -101,7 +102,7 @@ export interface DatabaseClusterProps {
    *
    * @default No parameter group
    */
-  readonly parameterGroup?: IClusterParameterGroup;
+  readonly parameterGroup?: IParameterGroup;
 
   /**
    * The CloudFormation policy to apply when the cluster and its instances

packages/@aws-cdk/aws-rds/lib/endpoint.ts

@@ -0,0 +1,27 @@
+/**
+ * Connection endpoint of a database cluster or instance
+ *
+ * Consists of a combination of hostname and port.
+ */
+export class Endpoint {
+  /**
+   * The hostname of the endpoint
+   */
+  public readonly hostname: string;
+
+  /**
+   * The port of the endpoint
+   */
+  public readonly port: string;
+
+  /**
+   * The combination of "HOSTNAME:PORT" for this endpoint
+   */
+  public readonly socketAddress: string;
+
+  constructor(address: string, port: string) {
+    this.hostname = address;
+    this.port = port;
+    this.socketAddress = `${address}:${port}`;
+  }
+}

packages/@aws-cdk/aws-rds/lib/index.ts

@@ -1,9 +1,14 @@
 export * from './cluster';
 export * from './cluster-ref';
 export * from './props';
-export * from './cluster-parameter-group';
+export * from './parameter-group';
 export * from './rotation-single-user';
 export * from './database-secret';
+export * from './endpoint';
+export * from './option-group';
+export * from './instance';
 
 // AWS::RDS CloudFormation Resources:
 export * from './rds.generated';
+
+import './rds-augmentations.generated';