Power BI Service with MotherDuck

Power BI is an interactive data visualization product developed by Microsoft. You can connect Power BI to MotherDuck through the built-in PostgreSQL database connector using MotherDuck's Postgres endpoint.

Preview

The Postgres endpoint is in preview. Features and behavior may change.

Power BI Service is the cloud-based version of Power BI that lets you publish, share, and schedule refreshes for reports and dashboards. To connect Power BI Service to MotherDuck, you need a Microsoft On-Premises Data Gateway that bridges the cloud service to MotherDuck's Postgres endpoint.

Both Import and DirectQuery modes work through the gateway.

Before you start

You'll need:

• A published .pbix report connected to MotherDuck through the Power BI Desktop setup
• A Power BI Pro or Premium Per User license (required for sharing reports and using the standard gateway)
• A MotherDuck access token
• A Windows machine to host the gateway (see Microsoft's gateway requirements)

Install the gateway

1. Download the standard gateway installer from Microsoft's gateway download page. Download the standard (enterprise) gateway, not the personal mode gateway.

2. Run the installer and accept the default installation path.

3. After installation, the configuration wizard opens. Sign in with your Microsoft work or school account (the one associated with your Power BI tenant).

4. Select Register a new gateway on this computer.

5. Enter a gateway name (for example, MD-PG-Gateway) and a recovery key. Store the recovery key securely.

6. Click Configure and wait for registration to complete.

Verify: The configuration wizard shows "The gateway is online and ready to be used." The Windows service On-premises data gateway service should be running in services.msc.

Add a MotherDuck data source

1. In Power BI Service, click the Settings gear and select Manage connections and gateways.

2. Verify your gateway shows Online.

3. Click + New and select On-premises.

4. Fill in the connection details:

   Field	Value
   Gateway cluster name	Select your gateway
   Connection name	A descriptive name (for example, MotherDuck-PG-sample_data)
   Data Source Type	PostgreSQL
   Server	Your Postgres host (for example, pg.us-east-1-aws.motherduck.com)
   Database	Your MotherDuck database name
   Authentication method	Basic
   Username	postgres
   Password	Your MotherDuck access token
   Encrypted Connection	Checked
   Privacy Level	Organizational

   
   

5. Click Create.

warning

The Server and Database values must match your .pbix file character-for-character. If they differ, the published dataset won't find the gateway data source.

Publish and connect a report

1. In Power BI Desktop, publish your report: File > Publish > Publish to Power BI and select a workspace.

2. In Power BI Service, go to the workspace and find the semantic model (dataset).

3. Open Settings for the semantic model and expand Gateway and cloud connections.

4. Map the connection to your gateway data source.

   

5. Under Data source credentials, click Edit credentials and enter:

   • Authentication method: Basic
   • User name: postgres
   • Password: Your MotherDuck access token
   • Encrypted connection: Checked

6. Click Sign in.

Set up scheduled refresh

For reports using Import mode, you can configure automatic data refreshes.

1. In the semantic model settings, expand Refresh.

2. Toggle Keep your data up to date to On.

3. Set your refresh frequency and time zone.

4. Click Apply.

To verify, trigger a manual refresh: open the semantic model's three-dot menu and select Refresh now. All steps should complete with green check marks.

DirectQuery through the gateway

For reports using DirectQuery mode, queries run against MotherDuck in real time through the gateway. No scheduled refresh is needed since data is always live.

After publishing and mapping the gateway data source (steps above), DirectQuery reports work automatically in Power BI Service.

Connection parameters

Parameter	Value
Server	pg.<region>-aws.motherduck.com (find yours at Postgres settings)
Database	Your database name
Username	postgres
Password	Your MotherDuck access token
Encrypted Connection	Checked

Troubleshooting

Gateway shows offline

Check the gateway machine is on, connected to the network, and the On-premises data gateway service Windows service is running. Restart the service if needed.

Firewall blocking port 5432

If Test-NetConnection -ComputerName pg.us-east-1-aws.motherduck.com -Port 5432 returns TcpTestSucceeded: False, add an outbound firewall rule allowing TCP 5432 to the MotherDuck Postgres host.

SSL/TLS handshake failure

MotherDuck uses certificates from a publicly trusted CA, so the gateway should trust them by default. If you see "The remote certificate is invalid," run Windows Update to refresh the root CA store, or manually import the ISRG Root X1 certificate into the machine-level Trusted Root Certification Authorities store. After importing, restart the gateway service.

Credential errors

• The username must be postgres.
• The password is your MotherDuck access token (starting with md_), not your web UI password.
• Check for trailing whitespace in the token.

Published dataset doesn't see the gateway

The Server and Database values in the gateway data source must match the .pbix file exactly, including case. Recreate the data source with the correct values if they differ.

Additional information

• Postgres endpoint reference for connection parameters, SSL options, and limitations
• Connect through the Postgres endpoint for a general how-to guide
• Microsoft gateway documentation
• Power BI Service documentation