User Guide Getting Started Help Center Documentation Community Training
Looker
Connections

The Connections page lists all of the database connections that you have configured for Looker use.

Viewing Connections

This page shows basic information about the connections you’ve defined and lets you test the status of those connections:

Column Description
Name The name of the connection, chosen by you, that is used in the connection LookML parameter. When you test the connection, Looker displays the list of status checks under the connection name.
Host:Port The host path where your database is located, and the port that Looker will use to connect to that host.
Username The username that Looker will use to connect to the database.
Database The name of the database that Looker will query when using this connection.
SSL Whether or not you are using SSL encryption to protect the data traveling between Looker and your database (please note there are other secure options that are not SSL).
Type The SQL dialect of the database connection.
Actions Actions you can take for a connection: test a connection, edit a connection, view other information about a connection, jump to a list of links to the connection’s Explores, or delete a connection.

Testing Connections

Looker lets you test your connections to make sure they are functioning properly. Each connection test includes a list of status checks to tell you whether or not Looker can successfully use the database connection. For example:

Potential issues are shown in yellow, while errors are shown in red.

You can check the status of:

Two checks are common cause for confusion:

These checks do not need to pass in order for Looker to function. However, you will need them to pass in order to use persistent derived tables, which are a very valuable modeling feature.

Adding Connections

To add a connection, click the New Database Connection button in the upper left of the page. Looker displays the Connections Settings page:

The fields Looker displays depends on your dialect setting.

For more information about applying user attributes to connection settings, see the “Connections” section of the User Attributes page.

For more information about using the PDT Overrides column to configure separate login credentials for PDT processes, see this section.

Connection Settings

The following options may be available for configuration, depending on your SQL dialect:

Name

The name of the connection as you want to refer to it. You should not use spaces. This value does not need to match anything in your database, it is just a label that you assign. You’ll use it in the connection parameter of your LookML model.

Dialect

The SQL dialect that matches your connection. It’s important to choose the correct value so that you are presented with the proper connection options, and so Looker can translate your LookML into SQL properly.

Host : Port

Your database host name, and the port that Looker should use to connect to your database host.

If you apply a user attribute to the Host field, the user attribute cannot have a user access level set to Editable.

Database

The name of the database on your host. For example, you might have a host name of my-instance.us-east-1.redshift.amazonaws.com on which there is a database called sales_info. You would enter sales_info in this field. If you have multiple databases on the same host, you may need to create multiple connections to use them (with the exception of MySQL, in which the word “database” means something a little bit different than most SQL dialects).

Username

The username that Looker should use to connect to your database. You should configure the user ahead of time according to the instructions in our database configuration instructions.

Password

The password that Looker should use to connect to your database. You should configure the password ahead of time according to the instructions in our database configuration instructions.

Schema

The default schema that Looker uses when a schema is not specified. This includes when using SQL Runner, during LookML project generation, and when querying tables.

Persistent Derived Tables

Check this box to enable persistent derived tables. This reveals the Temp Database field and the PDT Overrides column. Looker displays this option only if the database dialect you chose supports using PDTs.

Temp Database

Though labeled “temp database”, you’ll enter either the database name or schema name — as appropriate for your SQL dialect — that Looker should use to create persistent derived tables. You should configure this database or schema ahead of time, with the appropriate write permissions. On the Database Configuration Instructions page, select your database dialect to see the instructions for that dialect.

Each connection must have its own temp database or schema; they cannot be shared across connections.

Additional Params

You can include additional JDBC parameters for your queries here, if needed.

If you want to use a user attribute in a JDBC parameter, you can use liquid templating. The syntax is _user_attributes['name_of_your_user_attribute']. You must include a space after the opening {{ and before the closing }}. For example:

my_jdbc_param={{ _user_attributes['name_of_attribute'] }}

Here’s how it might look in the Additional Params field in Looker:

PDT and Datagroup Maintenance Schedule

This setting accepts a cron expression that indicates when Looker should check datagroups and persistent derived tables (that are based on sql_trigger_value) to be regenerated or dropped. The default value of */5 * * * * means “check every 5 minutes”. The maximum frequency of checks is every 5 minutes. A cron expression indicating more frequent checks will cause checks to occur every 5 minutes.

For additional details, read this Community topic about this feature.

SSL

Choose whether or not you want to use SSL encryption to protect data as it passes between Looker and your database. SSL is only one option that can be used to protect your data; other secure options are described here.

Verify SSL Cert

Choose whether you want to require verification of the SSL certificate used by the connection. If verification is required, the SSL Certificate Authority (CA) that signed the SSL certificate must come from the client’s list of trusted sources. If the CA is not a trusted source, the database connection is not established.

If this box is unchecked, SSL encryption is still used on the connection, but verification of the SSL connection is not required, so a connection can be established when the CA is not on the client’s list of trusted sources.

Max Connections

Here you can set the maximum number of connections that Looker can establish with your database. For the most part, you are setting the number of simultaneous queries that Looker can run against your database. Looker also reserves up to three connections for query killing. If the connection pool is very small, then Looker will reserve fewer connections.

You should set this value carefully. If the value is too high, you may overwhelm your database. If the value is too low, then queries have to share a small number of connections. Thus many queries may seem slow to users as the queries have to wait for other, earlier queries to return.

The default value (which varies depending upon your SQL dialect) is typically a reasonable starting point. Most databases also have their own settings for the maximum number of connections they will accept. If your database configuration limits connections, ensure that your Max Connections value is equal to or lower than your database’s limit.

Connection Pool Timeout

If your users do request more connections than the Max Connections setting, the requests will wait for others to finish before they are executed. The maximum amount of time that a request will wait is configured here. You should set this value carefully. If it is too low, users may find their queries get cancelled because there isn’t enough time for other user’s queries to finish. If it is too high, large numbers of queries may build up causing users to wait for a very long time. The default value is typically a reasonable starting point.

SQL Runner Precache

In SQL Runner, all table information is pre-loaded as soon as you select a connection and schema. This enables SQL Runner to quickly display table columns as soon as you click on a table name. However, for connections and schema with many tables or with very large tables, you may not want SQL Runner to pre-load all of the information.

If you prefer SQL Runner to load table information only when a table is selected, you can uncheck the SQL Runner Precache option to disable SQL Runner pre-loading for the connection.

Database Time Zone

The time zone in which your database stores time-based information. Looker needs to know this so that it can convert time values for users, making it easier to understand and use time-based data. See the Using Time Zone Settings documentation page for more information.

Query Time Zone

The Query Time Zone option is visible only if you have disabled User Specific Time Zones.

When User Specific Time Zones are disabled, the Query Time Zone is the time zone that is displayed to your users when they query time-based data, and the time zone into which Looker will convert time-based data from the Database Time Zone.

See the Using Time Zone Settings documentation page for more information.

Configuring Separate Login Credentials for PDT Processes

If your database supports persistent derived tables, and you have checked the Persistent Derived Tables box in the connection settings, Looker displays the PDT Overrides column. In the PDT Overrides column, you can enter separate JDBC parameters (host, port, database, username, password, schema, and additional parameters) that are specific to persistent derived table (PDT) processes. This can be valuable for a number of reasons:

For example, the configuration below shows a connection where the username and password fields are set to user attributes. This way, each user can access the database using their individual credentials. The PDT Override column creates a separate user (pdt_user) with its own password. The pdt_user account will be used for all PDT processes, with access levels appropriate to PDT creation and update:

In most cases, we recommend that you write your PDTs to the same database as your default connection. It is possible to use the PDT Overrides column to configure PDT processes to write to a separate database. However, if the PDTs are not visible to your default connection, you won’t be able to query them.

Editing Connections

To edit an existing connection, click the Edit button to the far right of a connection. You’ll be brought to same page that you use to create a connection (described above), but with the relevant information already filled out. Make any changes you need to, then click Update Connection.

Other Connection Options

You’ll notice there is also a gear drop-down menu to the far right of a connection. It offers the following options:

Show Tables

This option brings you to a Looker Explore page that lets you create Looker reports based on the metadata of your connection. Although this option begins with the schema name, table name, and column count selected, you can manipulate it just like any other Looker report.

Show Databases

This option brings you to a Looker Explore page that lets you create Looker reports based on the metadata of your connection. Although this option begins with the schema name, catalog name, table count, and column count selected, you can manipulate it just like any other Looker report.

Show Processes

This option brings you to a Looker Explore page that lets you create Looker reports based on the processes running on this connection, the state they are in, how long they have been running, and other info. This can be useful in helping determine the cause if Looker is running slow, or if a query is not running at all.

Show PDT Event Log

This option brings you to a Looker Explore page that lets you create Looker reports based on the derived table activity for this connection. The available fields are described in more detail on our PDTs page.

SQL Runner

This option brings you to Looker’s SQL Runner, with the proper connection and schema already selected.

Explore

This option brings you to a list of basic, automatically-generated Explore options for your connection. These are not based on your customized data models, but they enable some quick reporting on the raw data in your connection’s tables. This is typically only useful for getting an idea of table contents before modeling, rather than for actual data analysis purposes.

Deleting Connections

To delete an existing connection, click the gear drop-down menu to the far right of a connection and select Delete. You’ll be given the opportunity to confirm the deletion but, once you do so, it cannot be undone. Accidentally deleting a connection will disable any queries that use it. However, as long you re-create a new connection with the same name, functionality will be restored.

Top