Skip to main content

MotherDuck

This guide outlines the steps to create a MotherDuck connection within Syntropic.

Syntropic manages tables in a MotherDuck database using a read/write access token and MotherDuck's native DuckDB client.

Before you connect​

Create a MotherDuck service account or personal access token that can read and write the target database. Syntropic uses the token to create tables, update data, alter schemas, maintain row history, and delete tables.

A MotherDuck organization or workspace is not the same thing as a database. In the connection form, enter the database name shown in MotherDuck (for example my_db) and the schema within that database.

Creating a New MotherDuck Connection​

  1. Navigate to the Connections page from the main sidebar.
  2. Click the New Connection button located in the top right corner.
  3. Find and select MotherDuck from the list of available connection types.
  4. Enter a descriptive connection name.
  5. Enter the MotherDuck database name.
  6. Enter the schema name.
  7. Paste the access token and select Connect.

Do not paste a SQLAlchemy connection string such as duckdb:///md:my_db; only the database, schema, and token are required.

Required access​

The token must be able to:

  • Read the selected database and schema.
  • Create, alter, and drop tables and indexes.
  • Select, insert, update, and delete table rows.

The connection test performs a rolled-back table creation to confirm write access without leaving a test table behind.

Rotate a token​

Edit the connection and paste the replacement token. Leaving the token field empty keeps the currently stored token. Syntropic encrypts the token and never returns it from the API after it is saved.

For token and service-account instructions, see MotherDuck authentication.