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.

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

  • [CertificateStorePath] is the complete path to the proxy's certificate.
  • [ClientID] is the the Client ID to use when authenticating the connection using the Azure AD service.
  • [ClientSecret] is the the Client Secret to use when authenticating the connection using the Azure AD service.
  • [CredProviderHost] is the host name of your credentials provider service.
  • [ProxyHost] is the IP address of the proxy server you are connecting through.
  • [Proxy Password] is the password associated with the application's proxy user ID.
  • [ProxyUserID] is the ID your application uses to log into the proxy server.
  • [Region] is the AWS region of the Athena instance that you want to connect to.
  • [RoleSessionName] is the name of the assumed role session.
  • [SAMLURL] is the URL for the resource on the identity provider's website when using the SAML services through a browser plugin.
  • [S3Path] is the path of the Amazon S3 location where you want to store query results, prefixed by s3://.
  • [VPC Endpoint] is the endpoint URL for your Virtual Private Cloud.
  • [YourAccessKey] is the access key provided by your AWS account.
  • [YourCredProviderPassword] is your password for your credentials provider service.
  • [YourCredProviderUserName] is your user name for your crendetials provider service.
  • [YourProfileName] is the name of the IAM profile to use for authentication.
  • [YourSecretKey] is the secret key provided by your AWS account.
  • [YourTenantID] is the the Azure AD-provided unique ID associated with your Athena application.
  • [WebIdentityToken] is the JSON web token generated after OAuth authentication from Azure Active directory.

Connecting to Athena Using the Default Credentials Provider Chain

The following is the format of a DSN-less connection string for connecting to Athena using the default credentials provider chain:

Driver=Simba Athena ODBC Driver;AwsRegion=[Region];S3OutputLocation=[S3Path];AuthenticationType=Default Credentials;

For example:

Driver=Simba Athena ODBC Driver;AwsRegion=us-east-2;S3OutputLocation=s3://query-results-bucket/test-folder-1;AuthenticationType=Default Credentials;

Connecting to Athena Using a VPC Endpoint

The following is the format of a DSN-less connection string for connecting to Athena using ta VPC Endpoint:

Driver=Simba Athena ODBC Driver;EndpointOverride=[VPC Endpoint];AwsRegion=[Region];S3OutputLocation=[S3Path];AuthenticationType=IAM Profile;AWSProfile=[YourProfileName];

For example:

Driver=Simba Athena ODBC Driver;EndpointOverride=vpce-123456abc.athena.us-east-1.vpce.amazonaws.com:443;AwsRegion=us-east-2;S3OutputLocation=s3://query-results-bucket/test-folder-1;AuthenticationType=AuthenticationType=IAM Profile;AWSProfile=simba;

Connecting to Athena Using IAM Credentials

The following is the format of a DSN-less connection string for connecting to Athena using IAM credentials:

Driver=Simba Athena ODBC Driver;AwsRegion=[Region];S3OutputLocation=[S3Path];AuthenticationType=IAM Credentials;UID=[YourAccessKey];PWD=[YourSecretKey];

For example:

Driver=Simba Athena ODBC Driver;AwsRegion=us-east-2;S3OutputLocation=s3://query-results-bucket/test-folder-1;AuthenticationType=IAM Credentials;UID=ABCABCABC123ABCABC45;PWD=abCD+E1f2Gxhi3J4klmN/OP5QrSTuvwXYzabcdEF;

Connecting to Athena Using an IAM Profile

The following is the format of a DSN-less connection string for connecting to Athena using an IAM profile:

Driver=Simba Athena ODBC Driver;AwsRegion=[Region];S3OutputLocation=[S3Path];AuthenticationType=IAM Profile;AWSProfile=[YourProfileName];

For example:

Driver=Simba Athena ODBC Driver;AwsRegion=us-east-2;S3OutputLocation=s3://query-results-bucket/test-folder-1;AuthenticationType=IAM Profile;AWSProfile=simba;

Connecting to Athena Using an Instance Profile

The following is the format of a DSN-less connection string for connecting to Athena using an instance profile from the Amazon EC2 Instance Metadata Service:

Driver=Simba Athena ODBC Driver;AwsRegion=[Region];S3OutputLocation=[S3Path];AuthenticationType=Instance Profile;

For example:

Driver=Simba Athena ODBC Driver;AwsRegion=us-east-2;S3OutputLocation=s3://query-results-bucket/test-folder-1;AuthenticationType=Instance Profile;

Connecting to Athena Using the AD FS Credentials Provider

The following is the format of a DSN-less connection string for connecting to Athena using credentials provided by the AD FS service. If you are connecting to Athena from a Windows machine, the UID and PWD properties are optional.

Driver=Simba Athena ODBC Driver;AwsRegion=[Region];S3OutputLocation=[S3Path];AuthenticationType=ADFS;IdP_Host=[CredProviderHost];UID=[YourCredProviderUserName];PWD=[YourCredProviderPassword];

For example:

Driver=Simba Athena ODBC Driver;AwsRegion=us-east-2;S3OutputLocation=s3://query-results-bucket/test-folder-1;AuthenticationType=ADFS;IdP_Host=example.adfs.server;UID=HOME\jsmith;PWD=simba12345;

Connecting to Athena Using the Azure AD Credentials Provider

The following is the format of a DSN-less connection string for connecting to Athena using credentials provided by the Azure AD service.

Driver=Simba Athena ODBC Driver;AwsRegion=[Region];S3OutputLocation=[S3Path];AuthenticationType=AzureAD;UID=[YourCredProviderUserName];PWD=[YourCredProviderPassword];idp_tenant=[YourTenantID];client_id=[ClientID];client_secret=[ClientSecret];

For example:

Driver=Simba Athena ODBC Driver;AwsRegion=us-east-2;S3OutputLocation=s3://query-results-bucket/test-folder-1;AuthenticationType=AzureAD;UID=jsmith;PWD=simba12345;idp_tenant=xyz;client_id=xyz;client_secret=xyz;

Connecting to Athena Using the Browser Azure AD Credentials Provider

The following is the format of a DSN-less connection string for connecting to Athena using credentials provided by the Browser Azure AD service.

Driver=Simba Athena ODBC Driver;AwsRegion=[Region];S3OutputLocation=[S3Path];AuthenticationType=BrowserAzureAD;UID=[YourCredProviderUserName];PWD=[YourCredProviderPassword];idp_tenant=[YourTenantID];client_id=[ClientID];

For example:

Driver=Simba Athena ODBC Driver;AwsRegion=us-east-2;S3OutputLocation=s3://query-results-bucket/test-folder-1;AuthenticationType=BrowserAzureAD;UID=jsmith;PWD=simba12345;idp_tenant=xyz;client_id=xyz;

Connecting to Athena Using the Browser SAML Credentials Provider

The following is the format of a DSN-less connection string for connecting to Athena using credentials provided by the Browser SAML service.

Driver=Simba Athena ODBC Driver;AwsRegion=[Region];S3OutputLocation=[S3Path];AuthenticationType=BrowserSAML;UID=[YourCredProviderUserName];PWD=[YourCredProviderPassword];Login_URL=[SAMLURL];

For example:

Driver=Simba Athena ODBC Driver;AwsRegion=us-east-2;S3OutputLocation=s3://query-results-bucket/test-folder-1;AuthenticationType=BrowserSAML;UID=jsmith;PWD=simba12345;Login_URL=http://localhost:abc/athena;

Connecting to Athena Using a JSON Web Token (JWT)

The following is the format of a DSN-less connection string for connecting to Athena using a JWT.

Driver=Simba Athena ODBC Driver;AuthenticationType=JWT;web_identity_token=[WebIdentityToken];preferred_role=[IAMRole];role_session_name=[RoleSessionName];

For example:

Driver=Simba Athena ODBC Driver;AuthenticationType=JWT;web_identity_token=bjsdbhcjsdchsdchsdc;Preferred_Role=arn:aws:iam::187862086336:role/ADFS-Dev;role_session_name=athena

Connecting to Athena Using the Okta Credentials Provider

The following is the format of a DSN-less connection string for connecting to Athena using credentials provided by the Okta credentials service.

Driver=Simba Athena ODBC Connector;AwsRegion=[Region];S3OutputLocation=[S3Path];AuthenticationType=Okta;IdP_Host=[CredProviderHost];UID=[YourCredProviderUserName];PWD=[YourCredProviderPassword];App_ID=[YourOktaAppId];

For example:

Driver=Simba Athena ODBC Connector;AwsRegion=us-east-2;S3OutputLocation=s3://query-results-bucket/test-folder-1;AuthenticationType=Okta;IdP_Host=dev-123456.okta.com;UID=jsmith@example.com;PWD=simba12345;App_ID=12abc123456789/123;

Connecting to Athena Using the PingFederate Service

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

Driver=Simba Athena ODBC Connector;AwsRegion=[Region];S3OutputLocation=[S3Path];AuthenticationType=Ping;IdP_Host=[CredProviderHost];UID=[YourCredProviderUserName];PWD=[YourCredProviderPassword];Preferred_Role=[IAMRole];

For example:

Driver=Simba Athena ODBC Connector;AwsRegion=us-east-2;S3OutputLocation=s3://query-results-bucket/test-folder-1;AuthenticationType=Ping;IdP_Host=dev-123456.okta.com:;UID=jsmith@example.com;PWD=simba12345;IdP_Host=ping.simba.com;Preferred_Role=dbAdmin;

Connecting to Athena Using a Proxy Server

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

Driver=Simba Athena ODBC Driver;AwsRegion=[Region];S3OutputLocation=[S3Path];AuthenticationType=Default Credentials;UseProxy=1;ProxyScheme=HTTPS;ProxyHost=[ProxyHost];ProxyPort=[Port];ProxyUID=[ProxyUserID];ProxyPWD=[ProxyPassword];

For example:

Driver=Simba Athena ODBC Driver;AwsRegion=us-east-2;S3OutputLocation=s3://query-results-bucket/test-folder-1;AuthenticationType=Default Credentials;UseProxy=1;ProxyScheme=HTTPS;ProxyHost=123.456.789.012;ProxyPort=8080;ProxyUID=simba;ProxyPWD=simba;

Connecting to Athena Using a Proxy Server on a Non-Windows Machine With Trusted Certificate

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

Driver=Simba Athena ODBC Driver;AwsRegion=[Region];S3OutputLocation=[S3Path];AuthenticationType=Default Credentials;UseProxy=1;ProxyScheme=HTTPS;ProxyHost=[Proxy Host];ProxyPort=[Port];ProxyUID=[Proxy User ID];ProxyPWD=[Proxy Password];TrustedCerts=[CertificateStorePath];

For example:

Driver=Simba Athena ODBC Driver;AwsRegion=us-east-2;S3OutputLocation=s3://query-results-bucket/test-folder-1;AuthenticationType=Default Credentials;UseProxy=1;ProxyScheme=HTTPS;ProxyHost=123.456.789.012;ProxyPort=8080;ProxyUID=simba;ProxyPWD=simba;TrustedCerts=/disk/dir/certificates.pem;

Example: Using Workgroups

A workgroup is an Athena feature that enables you to control the data access and costs associated with running queries. For more information, see "Using Workgroups to Control Query Access and Costs" in the Amazon Athena User Guide: https://docs.aws.amazon.com/athena/latest/ug/manage-queries-control-costs-withworkgroups.html.

To use a workgroup when connecting to Athena through the Simba Athena ODBC Driver, either specify a workgroup in the DSN, write a connection URL that sets the Workgroup property to the name of your workgroup. For example, to use a workgroup named SimbaAdmins:

Specifying a workgroup does not change the way that you run SQL statements or make ODBC API calls. The connector passes the workgroup name to Athena, and all workgroup handling takes place in the Athena service instead of in the connector.

Related topics