Customise Connection String for Native Connectors

Applies to: Tableau Desktop

There are times when you might want to modify the connection made with a native connector. You can do this by creating a TDC (Tableau Datasource Customisation) file that passes configuration changes to the connection using the odbc-connect-string-extras customisation.

This article applies to connectors that use an ODBC driver.

Important: TDC files can be utilised to customise the functionality of a connection or to diagnose and resolve issues related to connecting to your data. Tableau is unable to thoroughly test every potential modification you might make with these files. Creating and using TDC files requires manual editing, and it is crucial to test them thoroughly before deploying them in a production environment.

Modify the connection string

When Tableau connects using an ODBC driver, it creates and passes a connection string to the driver manager. The connection string identifies the driver and contains all the parameters for the driver.

Here's an example connection string:

DRIVER=BagelDB Driver;SERVER=bageldb.lan;UID=creamcheese;PWD=bagel;

Let's say you want to override the DRIVER value of BagelDB Driver with BagelDB Driver 2.0 and add a port number. The connection string passed to the driver manager would be modified to:

DRIVER=BagelDB Driver 2.0;SERVER=bageldb.lan;UID=creamcheese;PWD=bagel;PORT=54321

You can modify the connection string parameters by using a TDC and the odbc-connect-string-extras tag. In general, the only parameter that can be overridden is DRIVER. Other parameters are appended to the end of the connection string. See how to "Use a TDC file" below.

Note: Because of security restrictions, there is limited support for the odbc-connect-string-extras customisation on Tableau Online. Some parameters might not be supported.

Use an allowlist to reduce security risk

Important: The following procedure needs to be done by a Tableau Server administrator on Tableau Server and should be evaluated by your IT department for compliance with your organisation’s security guidelines.

The odbc-connect-string-extras customisation can present a security risk. Your Tableau Server administrator can manage this risk by specifying a list of approved parameters in an allowlist (also known as a security list):

Any parameters specified by odbc-connect-string-extras that are not on the list are filtered out.
If there are no parameters specified in the list, then all parameters are allowed.

The allowlist is a comma-separated list with no spaces in between.

For example, to add the parameters UseDeclareFetch and App to the safelist, run the following commands:

tsm configuration set -k native_api.ODBCConnectStringSecurityList -v UseDeclareFetch,App --force-keys

tsm pending-changes apply

For information about running tsm commands, see tsm Command Line Reference(Link opens in a new window) in the Tableau Server Help.

Use a TDC file

A TDC file is an XML file that contains a vendor name, a driver name and a <connection-customization> section that can contain multiple types of customisations (both to the connection string and to the connection capabilities). For a native connector, the vendor name and driver name must match the connector’s class name. See the "Native connector class list" below for values. Any existing workbook or data source file that already has an enabled customisation section will use only the embedded customisations, not the TDC file.

Once you have created a TDC file, you must save it to the Datasources folder so that it can be used by your connection. If you create a workbook that you want to publish to Tableau Server, or if you use Tableau Prep or Tableau Bridge, then you need to save the TDC file to the Datasources directories for those products as well. For more information, see Installing tdc and properties files.

Note: If you create a data source or workbook with customised odbc-extras, the information is embedded in the connection attributes. Because of this, you can publish a workbook or data source to Tableau Server without having to install the TDC file on Tableau Server.

In the TDC file, you can use the odbc-connect-string-extras customisation to append attributes or override the DRIVER attribute to the connection string.

Create a TDC file

Open a plain text editor, such as Notepad or Notepad++.
Copy the information from the sample provided below, paste it into your text file and then specify the class, vendor name and driver name value. For native Tableau connectors, use the same value for class, vendor name and driver name.
Save the file with a .tdc extension – for example, mybagel.tdc – to the Datasources folder for each Tableau product. For more information, see Installing tdc and properties files.
Enter the customisations you want to make to the connection.

<connection-customization class='bagelDB' enabled='true' version='19.1'>
<vendor name='bagelDB' />
<driver name='bagelDB' />
 <customizations>
   <customization name='odbc-connect-string-extras' value='DRIVER=BagelDB Driver 2.0;PORT=54321' />
 </customizations>
</connection-customization>

Native connector class list

Locate your connector in the list below (listed in the format <connector>:<class>) to get the class value you need for customising the TDC file.

Actian Matrix: paraccel
Actian Vector: vectorwise
Amazon Aurora: aurora
Amazon EMR (Hive): awshadoophive
Amazon Redshift: redshift
Spark SQL: spark
Aster Database: asterncluster
Azure SQL Data Warehouse: azure_sql_dw
Cloudera Hadoop: hadoophive
Denodo: denodo
Exasol : exasolution
Firebird : firebird
Google Cloud SQL: googlecloudsql
Hortonworks Hadoop Hive: hortonworkshadoophive
IBM: BigInsights bigsql
IBM DB2: db2
IBM PDA (Netezza): netezza
Kognitio: kognitio
MapR Hadoop Hive: maprhadoophive
MariaDB: mariadb
MarkLogic: marklogic
MemSQL: memsql
Microsoft SQL Server: sqlserver
MonetDB: monetdb
MongoDB BI Connector: mongodb
MySQL: mysql
Oracle Essbase: essbase
Other Databases (ODBC): genericodbc
Pivotal Greenplum Database: greenplum
PostgreSQL: postgres
Presto: presto
Progress OpenEdge: progressopenedge
SAP HANA: saphana
SAP Sybase ASE: sybasease
SAP Sybase IQ: sybaseiq
Snowflake: snowflake
Splunk: splunk
Teradata: teradata
Tibco Data Virtualisation: composite
Vertica: vertica

Tableau Desktop and Web Authoring Help