Using a Connection String

For some applications, you might need to use a connection string to connect to your data source. For detailed information about how to use a connection string in an ODBC application, refer to the documentation for the application that you are using.

The connection strings in the following sections are examples showing the minimum set of connection attributes that you must specify to successfully connect to the data source. Depending on the configuration of the data source and the type of connection you are working with, you might need to specify additional connection attributes. For detailed information about all the attributes that you can use in the connection string, see Driver Configuration Options on page 1.

DSN Connection String Example

The following is an example of a connection string for a connection that uses a DSN:

DSN=[DataSourceName]

[DataSourceName] is the DSN that you are using for the connection.

You can set additional configuration options by appending key-value pairs to the connection string. Configuration options that are passed in using a connection string take precedence over configuration options that are set in the DSN.

DSN-less Connection String Examples

Some applications provide support for connecting to a data source using a connector without a DSN. To connect to a data source without using a DSN, use a connection string instead.

Important:

When you connect to the data store using a DSN-less connection string, the connector does not encrypt your credentials.

The placeholders in the examples are defined as follows, in alphabetical order:

[AzureClientID] is the client ID associated with your Redshift application in Azure AD.
[AzureClientSecret] is the secret key associated with your Redshift application in Azure AD.
[DatabaseName] is the database that you want to access.
[IAMRole] is the name or ID of the IAM role that you want to assume.
[IDP_PortNumber] is the number of the TCP port used by the server that is hosting the the identity provider service (AD FS, Ping, or Okta).
[IDP_Server] is the IP address or host name of the server that is hosting the the identity provider service (AD FS, Ping, or Okta).
[IDP_Tenant] is the Azure AD tenant ID associated with your Redshift application.
[OktaAppID] is the app ID assocaited with your Okta application.
[PortNumber] is the number of the TCP port that the Redshift server uses to listen for client connections.
[PPort] is the number of the TCP port that the proxy server uses to listen for client connection.
[PServer] is the IP address or host name of the proxy server to which you are connecting.
[Server] is the endpoint of the Redshift server to which you are connecting.
[UserID] is the user ID that you want to associate with your Redshift account.
[WebIdentityToken] is the token that is provided by the identity provider.
[YourAccessKey] is your IAM access key.
[YourSecretKey] is your IAM secret key.
[YourPassword] is the password corresponding to your user name.
[YourProfileName] is the name of the IAM profile that contains your Redshift credentials.
[YourUserName] is the user name that you use to authenticate your connection to Redshift. Depending on the authentication method being used, this may be the user name associated with your Redshift, AD FS, Ping, or Okta account.

Connecting to a Redshift Server Directly

The following is the format of a DSN-less connection string for a basic connection to a Redshift server:

Driver=Simba Amazon Redshift ODBC Driver;Server=[Server];
Port=[PortNumber];Database=[DatabaseName];
UID=[YourUserName];PWD=[YourPassword];

For example:

Driver=Simba Amazon Redshift ODBC Driver;
Server=testserver.abcabcabcabc.us-west-2.redshift.amazonaws.com;Port=5439;Database=TestDB;
UID=simba;PWD=simba;

Connecting to a Redshift Server Through a Proxy Server

The following is the format of a DSN-less connection string for connecting to a Redshift server through a proxy server:

Driver=Simba Amazon Redshift ODBC Driver;Server=[Server];
Port=[PortNumber];Database=[DatabaseName];
UID=[YourUserName];PWD=[YourPassword];ProxyHost=[PServer];
ProxyPort=[PPort];

For example:

Driver=Simba Amazon Redshift ODBC Driver;
Server=testserver.abcabcabcabc.us-west-2.redshift.amazonaws.com;Port=5439;Database=TestDB;
UID=jsmith;PWD=simba12345;ProxyHost=192.168.222.160;
ProxyPort=8000;

Connecting to a Redshift Server using an IAM Profile

You can authenticate the connection using IAM credentials stored in a chained roles profile or the Amazon EC2 instance profile. The following is the format of a DSN-less connection string for connecting to a Redshift server using a chained roles profile:

Driver=Simba Amazon Redshift ODBC Driver;Server=[Server];
Port=[PortNumber];Database=[DatabaseName];IAM=1;
Profile=[YourProfileName];

For example:

Driver=Simba Amazon Redshift ODBC Driver;
Server=testserver.abcabcabcabc.us-west-2.redshift.amazonaws.com;Port=5439;Database=TestDB;IAM=1;
Profile=simba_admin;

As another example, using the Amazon EC2 instance profile instead:

Driver=Simba Amazon Redshift ODBC Driver;
Server=testserver.abcabcabcabc.us-west-2.redshift.amazonaws.com;Port=5439;Database=TestDB;IAM=1;
InstanceProfile=1;

Important:

This example assumes that the profile contains a user name, password, and user ID. If this information is missing from the profile, then you must provide it by specifying the UID, PWD, and DbUser properties (respectively) in the connection string.
If the user ID specified in your profile or connection string does not already exist, then you must configure the connector to create it. To do this, set the AutoCreate property to 1, and set the DbGroups property to the database security group or groups that you want the ID to be associated with.
When you use this authentication method, the Server property is optional. However, if you omit the Server property, then you must set the ClusterID property to the name of your Redshift cluster and set the Region property to the AWS region where the cluster is located.

Connecting to a Redshift Server using IAM User Credentials

The following is the format of a DSN-less connection string for connecting to a Redshift server using an access key and secret key:

Driver=Simba Amazon Redshift ODBC Driver;Server=[Server];
Port=[PortNumber];Database=[DatabaseName];IAM=1;
DbUser=[YourUserID];AccessKeyId=[YourAccessKey];
SecretAccessKey=[YourSecretKey];

For example:

Driver=Simba Amazon Redshift ODBC Driver;Server=testserver.abcabcabcabc.us-west-2.redshift.amazonaws.com;Port=5439;Database=TestDB;IAM=1;
DbUser=Simba;AccessKeyId=AKIAIOSFODNN7EXAMPLE;
SecretAccessKey=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY;

Important:

If you are using temporary credentials associated with an IAM role, then you must also set the SessionToken property to your temporary session token.
If the specified user ID does not already exist, then you must configure the connector to create it. To do this, set the AutoCreate property to 1, and set the DbGroups property to the database security group or groups that you want the ID to be associated with.
When you use this authentication method, the Server property is optional. However, if you omit the Server property, then you must set the ClusterID property to the name of your Redshift cluster and set the Region property to the AWS region where the cluster is located.

Connecting to a Redshift Server using Active Directory Federation Services (AD FS)

The following is the format of a DSN-less connection string for connecting to a Redshift server using AD FS:

Driver=Simba Amazon Redshift ODBC Driver;Server=[Server];
Port=[PortNumber];Database=[DatabaseName];IAM=1;
plugin_name=adfs;UID=[YourUserName];PWD=[YourPassword];DbUser=[UserID];IdP_Host=[IDP_Server];
IdP_Port=[IDP_PortNumber];Preferred_Role=[IAMRole];

For example:

Driver=Simba Amazon Redshift ODBC Driver;
Server=testserver.abcabcabcabc.us-west-2.redshift.amazonaws.com;Port=5439;Database=TestDB;IAM=1;
plugin_name=adfs;UID=jsmith;PWD=simba12345;DbUser=Simba;IdP_Host=adfs.simba.com;
IdP_Port=1234;Preferred_Role=dbAdmin;

Important:

If the specified user ID does not already exist, then you must configure the connector to create it. To do this, set the AutoCreate property to 1, and set the DbGroups property to the database security group or groups that you want the ID to be associated with.
When you use this authentication method, the Server property is optional. However, if you omit the Server property, then you must set the ClusterID property to the name of your Redshift cluster and set the Region property to the AWS region where the cluster is located.

Connecting to a Redshift Server using Azure AD Portal

The following is the format of a DSN-less connection string for connecting to a Redshift server using Azure AD Portal:

Driver=Simba Amazon Redshift ODBC Driver;Server=[Server];
Port=[PortNumber];Database=[DatabaseName];IAM=1;
plugin_name=AzureAD;UID=[YourUserName];PWD=[YourPassword];DbUser=[UserID];IdP_Tenant=[IDP_Tenant];Client_ID=[AzureClientID];Client_Secret=[AzureClientSecret];

For example:

Driver=Simba Amazon Redshift ODBC Driver;
Server=testserver.abcabcabcabc.us-west-2.redshift.amazonaws.com;Port=5439;Database=TestDB;IAM=1;
plugin_name=AzureAD;UID=jsmith;PWD=simba12345;DbUser=Simba;IdP_Tenant=e12x4am2-7571-23pl-ete9-4na018221n09;Client_ID=cl007ent-66i6-4de9-1x2a-mp02le2021ss;Client_Secret=example.E1-wC7Hiy2AwE2XAM:ple;

Important:

If the specified user ID does not already exist, then you must configure the connector to create it. To do this, set the AutoCreate property to 1, and set the DbGroups property to the database security group or groups that you want the ID to be associated with.
When you use this authentication method, the Server property is optional. However, if you omit the Server property, then you must set the ClusterID property to the name of your Redshift cluster and set the Region property to the AWS region where the cluster is located.

Connecting to a Redshift Server using a JSON Web Token (JWT)

The following is the format of a DSN-less connection string for connecting to a Redshift server using a JWT:

Driver=Simba Amazon Redshift ODBC Driver;Server=[Server];
Port=[PortNumber];Database=[DatabaseName];IAM=1;plugin_name=jwt;web_identity_token=[WebIdentityToken];

For example:

Driver=Simba Amazon Redshift ODBC Driver;Server=testserver.abcabcabcabc.us-west2.redshift.amazonaws.com;Port=5439;Database=TestDB;IAM=1;plugin_name=jwt;web_identity_token=eyJhbGciOiJSUzI1NiIsImt;

Connecting to a Redshift Server using the Okta Service

The following is the format of a DSN-less connection string for connecting to a Redshift server using Okta:

Driver=Simba Amazon Redshift ODBC Driver;Server=[Server];
Port=[PortNumber];Database=[DatabaseName];IAM=1;
plugin_name=okta;UID=[YourUserName];PWD=[YourPassword];

DbUser=[UserID];IdP_Host=[IDP_Server];

Preferred_Role=[IAMRole];App_ID=[OktaAppID];

For example:

Driver=Simba Amazon Redshift ODBC Driver;Server=testserver.abcabcabcabc.us-west-2.redshift.amazonaws.com;Port=5439;Database=TestDB;IAM=1;
plugin_name=okta;UID=jsmith;PWD=simba12345;DbUser=Simba;IdP_Host=okta.simba.com;Preferred_Role=dbAdmin;App_ID=mQkRaOqFRNy5hAc262lW;

Important:

If the specified user ID does not already exist, then you must configure the connector to create it. To do this, set the AutoCreate property to 1, and set the DbGroups property to the database security group or groups that you want the ID to be associated with.
When you use this authentication method, the Server property is optional. However, if you omit the Server property, then you must set the ClusterID property to the name of your Redshift cluster and set the Region property to the AWS region where the cluster is located.

Connecting to a Redshift Server using the PingFederate Service

The following is the format of a DSN-less connection string for connecting to a Redshift server using the PingFederate service:

Driver=Simba Amazon Redshift ODBC Driver;Server=[Server];

Port=[PortNumber];Database=[DatabaseName];IAM=1;

plugin_name=ping;UID=[YourUserName];PWD=[YourPassword];

DbUser=[UserID];IdP_Host=[IDP_Server];

IdP_Port=[IDP_PortNumber];Preferred_Role=[IAMRole];

For example:

Driver=Simba Amazon Redshift ODBC Driver;Server=testserver.abcabcabcabc.us-west-2.redshift.amazonaws.com;Port=5439;Database=TestDB;IAM=1;plugin_name=ping;UID=jsmith;PWD=simba12345;DbUser=Simba;IdP_Host=ping.simba.com;IdP_Port=1234;Preferred_Role=dbAdmin;

Important:

If the specified user ID does not already exist, then you must configure the connector to create it. To do this, set the AutoCreate property to 1, and set the DbGroups property to the database security group or groups that you want the ID to be associated with.
When you use this authentication method, the Server property is optional. However, if you omit the Server property, then you must set the ClusterID property to the name of your Redshift cluster and set the Region property to the AWS region where the cluster is located.

Connecting to a Redshift Server using an External Credentials Service

Aside from using AD FS, PingFederate, or Okta, you can also configure the Windows connector to authenticate connections using any SAML-based credential provider plugin of your choice. To do this, create a profile that specifies the plugin, and then configure the connector to use the profile. For an example of the DSN-less connection string format that you would use to configure this type of connection, see Connecting to a Redshift Server using an IAM Profile.