Skip to main content

Installation & authentication

Prerequisites​

MotherDuck Python supports the following operating systems:

  • Linux (x64, glibc v2.31+, equivalent to ubuntu v20.04+)
  • Mac OSX 11+ (M1/ARM or x64)
  • Python 3.4 or later Please let us know if your configuration is unsupported.

Installing DuckDB​

caution

MotherDuck currently supports DuckDB version v0.9.2 only. Support for v0.10.0 is coming soon!

Use the following pip command to install the supported version of DuckDB:

pip install duckdb==v0.9.2

Connect to MotherDuck​

You can connect to and work with multiple local and MotherDuck-hosted DuckDB databases at the same time. Currently, the connection syntax varies depending on how you’re opening local DuckDB and MotherDuck.

Authenticating to MotherDuck​

You can authenticate to MotherDuck using human user authentication or a service token as shown in the following examples.

Using human user authentication​

import duckdb

# connect to MotherDuck using 'md:' or 'motherduck:'
con = duckdb.connect('md:')

You are then prompted to login with your web browser. Follow the instructions displayed in the terminal.

Using a service token​

import duckdb

# initiate the MotherDuck connection through a service token through
con = duckdb.connect('md:?motherduck_token=<token>')

To know more about how to persist your authentication credentials, read Authenticating to MotherDuck

Connect to MotherDuck first​

import duckdb

# initiate the MotherDuck connection through a service token through
con = duckdb.connect('md:')

# connect to your MotherDuck database through 'md:mydatabase' or 'motherduck:mydatabase'
# if the database doesn't exist, MotherDuck creates it when you connect
con = duckdb.connect('md:mydatabase')

# run a query to check verify that you are connected
con.sql("SHOW DATABASES").show()
info

When you connect to MotherDuck without specifying a database, you connect to a default database called my_db. This is the current database. You can query any table in this database by just specifying the table name. The USE command allows you to switch the current database.

After you connect to MotherDuck, you can open local DuckDB databases in the same way that DuckDB allows you to connect to multiple databases, as shown in the following examples.

# connecting to a local DuckDB database after opening Motherduck
con = duckdb.connect('md:')
con.sql("ATTACH 'localfile.duckdb'")
con.sql("ATTACH 'localfile2.duckdb'")

# listing all databases
con.sql("SHOW DATABASES").show()

Connecting to MotherDuck after opening a local DuckDB database​

If you’ve already established a DuckDB connection object with local databases, you can still connect to MotherDuck using the syntax shown in the following example.

# first open a local DuckDB database
hybrid_con = duckdb.connect('localfile.duckdb')

# next load the MotherDuck extension and connect to MotherDuck
hybrid_con.execute("LOAD motherduck")
hybrid_con.execute("PRAGMA MD_CONNECT")