Skip to main content

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.