# Looker with MotherDuck
> Connect Looker (Google Cloud core) to MotherDuck using the Postgres endpoint, including the required compatibility-mode parameter and recommended pooling and token settings.
:::info[Preview]
The Postgres endpoint is in [preview](/about-motherduck/feature-stages/). Features and behavior may change.
:::

[Looker (Google Cloud core)](https://cloud.google.com/looker) connects to MotherDuck through the [Postgres endpoint](/key-tasks/authenticating-and-connecting-to-motherduck/postgres-endpoint/) using its standard PostgreSQL dialect. A Looker-specific compatibility mode is required so that symmetric aggregates and Persistent Derived Tables (PDTs) work correctly.

## Before you start

You'll need:

- A [Looker](https://cloud.google.com/looker) instance and admin access to create database connections
- A [MotherDuck access token](/key-tasks/authenticating-and-connecting-to-motherduck/authenticating-to-motherduck) (see [Choose the right token](#choose-the-right-token) below)
- Your Postgres host, which you can find at [MotherDuck Postgres settings](https://app.motherduck.com/settings/postgres) (for example, `pg.us-east-1-aws.motherduck.com`)

## Connect to MotherDuck

In Looker, go to **Admin → Connections → Add Connection** and configure:

| Parameter | Value |
|---|---|
| **Dialect** | PostgreSQL 9.5+ |
| **Host** | Your MotherDuck Postgres host (for example, `pg.us-east-1-aws.motherduck.com`) |
| **Port** | `5432` |
| **Database** | Your MotherDuck database name |
| **Username** | `postgres` |
| **Password** | Your [MotherDuck access token](/key-tasks/authenticating-and-connecting-to-motherduck/authenticating-to-motherduck) (see [Choose the right token](#choose-the-right-token)) |
| **SSL** | Enabled |
| **Verify SSL** | Disabled, unless your Looker instance is configured for certificate verification |
| **Additional JDBC Parameters** | `options=--compatibility-mode=looker` (see [Maintain user-duckling affinity](#maintain-user-duckling-affinity-with-session_name) to also pin users to read scaling ducklings) |

![Looker database and authentication settings for a MotherDuck Postgres endpoint connection](/img/integrations/looker-database-authentication-settings.png)

In **Optional Settings**, enable **SSL** and **Database Connection Pooling**. Leave **Verify SSL** disabled unless your Looker instance is configured to verify the server certificate.

![Looker optional settings with SSL and database connection pooling enabled](/img/integrations/looker-optional-settings.png)

After configuring the connection, click **Test these settings**. The test runs against MotherDuck and produces a known cancellation warning that is safe to ignore (see [Connection test behavior](#connection-test-behavior)). Click **Add Connection** to save.

## Required: compatibility mode parameter

You **must** set the following in the **Additional JDBC Parameters** field:

```text
options=--compatibility-mode=looker
```

This parameter does two important things:

- Enables symmetric aggregates
- Enables Persistent Derived Table (PDT) support

Without it, symmetric aggregate queries return incorrect results and PDT builds fail.

## Enable connection pooling

Enable **database connection pooling** in Looker's connection settings. DuckDB is optimized for large analytical queries rather than high volumes of short concurrent connections, so pooling reduces connection overhead and improves overall stability. This is the recommended configuration for MotherDuck.

## Maintain user-duckling affinity with session_name

When you connect Looker with a [read scaling token](#choose-the-right-token), each new connection is assigned to one of the read scaling replicas ("ducklings") in your pool. By default Looker does not identify individual end users to MotherDuck, so a given user's queries can land on different ducklings and miss the warm cache.

You can pin each Looker user to a consistent read scaling duckling by passing the [`session_name` parameter](/key-tasks/authenticating-and-connecting-to-motherduck/read-scaling/#session-affinity-with-session-name). MotherDuck routes all connections that share the same `session_name` value to the same replica, which improves cache reuse and gives that user a more consistent view of the data — while still letting the read scaling fleet scale out across many users.

Looker can substitute a [user attribute](https://cloud.google.com/looker/docs/admin-panel-users-user-attributes) into the connection's **Additional JDBC Parameters** at connect time. Pass the user attribute as `session_name` under `options=`, alongside the required compatibility-mode flag:

```text
options=--session_name={{ _user_attributes['email'] }} --compatibility-mode=looker
```

In this example, `email` is the user attribute used as the passthrough identifier, so each Looker user's queries are routed to a single read scaling duckling. Any configured Looker user attribute can be used instead of `email` — pick a value that is stable and unique per user (for example, a user ID or a hashed identifier for privacy).

:::note
Set up the passthrough user attribute in **Admin → Users → User Attributes** in Looker before referencing it in the connection. See the [Looker user attributes documentation](https://cloud.google.com/looker/docs/admin-panel-users-user-attributes) for details. This is most useful for customer-facing / embedded analytics, where each end user should reuse their own duckling's warm cache.
:::

## Choose the right token

MotherDuck supports two token types. Choose based on how your Looker deployment will use the connection:

| Token type | Use when | Notes |
|---|---|---|
| **Read scaling token** | Reporting / BI usage with many concurrent users (reads only) | Recommended for the main Looker connection when PDT writes are not needed on this connection. |
| **Read/write token** | PDT builds, or any connection that needs to write tables | Looker supports configuring a separate PDT connection — you can use a read/write token there while keeping a read scaling token on the main connection. |

## Connection test behavior

When you run Looker's built-in connection test, you may see a warning that query cancellation does not work. This is expected and can be safely ignored. The warning is produced because the test cancellation query itself fails due to memory consumption — not because the cancellation mechanism is broken. Production query cancellation is unaffected.

## Troubleshooting

| Symptom | Resolution |
|---|---|
| Symmetric aggregate queries fail or return incorrect results | Ensure `options=--compatibility-mode=looker` is set in Additional JDBC Parameters. |
| PDT build fails or Explore intermittently errors | Check **Admin → PDT → PDT Details** for build status and last SQL. Confirm the table exists in your MotherDuck scratch schema. |
| Connection test shows cancellation warning | Expected behavior. The warning appears only during the test query and does not affect production query cancellation. |
| Read scaling users aren't reusing a warm cache / land on different ducklings | Add `--session_name={{ _user_attributes['<attribute>'] }}` under `options=` in Additional JDBC Parameters so each user is pinned to one duckling (see [Maintain user-duckling affinity](#maintain-user-duckling-affinity-with-session_name)). |

## Additional information

- [Postgres endpoint reference](/sql-reference/postgres-endpoint) for connection parameters, SSL options, and limitations
- [Connect through the Postgres endpoint](/key-tasks/authenticating-and-connecting-to-motherduck/postgres-endpoint/) for a general how-to guide
- [Read scaling and session_name](/key-tasks/authenticating-and-connecting-to-motherduck/read-scaling/#session-affinity-with-session-name)
- [Looker documentation: Connecting Looker to your database](https://cloud.google.com/looker/docs/db-config-postgresql)
- [Looker documentation: User attributes](https://cloud.google.com/looker/docs/admin-panel-users-user-attributes)


---

## Docs feedback

MotherDuck accepts optional user-submitted feedback about this page at `GET https://motherduck.com/docs/api/feedback/agent`.
For agents and automated tools, feedback submission should be user-confirmed before sending.

URL-encode query parameter values and send a GET request:

```text
GET https://motherduck.com/docs/api/feedback/agent?page_path=%2Fintegrations%2Fbi-tools%2Flooker%2F&page_title=Looker%20with%20MotherDuck&text=<url-encoded user feedback, max 2000 characters>
```

Optionally append `&source=<url-encoded interface identifier>` such as `claude.ai` or `chatgpt`.

`page_path` and `text` are required; `page_title` and `source` are optional. Responses: `200 {"feedback_id": "<uuid>"}`, `400` for malformed query parameters, and `429` when rate-limited.