AWS athena: Athena ODBC v2 driver: add BinaryColumnLength and EnableConnectionCaching options
Summary
Adds documentation for a new Binary column length parameter and an Enable connection caching parameter that caches the GetWorkGroup result for five minutes per driver process, plus clarifications on UseSingleCatalogAndSchema and WCHAR type reporting.
Security assessment
The new EnableConnectionCaching option caches an authorization-relevant GetWorkGroup lookup keyed by credential identity, and the docs explicitly note that a revoked permission is only reported after the cache expires, which is a security-adjacent behavior with delayed revocation impact. No specific vulnerability or CVE is referenced.
Evidence
If you connect within five minutes of a successful connection with the same key, the driver skips the `GetWorkGroup` call. A revoked permission or a changed workgroup engine version is reported at your first query, or at the next connection after the cache expires.
Diff
diff --git a/athena/latest/ug/odbc-v2-driver-advanced-options.md b/athena/latest/ug/odbc-v2-driver-advanced-options.md index 2e2f2a8..e44aabe 100644 --- a//athena/latest/ug/odbc-v2-driver-advanced-options.md +++ b//athena/latest/ug/odbc-v2-driver-advanced-options.md @@ -7 +7 @@ -Fetch sizeResult fetcherEnable result reuseResult reuse maximum ageUse multiple S3 threadsUse single catalog and schemaUse query to list tablesUse WCHAR for string typesQuery external catalogsVerify SSLS3 result block sizeString column lengthComplex type column lengthTrusted CA certificateUser-Agent privacy modeMin poll periodMax poll periodPoll multiplierMax poll durationConnection timeoutRequest timeout +Fetch sizeResult fetcherEnable result reuseResult reuse maximum ageUse multiple S3 threadsUse single catalog and schemaUse query to list tablesUse WCHAR for string typesQuery external catalogsVerify SSLS3 result block sizeString column lengthComplex type column lengthBinary column lengthTrusted CA certificateUser-Agent privacy modeMin poll periodMax poll periodPoll multiplierMax poll durationConnection timeoutRequest timeoutEnable connection caching @@ -61 +61,3 @@ UseMultipleS3Threads | Optional | `0` | `UseMultipleS3Threads=1;` -By default, the ODBC driver queries Athena to get the list of available catalogs and schemas. This option forces the driver to use the catalog and schema specified by the ODBC Data Source Administrator configuration dialog box or connection parameters. +By default, the ODBC driver queries Athena to get the list of available catalogs and schemas. This option forces the driver to use the catalog and schema specified by the ODBC Data Source Administrator configuration dialog box or connection parameters. When this option is set to `1`, catalog functions such as `SQLTables` and `SQLColumns` return only the configured `Catalog` and `Schema`, and the driver does not call Athena or AWS Glue to list them. + +Set this parameter to `0` or `1`. Any other value causes the connection to fail. An empty value in a DSN is treated as `0`. @@ -77 +79 @@ UseQueryToListTables | Optional | `1` | `UseQueryToListTables=1;` -By default, the ODBC driver uses `SQL_CHAR` and `SQL_VARCHAR` for Athena the string data types `char`, `varchar`, `string`, `array`, `map<>`, `struct<>`, and `row`. Setting this parameter to `1` forces the driver to use `SQL_WCHAR` and `SQL_WVARCHAR` for string data types. Wide character and wide variable character types are used to ensure that characters from different languages can be stored and retrieved correctly. +By default, the ODBC driver uses `SQL_CHAR` and `SQL_VARCHAR` for Athena the string data types `char`, `varchar`, `string`, `array`, `map<>`, `struct<>`, and `row`. Setting this parameter to `1` forces the driver to use `SQL_WCHAR` and `SQL_WVARCHAR` for string data types. Wide character and wide variable character types are used to ensure that characters from different languages can be stored and retrieved correctly. When this parameter is set to `1`, catalog result sets also describe their text columns as `SQL_WVARCHAR`, and `SQLColumns` reports wide types and four bytes per character in `BUFFER_LENGTH` and `CHAR_OCTET_LENGTH` for string columns. When this parameter is `1`, the octet length of `time with time zone` and `timestamp with time zone` result columns is 108 and 260. When it is `0`, the octet length is 27 and 65, the same as the column size. @@ -122,0 +125,8 @@ ComplexTypeColumnLength | Optional | 65535 | `ComplexTypeColumnLength=123456;` +## Binary column length + +Specifies the column length for columns with the `varbinary` data type. The driver reports this value as the column size, buffer length, and precision of `varbinary` columns and as the `COLUMN_SIZE` of the `SQL_VARBINARY` type in `SQLGetTypeInfo`. The display size is twice this value. In Windows, you can also set this value in the **Binary Column Length** field of the **Advanced options** dialog box. + +Connection string name | Parameter type | Default value | Connection string example +---|---|---|--- +BinaryColumnLength | Optional | 32767 | `BinaryColumnLength=65535;` + @@ -196,0 +207,12 @@ RequestTimeout | Optional | `10000` | `RequestTimeout=30000;` +## Enable connection caching + +Use this parameter to cache the result of the `GetWorkGroup` call that the driver makes when you connect. When you set `EnableConnectionCaching=1`, the driver reuses the result for five minutes per driver process instead of calling Athena on every connection. The driver keeps one cache entry for each combination of AWS Region, workgroup, Athena endpoint override, and your credential identity. For the `SageMakerIam` and `SageMakerBrowserIdc` plugins, the cache entry is keyed by the Region, workgroup, endpoint overrides, SageMaker domain, project, and domain Region instead of your credential identity. The driver also caches the SageMaker connection lookup for five minutes. + +If you connect within five minutes of a successful connection with the same key, the driver skips the `GetWorkGroup` call. A revoked permission or a changed workgroup engine version is reported at your first query, or at the next connection after the cache expires. Only the literal value `1` enables caching. A missing or empty value, `0`, or any other value leaves caching disabled, and the driver performs a live check on every connection. + +The Windows ODBC Data Source Administrator dialog box has no field for this parameter. Its **Test** button always performs a live check, and saving a DSN from that dialog box removes the parameter. Set this parameter in your connection string or directly in your DSN. + +**Connection string name** | **Parameter type** | **Default value** | **Connection string example** +---|---|---|--- +EnableConnectionCaching | Optional | `0` | `EnableConnectionCaching=1;` +