Skip to main content

FAQ

What's the difference between .open md: & ATTACH 'md:' ?​

.open initiates a new database connection (to a given database or my_db by default) and can be passed different parameters in the connection strings like motherduck_token or saas_mode flag. If you have previous local database attached, it will be detached when using .open. ATTACH keeps the current database connection and attaches a new motherduck (cloud) database(s) to the current connection. You'll need to use USE to select the database you want to query.

How do I know which version of DuckDB I should be running ?​

MotherDuck currently supports DuckDB 1.1.3 and it is compatible with any client version 0.10.2 through 1.1.3

Check that you have a compatible version of DuckDB running locally.

How do I know which version of DuckDB am I running?​

You can use the VERSION pragma to find out which version of DuckDB you are running

PRAGMA VERSION;

I changed database/table structure outside of the current session; why can't I see the changes?​

While catalog changes done in the current DuckDB session will be reflected immediately, external changes will not. Instead, MotherDuck will fetch the refreshed catalog with the next remote or hybrid query.

An easy way to trigger the local catalog refresh is to run select * from [EXISTING_DATABASE].[EXISTING_TABLE] limit 1 against one of your MotherDuck tables.

See the Hybrid execution section for a full explanation of which queries get processed in MotherDuck, and which are local-only.

How do I know what's executed locally and what's executed remote ?​

If you run an explain on your query, you will see the phyical plan. Each operation is followed by either (L)= Local or (R)= Remote as shown in the query plan example below.

EXPLAIN [Your Query]

explain-sample

note

The explain output will resemble the regular DuckDB explain output, with two main differences:

  • Operations that run locally are marked as (L), and operations running remotely on the MotherDuck service are marked as (R).
  • The MotherDuck DuckDB extension adds four new type of custom operators, to exchange data between your local DuckDB and the MotherDuck service:
    • The UploadSink operator runs locally and sends data from your local DuckDB to the remote MotherDuck service.
    • The UploadSource operator runs remotely in the DuckDB on the MotherDuck side and consumes the uploaded data.
    • The DownloadSink operator runs remotely on the MotherDuck side and prepares the data to be downloaded by the local DuckDB.
    • The DownloadSource operator runs in your local DuckDB, fetching the data from the MotherDuck service made available via the remote DownloadSink.

VACUUM causing fatal exception​

Trying to execute a VACUUM command will cause the client-side (local) DuckDB database to enter an invalid state and require a restart. The error displayed will be:

INTERNAL Error: Calling GetStorage on a TableCatalogEntry that is not a DuckTableEntry

Subsequent queries will display the error:

FATAL Error: Failed: database has been invalidated because of a previous fatal error.
The database must be restarted prior to being used again.

To resume querying, reconnect to DuckDB and MotherDuck. In the Web UI, refresh the page. In other clients like Python or the CLI, disconnect and reconnect.

What DuckDB extensions are available?​

Why am I not in the same Organization as my team?​

If you sign up to MotherDuck directly, you will create your own Organization as a part of the sign up flow. To join your team's Organization, reach out to your team and request that they invite you to their Organization. As an alternative, you may reach out to MotherDuck support and we can search for other users within your domain.

How do I use my team's shared databases?​

Some database shares are scoped at the ORGANIZATION level. To use those shares, you must be in the same Organization as the person who created the share. In addition, some shares are marked as 'DISCOVERABLE`. This allows members of the same Organization to easily find those shares through the UI. Follow the steps outlined in "Why am I not in the same Organization as my team?" to join your team!