home User Guide Getting Started Help Center Documentation Community Training Certification
menu
close
settings
Looker keyboard_arrow_down
language keyboard_arrow_down
English
Français
Deutsch
日本語
search
print
Custom JDBC Drivers

The instructions on this page are not for installing unsupported JDBC drivers into Looker to connect to other databases. Custom JDBC drivers are supported only for pre-existing Looker-supported dialects and their JDBC drivers.

In addition, the following process applies to customer-hosted Looker deployments only. For Looker-hosted deployments, contact your Looker analyst for assistance.

Configuring Looker to Use Custom JDBC Drivers

For some of Looker’s supported dialects, the JDBC driver cannot be packaged in the Looker JAR file for licensing-related reasons. In these cases, you must install the JDBC driver on your Looker server, then configure Looker to register the custom driver as described below.

Prerequisites

To connect Looker to a database that requires a custom JDBC driver, you will need:

Looker Driver Symbols

These are the driver symbols Looker uses to register JDBC drivers to dialects. For completeness, this list includes all of the dialects, including those that don’t require a custom JDBC driver.

Driver Entries in the YAML Configuration File

Here is an example driver entry in the custom_jdbc_config.yml file:

  - name: driver_symbol
    dir_name: driver_symbol
    module_path: com.dialect.jdbc.DialectDriver
    override_jdbc_url_subprotocol: driver_subprotocol  # optional

When writing the driver entry for your dialect:

jdbc:mysql://localhost:3306/database_name[?propertyName1][=propertyValue1]

Where mysql is the JDBC subprotocol being used.

If you specify override_jdbc_url_subprotocol: driver_subprotocol, then this JDBC string will become:

jdbc:driver_subprotocol://localhost:3306/database_name[?propertyName1][=propertyValue1]

This option is useful if you want to use a custom JDBC driver that requires a URL subprotocol other than Looker’s default URL subprotocol. For the most part, this is not necessary unless the dialect’s documentation explicitly says otherwise. MongoBI is an example of a dialect that requires this option.

Installing Custom JDBC Drivers

  1. Change into the Looker application base directory. For this document we will assume it is looker

    cd looker
    
  2. Create a directory called custom_jdbc_drivers. This is the top-level directory for all custom JDBC driver installations. The path to this directory should be looker/custom_jdbc_drivers

    mkdir custom_jdbc_drivers
    
  3. In the custom_jdbc_drivers directory, create a subdirectory named with your dialect’s driver symbol. This example uses the generic value driver_symbol. The resulting path to the directory will look like looker/custom_jdbc_drivers/driver_symbol

    cd custom_jdbc_drivers
    mkdir driver_symbol
    

  4. Place the JDBC driver files for your dialect into this directory. The method for this depends on where your dialect’s driver can be found and uploaded onto the server, but be sure that the relevant JAR file(s) are inside the driver_symbol directory: looker/custom_jdbc_drivers/driver_symbol/
    For example: looker/custom_jdbc_drivers/driver_symbol/DialectDriver.jar

Moving the necessary files onto the Looker server will vary based on where you get the driver files and your preference for file transferring. Examples of commands for transferring files into this directory are wget, scp, curl, etc.

  1. Change back into the Looker application directory and create a configuration file named custom_jdbc_config.yml. The path to this file should be looker/custom_jdbc_config.yml. This file will contain the information Looker needs to locate and register the custom JDBC driver.

    cd looker
    vim custom_jdbc_config.yml
    
  2. Add a new entry for your dialect into the custom_jdbc_config.yml configuration file. See this section for information on driver entries.

    - name: driver_symbol
      dir_name: driver_symbol
      module_path: com.dialect.jdbc.DialectDriver
    
  3. Create or update the file lookerstart.cfg so that the Looker application starts up with the custom JDBC driver configuration. The path to this file should be looker/lookerstart.cfg. Add the option --use-custom-jdbc-config. If there are other options, append this to the end of the Looker startup options:

    LOOKERARGS="--use-custom-jdbc-config"
    

If you have LOOKERARGS set somewhere other than lookerstart.cfg, like in an environment variable, you may add this startup flag there. Alternatively, you can set LOOKERARGS="${LOOKERARGS} --use-custom-jdbc-config" so that the existing values will be expanded into this file.

  1. Restart the Looker application. In this command, use the name of your Looker startup script, such as ./looker or ./looker.sh

    ./looker restart
    

    or

    ./looker stop
    ./looker start
    

Multiple Custom JDBC Drivers

If you need to configure more than one dialect to use custom JDBC drivers, the above process still applies. The custom_jdbc_drivers directory will have multiple dialect subdirectories with their own driver JARs, and the custom_jdbc_config.yml file will have multiple entries:

ls looker/custom_jdbc_drivers

driver_symbol_1 driver_symbol_2
ls looker/custom_jdbc_drivers/driver_symbol_1

Dialect1Driver.jar
- name: driver_symbol_1
  dir_name: driver_symbol_1
  module_path: com.dialect.jdbc.Dialect1Driver

- name: driver_symbol_2
  dir_name: driver_symbol_2
  module_path: com.dialect.jdbc.Dialect2Driver
Top