Skip to main content

Terraform

The MotherDuck Terraform provider manages databases, schemas, shares and grants, roles, secrets, snapshots, and service accounts as code. Works with Terraform 1.5 or later and with OpenTofu.

The MotherDuck Terraform provider manages MotherDuck resources as code. Use it to version, review, and reproduce the databases, schemas, shares, roles, secrets, and service accounts that make up an environment.

It works with Terraform 1.5 or later and with OpenTofu.

Prerequisites​

Configure the provider​

Declare the provider and run terraform init. Terraform downloads it from the Terraform Registry and verifies its signature.

terraform {
  required_version = ">= 1.5.0"

  required_providers {
    motherduck = {
      source  = "motherduckdb/motherduck"
      version = "~> 0.2.2"
    }
  }
}

provider "motherduck" {}

The provider reads MOTHERDUCK_TOKEN from the environment, so no credentials belong in your configuration:

export MOTHERDUCK_TOKEN=<your_token>

Managing organization resources such as service accounts and access tokens additionally needs an organization admin token, read from MOTHERDUCK_ADMIN_TOKEN.

warning

Terraform records managed resources in state, and state can contain sensitive values. Use a remote backend with encryption and restricted access rather than committing state to version control.

Create a database​

resource "motherduck_database" "analytics" {
  name = "analytics"
}

resource "motherduck_schema" "reporting" {
  database = motherduck_database.analytics.name
  name     = "reporting"
}

Run terraform plan to preview the changes and terraform apply to create them.

What you can manage​

Databases, schemas, tables, and views; shares and share grants; roles and role grants; secrets; snapshots; and, with an admin token, service accounts, access tokens, and Duckling configuration.

Known limitations​

  • Databases created outside Terraform are not managed until you import them.
  • Human organization membership and identity-provider provisioning are outside the provider. Terraform can manage SQL role memberships and share grants through motherduck_role_grant and motherduck_share_grant.
  • Creating custom roles requires a Business or Enterprise plan and role-management permissions. Apply share grants as the share owner. See roles and access control.

Manage and audit access​

Manage memberships and share grants with their role configuration. A clean plan checks resources in Terraform state but does not prove that no other grants exist. Use the provider’s access-control example and share-audience audit to compare observed grants with your intended policy. Audit reads do not revoke grants.