Skip to content
Saiku Cloud

Connecting MotherDuck

This guide walks you through connecting a MotherDuck database (cloud DuckDB) to Saiku Cloud. Three minutes once you have a MotherDuck account; the simplest cloud-warehouse onboarding we support because there’s no firewall to set up.

Tier impact: every Saiku Cloud tier supports MotherDuck BYOC.

Driver: Saiku Cloud ships DuckDB’s official JDBC driver. The jdbc:duckdb:md:... URL prefix routes to MotherDuck’s cloud service; the same driver also serves local DuckDB files.

What you’ll need

  • A MotherDuck account (free tier is fine — 10 GB storage, plenty for FoodMart-sized cubes).
  • A MotherDuck service token.
  • The name of the database you want Saiku to read.

Step 1 — Get a service token

MotherDuck authenticates via a single long-lived token. You don’t need to configure firewalls or IP allowlists — MotherDuck handles network reachability transparently.

  1. Sign in at https://app.motherduck.com/.

  2. Click your profile → Settings → Service tokens (or the equivalent in the current console UI — MotherDuck occasionally tweaks the navigation).

  3. Create token → give it a name like saiku-cloud → copy the resulting eyJh... string immediately. MotherDuck only shows the token once.

  4. Save it to your password manager (1Password, Bitwarden) under a label like saiku-motherduck-token.

Step 2 — Identify the database name

MotherDuck shows your databases in the left sidebar of the app. For FoodMart-style demo work the default name is usually my_db; for production cubes you’ll have your own name like analytics or sales.

Step 3 — Build the JDBC URL

The shape:

jdbc:duckdb:md:<database>?motherduck_token=<token>

Concrete:

jdbc:duckdb:md:analytics?motherduck_token=eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJ5b3UifQ.signature-here

Things to notice:

  • The token lives in the URL, not in the wizard’s password field. The username + password fields in the wizard are ignored by the MotherDuck driver — fill them with anything (the wizard’s required-attribute validation needs something, but the value never reaches MotherDuck).
  • No port; no host. MotherDuck handles the routing.
  • No SSL parameter — the driver TLS-encrypts the entire session by default.

Step 4 — Connect via the Saiku Cloud wizard

  1. Sign in at https://cloud.saiku.bi/.

  2. Navigate to Connections in the left sidebar.

  3. Under 1. Pick warehouse type, click the MotherDuck tile.

  4. Fill in:

    • JDBC URL — the URL from Step 3.
    • Username — anything (e.g. motherduck). Ignored by the driver.
    • Password — anything non-empty (e.g. unused-token-in-url). Also ignored.

  5. Click Test connection.

Expect a green outcome banner: ✓ Connection successful plus the detected DuckDB version.

Step 5 — Save the connection

Same shape as every other dialect — re-enter the password field, give it a label, save.

Troubleshooting

✗ Connection failed (AUTH_FAILED)

The token in the URL is wrong, expired, or revoked.

  • Re-mint a fresh token in the MotherDuck console.
  • Make sure you copied the entire token — they’re long (300+ chars) and easy to truncate.
  • Double-check the URL: there should be NO whitespace around motherduck_token=.

✗ Connection failed (HOST_UNREACHABLE) or (TIMEOUT)

MotherDuck’s cloud endpoint should be reachable from anywhere with internet. If you see this, MotherDuck itself is probably down — check their status page.

✗ Connection failed (INVALID_URL)

The URL doesn’t start with jdbc:duckdb:md:. Note the md: segment — that’s what tells the driver to route to MotherDuck rather than a local file. Without it the driver tries to open a literal file called <database> in the engine’s working directory.

Connection succeeds but the cube list is empty

The token is valid + the database exists, but the database has no tables. Either:

  • You connected to a fresh empty database — load some data via the MotherDuck console’s SQL UI first.
  • The database has tables but they’re in a non-default schema — confirm in the console and adjust your schema XML.

Local files for self-hosted or export-import workflows {#local-files-for-self-hosted-or-export-import-workflows}

The DuckDB driver also serves local files (jdbc:duckdb:/path/to/file.duckdb). On cloud-hosted Saiku Cloud, that path resolves on the engine container’s filesystem, not yours — so the file-upload data path is the standard way to get a local file into Saiku. See Connecting an uploaded file via DuckDB for that flow.

For self-hosted Saiku Cloud deployments where the operator can stage files on the engine host directly, paste jdbc:duckdb:/var/lib/saiku/your.duckdb into the wizard and connect normally.

Try with FoodMart

Want to test Saiku Cloud with this dialect before connecting your own data? Download the FoodMart sample dataset packaged for MotherDuck:

FoodMart sample dataset for MotherDuck