@aws-cdk/rds

AWS RDS Construct Library

The aws-cdk-rds package contains Constructs for setting up RDS instances.

Supported:

  • Clustered databases

Not supported:

  • Instance databases
  • Setting up from a snapshot

Starting a Clustered Database

To set up a clustered database (like Aurora), create an instance of DatabaseCluster. You must always launch a database in a VPC. Use the vpcPlacement attribute to control whether your instances will be launched privately or publicly:

const cluster = new DatabaseCluster(stack, 'Database', {
    engine: DatabaseClusterEngine.Aurora,
    masterUser: {
        username: 'admin',
        password: '7959866cacc02c2d243ecfe177464fe6',
    },
    instanceProps: {
        instanceType: new InstanceTypePair(InstanceClass.Burstable2, InstanceSize.Small),
        vpcPlacement: {
            usePublicSubnets: true
        },
        vpc
    }
});

Your cluster will be empty by default. To add a default database upon construction, specify the defaultDatabaseName attribute.

Connecting

To control who can access the cluster, use the .connections attribute. RDS database have a default port, so you don’t need to specify the port:

cluster.connections.allowFromAnyIpv4('Open to the world');

The endpoints to access your database will be available as the .clusterEndpoint and .readerEndpoint attributes:

const writeAddress = cluster.clusterEndpoint.socketAddress;   // "HOSTNAME:PORT"

Reference

BackupProps (interface)

class _aws-cdk_rds.BackupProps

Backup configuration for RDS databases

retentionDays

How many days to retain the backup

Type:number
preferredWindow

A daily time range in 24-hours UTC format in which backups preferably execute. Must be at least 30 minutes long. Example: ‘01:00-02:00’

Type:string or None

ClusterIdentifier

class _aws-cdk_rds.ClusterIdentifier([valueOrFunction])

Identifier of a cluster

Extends:Token
Parameters:valueOrFunction (any or None) –

DatabaseCluster

class _aws-cdk_rds.DatabaseCluster(parent, name, props)

Create a clustered database with a given number of instances.

Extends:

DatabaseClusterRef

Parameters:
  • parent (Construct) –
  • name (string) –
  • props (DatabaseClusterProps) –
clusterIdentifier

Identifier of the cluster

Type:ClusterIdentifier (readonly)
instanceIdentifiers

Identifiers of the replicas

Type:InstanceIdentifier (readonly)
clusterEndpoint

The endpoint to use for read/write operations

Type:Endpoint (readonly)
readerEndpoint

Endpoint to use for load-balanced read-only operations.

Type:Endpoint (readonly)
instanceEndpoints

Endpoints which address each individual replica.

Type:Endpoint (readonly)
defaultPortRange

Default port to connect to this database

Type:IPortRange (readonly)
connections

Access to the network connections

Type:DefaultConnections (readonly)
securityGroupId

Security group identifier of this database

Type:SecurityGroupId

DatabaseClusterEngine (enum)

class _aws-cdk_rds.DatabaseClusterEngine
Aurora
Neptune

DatabaseClusterProps (interface)

class _aws-cdk_rds.DatabaseClusterProps

Properties for a new database cluster

engine

What kind of database to start

Type:DatabaseClusterEngine
instances

How many replicas/instances to create Has to be at least 1.

Type:number or None
instanceProps

Settings for the individual instances that are launched

Type:InstanceProps
masterUser

Username and password for the administrative user

Type:Login
backup

Backup settings

Type:BackupProps or None
port

What port to listen on If not supplied, the default for the engine is used.

Type:number or None
clusterIdentifier

An optional identifier for the cluster If not supplied, a name is automatically generated.

Type:string or None
instanceIdentifierBase

Base identifier for instances Every replica is named by appending the replica number to this string, 1-based. If not given, the clusterIdentifier is used with the word “Instance” appended. If clusterIdentifier is also not given, the identifier is automatically generated.

Type:string or None
defaultDatabaseName

Name of a database which is automatically created inside the cluster

Type:string or None
kmsKeyArn

ARN of KMS key if you want to enable storage encryption

Type:KeyArn or None
preferredMaintenanceWindow

A daily time range in 24-hours UTC format in which backups preferably execute. Must be at least 30 minutes long. Example: ‘01:00-02:00’

Type:string or None
parameters

Additional parameters to pass to the database engine

Type:any or None

DatabaseClusterRef

class _aws-cdk_rds.DatabaseClusterRef(parent, name)

Create a clustered database with a given number of instances.

Extends:

Construct

Implements:

IDefaultConnectable

Abstract:

Yes

Parameters:
  • parent (Construct) – The parent construct
  • name (string) –
static import(parent, name, props) → @aws-cdk/rds.DatabaseClusterRef

Import an existing DatabaseCluster from properties

Parameters:
  • parent (Construct) –
  • name (string) –
  • props (DatabaseClusterRefProps) –
Return type:

DatabaseClusterRef

export() → @aws-cdk/rds.DatabaseClusterRefProps

Export a Database Cluster for importing in another stack

Return type:DatabaseClusterRefProps
defaultPortRange

Default port to connect to this database

Type:IPortRange (readonly) (abstract)
connections

Access to the network connections

Type:DefaultConnections (readonly) (abstract)
clusterIdentifier

Identifier of the cluster

Type:ClusterIdentifier (readonly) (abstract)
instanceIdentifiers

Identifiers of the replicas

Type:InstanceIdentifier (readonly) (abstract)
clusterEndpoint

The endpoint to use for read/write operations

Type:Endpoint (readonly) (abstract)
readerEndpoint

Endpoint to use for load-balanced read-only operations.

Type:Endpoint (readonly) (abstract)
instanceEndpoints

Endpoints which address each individual replica.

Type:Endpoint (readonly) (abstract)
securityGroupId

The security group for this database cluster

Type:SecurityGroupId (readonly) (abstract)

DatabaseClusterRefProps (interface)

class _aws-cdk_rds.DatabaseClusterRefProps

Properties that describe an existing cluster instance

port

The database port

Type:Port
securityGroupId

The security group for this database cluster

Type:SecurityGroupId
clusterIdentifier

Identifier for the cluster

Type:ClusterIdentifier
instanceIdentifiers

Identifier for the instances

Type:InstanceIdentifier
clusterEndpointAddress

Cluster endpoint address

Type:DBClusterEndpointAddress
readerEndpointAddress

Reader endpoint address

Type:DBClusterEndpointAddress
instanceEndpointAddresses

Endpoint addresses of individual instances

Type:DBClusterEndpointAddress

DatabaseInstance

class _aws-cdk_rds.DatabaseInstance(parent, name)

Create a database instance This can be a standalone database instance, or part of a cluster.

Extends:

Construct

Parameters:
  • parent (Construct) – The parent construct
  • name (string) –

Endpoint

class _aws-cdk_rds.Endpoint(address, port)

Connection endpoint of a database cluster or instance Consists of a combination of hostname and port.

Parameters:
  • address (DBClusterEndpointAddress) –
  • port (Port) –
hostname

The hostname of the endpoint

Type:DBClusterEndpointAddress (readonly)
port

The port of the endpoint

Type:Port (readonly)
socketAddress

The combination of “HOSTNAME:PORT” for this endpoint

Type:SocketAddress (readonly)

InstanceIdentifier

class _aws-cdk_rds.InstanceIdentifier([valueOrFunction])

Identifier of an instance

Extends:Token
Parameters:valueOrFunction (any or None) –

InstanceProps (interface)

class _aws-cdk_rds.InstanceProps

Instance properties for database instances

instanceType

What type of instance to start for the replicas

Type:InstanceType
vpc

What subnets to run the RDS instances in. Must be at least 2 subnets in two different AZs.

Type:VpcNetworkRef
vpcPlacement

Where to place the instances within the VPC

Type:VpcPlacementStrategy or None

Login (interface)

class _aws-cdk_rds.Login

Username and password combination

username

Username

Type:Username
password

Password Do not put passwords in your CDK code directly. Import it from a Stack Parameter or the SSM Parameter Store instead.

Type:Password

Password

class _aws-cdk_rds.Password([valueOrFunction])

An RDS password

Extends:Token
Parameters:valueOrFunction (any or None) –

Port

class _aws-cdk_rds.Port([valueOrFunction])

Port part of an address

Extends:Token
Parameters:valueOrFunction (any or None) –

SocketAddress

class _aws-cdk_rds.SocketAddress([valueOrFunction])

A complete socket address (hostname + “:” + port)

Extends:Token
Parameters:valueOrFunction (any or None) –

Username

class _aws-cdk_rds.Username([valueOrFunction])

An RDS username

Extends:Token
Parameters:valueOrFunction (any or None) –