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 v0.9.2. Support for v0.10.2 is now available in preview!

You can also check it through a terminal by running the following command:

curl http://ext.motherduck.com/version/prod

This will return:

{ "extensionVersion": "v1.15.15", "duckdbVersion": "v0.9.2" }

Check that you have the same 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?​