@aws-cdk/aws-redshift

All classes with the Cfn prefix in this module (CFN Resources) are always stable and safe to use.

The APIs of higher level constructs in this module are experimental and under active development. They are subject to non-backward compatible changes or removal in any future version. These are not subject to the Semantic Versioning model and breaking changes will be announced in the release notes. This means that while you may use them, you may need to update your source code when upgrading to a newer version of this package.

Starting a Redshift Cluster Database

import * as ec2 from '@aws-cdk/aws-ec2';

const vpc = new ec2.Vpc(this, 'Vpc');
const cluster = new Cluster(this, 'Redshift', {
  masterUser: {
    masterUsername: 'admin',
  },
  vpc
});

Connecting

The endpoint to access your database cluster will be available as the `.clusterEndpoint` attribute:

```ts fixture=cluster
cluster.clusterEndpoint.socketAddress;   // "HOSTNAME:PORT"

Database Resources

Creating Users

By default, the user credentials are encrypted with your AWS account's default Secrets
Manager encryption key. You can specify the encryption key used for this purpose by
supplying a key in the `encryptionKey` property.

```ts fixture=cluster
import * as kms from '@aws-cdk/aws-kms';

const encryptionKey = new kms.Key(this, 'Key');
new User(this, 'User', {
  encryptionKey: encryptionKey,
  cluster: cluster,
  databaseName: 'databaseName',
});

The user password is generated by AWS Secrets Manager using the default configuration
found in
[`secretsmanager.SecretStringGenerator`](https://docs.aws.amazon.com/cdk/api/latest/docs/@aws-cdk_aws-secretsmanager.SecretStringGenerator.html),
except with password length `30` and some SQL-incompliant characters excluded. The
plaintext for the password will never be present in the CDK application; instead, a
[CloudFormation Dynamic
Reference](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/dynamic-references.html)
will be used wherever the password value is required.

### Creating Tables

Create a table within a Redshift cluster database by instantiating a `Table`
construct. This will make a query to the Redshift cluster to create a new database table
with the supplied schema.

```ts fixture=cluster
new Table(this, 'Table', {
  tableColumns: [{ name: 'col1', dataType: 'varchar(4)' }, { name: 'col2', dataType: 'float' }],
  cluster: cluster,
  databaseName: 'databaseName',
});

{ name: 'col1', dataType: 'varchar(4)', distKey: true },
{ name: 'col2', dataType: 'float' },

The table can also be configured to have sortStyle attribute and sortKey columns:

```ts fixture=cluster
new Table(this, 'Table', {
  tableColumns: [
    { name: 'col1', dataType: 'varchar(4)', sortKey: true },
    { name: 'col2', dataType: 'float', sortKey: true },
  ],
  cluster: cluster,
  databaseName: 'databaseName',
  sortStyle: TableSortStyle.COMPOUND,
});

Granting Privileges

Take care when managing privileges via the CDK, as attempting to manage a user's
privileges on the same table in multiple CDK applications could lead to accidentally
overriding these permissions. Consider the following two CDK applications which both refer
to the same user and table. In application 1, the resources are created and the user is
given `INSERT` permissions on the table:

```ts fixture=cluster
const databaseName = 'databaseName';
const username = 'myuser'
const tableName = 'mytable'

const user = new User(this, 'User', {
  username: username,
  cluster: cluster,
  databaseName: databaseName,
});
const table = new Table(this, 'Table', {
  tableColumns: [{ name: 'col1', dataType: 'varchar(4)' }, { name: 'col2', dataType: 'float' }],
  cluster: cluster,
  databaseName: databaseName,
});
table.grant(user, TableAction.INSERT);

Both applications attempt to grant the user the appropriate privilege on the table by
submitting a `GRANT USER` SQL query to the Redshift cluster. Note that the latter of these
two calls will have no effect since the user has already been granted the privilege.

Now, if application 1 were to remove the call to `grant`, a `REVOKE USER` SQL query is
submitted to the Redshift cluster. In general, application 1 does not know that
application 2 has also granted this permission and thus cannot decide not to issue the
revocation. This leads to the undesirable state where application 2 still contains the
call to `grant` but the user does not have the specified permission.

Note that this does not occur when duplicate privileges are granted within the same
application, as such privileges are de-duplicated before any SQL query is submitted.

## Rotating credentials

When the master password is generated and stored in AWS Secrets Manager, it can be rotated automatically:

```ts fixture=cluster
cluster.addRotationSingleUser(); // Will rotate automatically after 30 days