Authenticating to MotherDuck
MotherDuck supports two types of authentication:
- Human users authentication, typically used by the MotherDuck UI
- Authentication using an access token, more convenient for Python or CLI
Human user authentication
MotherDuck UI authenticates using several methods:
- Github
- Username and password
You can leverage multiple modes of authentication in your account. For example, you can authenticate both via Google and via username and password as you see fit.
To authenticate in CLI or Python, human users will be redirected to an authentication web page. Currently, this happens every session. To avoid having to re-authenticate, you can save your access token - please read Authenticating With an Access Token for more information.
Authentication using an access token
If you are using Python or CLI and don't want to authenticate every session, you can securely save your credentials locally.
Creating an access token
To create an access token:
- Go to the MotherDuck UI
- In top left click on organization name and then
Settings
- In the
General
tab, click onCopy token
to copy the access token to your clipboard
Storing the access token as an environment variable
You can save the access token as motherduck_token
in your environment variables.
An example of setting this in a terminal:
export motherduck_token='<token>'
You can also add this line to your ~/.zprofile
or ~/.bash_profile
.
Once this is done, your authentication token is saved and you can simply connect to MotherDuck:
- CLI
- Python
When launching DuckDB CLI
duckdb "md:"
When in the DuckDB CLI, you can use the command :
ATTACH 'md:';
You can also use .open
to connect to MotherDuck. This will create a new connection to MotherDuck and will detach any existing connection to a local DuckDB database. Learn more about .open
vs ATTACH
here.
# connecting to MotherDuck, assuming environment variable is set
con=duckdb.connect('md:')
This is the best practice for security reasons. The token is sensitive information and should be kept safe. Do not share it with others.
Using connection string parameters
Using the token to authenticate
Alternatively, you can specify an access token in the MotherDuck connection string: md:?motherduck_token=<token>
.
- CLI
- Python
When launching DuckDB CLI
duckdb "md:?motherduck_token=<motherduck_token>"
When in the DuckDB CLI, you can use the .open
command and specify the connection string as an argument.
.open md:?motherduck_token=<motherduck_token>
In Python, you can either use the connection string or set the token through config dictionary.
import duckdb
con = duckdb.connect("md:?motherduck_token=<motherduck_token>")
import duckdb
con = duckdb.connect("md:", config={ 'motherduck_token': token})
Using saas mode
You can limit MotherDuck's ability to interact with your local environment using SaaS Mode
:
- Disable reading or writing local files
- Disable reading or writing local DuckDB databases
- Disable installing or loading any DuckDB extensions locally
- Disable changing any DuckDB configurations locally
This mode is useful for third-party tools, such as BI vendors, that host DuckDB themselves and require additional security controls to protect their environments.
Using this parameter requires to use .open
when using the DuckDB CLI or duckdb.connect
when using Python. This initiates a new connection to MotherDuck and will detach any existing connection to a local DuckDB database.
Using attach mode
By default, when you connect to MotherDuck, you will be connected to all databases you have access to.
If you want limited the connection to only one database, you can use the attach_mode
with the value single
.
For example, to connect to a database named my_database
:
ATTACH 'md:my_database?attach_mode=single'
Syntax
- CLI
- Python
.open md:[<database_name>]?[motherduck_token=<motherduck_token>]&saas_mode=true
import duckdb
con = duckdb.connect('md:[<database_name>]?[motherduck_token=<motherduck_token>]&saas_mode=true')
Notes:
<database_name>
will be created if it doesn't exist already<database_name>
that starts with a number cannot be connected to directly. You will need to connect without a database specified and thenCREATE
andUSE
using a double quoted name. Eg:USE DATABASE "1database"
Example usage
- CLI
- Python
.open md:?saas_mode=true
import duckdb
con = duckdb.connect('md:?saas_mode=true')