Overview

This tutorial guides you step-by-step on how to connect to the Data Adapter. For this tutorial we will use DBeaver, a free SQL tool. However, this guide is also a good reference for connecting with Data Adapter using other tools like Power BI, Google Looker, Tableau and Qlik.

📘

JDBC drivers required

Most SQL tools require the AWS Athena JDBC Drivers to connect to AWS Athena. If you are prompted to download and install the JDBC drivers at any point during the setup process, please do so.

Step 1: Get your credentials

If you haven't already, follow the steps in the Data Adapter overview guide to create your credentials on the Root management dashboard.

Step 2: Download and install DBeaver

Download and install the community version of DBeaver (official download page):

• Windows installer
• MacOS for Intel installer
• MacOS for Apple Silicon installer

📘

MacOS: Intel vs Apple Silicon

If you have a Mac and you're not sure which installer to select, click on the Apple logo in the top left of your screen and click on "About This Mac". If the "Chip" is "Intel", select the "MacOS for Intel installer". If the "Chip" is "Apple", select the "MacOS for Apple Silicon installer".

Step 3: Create a new database connection

1. Open DBeaver and go to "Database" > "New Database Connection"

2. Click on "All" in the sidebar and search for Athena
3. Select Athena and click on "Next"

Step 4: Set up the driver, enter your credentials and test the connection

📘

Complete steps in the specified order

In this section it is important that you complete the "Driver properties" and "Main" tabs and then "Test Connection...", before clicking on "Finish".

Let's start with the driver properties. Click on “Driver properties”. If you are prompted to download the latest drivers, please do so by clicking on "Download".

Included in your Data Adapter credentials are your Athena schema and Athena workgroup. Add these to the "Driver properties". Note: Don't click on "Finish" yet.

Go to the "Main" tab. Enter your AWS region, AWS S3 path (S3 location), AWS access key Id (Username) and AWS secret access key (Password). These can be found in your Data Adapter credentials.

Click on "Test Connection..."

A pop-up should appear showing a successful connection was established. Click on "OK". If the connection was successful, click on "Finish".

If you've got this far you have successfully connected to the Data Adapter. Congratulations! You can now query your organisation's data.

Step 5: Open the SQL script editor

Right-click on the Data Adapter connection and select "SQL Editor" > "New SQL script"

Step 6: Enter and run your query

Enter the following query and click on the execute button on the left of the script editor. You should see the results appear below the script editor:

SELECT * FROM policies LIMIT 10

If you experience any issues with your query, check out the Common issues with DBeaver section below.

If your query was successful, you are ready to use the Data Adapter with DBeaver! For more examples of queries, you can go to the Data Adapter queries guide.

If you want to get started with a different tool, head to the Data Adapter overview guide for more useful information.

Common issues with DBeaver

Issue	Resolution
Error messages not showing due to JDBC driver	If your query returns an error without any useful information about what the issue with the query is, you may have an older version of the JDBC driver installed. You can download the latest version of the JDBC drivers from the Amazon website. To use the downloaded driver with DBeaver: - Delete your Athena connection - Go to Database > Driver Manager > AWS > Athena > Edit > Libraries - Delete all of the drivers listed - Click on Add File and select the file you downloaded - Click on Find Class and then click on OK - Repeat Step 3: Create a new database connection to set up a new connection - You may need to close and re-open DBeaver for the new drivers to take effect - Once your new connection is set up, you need to open a new SQL script using your new connection. Any previous SQL scripts will point to the old deleted connections.
Error messages not showing even after updating the JDBC driver above	If error messages still don't show useful information about the issue with the query, you may need to update the language settings on your computer. Go to your computer's language settings and make sure the language is set to the correct region e.g. if you are in South Africa, use English (South Africa). After you have changed your language settings, close and re-open DBeaver and try to run the SQL queries again.