Creating a New Integration

Integration with MotherDuck is almost the same as integrating with DuckDB, which means you can do it from any language or framework!

There are a few differences:

1. Use "md:" or "md:my_database" connection string instead of the local filesystem path.
2. Pass motherduck_token configuration property (through the config dictionary, connection string parameter or environment variable).
3. Pass custom_user_agent to identify the new integration.

User-agent guidelines

• The format is integration/version(custom-metadata1;custom-metadata2) where the version and metadata sections are optional.
• Avoid using spaces in integration and version sections.
• multiple custom metadata sections should be separated by semicolons.

Some examples:

• my-integration
• my-integration/2.9.0
• my-integration/2.9.0(linux_amd64)
• my-integration/2.9.0(linux_amd64;us-east-1)

Language / Framework examples

Python

con = duckdb.connect("md:my_database", config={
        "motherduck_token": token,
        "custom_user_agent": "INTEGRATION_NAME"
});

Python with SQLAlchemy

eng = create_engine("duckdb:///md:my_database", connect_args={
    'config': {
        'motherduck_token': token,
        'custom_user_agent': 'INTEGRATION_NAME'
    }
})

Java / JDBC

Properties config = new Properties();
config.setProperty("motherduck_token", token);
config.setProperty("custom_user_agent", "INTEGRATION_NAME");
Connection mdConn = DriverManager.getConnection("jdbc:duckdb:md:my_database", config);

NodeJS

var db = new duckdb.Database('md:my_database', {
    'motherduck_token': token,
    'custom_user_agent': 'INTEGRATION_NAME'
});

Go

db, err := sql.Open("duckdb", "md:my_database?custom_user_agent=INTEGRATION_NAME")

Implementation best practices

If you use DuckDB/MotherDuck in a shared environment where multiple users are served by the same process, the connection string (e.g. URL for JDBC, Database for Python/ODBC) must be unique per user. You can disambiguate the connection string with a unique-per-user substring, for example md:database_name?user=unique_user_name. If using the motherduck_token in the connection string, make sure not to log it in plaintext.