Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China (PDF).

Connecting to Amazon Redshift Serverless

Once you've set up your Amazon Redshift Serverless instance, you can connect to it in a variety of methods, outlined below. If you have multiple teams or projects and want to manage costs separately, you can use separate Amazon Web Services accounts.

For a list of Amazon Web Services Regions where the Amazon Redshift Serverless is available, see the endpoints listed for Redshift Serverless API in the Amazon Web Services General Reference.

Amazon Redshift Serverless connects to the serverless environment in your Amazon Web Services account in the current Amazon Web Services Region. Amazon Redshift Serverless runs in a VPC within the port ranges 5431-5455 and 8191-8215. The default is 5439. Currently, you can only change ports with the API operation UpdateWorkgroup and the Amazon CLI operation update-workgroup.

Connecting to Amazon Redshift Serverless

You can connect to a database (named dev) in Amazon Redshift Serverless with the following syntax.

workgroup-name.account-number.aws-region.redshift-serverless.amazonaws.com:port/dev

For example, the following connection string specifies Region us-east-1.

default.123456789012.us-east-1.redshift-serverless.amazonaws.com:5439/dev

Connecting to Amazon Redshift Serverless through JDBC drivers

You can use one of the following methods to connect to Amazon Redshift Serverless with your preferred SQL client using the Amazon Redshift-provided JDBC driver version 2 driver.

To connect with sign-in credentials for database authentication using JDBC driver version 2.1.x or later, use the following syntax. The port number is optional; if not included, Amazon Redshift Serverless defaults to port number 5439. You can change to another port from the port range of 5431-5455 or 8191-8215. To change the default port for a serverless endpoint, use the Amazon CLI and Amazon Redshift API.

jdbc:redshift://workgroup-name.account-number.aws-region.redshift-serverless.amazonaws.com:5439/dev

For example, the following connection string specifies the workgroup default, the account ID 123456789012, and the Region us-east-2.

jdbc:redshift://default.123456789012.us-east-2.redshift-serverless.amazonaws.com:5439/dev

To connect with IAM using JDBC driver version 2.1.x or later, use the following syntax. The port number is optional; if not included, Amazon Redshift Serverless defaults to port number 5439. You can change to another port from the port range of 5431-5455 or 8191-8215. To change the default port for a serverless endpoint, use the Amazon CLI and Amazon Redshift API.

jdbc:redshift:iam://workgroup-name.account-number.aws-region.redshift-serverless.amazonaws.com:5439/dev

For example, the following connection string specifies the workgroup default, the account ID 123456789012, and the Region us-east-2.

jdbc:redshift:iam://default.123456789012.us-east-2.redshift-serverless.amazonaws.com:5439/dev

For ODBC, use the following syntax.

Driver={Amazon Redshift (x64)}; Server=workgroup-name.account-number.aws-region.redshift-serverless.amazonaws.com; Database=dev

If you are using a JDBC driver version prior to 2.1.0.9 and connecting with IAM, you will need to use the following syntax.

jdbc:redshift:iam://redshift-serverless-<name>:aws-region/database-name

For example, the following connection string specifies the workgroup default and the Amazon Web Services Region us-east-1.

jdbc:redshift:iam://redshift-serverless-default:us-east-1/dev

For more information about drivers, see Configuring connections in Amazon Redshift.

Finding your JDBC and ODBC connection string

To connect to your workgroup with your SQL client tool, you must have the JDBC or ODBC connection string. You can find the connection string in the Amazon Redshift Serverless console, on a workgroup's details page.

Connecting to Amazon Redshift Serverless with the Data API

You can also use the Amazon Redshift Data API to connect to Amazon Redshift Serverless. Use the workgroup-name parameter instead of the cluster-identifier parameter in your Amazon CLI calls.

For more information about the Data API, see Using the Amazon Redshift Data API. For example code calling the Data API in Python and other examples, see Getting Started with Redshift Data API and look in the quick-start and use-cases folders in GitHub.

Connecting with SSL to Amazon Redshift Serverless

Configuring a secure connection to Amazon Redshift Serverless

To support SSL connections, Redshift Serverless creates and installs an Amazon Certificate Manager (ACM) issued SSL certificate for each workgroup. ACM certificates are publicly trusted by most operating systems, web browsers, and clients. You might need to download a certificate bundle if your SQL clients or applications connect to Redshift Serverless using SSL with the sslmode connection option set to require, verify-ca, or verify-full. If your client needs a certificate, Redshift Serverless provides a bundle certificate as follows:

By default, workgroup databases accept a connection whether it uses SSL or not.

To create a new workgroup that only accepts SSL connections, use the create-workgroup command and set the require_ssl parameter to true. To use the following example, replace yourNamespaceName with the name of your namespace and replace yourWorkgroupName with the name of your workgroup.

aws redshift-serverless create-workgroup \
--namespace-name yourNamespaceName \
--workgroup-name yourWorkgroupName \
--config-parameters parameterKey=require_ssl,parameterValue=true

To update an existing workgroup to only accept SSL connections, use the update-workgroup command and set the require_ssl parameter to true. Note that Redshift Serverless will restart your workgroup when you update the require_ssl parameter. To use the following example, replace yourWorkgroupName with the name of your workgroup.

aws redshift-serverless update-workgroup \
--workgroup-name yourWorkgroupName \
--config-parameters parameterKey=require_ssl,parameterValue=true

Amazon Redshift supports the Elliptic Curve Diffie—Hellman Ephemeral (ECDHE) key agreement protocol. With ECDHE, the client and server each have an elliptic curve public-private key pair that is used to establish a shared secret over an insecure channel. You don't need to configure anything in Amazon Redshift to enable ECDHE. If you connect from a SQL client tool that uses ECDHE to encrypt communication between the client and server, Amazon Redshift uses the provided cipher list to make the appropriate connection. For more information, see Elliptic curve diffie—hellman on Wikipedia and Ciphers on the OpenSSL website.

Configuring a FIPS-compliant SSL connection to Amazon Redshift Serverless

To create a new workgroup that uses a FIPS-compliant SSL connection, use the create-workgroup command and set the use_fips_ssl and require_ssl parameters to true. To use the following example, replace yourNamespaceName with the name of your namespace and replace yourWorkgroupName with the name of your workgroup.

aws redshift-serverless create-workgroup \
--namespace-name yourNamespaceName \
--workgroup-name yourWorkgroupName \
--config-parameters '[{"parameterKey": "require_ssl", "parameterValue": "true"}, {"parameterKey": "use_fips_ssl", "parameterValue": "true"}]'

To update an existing workgroup to use a FIPS-compliant SSL connection, use the update-workgroup command and set the use_fips_ssl and require_ssl parameters to true. Note that Redshift Serverless will restart your workgroup when you update the use_fips_ssl parameter. To use the following example, replace yourWorkgroupName with the name of your workgroup.

aws redshift-serverless update-workgroup \
--workgroup-name yourWorkgroupName \
--config-parameters '[{"parameterKey": "require_ssl", "parameterValue": "true"}, {"parameterKey": "use_fips_ssl", "parameterValue": "true"}]'

For more information about configuring Redshift Serverless to use FIPS-compliant connections, see use_fips_ssl in the Amazon Redshift Database Developer Guide.

Connecting to Amazon Redshift Serverless from an Amazon Redshift managed VPC endpoint

Connecting to Amazon Redshift Serverless from other VPC endpoints

For information about setting up or configuring a managed-VPC endpoint for an Amazon Redshift Serverless workgroup, see Working with Redshift-managed VPC endpoints.

Connecting to Amazon Redshift Serverless from an interface VPC endpoint (Amazon PrivateLink)

For information about connecting to Amazon Redshift Serverless from an interface VPC endpoint (Amazon PrivateLink), see Interface VPC endpoints.

Connecting to Amazon Redshift Serverless from a Redshift VPC endpoint in another account

Connecting to Amazon Redshift Serverless from a cross VPC endpoint

Amazon Redshift Serverless is provisioned in a VPC. You can grant access to a VPC in another account to access Amazon Redshift Serverless in your account. This is similar to a connection from a managed VPC endpoint, but in this case the connection originates, for example, from a database client in another account. There are a few operations that you can perform:

The main benefit of cross-account access is allowing easier database collaboration. Users don't have to be provisioned in the account that contains the database to access it, which reduces configuration steps and saves time.

Permissions required to grant access to a VPC in another account

To grant access or change the access allowed, the grantor requires an assigned permissions policy with the following permissions:

You might need other permissions that are specified in the Amazon managed policy AmazonRedshiftFullAccess. For more information, see Granting permissions to Amazon Redshift Serverless.

The grantee requires an assigned permissions policy with the following permissions:

As a best practice, we recommend attaching permissions policies to an IAM role and then assigning it to users and groups as needed. For more information, see Identity and access management in Amazon Redshift.

This is a sample resource policy used to configure cross-VPC access:

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "CrossAccountCrossVPCAccess",
            "Effect": "Allow",
            "Principal": {
                "AWS": [
                   "123456789012",
                   "234567890123"
                ]
             },
            "Action": [
                "redshift-serverless:CreateEndpointAccess",
                "redshift-serverless:UpdateEndpointAccess",
                "redshift-serverless:DeleteEndpointAccess",
                "redshift-serverless:GetEndpointAccess"
            ],
            "Condition": {
                "ArnLike": {
                    "redshift-serverless:AuthorizedVpc": [
                        "arn:aws:ec2:us-east-1:123456789012:vpc/*",
                        "arn:aws:ec2:us-east-1:234567890123:vpc/vpc-456",
                        "arn:aws:ec2:us-east-1:234567890123:vpc/vpc-987"
                        ]
                    }
                }
            }
        }
    ]
}

The procedures that follow in this section assume that the user performing them has the appropriate assigned permissions, for example, by means of an assigned IAM role that has the permissions listed. The procedures also assume that the workgroup has an IAM role attached with appropriate resource permissions.

Granting VPC access to other accounts, using the console

This procedure shows the steps for configuring database access when you're the database owner, and you want to grant access to it.

When you save the changes, the account appears in the list of Granted accounts. The entry shows the Account ID and the list of VPCs granted access.

The database owner can also revoke access to an account. The owner can revoke access at any time.

After access is granted, a database administrator for the grantee can check the console to determine if they have access.

Granting access to other accounts, using CLI commands

The account granting access must first grant access to another account to connect by using put-resource-policy. The database owner can call put-resource-policy to authorize another account to create connections to the workgroup. The grantee account can then use create-endpoint-authorization to create connections to the workgroup through their allowed VPCs.

The following shows the properties for put-resource-policy, which you can call to allow access to a specific account and VPC.

aws redshift-serverless put-resource-policy
--resource-arn <value> 
--policy <value>

After calling the command, you can call get-resource-policy, specifying the resource-arn to see which accounts and VPCs are allowed to access the resource.

The following call can be made by the grantee. It shows information about the granted access. Specifically, it returns a list that contains the VPCs granted access.

aws redshift-serverless list-workgroups
--owner-account <value>

The purpose of this is for the grantee to get information from the granting account about endpoint authorizations. The owner-account is the sharing account. When you run this, it returns the CrossAccountVpcs for each workgroup, which is a list of allowed VPCs. For reference, the following shows all of the properties available for a workgroup:

Output: workgroup (Object)
workgroupId String,
workgroupArn String,
workgroupName String,
status: String,
namespaceName: String,
baseCapacity: Integer, (Not-applicable)
enhancedVpcRouting: Boolean,
configParameters: List,
securityGroupIds: List,
subnetIds: List,
endpoint: String,
publiclyAccessible: Boolean,
creationDate: Timestamp,
port: Integer,
CrossAccountVpcs: List

Additional resources

Instructions for setting your network traffic settings are available in Public accessibility with default or custom security group configuration. This includes a use case where the cluster is publicly accessible.

Instructions for setting your network traffic settings are available in Private accessibility with default or custom security group configuration. This includes a use case where the cluster isn't available to the internet.

For more information about secure connections to Amazon Redshift Serverless, including granting permissions, authorizing access to additional services, and creating IAM roles, see Identity and access management in Amazon Redshift Serverless.