## Dialects that use these instructions

MySQL, MariaDB, and SingleStore (formerly MemSQL) share the database setup requirements that are described on this page for connecting Looker to your analytics database. To configure MySQL as the internal backend database for a customer-hosted Looker instance, see [Migrating the Looker backend database to MySQL](https://docs.cloud.google.com/looker/docs/2622/migrating-looker-backend-db-to-mysql.md.txt).

## Encrypting network traffic

It is a best practice to encrypt network traffic between the Looker application and your database. Consider one of the options that are described on the [Enabling secure database access](https://docs.cloud.google.com/looker/docs/2622/enabling-secure-db-access.md.txt) documentation page.

If you're interested in using SSL encryption, see this [MySQL documentation page](https://dev.mysql.com/doc/refman/5.7/en/encrypted-connections.html).

## Users and security

To create and grant the required access to the Looker user, follow the instructions in the section for your database dialect and version.

> [!NOTE]
> **Note:** The Looker **MySQL 8.0.12+** dialect option supports MySQL versions 8.0.12 and later 8.X releases, including MySQL 8.4.X. Patch version 8.0.12 or later is required for [subtotals](https://docs.cloud.google.com/looker/docs/2622/table-options#subtotals) because of a [MySQL deprecation](https://dev.mysql.com/worklog/task/?id=8693) of implicit sorting in the `GROUP BY` clause, which causes SQL generation errors in MySQL versions 8.0.0 through 8.0.11. Upgrade MySQL 8.0.X databases to at least 8.0.12 for full integration.

### MySQL 8.4.X

In MySQL 8.4.X, the default authentication plugin is [`caching_sha2_password`](https://dev.mysql.com/doc/refman/8.4/en/caching-sha2-pluggable-authentication.html), and the [`mysql_native_password`](https://dev.mysql.com/doc/refman/8.4/en/native-pluggable-authentication.html) plugin is deactivated by default. Choose one of the following authentication methods depending on whether SSL is enabled for your Looker connection:

- **When connecting with SSL enabled (recommended):** The Looker JDBC driver supports `caching_sha2_password` over SSL connections without enabling `mysql_native_password`. Select **SSL** when you [create the Looker connection](https://docs.cloud.google.com/looker/docs/2622/db-config-mysql-mariadb-singlestore.md.txt#creating-the-connection-to-your-database), and run the following commands to create the user and grant `SELECT` privileges:

  ```sql
  CREATE USER 'DB_USERNAME'@'%' IDENTIFIED WITH caching_sha2_password BY 'PASSWORD';
  GRANT SELECT ON DATABASE_NAME.* TO 'DB_USERNAME'@'%';
  ```
- **When connecting without SSL enabled:** Because Looker doesn't enable automatic RSA public key retrieval (`allowPublicKeyRetrieval`) on unencrypted customer database connections, you must authenticate with `mysql_native_password`:

  1. Configure the MySQL 8.4.X server to [enable the `mysql_native_password` plugin](https://dev.mysql.com/doc/refman/8.4/en/native-pluggable-authentication.html#native-pluggable-authentication-installation) by using one of the following methods, depending on your deployment:

     - Start the MySQL server with the `--mysql-native-password=ON` flag.
     - Set the property in the [`my.cnf`](https://dev.mysql.com/doc/refman/8.4/en/option-files.html) configuration file:

           [mysqld]
           mysql_native_password=ON

     - For cloud-hosted MySQL 8.4.X instances on Google Cloud, AWS, or Azure, enable the `mysql_native_password` database flag or parameter in your instance configuration or parameter group if it isn't enabled by default, and restart the database instance if required. See your cloud provider's documentation for configuration details.

  2. Create the database user with `mysql_native_password` and grant `SELECT` privileges:

     ```sql
     CREATE USER 'DB_USERNAME'@'%' IDENTIFIED WITH mysql_native_password BY 'PASSWORD';
     GRANT SELECT ON DATABASE_NAME.* TO 'DB_USERNAME'@'%';
     ```

Replace the following placeholders in the preceding commands:

- <var class="edit" scope="DB_USERNAME" translate="no">DB_USERNAME</var>: the username for the Looker database user, such as `looker`
- <var class="edit" scope="PASSWORD" translate="no">PASSWORD</var>: a unique, secure password
- <var class="edit" scope="DATABASE_NAME" translate="no">DATABASE_NAME</var>: the name of your database

### MySQL 8.0.X

In MySQL 8.0.X, the default authentication plugin is `caching_sha2_password`. Looker uses the `mysql_native_password` plugin to authenticate to MySQL 8.0.X databases through the JDBC driver. For MySQL 8.0.X to work properly, complete the following steps:

1. Configure the MySQL database to use the `mysql_native_password` plugin. This can be done in multiple ways, and will depend on how your MySQL 8 database is deployed and what type of access you have to the configuration:

   - Start the process with the flag `--default-auth=mysql_native_password`

   - Set the property in the [`my.cnf`](https://dev.mysql.com/doc/refman/8.0/en/option-files.html) configuration file:

       [mysqld]
       default-authentication-plugin=mysql_native_password

   - If your database instance is hosted through AWS RDS, set the `default_authentication_plugin` parameter through an RDS Parameter Group that is applied to this database instance.
2. Run the following commands, replacing `PASSWORD` with a unique, secure password:

       CREATE USER looker IDENTIFIED WITH mysql_native_password BY 'PASSWORD';
       GRANT SELECT ON database_name.* TO 'looker'@'%';

### MySQL 5.7.X and earlier, MariaDB, and SingleStore:

Run the following commands, replacing `PASSWORD` with a unique, secure password:

```sql
CREATE USER looker;
SET PASSWORD FOR looker = PASSWORD ('PASSWORD');
GRANT SELECT ON database_name.* TO 'looker'@'%';
```

## Temp schema setup for persistent derived tables

These database dialects support the creation of [persistent derived tables (PDTs)](https://docs.cloud.google.com/looker/docs/2622/derived-tables.md.txt#persistent-derived-tables). This feature can be very useful, and we recommend enabling it when possible.

To enable PDTs, you need to configure a temp schema. The following commands show an example of creating a temp database and granting the required privileges to the `looker` user.
> You can specify the name of the temp database in the [**Temp Database**](https://docs.cloud.google.com/looker/docs/2622/connecting-to-your-db.md.txt#temp_database) field when [creating your database connection](https://docs.cloud.google.com/looker/docs/2622/connecting-to-your-db.md.txt). If you don't specify a temp database name, Looker generates a scratch database named `looker_tmp`. The following commands use `looker_tmp`, but if you specified a different temp database name, use your temp database name instead of `looker_tmp`.

```sql
CREATE SCHEMA looker_tmp;
GRANT
  SELECT,
  INDEX,
  INSERT,
  UPDATE,
  DELETE,
  CREATE,
  DROP,
  ALTER,
  CREATE TEMPORARY TABLES
ON looker_tmp.* TO 'looker'@'%';
```

For SingleStore, or if your database uses GTID-based replication, you must use the [`create_process`](https://docs.cloud.google.com/looker/docs/2622/reference/param-view-create-process) LookML parameter to use PDTs, because GTID does not support `CREATE TABLE AS SELECT` statements.

## Alternative setup for regular derived tables

If you don't want to allow the creation of [persistent derived tables](https://docs.cloud.google.com/looker/docs/2622/derived-tables.md.txt#persistent-derived-tables), you can still use [regular derived tables](https://docs.cloud.google.com/looker/docs/2622/derived-tables.md.txt#regular-or-ephemeral-derived-tables). To use regular derived tables, you still need to add certain permissions to a schema called `looker_tmp`. However, the `looker_tmp` schema does not actually need to exist in your database!

```sql
GRANT
  SELECT,
  INDEX,
  INSERT,
  DROP,
  CREATE TEMPORARY TABLES
ON looker_tmp.* TO 'looker'@'%';
-- Note that the looker_tmp schema does not need to actually exist,
-- even though these permission grants are still needed
```

## Setting the `max_allowed_packet` variable

For MySQL, set the MySQL `max_allowed_packet` variable to its maximum value, 1073741824, to prevent "SQLException: Packet for query is too large" errors.

## Creating the Looker connection to your database

After completing the database configuration, you can connect to the database from Looker. Follow these steps to create the connection from Looker to your database:

1. In the **Admin** section of Looker, select **Connections** , and then click **Add Connection**.
2. From the **Dialect** drop-down menu, select your database dialect name: **MySQL** , **MySQL 8.0.12+** (for MySQL 8.0.12 and later 8.X versions, including MySQL 8.4.X), **MariaDB** , **SingleStore** , or **SingleStore 7+**.

   > [!NOTE]
   > **Note:** If you are on a [Looker (Google Cloud core)](https://docs.cloud.google.com/looker/docs/looker-core-overview.md.txt) instance and you don't see your dialect listed in the **Dialect** drop-down menu, see the [Looker (Google Cloud core) documentation](https://docs.cloud.google.com/looker/docs/looker-core-dialects.md.txt#supported_dialects_for) to verify that the dialect is supported for Looker (Google Cloud core) instances.

3. Fill out the connection details. The majority of the settings are common to most database dialects. See the [Connecting Looker to your database](https://docs.cloud.google.com/looker/docs/2622/connecting-to-your-db.md.txt) documentation page for information.

4. To verify that the connection is successful, click the **Test Connection** button in the **Status details** section at the bottom of the **Connections Settings** page.

5. If Looker displays **Can Connect** , press **Connect** to create the connection.

Your database connection is then added to the list on the Looker [**Connections**](https://docs.cloud.google.com/looker/docs/2622/admin-panel-database-connections.md.txt) **Admin** page.

## Supported JDBC parameters

For MySQL, MariaDB, and SingleStore, Looker supports the following JDBC parameters in the [**Additional JDBC parameters**](https://docs.cloud.google.com/looker/docs/2622/connecting-to-your-db.md.txt#additional_jdbc_parameters) field for the connection. See the documentation for your database for information on these parameters.

- `allowMultiQueries`
- `autocommit`
- `characterSetResults`
- `clientCertificateKeyStorePassword`
- `clientCertificateKeyStoreUrl`
- `connectionAttributes`
- `connectionCollation`
- `connectionTimeZone`
- `connectTimeout`
- `defaultAuthenticationPlugin`
- `disableSslHostnameVerification`
- `disconnectOnExpiredPasswords`
- `enabledSslCipherSuites`
- `failOverReadOnly`
- `fallbackToSystemTrustStore`
- `forceConnectionTimeZoneToSession`
- `interactiveClient`
- `lookerFailover`
- `maxIdleTime`
- `maxQuerySizeToLog`
- `oldModeNoPrecisionTimestamp`
- `password`
- `passwordCharacterEncoding`
- `permitMysqlScheme`
- `pinGlobalTxToPhysicalConnection`
- `preserveInstants`
- `queryInterceptors`
- `restrictedAuth`
- `rewriteBatchedStatements`
- `socketTimeout`
- `sslMode`
- `tcpKeepAlive`
- `trustCertificateKeyStorePassword`
- `trustCertificateKeyStoreUrl`
- `useCompression`
- `usePipelineAuth`
- `user`
- `useServerPrepStmts`
- `verifyServerCertificate`
- `yearIsDateType`

## Feature support

For Looker to support some features, your database dialect must also support them.

MySQL supports the following features as of Looker 26.22:

| Feature | Supported? |
|---|---|
| Looker (Google Cloud core) | No |
| Symmetric aggregates | Yes |
| Derived tables | Yes |
| Persistent SQL derived tables | Yes |
| Persistent native derived tables | Yes |
| Stable views | Yes |
| Query killing | Yes |
| SQL-based pivots | Yes |
| Time zones | Yes |
| SSL | Yes |
| Subtotals | Yes |
| JDBC additional params | Yes |
| Case-sensitive | No |
| Location type | Yes |
| List type | Yes |
| Percentile | Yes |
| Distinct percentile | Yes |
| SQL Runner Show Processes | Yes |
| SQL Runner Describe Table | Yes |
| SQL Runner Show Indexes | Yes |
| SQL Runner Select 10 | Yes |
| SQL Runner Count | Yes |
| SQL Explain | Yes |
| OAuth 2.0 credentials | No |
| Context comments | Yes |
| Connection pooling | No |
| HLL sketches | No |
| Aggregate awareness | Yes |
| Incremental PDTs | Yes |
| Milliseconds | Yes |
| Microseconds | Yes |
| Materialized views | No |
| Period-over-period measures | No |
| Approximate count distinct | No |
| In-database analytic models | No |
| Custom calendars | Yes |

MySQL 8.0.12+ supports the following features as of Looker 26.22:

| Feature | Supported? |
|---|---|
| Looker (Google Cloud core) | Yes |
| Symmetric aggregates | Yes |
| Derived tables | Yes |
| Persistent SQL derived tables | Yes |
| Persistent native derived tables | Yes |
| Stable views | Yes |
| Query killing | Yes |
| SQL-based pivots | Yes |
| Time zones | Yes |
| SSL | Yes |
| Subtotals | Yes |
| JDBC additional params | Yes |
| Case-sensitive | No |
| Location type | Yes |
| List type | Yes |
| Percentile | Yes |
| Distinct percentile | Yes |
| SQL Runner Show Processes | Yes |
| SQL Runner Describe Table | Yes |
| SQL Runner Show Indexes | Yes |
| SQL Runner Select 10 | Yes |
| SQL Runner Count | Yes |
| SQL Explain | Yes |
| OAuth 2.0 credentials | No |
| Context comments | Yes |
| Connection pooling | No |
| HLL sketches | No |
| Aggregate awareness | Yes |
| Incremental PDTs | Yes |
| Milliseconds | Yes |
| Microseconds | Yes |
| Materialized views | No |
| Period-over-period measures | Yes |
| Approximate count distinct | No |
| In-database analytic models | No |
| Custom calendars | Yes |

MariaDB supports the following features as of Looker 26.22:

| Feature | Supported? |
|---|---|
| Looker (Google Cloud core) | Yes |
| Symmetric aggregates | Yes |
| Derived tables | Yes |
| Persistent SQL derived tables | Yes |
| Persistent native derived tables | Yes |
| Stable views | Yes |
| Query killing | Yes |
| SQL-based pivots | No |
| Time zones | Yes |
| SSL | Yes |
| Subtotals | Yes |
| JDBC additional params | Yes |
| Case-sensitive | No |
| Location type | Yes |
| List type | Yes |
| Percentile | Yes |
| Distinct percentile | Yes |
| SQL Runner Show Processes | Yes |
| SQL Runner Describe Table | Yes |
| SQL Runner Show Indexes | Yes |
| SQL Runner Select 10 | Yes |
| SQL Runner Count | Yes |
| SQL Explain | Yes |
| OAuth 2.0 credentials | No |
| Context comments | Yes |
| Connection pooling | No |
| HLL sketches | No |
| Aggregate awareness | Yes |
| Incremental PDTs | No |
| Milliseconds | Yes |
| Microseconds | Yes |
| Materialized views | No |
| Period-over-period measures | No |
| Approximate count distinct | No |
| In-database analytic models | No |
| Custom calendars | Yes |

SingleStore supports the following features as of Looker 26.22:

| Feature | Supported? |
|---|---|
| Looker (Google Cloud core) | No |
| Symmetric aggregates | Yes |
| Derived tables | Yes |
| Persistent SQL derived tables | Yes |
| Persistent native derived tables | Yes |
| Stable views | Yes |
| Query killing | Yes |
| SQL-based pivots | Yes |
| Time zones | Yes |
| SSL | Yes |
| Subtotals | Yes |
| JDBC additional params | Yes |
| Case-sensitive | No |
| Location type | Yes |
| List type | Yes |
| Percentile | No |
| Distinct percentile | No |
| SQL Runner Show Processes | Yes |
| SQL Runner Describe Table | Yes |
| SQL Runner Show Indexes | Yes |
| SQL Runner Select 10 | Yes |
| SQL Runner Count | Yes |
| SQL Explain | Yes |
| OAuth 2.0 credentials | No |
| Context comments | Yes |
| Connection pooling | No |
| HLL sketches | No |
| Aggregate awareness | Yes |
| Incremental PDTs | No |
| Milliseconds | Yes |
| Microseconds | Yes |
| Materialized views | No |
| Period-over-period measures | No |
| Approximate count distinct | No |
| In-database analytic models | No |
| Custom calendars | No |

SingleStore 7+ supports the following features as of Looker 26.22:

| Feature | Supported? |
|---|---|
| Looker (Google Cloud core) | Yes |
| Symmetric aggregates | Yes |
| Derived tables | Yes |
| Persistent SQL derived tables | Yes |
| Persistent native derived tables | Yes |
| Stable views | Yes |
| Query killing | Yes |
| SQL-based pivots | Yes |
| Time zones | Yes |
| SSL | Yes |
| Subtotals | Yes |
| JDBC additional params | Yes |
| Case-sensitive | No |
| Location type | Yes |
| List type | Yes |
| Percentile | Yes |
| Distinct percentile | No |
| SQL Runner Show Processes | Yes |
| SQL Runner Describe Table | Yes |
| SQL Runner Show Indexes | Yes |
| SQL Runner Select 10 | Yes |
| SQL Runner Count | Yes |
| SQL Explain | Yes |
| OAuth 2.0 credentials | No |
| Context comments | Yes |
| Connection pooling | No |
| HLL sketches | No |
| Aggregate awareness | Yes |
| Incremental PDTs | No |
| Milliseconds | Yes |
| Microseconds | Yes |
| Materialized views | No |
| Period-over-period measures | No |
| Approximate count distinct | No |
| In-database analytic models | No |
| Custom calendars | No |