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


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);


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


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