Customize 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 Customization) file that passes configuration changes to the connection using the odbc-connect-string-extras customization.

This article applies to connectors that use an ODBC driver.

Important: TDC files can be utilized to customize 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 customization 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 organization’s security guidelines.

The odbc-connect-string-extras customization 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 customizations (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 customization section will use only the embedded customizations, 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 customized 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 customization to append attributes or override the DRIVER attribute to the connection string.

Create a TDC file

  1. Open a plain text editor, such as Notepad or Notepad++.
  2. 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.
  3. 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.
  4. Enter the customizations 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 customizing 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 Virtualization: composite
  • Vertica: vertica

See also

Other Databases (ODBC) – Describes how to connect to your data using the ODBC connector.

Example: Customize an ODBC Connection - Step-by-step process showing how customization can be accomplished for capabilities and ODBC connection strings.

Tableau and ODBC – Provides background information about ODBC, describes how Tableau determines the functionality of an ODBC driver, and lists frequently asked questions.

Tableau Capability Customizations Reference – Lists customizations you can use to define which Tableau capabilities are supported by the data source.

ODBC/SQL Customizations Reference – Lists customizations that represent the parts of the ODBC and SQL standards that the ODBC driver reports supporting.

Back to top
Thanks for your feedback!Your feedback has been successfully submitted. Thank you!