# Amazon Redshift Construct Library
<!--BEGIN STABILITY BANNER-->---
> AWS CDK v1 has reached End-of-Support on 2023-06-01.
> This package is no longer being updated, and users should migrate to AWS CDK v2.
>
> For more information on how to migrate, see the [*Migrating to AWS CDK v2* guide](https://docs.aws.amazon.com/cdk/v2/guide/migrating-v2.html).
---
<!--END STABILITY BANNER-->
## Starting a Redshift Cluster Database
To set up a Redshift cluster, define a `Cluster`. It will be launched in a VPC.
You can specify a VPC, otherwise one will be created. The nodes are always launched in private subnets and are encrypted by default.
```python
import aws_cdk.aws_ec2 as ec2
vpc = ec2.Vpc(self, "Vpc")
cluster = Cluster(self, "Redshift",
master_user=Login(
master_username="admin"
),
vpc=vpc
)
```
By default, the master password will be generated and stored in AWS Secrets Manager.
A default database named `default_db` will be created in the cluster. To change the name of this database set the `defaultDatabaseName` attribute in the constructor properties.
By default, the cluster will not be publicly accessible.
Depending on your use case, you can make the cluster publicly accessible with the `publiclyAccessible` property.
## Connecting
To control who can access the cluster, use the `.connections` attribute. Redshift Clusters have
a default port, so you don't need to specify the port:
```python
cluster.connections.allow_default_port_from_any_ipv4("Open to the world")
```
The endpoint to access your database cluster will be available as the `.clusterEndpoint` attribute:
```python
cluster.cluster_endpoint.socket_address
```
## Database Resources
This module allows for the creation of non-CloudFormation database resources such as users
and tables. This allows you to manage identities, permissions, and stateful resources
within your Redshift cluster from your CDK application.
Because these resources are not available in CloudFormation, this library leverages
[custom
resources](https://docs.aws.amazon.com/cdk/api/latest/docs/custom-resources-readme.html)
to manage them. In addition to the IAM permissions required to make Redshift service
calls, the execution role for the custom resource handler requires database credentials to
create resources within the cluster.
These database credentials can be supplied explicitly through the `adminUser` properties
of the various database resource constructs. Alternatively, the credentials can be
automatically pulled from the Redshift cluster's default administrator
credentials. However, this option is only available if the password for the credentials
was generated by the CDK application (ie., no value vas provided for [the `masterPassword`
property](https://docs.aws.amazon.com/cdk/api/latest/docs/@aws-cdk_aws-redshift.Login.html#masterpasswordspan-classapi-icon-api-icon-experimental-titlethis-api-element-is-experimental-it-may-change-without-noticespan)
of
[`Cluster.masterUser`](https://docs.aws.amazon.com/cdk/api/latest/docs/@aws-cdk_aws-redshift.Cluster.html#masteruserspan-classapi-icon-api-icon-experimental-titlethis-api-element-is-experimental-it-may-change-without-noticespan)).
### Creating Users
Create a user within a Redshift cluster database by instantiating a `User` construct. This
will generate a username and password, store the credentials in a [AWS Secrets Manager
`Secret`](https://docs.aws.amazon.com/cdk/api/latest/docs/@aws-cdk_aws-secretsmanager.Secret.html),
and make a query to the Redshift cluster to create a new database user with the
credentials.
```python
User(self, "User",
cluster=cluster,
database_name="databaseName"
)
```
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.
```python
import aws_cdk.aws_kms as kms
encryption_key = kms.Key(self, "Key")
User(self, "User",
encryption_key=encryption_key,
cluster=cluster,
database_name="databaseName"
)
```
By default, a username is automatically generated from the user construct ID and its path
in the construct tree. You can specify a particular username by providing a value for the
`username` property. Usernames must be valid identifiers; see: [Names and
identifiers](https://docs.aws.amazon.com/redshift/latest/dg/r_names.html) in the *Amazon
Redshift Database Developer Guide*.
```python
User(self, "User",
username="myuser",
cluster=cluster,
database_name="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.
```python
Table(self, "Table",
table_columns=[Column(name="col1", data_type="varchar(4)"), Column(name="col2", data_type="float")],
cluster=cluster,
database_name="databaseName"
)
```
The table can be configured to have distStyle attribute and a distKey column:
```python
Table(self, "Table",
table_columns=[Column(name="col1", data_type="varchar(4)", dist_key=True), Column(name="col2", data_type="float")
],
cluster=cluster,
database_name="databaseName",
dist_style=TableDistStyle.KEY
)
```
The table can also be configured to have sortStyle attribute and sortKey columns:
```python
Table(self, "Table",
table_columns=[Column(name="col1", data_type="varchar(4)", sort_key=True), Column(name="col2", data_type="float", sort_key=True)
],
cluster=cluster,
database_name="databaseName",
sort_style=TableSortStyle.COMPOUND
)
```
### Granting Privileges
You can give a user privileges to perform certain actions on a table by using the
`Table.grant()` method.
```python
user = User(self, "User",
cluster=cluster,
database_name="databaseName"
)
table = Table(self, "Table",
table_columns=[Column(name="col1", data_type="varchar(4)"), Column(name="col2", data_type="float")],
cluster=cluster,
database_name="databaseName"
)
table.grant(user, TableAction.DROP, TableAction.SELECT)
```
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:
```python
database_name = "databaseName"
username = "myuser"
table_name = "mytable"
user = User(self, "User",
username=username,
cluster=cluster,
database_name=database_name
)
table = Table(self, "Table",
table_columns=[Column(name="col1", data_type="varchar(4)"), Column(name="col2", data_type="float")],
cluster=cluster,
database_name=database_name
)
table.grant(user, TableAction.INSERT)
```
In application 2, the resources are imported and the user is given `INSERT` permissions on
the table:
```python
database_name = "databaseName"
username = "myuser"
table_name = "mytable"
user = User.from_user_attributes(self, "User",
username=username,
password=SecretValue.unsafe_plain_text("NOT_FOR_PRODUCTION"),
cluster=cluster,
database_name=database_name
)
table = Table.from_table_attributes(self, "Table",
table_name=table_name,
table_columns=[Column(name="col1", data_type="varchar(4)"), Column(name="col2", data_type="float")],
cluster=cluster,
database_name="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:
```python
cluster.add_rotation_single_user()
```
The multi user rotation scheme is also available:
```python
user = User(self, "User",
cluster=cluster,
database_name="databaseName"
)
cluster.add_rotation_multi_user("MultiUserRotation",
secret=user.secret
)
```
Raw data
{
"_id": null,
"home_page": "https://github.com/aws/aws-cdk",
"name": "aws-cdk.aws-redshift",
"maintainer": "",
"docs_url": null,
"requires_python": "~=3.7",
"maintainer_email": "",
"keywords": "",
"author": "Amazon Web Services",
"author_email": "",
"download_url": "https://files.pythonhosted.org/packages/3d/61/e1570a6e3ee99255154740f97a6c55fd7215168050cebcf8d0fce3223cea/aws-cdk.aws-redshift-1.204.0.tar.gz",
"platform": null,
"description": "# Amazon Redshift Construct Library\n\n<!--BEGIN STABILITY BANNER-->---\n\n\n\n\n> AWS CDK v1 has reached End-of-Support on 2023-06-01.\n> This package is no longer being updated, and users should migrate to AWS CDK v2.\n>\n> For more information on how to migrate, see the [*Migrating to AWS CDK v2* guide](https://docs.aws.amazon.com/cdk/v2/guide/migrating-v2.html).\n\n---\n<!--END STABILITY BANNER-->\n\n## Starting a Redshift Cluster Database\n\nTo set up a Redshift cluster, define a `Cluster`. It will be launched in a VPC.\nYou can specify a VPC, otherwise one will be created. The nodes are always launched in private subnets and are encrypted by default.\n\n```python\nimport aws_cdk.aws_ec2 as ec2\n\n\nvpc = ec2.Vpc(self, \"Vpc\")\ncluster = Cluster(self, \"Redshift\",\n master_user=Login(\n master_username=\"admin\"\n ),\n vpc=vpc\n)\n```\n\nBy default, the master password will be generated and stored in AWS Secrets Manager.\n\nA default database named `default_db` will be created in the cluster. To change the name of this database set the `defaultDatabaseName` attribute in the constructor properties.\n\nBy default, the cluster will not be publicly accessible.\nDepending on your use case, you can make the cluster publicly accessible with the `publiclyAccessible` property.\n\n## Connecting\n\nTo control who can access the cluster, use the `.connections` attribute. Redshift Clusters have\na default port, so you don't need to specify the port:\n\n```python\ncluster.connections.allow_default_port_from_any_ipv4(\"Open to the world\")\n```\n\nThe endpoint to access your database cluster will be available as the `.clusterEndpoint` attribute:\n\n```python\ncluster.cluster_endpoint.socket_address\n```\n\n## Database Resources\n\nThis module allows for the creation of non-CloudFormation database resources such as users\nand tables. This allows you to manage identities, permissions, and stateful resources\nwithin your Redshift cluster from your CDK application.\n\nBecause these resources are not available in CloudFormation, this library leverages\n[custom\nresources](https://docs.aws.amazon.com/cdk/api/latest/docs/custom-resources-readme.html)\nto manage them. In addition to the IAM permissions required to make Redshift service\ncalls, the execution role for the custom resource handler requires database credentials to\ncreate resources within the cluster.\n\nThese database credentials can be supplied explicitly through the `adminUser` properties\nof the various database resource constructs. Alternatively, the credentials can be\nautomatically pulled from the Redshift cluster's default administrator\ncredentials. However, this option is only available if the password for the credentials\nwas generated by the CDK application (ie., no value vas provided for [the `masterPassword`\nproperty](https://docs.aws.amazon.com/cdk/api/latest/docs/@aws-cdk_aws-redshift.Login.html#masterpasswordspan-classapi-icon-api-icon-experimental-titlethis-api-element-is-experimental-it-may-change-without-noticespan)\nof\n[`Cluster.masterUser`](https://docs.aws.amazon.com/cdk/api/latest/docs/@aws-cdk_aws-redshift.Cluster.html#masteruserspan-classapi-icon-api-icon-experimental-titlethis-api-element-is-experimental-it-may-change-without-noticespan)).\n\n### Creating Users\n\nCreate a user within a Redshift cluster database by instantiating a `User` construct. This\nwill generate a username and password, store the credentials in a [AWS Secrets Manager\n`Secret`](https://docs.aws.amazon.com/cdk/api/latest/docs/@aws-cdk_aws-secretsmanager.Secret.html),\nand make a query to the Redshift cluster to create a new database user with the\ncredentials.\n\n```python\nUser(self, \"User\",\n cluster=cluster,\n database_name=\"databaseName\"\n)\n```\n\nBy default, the user credentials are encrypted with your AWS account's default Secrets\nManager encryption key. You can specify the encryption key used for this purpose by\nsupplying a key in the `encryptionKey` property.\n\n```python\nimport aws_cdk.aws_kms as kms\n\n\nencryption_key = kms.Key(self, \"Key\")\nUser(self, \"User\",\n encryption_key=encryption_key,\n cluster=cluster,\n database_name=\"databaseName\"\n)\n```\n\nBy default, a username is automatically generated from the user construct ID and its path\nin the construct tree. You can specify a particular username by providing a value for the\n`username` property. Usernames must be valid identifiers; see: [Names and\nidentifiers](https://docs.aws.amazon.com/redshift/latest/dg/r_names.html) in the *Amazon\nRedshift Database Developer Guide*.\n\n```python\nUser(self, \"User\",\n username=\"myuser\",\n cluster=cluster,\n database_name=\"databaseName\"\n)\n```\n\nThe user password is generated by AWS Secrets Manager using the default configuration\nfound in\n[`secretsmanager.SecretStringGenerator`](https://docs.aws.amazon.com/cdk/api/latest/docs/@aws-cdk_aws-secretsmanager.SecretStringGenerator.html),\nexcept with password length `30` and some SQL-incompliant characters excluded. The\nplaintext for the password will never be present in the CDK application; instead, a\n[CloudFormation Dynamic\nReference](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/dynamic-references.html)\nwill be used wherever the password value is required.\n\n### Creating Tables\n\nCreate a table within a Redshift cluster database by instantiating a `Table`\nconstruct. This will make a query to the Redshift cluster to create a new database table\nwith the supplied schema.\n\n```python\nTable(self, \"Table\",\n table_columns=[Column(name=\"col1\", data_type=\"varchar(4)\"), Column(name=\"col2\", data_type=\"float\")],\n cluster=cluster,\n database_name=\"databaseName\"\n)\n```\n\nThe table can be configured to have distStyle attribute and a distKey column:\n\n```python\nTable(self, \"Table\",\n table_columns=[Column(name=\"col1\", data_type=\"varchar(4)\", dist_key=True), Column(name=\"col2\", data_type=\"float\")\n ],\n cluster=cluster,\n database_name=\"databaseName\",\n dist_style=TableDistStyle.KEY\n)\n```\n\nThe table can also be configured to have sortStyle attribute and sortKey columns:\n\n```python\nTable(self, \"Table\",\n table_columns=[Column(name=\"col1\", data_type=\"varchar(4)\", sort_key=True), Column(name=\"col2\", data_type=\"float\", sort_key=True)\n ],\n cluster=cluster,\n database_name=\"databaseName\",\n sort_style=TableSortStyle.COMPOUND\n)\n```\n\n### Granting Privileges\n\nYou can give a user privileges to perform certain actions on a table by using the\n`Table.grant()` method.\n\n```python\nuser = User(self, \"User\",\n cluster=cluster,\n database_name=\"databaseName\"\n)\ntable = Table(self, \"Table\",\n table_columns=[Column(name=\"col1\", data_type=\"varchar(4)\"), Column(name=\"col2\", data_type=\"float\")],\n cluster=cluster,\n database_name=\"databaseName\"\n)\n\ntable.grant(user, TableAction.DROP, TableAction.SELECT)\n```\n\nTake care when managing privileges via the CDK, as attempting to manage a user's\nprivileges on the same table in multiple CDK applications could lead to accidentally\noverriding these permissions. Consider the following two CDK applications which both refer\nto the same user and table. In application 1, the resources are created and the user is\ngiven `INSERT` permissions on the table:\n\n```python\ndatabase_name = \"databaseName\"\nusername = \"myuser\"\ntable_name = \"mytable\"\n\nuser = User(self, \"User\",\n username=username,\n cluster=cluster,\n database_name=database_name\n)\ntable = Table(self, \"Table\",\n table_columns=[Column(name=\"col1\", data_type=\"varchar(4)\"), Column(name=\"col2\", data_type=\"float\")],\n cluster=cluster,\n database_name=database_name\n)\ntable.grant(user, TableAction.INSERT)\n```\n\nIn application 2, the resources are imported and the user is given `INSERT` permissions on\nthe table:\n\n```python\ndatabase_name = \"databaseName\"\nusername = \"myuser\"\ntable_name = \"mytable\"\n\nuser = User.from_user_attributes(self, \"User\",\n username=username,\n password=SecretValue.unsafe_plain_text(\"NOT_FOR_PRODUCTION\"),\n cluster=cluster,\n database_name=database_name\n)\ntable = Table.from_table_attributes(self, \"Table\",\n table_name=table_name,\n table_columns=[Column(name=\"col1\", data_type=\"varchar(4)\"), Column(name=\"col2\", data_type=\"float\")],\n cluster=cluster,\n database_name=\"databaseName\"\n)\ntable.grant(user, TableAction.INSERT)\n```\n\nBoth applications attempt to grant the user the appropriate privilege on the table by\nsubmitting a `GRANT USER` SQL query to the Redshift cluster. Note that the latter of these\ntwo calls will have no effect since the user has already been granted the privilege.\n\nNow, if application 1 were to remove the call to `grant`, a `REVOKE USER` SQL query is\nsubmitted to the Redshift cluster. In general, application 1 does not know that\napplication 2 has also granted this permission and thus cannot decide not to issue the\nrevocation. This leads to the undesirable state where application 2 still contains the\ncall to `grant` but the user does not have the specified permission.\n\nNote that this does not occur when duplicate privileges are granted within the same\napplication, as such privileges are de-duplicated before any SQL query is submitted.\n\n## Rotating credentials\n\nWhen the master password is generated and stored in AWS Secrets Manager, it can be rotated automatically:\n\n```python\ncluster.add_rotation_single_user()\n```\n\nThe multi user rotation scheme is also available:\n\n```python\nuser = User(self, \"User\",\n cluster=cluster,\n database_name=\"databaseName\"\n)\ncluster.add_rotation_multi_user(\"MultiUserRotation\",\n secret=user.secret\n)\n```\n",
"bugtrack_url": null,
"license": "Apache-2.0",
"summary": "The CDK Construct Library for AWS::Redshift",
"version": "1.204.0",
"project_urls": {
"Homepage": "https://github.com/aws/aws-cdk",
"Source": "https://github.com/aws/aws-cdk.git"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "504192939f87e08e57a139d636385ae4d5a60195b3a0c3ed5d5c32c75ec3ec59",
"md5": "95f6838b639288a6a2524b3294890e4b",
"sha256": "beffda13cc8a95b69836a909762d52a1afba26c90c1bfe326555a175ed31856d"
},
"downloads": -1,
"filename": "aws_cdk.aws_redshift-1.204.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "95f6838b639288a6a2524b3294890e4b",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "~=3.7",
"size": 309214,
"upload_time": "2023-06-19T21:00:29",
"upload_time_iso_8601": "2023-06-19T21:00:29.323785Z",
"url": "https://files.pythonhosted.org/packages/50/41/92939f87e08e57a139d636385ae4d5a60195b3a0c3ed5d5c32c75ec3ec59/aws_cdk.aws_redshift-1.204.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "3d61e1570a6e3ee99255154740f97a6c55fd7215168050cebcf8d0fce3223cea",
"md5": "f2a304da148435066ce4c866254072c3",
"sha256": "dfcc3da04fd54191f1c10b5bb791e259401747e86ef235876f35c95fac0ac7db"
},
"downloads": -1,
"filename": "aws-cdk.aws-redshift-1.204.0.tar.gz",
"has_sig": false,
"md5_digest": "f2a304da148435066ce4c866254072c3",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "~=3.7",
"size": 309182,
"upload_time": "2023-06-19T21:06:49",
"upload_time_iso_8601": "2023-06-19T21:06:49.431465Z",
"url": "https://files.pythonhosted.org/packages/3d/61/e1570a6e3ee99255154740f97a6c55fd7215168050cebcf8d0fce3223cea/aws-cdk.aws-redshift-1.204.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-06-19 21:06:49",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "aws",
"github_project": "aws-cdk",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "aws-cdk.aws-redshift"
}
JSON
