> ## Documentation Index > Fetch the complete documentation index at: https://docs.cube.dev/llms.txt > Use this file to discover all available pages before exploring further. # AWS Redshift > Authenticate Cube to Amazon Redshift with database passwords or IAM roles and ensure network reachability from your deployment. ## Prerequisites * The [hostname][aws-redshift-docs-connection-string] for the [AWS Redshift][aws-redshift] cluster * The [username/password][aws-redshift-docs-users] for the [AWS Redshift][aws-redshift] cluster **or** IAM credentials with `redshift:GetClusterCredentialsWithIAM` and `redshift:DescribeClusters` permissions * The name of the database to use within the [AWS Redshift][aws-redshift] cluster If the cluster is configured within a [VPC][aws-vpc], then Cube **must** have a network route to the cluster. ## Setup ### Manual Add the following to a `.env` file in your Cube project: #### Password Authentication ```dotenv theme={"dark"} CUBEJS_DB_TYPE=redshift CUBEJS_DB_HOST=my-redshift-cluster.cfbs3dkw1io8.eu-west-1.redshift.amazonaws.com CUBEJS_DB_NAME=my_redshift_database CUBEJS_DB_USER= CUBEJS_DB_PASS= ``` #### IAM Authentication For enhanced security, you can configure Cube to use IAM authentication instead of username and password. When running in AWS (EC2, ECS, EKS with IRSA), the driver can use the instance's IAM role to obtain temporary database credentials automatically. Omit [`CUBEJS_DB_USER`](/reference/configuration/environment-variables#cubejs_db_user) and [`CUBEJS_DB_PASS`](/reference/configuration/environment-variables#cubejs_db_pass) to enable IAM authentication: ```dotenv theme={"dark"} CUBEJS_DB_TYPE=redshift CUBEJS_DB_HOST=my-redshift-cluster.xxx.eu-west-1.redshift.amazonaws.com CUBEJS_DB_NAME=my_redshift_database CUBEJS_DB_SSL=true CUBEJS_DB_REDSHIFT_AWS_REGION=eu-west-1 CUBEJS_DB_REDSHIFT_CLUSTER_IDENTIFIER=my-redshift-cluster ``` The driver uses the AWS SDK's default credential chain (IAM instance profile, EKS IRSA, etc.) to obtain temporary database credentials via the `redshift:GetClusterCredentialsWithIAM` API. #### IAM Role Assumption For cross-account access or enhanced security, you can configure Cube to assume an IAM role: ```dotenv theme={"dark"} CUBEJS_DB_REDSHIFT_AWS_REGION=eu-west-1 CUBEJS_DB_REDSHIFT_CLUSTER_IDENTIFIER=my-redshift-cluster CUBEJS_DB_REDSHIFT_ASSUME_ROLE_ARN=arn:aws:iam::123456789012:role/RedshiftAccessRole CUBEJS_DB_REDSHIFT_ASSUME_ROLE_EXTERNAL_ID=unique-external-id ``` ### Cube Cloud In some cases you'll need to allow connections from your Cube Cloud deployment IP address to your database. You can copy the IP address from either the Database Setup step in deployment creation, or from **Settings → Configuration** in your deployment. The following fields are required when creating an AWS Redshift connection: Cube Cloud AWS Redshift Configuration Screen #### OIDC workload identity Instead of a database password, Cube Cloud deployments can authenticate to Redshift with [OIDC workload identity][ref-oidc-aws-redshift]: an IAM role in your account trusts Cube's OIDC issuer, and the driver uses it to obtain temporary database credentials via [IAM authentication](#iam-authentication). Set `AWS_ROLE_ARN` alongside the IAM authentication variables and omit `CUBEJS_DB_USER` / `CUBEJS_DB_PASS`: ```dotenv theme={"dark"} CUBEJS_DB_TYPE=redshift AWS_ROLE_ARN=arn:aws:iam::123456789012:role/cube-deployment-acme CUBEJS_DB_HOST=my-redshift-cluster.xxx.eu-west-1.redshift.amazonaws.com CUBEJS_DB_NAME=my_redshift_database CUBEJS_DB_SSL=true CUBEJS_DB_REDSHIFT_AWS_REGION=eu-west-1 CUBEJS_DB_REDSHIFT_CLUSTER_IDENTIFIER=my-redshift-cluster ``` See the [AWS OIDC guide][ref-oidc-aws-redshift] for the IAM role, trust policy, and permissions setup. Cube Cloud also supports connecting to data sources within private VPCs if [single-tenant infrastructure][ref-dedicated-infra] is used. Check out the [VPC connectivity guide][ref-cloud-conf-vpc] for details. [ref-dedicated-infra]: /docs/deployment/cloud/infrastructure#dedicated-infrastructure [ref-cloud-conf-vpc]: /docs/deployment/cloud/vpc ## Environment Variables | Environment Variable | Description | Possible Values | Required | | ----------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- | -------------------------------------- | :-----------: | | [`CUBEJS_DB_HOST`](/reference/configuration/environment-variables#cubejs_db_host) | The host URL for a database | A valid database host URL | ✅ | | [`CUBEJS_DB_PORT`](/reference/configuration/environment-variables#cubejs_db_port) | The port for the database connection | A valid port number | ❌ | | [`CUBEJS_DB_NAME`](/reference/configuration/environment-variables#cubejs_db_name) | The name of the database to connect to | A valid database name | ✅ | | [`CUBEJS_DB_USER`](/reference/configuration/environment-variables#cubejs_db_user) | The username used to connect to the database | A valid database username | ✅1 | | [`CUBEJS_DB_PASS`](/reference/configuration/environment-variables#cubejs_db_pass) | The password used to connect to the database | A valid database password | ✅1 | | [`CUBEJS_DB_SSL`](/reference/configuration/environment-variables#cubejs_db_ssl) | If `true`, enables SSL encryption for database connections from Cube | `true`, `false` | ❌ | | [`CUBEJS_DB_MAX_POOL`](/reference/configuration/environment-variables#cubejs_db_max_pool) | The maximum number of concurrent database connections to pool. Default is `16` | A valid number | ❌ | | [`CUBEJS_DB_REDSHIFT_CLUSTER_IDENTIFIER`](/reference/configuration/environment-variables#cubejs_db_redshift_cluster_identifier) | The Redshift cluster identifier. Required for IAM authentication | A valid cluster identifier | ❌ | | [`CUBEJS_DB_REDSHIFT_AWS_REGION`](/reference/configuration/environment-variables#cubejs_db_redshift_aws_region) | The AWS region of the Redshift cluster. Required for IAM authentication | [A valid AWS region][aws-docs-regions] | ❌ | | [`CUBEJS_DB_REDSHIFT_ASSUME_ROLE_ARN`](/reference/configuration/environment-variables#cubejs_db_redshift_assume_role_arn) | The ARN of the IAM role to assume for cross-account access | A valid IAM role ARN | ❌ | | [`CUBEJS_DB_REDSHIFT_ASSUME_ROLE_EXTERNAL_ID`](/reference/configuration/environment-variables#cubejs_db_redshift_assume_role_external_id) | The external ID for the assumed role's trust policy | A string | ❌ | | [`CUBEJS_DB_EXPORT_BUCKET_REDSHIFT_ARN`](/reference/configuration/environment-variables#cubejs_db_export_bucket_redshift_arn) | | | ❌ | | [`CUBEJS_CONCURRENCY`](/reference/configuration/environment-variables#cubejs_concurrency) | The number of [concurrent queries][ref-data-source-concurrency] to the data source | A valid number | ❌ | 1 Required when using password-based authentication. When using IAM authentication, omit these and set [`CUBEJS_DB_REDSHIFT_CLUSTER_IDENTIFIER`](/reference/configuration/environment-variables#cubejs_db_redshift_cluster_identifier) and [`CUBEJS_DB_REDSHIFT_AWS_REGION`](/reference/configuration/environment-variables#cubejs_db_redshift_aws_region) instead. The driver uses the AWS SDK's default credential chain (IAM instance profile, EKS IRSA, or [OIDC workload identity][ref-oidc-aws-redshift] in Cube Cloud) to obtain temporary database credentials. [ref-data-source-concurrency]: /admin/connect-to-data/concurrency#data-source-concurrency ## Pre-Aggregation Feature Support ### count\_distinct\_approx Measures of type [`count_distinct_approx`][ref-schema-ref-types-formats-countdistinctapprox] can not be used in pre-aggregations when using AWS Redshift as a source database. ## Pre-Aggregation Build Strategies To learn more about pre-aggregation build strategies, [head here][ref-caching-using-preaggs-build-strats]. | Feature | Works with read-only mode? | Is default? | | ------------- | :------------------------: | :---------: | | Batching | ❌ | ✅ | | Export Bucket | ❌ | ❌ | By default, AWS Redshift uses [batching][self-preaggs-batching] to build pre-aggregations. ### Batching Cube requires the Redshift user to have ownership of a schema in Redshift to support pre-aggregations. By default, the schema name is `prod_pre_aggregations`. It can be set using the [`pre_aggregations_schema` configration option][ref-conf-preaggs-schema]. No extra configuration is required to configure batching for AWS Redshift. ### Export bucket AWS Redshift **only** supports using AWS S3 for export buckets. #### AWS S3 For [improved pre-aggregation performance with large datasets][ref-caching-large-preaggs], enable export bucket functionality by configuring Cube with the following environment variables: Ensure the AWS credentials are correctly configured in IAM to allow reads and writes to the export bucket in S3. ```dotenv theme={"dark"} CUBEJS_DB_EXPORT_BUCKET_TYPE=s3 CUBEJS_DB_EXPORT_BUCKET=my.bucket.on.s3 CUBEJS_DB_EXPORT_BUCKET_AWS_KEY= CUBEJS_DB_EXPORT_BUCKET_AWS_SECRET= CUBEJS_DB_EXPORT_BUCKET_AWS_REGION= ``` ## SSL To enable SSL-encrypted connections between Cube and AWS Redshift, set the [`CUBEJS_DB_SSL`](/reference/configuration/environment-variables#cubejs_db_ssl) environment variable to `true`. For more information on how to configure custom certificates, please check out [Enable SSL Connections to the Database][ref-recipe-enable-ssl]. [aws-redshift-docs-connection-string]: https://docs.aws.amazon.com/redshift/latest/mgmt/configuring-connections.html#connecting-drivers [aws-redshift-docs-users]: https://docs.aws.amazon.com/redshift/latest/dg/r_Users.html [aws-redshift]: https://aws.amazon.com/redshift/ [aws-vpc]: https://aws.amazon.com/vpc/ [aws-docs-regions]: https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/using-regions-availability-zones.html#concepts-available-regions [ref-caching-large-preaggs]: /docs/pre-aggregations/using-pre-aggregations#export-bucket [ref-caching-using-preaggs-build-strats]: /docs/pre-aggregations/using-pre-aggregations#pre-aggregation-build-strategies [ref-oidc-aws-redshift]: /admin/deployment/oidc/aws#redshift [ref-recipe-enable-ssl]: /recipes/configuration/using-ssl-connections-to-data-source [ref-schema-ref-types-formats-countdistinctapprox]: /reference/data-modeling/measures#type [self-preaggs-batching]: #batching [ref-conf-preaggs-schema]: /reference/configuration/config#pre_aggregations_schema