Amazon Athena ODBC 2.x release notes

• AuthenticationType validated – The driver now rejects any AuthenticationType value that is not one of the documented values and fails the connection with HY000 instead of falling back to IAM credentials. Default is now accepted as a shorter form of Default Credentials. For more information, see Authentication options.

• UseSingleCatalogAndSchema validated – The driver now accepts only 0 or 1 for UseSingleCatalogAndSchema. Any other value fails the connection with HY000. For more information, see Use single catalog and schema.

• LogLevel validated – The driver now fails the connection with HY000 for a LogLevel value that it does not recognize, and a driver-wide LogLevel other than OFF now requires LogPath. For more information, see Logging options.

• AWS Glue catalog listing errors reported – When multi-catalog browsing cannot list AWS Glue catalogs for a reason other than access denied or entity not found, such as throttling, the catalog function now fails with HY000 and a message that begins with [AmazonAthena][GlueClientError] instead of returning a shorter list. For more information, see AWS Glue endpoint override.

• Single catalog and schema mode enforced – With UseSingleCatalogAndSchema=1, catalog functions now return only the configured Catalog and Schema without calling Athena or AWS Glue. This also prevents the Power BI error "cannot convert the value null to type Record". To list every catalog and schema, set UseSingleCatalogAndSchema=0. For more information, see Use single catalog and schema.

• Catalog search patterns disabled under SQL_ATTR_METADATA_ID – If you set SQL_ATTR_METADATA_ID to SQL_TRUE on the connection, catalog function arguments on its statements are now treated as identifiers rather than search patterns, so wildcard arguments no longer match.

• AWS Glue endpoint override – Added the GlueEndpointOverride parameter to set the endpoint for the AWS Glue calls used in multi-catalog browsing. For more information, see AWS Glue endpoint override.

• Binary column length – Added the BinaryColumnLength parameter to set the column size the driver reports for varbinary columns. For more information, see Binary column length.

• Connection caching – Added the EnableConnectionCaching parameter. When set to 1, the driver caches the result of the GetWorkGroup call that it makes when you connect for five minutes per driver process. For more information, see Enable connection caching.

• IAM profile credentials – Connections that use the IAM Profile authentication plugin now reload credentials when the AWS credentials or config file changes for the selected profile. For more information, see IAM profile.

• SQLGetInfo additions – Added SQL_ODBC_VER, SQL_XOPEN_CLI_YEAR, SQL_ODBC_SAG_CLI_CONFORMANCE, and the SQL_CONVERT_WCHAR, SQL_CONVERT_WVARCHAR, and SQL_CONVERT_WLONGVARCHAR conversion masks.

• Query error messages – When an Athena query fails with an empty error message, the driver now reports the state change reason that Athena returns for the query.

• SQLBrowseConnect keywords – SQLBrowseConnect now lists AuthenticationType, AwsProfile, Catalog, Schema, SessionToken, and Workgroup as optional keywords.

• Specific SQLSTATEs – Unsupported or unknown attributes and SQLGetInfo types, SQLDescribeParam, and conversion errors now return specific SQLSTATEs instead of a bare SQL_ERROR or a generic code.

• Connection failure SQLSTATEs – A connection failure from the GetWorkGroup call made when you connect now returns 28000 for credential errors, 08004 for request errors such as a missing workgroup, 08S01 for network and request timeout errors, and 08001 otherwise.

• Wide character catalog metadata – With UseWCharForStringTypes=1, SQLColumns and the catalog result sets now report wide character types and byte lengths. For more information, see Use WCHAR for string types.

• Licensing update – The driver license now permits redistribution of the compiled driver when it is embedded in your product.

• Fixed an issue that could cause a result block downloaded from Amazon S3 to contain stale bytes from an aborted attempt. The driver now checks each block against the requested byte range and fails a short block with HY000 and the message "Result set is incomplete".

• Fixed an issue that caused SQLColumns to fail on tables with a varbinary column. The column size now comes from BinaryColumnLength.

• Fixed an issue that caused SQLColumns to fail on tables and views with an interval year to month or interval day to second column.

• Fixed an issue that caused SQLSetConnectAttrW to store an empty catalog name when SQL_ATTR_CURRENT_CATALOG was set with SQL_NTS.

• Fixed an issue that caused SQLRowCount to crash when RowCountPtr was null.

• Improved SQL_C_WCHAR output to write characters outside the Basic Multilingual Plane as surrogate pairs. Chunked SQLGetData is now supported on SQL_WVARCHAR columns, including a change of target type between calls.

• Fixed an issue that caused SQL_C_DEFAULT in SQLBindCol, SQLFetch, and SQLGetData to be passed through unresolved.

• Fixed an issue that caused a binary value read as hexadecimal text to end in the middle of a byte.

• Fixed an issue that caused the sign of a negative interval to overwrite its first digit. Interval fraction digits now follow the column precision.

• Fixed an issue that caused the SQLParamData token to be truncated to 32 bits on 64-bit platforms.

• Fixed an issue that caused SQLTables with SQL_ATTR_METADATA_ID set to SQL_TRUE to reject a null TableType argument.

• Fixed an issue that caused the octet length of time with time zone and timestamp with time zone result columns to be reported as if the columns were VARCHAR instead of equal to the column size when UseWCharForStringTypes is 0.

• Fixed an issue that caused date and timestamp values with an impossible day, such as February 30, to be accepted instead of returning 22018.

• Fixed an issue that caused SQL_DESC_AUTO_UNIQUE_VALUE and SQL_DESC_CASE_SENSITIVE to be written as 2-byte values instead of 4-byte integers.

• Fixed an issue that caused SQL_COLUMN_PRECISION for floating point types to return the bit length instead of decimal digits.

• Fixed an issue that caused a prepared REAL column to be named real while the executed result set named it float.

• Fixed an issue that caused VARBINARY literals to use the 0x'...' form instead of X'...'.

• Fixed an issue that caused SQLNumParams to report a stale count after a catalog function.

• Fixed an issue that caused a malformed varbinary value to fail the whole row instead of only that value.

• Fixed an issue that caused a SQL_C_BINARY buffer that is too small for a string or binary value to fail instead of returning the data across SQLGetData calls.

• Fixed an issue that caused chunked SQLGetData to report SQL_NO_TOTAL instead of the remaining byte count.

• Fixed an issue that caused the driver to report asynchronous execution support that it does not provide.

• Fixed an issue that caused SQLTables and SQLColumns to omit tables at approximately position 200 and later within a schema. This happened when the driver received two consecutive empty pages while paginating metadata results.

• Fixed an issue that caused empty string filter patterns from ADO.NET applications such as Power BI to return zero rows instead of all rows. The driver now treats an empty string pattern as no restriction, which matches all values.

• Fixed an issue that caused SQLColumns to fail on column types that the driver does not recognize, such as uuid or json. These columns are now reported with the SQL type VARCHAR. The TYPE_NAME column continues to report the Athena type name.

• Fixed an issue that caused connections that use the SageMakerBrowserIdc authentication plugin to stop responding until the identity provider response timeout elapsed when the SSOOIDCEndpointOverride parameter was set.

• Fixed an issue that caused the driver to ignore the SSOEndpointOverride parameter for connections that use the BrowserSSOOIDC authentication plugin.

• Fixed an issue that caused connections through a proxy server to fail with Domain Name System (DNS) resolution errors when the proxy performs DNS resolution. HTTP clients that the AWS SDK creates internally now use the driver's configured proxy settings.

• Fixed an issue that caused Transport Layer Security (TLS) certificate verification to fail on Linux when the TrustedCerts parameter was not set. The driver now locates the CA bundle at runtime and honors the CURL_CA_BUNDLE and SSL_CERT_FILE environment variables. The resolved CA bundle is also applied to HTTP clients that the AWS SDK creates internally.

• Fixed an issue that prevented the Linux driver from installing on distributions with glibc 2.28, including Red Hat Enterprise Linux 8 and Rocky Linux 8. The Linux driver now builds against a glibc 2.28 baseline and requires glibc 2.28 or later. On SUSE Linux Enterprise Server 15, use SP3 or later, which provides a compatible glibc version.

• Fixed an issue that could cause the Linux driver to crash when a host application that had already loaded a different OpenSSL library, such as an R environment, loaded the driver. The driver now restricts its exported symbols to the ODBC API so that its bundled cryptography library is not affected by the host application's OpenSSL.

• Fixed an issue that caused the driver to send requests to identity providers without a User-Agent header.

  Action required: User-Agent header change

  This release changes the driver User-Agent header for Athena, AWS Glue, Amazon S3, and supported identity provider requests. Windows Integrated Authentication continues to use a browser User-Agent.

  If you match the driver's User-Agent in IAM aws:UserAgent policy conditions, log filters, or identity provider sign-on rules, update the pattern to *lib/AmazonAthenaODBC#*. This pattern does not match Windows Integrated Authentication requests.

• Fixed an issue that could cause SageMakerBrowserIdc and BrowserSSOOIDC authentication to fail on hosts that have ambient AWS credentials. The driver no longer SigV4-signs the SSO OIDC RegisterClient and CreateToken requests used by these plugins. BrowserSSOOIDC also no longer SigV4-signs SSO GetRoleCredentials requests. CreateTokenWithIAM requests remain SigV4-signed.

• Fixed issues that could cause transient Amazon S3 result-fetch failures to return partial results. The issues could also cause the driver to stop responding when the stream ended with an unterminated quoted multiline CSV record. The driver now makes up to three attempts per block. Each attempt fetches the byte range from the current stream offset. Between attempts, the driver recreates the Amazon S3 client so that the retry can use refreshed credentials. Errors that are not transient, such as access denied, are returned without a retry. If the result file ends prematurely, applications now receive SQL_ERROR instead of partial rows followed by SQL_NO_DATA.

• Fixed an issue in how the driver formats parameter values that you bind with SQLBindParameter. The driver now sends each value as a typed SQL literal and escapes single quotation marks within it, so a value that contains a quotation mark is no longer interpreted as part of the query. String parameters are no longer wrapped in CAST(value AS CHAR(n)). A value that contains an embedded null character is now rejected with SQL_ERROR. This behavior matches the Amazon Athena JDBC 3.x driver.

  Action required: trailing spaces in bound string parameters

  Because the driver no longer sends string parameters as CHAR values, comparisons against them no longer ignore trailing spaces. A predicate such as WHERE column = ? that previously matched rows whose column values differ from the bound value only in trailing spaces now returns fewer rows. If your application depends on the earlier behavior, trim both sides of the comparison, for example WHERE rtrim(column) = rtrim(?).

• Fixed an issue that caused parameters bound as null with SQL_NULL_DATA to be sent as values instead of as NULL. A null SQL_REAL, SQL_FLOAT, or SQL_DOUBLE parameter was sent as 0.0. A null parameter of any other type was sent as the string NULL. For string parameters, this value matched rows that contain the text NULL. Queries that bind null date and time parameters failed. The driver now sends NULL for a null parameter of any type.

• Added the optional UserAgentPrivacyMode connection parameter. Set this parameter to 1 to omit runtime environment metadata from the User-Agent header on identity provider requests, while retaining lib/AmazonAthenaODBC#<version>. Requests to AWS services, including Athena, AWS Glue, and Amazon S3, always include the full User-Agent header.

• Fixed an issue that caused some browser-based authentication requests to fail because of a missing Content-Length header.

• Fixed an issue that caused query parameters to be truncated when you use SQL_C_WCHAR bindings.

• The license file now includes a reference to the AWS Service Terms.

• SageMaker authentication – Added support for the SageMaker authentication plugins SageMakerBrowserIdc and SageMakerIam. You can now connect to your SageMaker projects and work with the data from your preferred third-party tool. For more information, see SageMaker Browser IDC and SageMaker IAM.

• Multi-catalog browsing – Added multi-catalog browsing support for lakehouse features. The driver can now discover and connect to all catalogs in federated catalog environments, enabling use of S3 Tables and catalog federation through Amazon Athena.

• macOS universal installer – The macOS driver is now distributed as a single universal binary that supports both ARM and Intel architectures, simplifying installation across all Mac hardware.

• HTTP client migration – Removed the libcurl dependency from ODBC binaries by migrating to the AWS SDK CRT HTTP client. The CRT client uses the platform's native TLS stack and system trust store, improving connection reliability and eliminating transitive dependencies on OpenSSL and zlib.

• Added ExternalId support for STS AssumeRole for cross-account role assumption. The ExternalId is read from the AWS profile configuration.

• SSL certificate validation enabled by default – The driver now enforces SSL certificate verification when connecting to identity providers. If you use a local identity provider without a valid SSL certificate, you must explicitly set SSL_Insecure=1 in your connection string. For more information, see SSL insecure (IdP).

• TLS 1.2 minimum enforced – The driver no longer accepts TLS 1.0 or TLS 1.1 connections to identity providers. All IdP connections now require TLS 1.2 or later.

• BrowserSSOOIDC authentication flow updated – The BrowserSSOOIDC plugin now uses Authorization Code with PKCE instead of Device Code Authorization. A new optional parameter listen_port (default 7890) is available for the OAuth 2.0 callback server. You may need to allowlist this port on your network. The default scope has changed to sso:account:access. For more information, see Browser SSO OIDC.

• BrowserSSOOIDC – Migrated from Device Code flow to Authorization Code with PKCE for improved security.

• BrowserAzureAD – Added PKCE (Proof Key for Code Exchange) to the OAuth 2.0 authorization flow to prevent authorization code interception attacks.

• BrowserSAML – Added RelayState CSRF protection to prevent SAML token injection attacks.

• Credentials cache – Starting in v2.1.0.0, cached credentials are stored as plaintext JSON in the user-profile/.athena-odbc/ directory with file permissions restricted to the owning user, consistent with how the AWS CLI protects locally stored credentials.

• IAM Profile – Added support for EcsContainer and Environment credential sources in addition to the existing Ec2InstanceMetadata.

• Connection string parser – Implemented proper ODBC }} escape handling.

• Catalog queries – Added SQL identifier escaping for schema names and table patterns.

• ODBC pattern matching – Replaced regex-based matching with direct ODBC LIKE wildcard matcher.

• XML parsing – Added recursion depth limit (100 levels) and size limit (1MB) for SAML tokens.

• ADFS authentication – Added response size limit (200KB) for ADFS server responses.

• Fixed improper neutralization of special elements in authentication components that could allow code execution or authentication flow redirection via crafted connection parameters. Affects BrowserSSOOIDC, BrowserAzureAD, and BrowserSAML plugins.

• Fixed improper neutralization of special elements in query processing components that could allow denial of service or SQL injection via crafted table metadata.

• Fixed improper certificate validation when connecting to identity providers.

• Fixed missing authentication security controls in browser-based authentication flows, including PKCE for OAuth, CSRF protection for SAML, secure credential caching, and exclusive callback port binding.

• Fixed uncontrolled resource consumption in parsing components that could allow denial of service via crafted input patterns, unbounded server responses, or deeply nested XML payloads.

• Fixed an issue where SQLColumns and SQLTables returned no results when using UseSingleCatalogAndSchema=1 with cross-account federated catalogs in Power BI Import mode.

• Browser Trusted Identity Propagation authentication plugin – Added a new authentication plugin to support browser-based OpenID Connect (OIDC) authentication with trusted identity propagation. This plugin provides a seamless authentication experience by handling the complete OAuth 2.0 flow through your default browser, automatically fetching the JSON Web Token (JWT), and integrating with trusted identity propagation. The plugin is specifically designed for single-user desktop environments. For information on enabling and using trusted identity propagation, see What is trusted identity propagation?.

• Enhanced logging framework – Significantly improved the driver's logging mechanism by:

  • Introducing more granular log levels beyond basic 0/1 options

  • Removing redundant log statements

  • Optimizing the logging framework to include diagnostically relevant information

  • Addressing performance issues that were causing operational delays

  • Reducing excessive log file generation when logging is enabled

• Result fetcher optimization – Fixed an issue where fetch size parameter limitations were incorrectly applied to both streaming and non-streaming result fetchers. The limitation is now correctly applied only to non-streaming result fetchers.

The Amazon Athena ODBC v2.0.5.1 driver contains the following fixes to browser-based authentication plugins.

• Implemented validation for login URL and schema checking.

• Improved browser launch mechanism on Linux to utilize system APIs, resulting in improved stability and security.

• JWT Trusted Identity Provider (TIP) authentication plugin – Added a new authentication plugin to support JWT Trusted Identity Provider (TIP) integration with ODBC drivers. This authentication type allows you to use a JSON web token (JWT) obtained from an external identity provider as a connection parameter to authenticate with Athena. With TIP, identity context is added to an IAM role to identify the user requesting access to AWS resources. For information on enabling and using TIP, see What is Trusted Identity Propagation?.

• Custom SSO admin endpoints support – Added support for custom SSO Admin endpoints in the ODBC driver. This enhancement allows you to specify your own endpoints for SSO services when running ODBC behind VPCs.

• AWS SDK version update – We have updated the AWS SDK version used in the driver to 2.32.16 and have updated the project dependencies for release 2.0.5.0.

• Result Fetcher – The driver now automatically selects the method to download query results. This removes the need to manually configure the fetcher in most situations. For more information, see Result fetcher.

• Curl Library has been updated to 8.12.1.

• Fixed proxy configuration for IAM profile when connecting to STS. The fix allows IAM Profile to be used for successful authentication.

• Read all additional configuration options for IAM profile with authentication plugins. This includes UseProxyForIdP, SSL_Insecure, LakeformationEnabled, and LoginToRP to resolve misconfigurations for the affected plugins.

• Fixed round function by allowing it to take in an optional 2nd parameter. It successfully processes queries containing the escape syntax.

• Fixed column size for TIME WITH TIME ZONE and TIMESTAMP WITH TIME ZONE data types. Values with timestamp and timezone data type will not get truncated.

• Added MFA support for the Okta authentication plugin on Linux and Mac platforms.

• Both the athena-odbc.dll library and the AmazonAthenaODBC-2.x.x.x.msi installer for Windows are now signed.

• Updated the CA certificate cacert.pem file that is installed with the driver.

• Improved the time required to list tables under Lambda catalogs. For LAMBDA catalog types, the ODBC driver can now submit a SHOW TABLES query to get a list of available tables. For more information, see Use query to list tables.

• Introduced the UseWCharForStringTypes connection parameter to report string data types using SQL_WCHAR and SQL_WVARCHAR. For more information, see Use WCHAR for string types.

• Fixed a registry corruption warning that occurred when the Get-OdbcDsn PowerShell tool was used.

• Updated the parsing logic to handle comments at the start of query strings.

• Date and timestamp data types now allow zero in the year field.

• Added two connection parameters, StringColumnLength and ComplexTypeColumnLength, that you can use to change the default column length for string and complex data types. For more information, see String column length and Complex type column length.

• Support has been added for the Linux and macOS (Intel and ARM) operating systems. For more information, see Linux and macOS.

• AWS-SDK-CPP has been updated to the 1.11.245 tag version.

• The curl library has been updated to the 8.6.0 version.

• Resolved an issue that cause incorrect values to be reported in result-set metadata for string-like data types in the precision column.

• Improved ODBC driver thread safety for all interfaces.

• When logging is enabled, datetime values are now recorded with millisecond precision.

• During authentication with the Browser SSO OIDC plugin, the terminal now opens to display the device code to the user.

• Resolved a memory release issue that occurred when parsing results from the streaming API.

• Requests for the interfaces SQLTablePrivileges(), SQLSpecialColumns(), SQLProcedureColumns(), and SQLProcedures() now return empty result sets.

• File cache feature added for the Browser Azure AD, Browser SSO OIDC, and Okta browser-based authentication plugins.

  BI Tools like Power BI and browser-based plugins use multiple browser windows. The new file cache connection parameter enables temporary credentials to be cached and reused between the multiple processes opened by BI applications.

• Applications can now query information about the result set after a statement is prepared.

• Default connection and request timeouts have been increased for use with slower client networks. For more information, see Connection timeout and Request timeout.

• Endpoint overrides have been added for SSO and SSO OIDC. For more information, see Endpoint overrides.

• Added a connection parameter to pass a URI argument for an authentication request to Ping. You can use this parameter to bypass the Lake Formation single role limitation. For more information, see Ping URI param.

• Fixed an integer overflow issue that occurred when using the row-based binding mechanism.

• Removed timeout from the list of required connection parameters for the Browser SSO OIDC authentication plugin.

• Added missing interfaces for SQLStatistics(), SQLPrimaryKeys(), SQLForeignKeys(), and SQLColumnPrivileges(), and added the ability to return empty result sets upon request.

• Added URI logging to the Okta authentication plugin.

• Added the preferred role parameter to the external credentials provider plugin.

• Adding handling for the profile prefix in the profile name of AWS configuration file.

• Corrected a AWS Region use issue that occurred when working with Lake Formation and AWS STS clients.

• Restored missing partition keys to the list of table columns.

• Added the missing BrowserSSOOIDC authentication type to the AWS profile.