How to Customize JDBC Connections in Tableau

While Tableau offers a vast library of native connectors for popular databases and services, it can't possibly cover every single data source out there. That's where the generic Other Databases (JDBC) connector becomes your best friend. This article will show you exactly how to establish and customize a JDBC connection, allowing you to pull data from virtually any source that offers a JDBC driver. We'll walk through the process step-by-step, including how to fine-tune your connection with TDC and properties files for optimal performance and functionality.

Graphed

Build AI Agents for Marketing

Build virtual employees that run your go to market. Connect your data sources, deploy autonomous agents, and grow your company.

Build Your First Agent

What is a JDBC Connection and Why Use One?

JDBC stands for Java Database Connectivity. Think of it as a universal translator. It's a standard programming interface that allows Java-based applications, like Tableau, to communicate with a wide variety of databases, regardless of the database's specific language or protocol.

You’ll typically turn to a JDBC connection in a few key scenarios:

• Unsupported Data Source: The most common reason. Your company uses a specific database or data warehouse (like Presto, Dremio, or a niche cloud service) that doesn't have a dedicated, pre-built connector in Tableau.
• Better Functionality: Sometimes, a data source's JDBC driver offers more advanced features, better performance, or more granular control than its corresponding ODBC driver or even Tableau's native connector.
• Driver Issues: You might encounter bugs or performance bottlenecks with an existing ODBC driver and want to see if the JDBC driver provides a more stable connection.

In short, using JDBC opens up a world of possibilities, ensuring that your data isn't siloed just because a native connector doesn't exist.

Before You Begin: Required Setup

Before you can connect, you need to lay a little groundwork. This involves getting the correct driver file and putting it where Tableau can find it.

1. Download the Correct JDBC Driver (.jar file)

Your first step is to obtain the JDBC driver for your target database. This driver is usually provided directly by the database vendor as a .jar file (a Java ARchive). Search online for "[Your Database Name] JDBC Driver" to find the official download page.

A few examples:

• Amazon Athena: Downloadable from AWS documentation.
• PostgreSQL: Available from the official PostgreSQL JDBC Driver site.
• Snowflake: Provided via the Maven Central Repository.

Always download the driver from the official source to ensure you have the most recent, stable, and secure version.

AI Agents for Marketing

Crash Course

Graphed

Free PDF · the crash course

AI Agents for Marketing Crash Course

Learn how to deploy AI marketing agents across your go-to-market — the best tools, prompts, and workflows to turn your data into autonomous execution without writing code.

Download the PDF

2. Place the Driver in the Tableau Directory

Once you've downloaded the .jar file, Tableau needs to know where it is. You must place it in the correct Tableau driver directory. A common mistake is putting it in the wrong folder.

• For Windows: C:\Program Files\Tableau\Drivers
• For Mac: ~/Library/Tableau/Drivers

After moving the file into this folder, you must restart Tableau Desktop. Tableau only scans this directory for new drivers when it starts up, so it won’t see your new driver until you reopen the application.

Creating a Basic JDBC Connection in Tableau

With your driver correctly installed, you're ready to create the connection. The process is straightforward and happens directly within Tableau’s connection pane.

Here are the step-by-step instructions:

1. Open the Connector: Launch Tableau Desktop. From the Connect pane on the left, under the heading To a Server, click on Other Databases (JDBC).
2. Fill in the Connection Details: A dialog box will appear asking for several pieces of information.
3. Sign In: Click the Sign In button. If your URL, driver, and credentials are correct, Tableau will establish the connection, and you’ll see a list of your schemas and tables, ready for analysis.

The Power of Customization: TDC & Properties Files

Sometimes, the default connection isn't quite right. You may run into issues where:

• You need to pass non-standard authentication parameters not supported by the dialog box.
• Queries run slowly due to incorrect settings that need tuning.
• Tableau misinterprets a custom data type from your database.
• A specific SQL function you want to use isn't recognized.

This is where customization files come in. Tableau gives you two powerful tools to modify the behavior of a JDBC connection:

• Properties File (.properties): A simple text file with key-value pairs that are passed to the JDBC driver during the initial connection handshake. This is used for setting driver-specific parameters, especially for authentication or configuring proxies.
• Tableau Datasource Customization File (.tdc): An XML file that allows you to modify how Tableau interacts with the data source after a connection is established. Use this to tweak SQL generation, declare supported functions, and override default performance settings.

How to Use a Properties File for Connection Parameters

Imagine your database requires a specific security token or an application name to be sent when you first connect. These aren't standard username/password fields, so you can't enter them in the default dialog. A properties file is the solution.

Graphed

Build AI Agents for Marketing

Build virtual employees that run your go to market. Connect your data sources, deploy autonomous agents, and grow your company.

Build Your First Agent

1. Create the Properties File

Open a plain text editor and create a new file. The format is a simple list of key-value pairs, one per line. The exact keys you can use are specific to your JDBC driver, so you must refer to the driver's documentation.

For example, if you were connecting to AWS Athena and needed to specify an S3 staging directory, your properties file (let’s call it athena-connection.properties) might look like this:

# My custom Athena properties
s3_staging_dir=s3://my-tableau-query-results/
connection_timeout=5000

2. Use the File in Tableau

In the Other Databases (JDBC) connection dialog in Tableau, next to the Username and Password fields, there is a Properties File... button. Click it, navigate to the .properties file you just created, and select it. Tableau will now pass these parameters to the driver when it attempts to sign in.

Advanced Control with TDC Files

TDC files give you in-depth control over the entire data source interaction. They work by targeting customizations to a specific driver and vendor, allowing you to tell Tableau exactly what your database can and cannot do.

1. Finding the Vendor and Driver Names

To create a TDC file, you first need to know what connection to target. The easiest way to find this information is to check the Tableau logs.

1. Make a successful (or even a failed) connection attempt using your JDBC driver in Tableau.
2. Navigate to your My Tableau Repository folder (usually in My Documents).
3. Open the Logs subfolder and open the most recent log.txt file.
4. Search for the term "vendor" or "genericjdbc". You should find a log entry that details the connection you just made. Look for lines containing vendor, driver, and class.

For example, you might see something like Found matching TDC for class='clickhouse', vendor='ClickHouse', driver='clickhouse-jdbc-0.3.2'.

2. Creating the TDC File

A TDC file is an XML document. Create a new text file and save it with a .tdc extension (e.g., MyJDBCCustomizations.tdc). The basic structure looks like this:

<connection-customization class='genericjdbc' enabled='true' version='10.0'>
  <vendor name='ClickHouse' />
  <driver name='clickhouse-jdbc-0.3.2' />
  <customizations>
    < customization name='CAP_SOME_CAPABILITY' value='yes' />
    < customization name='CAP_ANOTHER_CAPABILITY' value='no' />
  </customizations>
</connection-customization>

Replace the vendor name and driver name with the values you found in your log file. The customizations themselves are the most important part. Tableau has dozens of named capabilities (most start with CAP_) that control its behavior. You can find lists of these in Tableau's official documentation or community forums.

AI Agents for Marketing

Crash Course

Graphed

Free PDF · the crash course

AI Agents for Marketing Crash Course

Learn how to deploy AI marketing agents across your go-to-market — the best tools, prompts, and workflows to turn your data into autonomous execution without writing code.

Download the PDF

Common TDC Customizations:

• Function Support: Tell Tableau if your database supports certain functions like TRIM, LEFT, or RIGHT.
• Data Type Resolutions: Fix issues where a data type is being incorrectly interpreted.
• Performance Tuning: Control settings like query batching, fetch sizes, and metadata handling to speed up interactions.

3. Saving and Activating the TDC File

Save your .tdc file in the My Tableau Repository\Datasources folder. Just like with drivers, you must restart Tableau Desktop for the customizations to take effect. If structured correctly, Tableau will automatically apply these settings the next time you connect using that specific JDBC driver.

Final Thoughts

Mastering JDBC connections in Tableau is a powerful skill, turning an "unsupported" data source into just another table you can analyze and visualize. By installing the correct driver, authenticating with a properties file for unique parameters, and fine-tuning Tableau’s SQL dialect with a TDC file, you can successfully connect to almost any database and squeeze the best possible performance from it.

Of course, digging through driver documentation, configuring custom XML files, and checking log files can still be a complex process. This is the kind of manual data wrangling we aim to eliminate. With Graphed, we handle the technical friction for you. Instead of troubleshooting connection strings, you can connect your advertising platforms, CRMs, and analytics tools with a few clicks. From there, you just ask questions in plain English to build real-time dashboards and get immediate insights, leaving the technical details behind for good.