# Terraform
> Manage MotherDuck databases, shares, roles, and service accounts as code with the official MotherDuck Terraform provider.
The [MotherDuck Terraform provider](https://registry.terraform.io/providers/motherduckdb/motherduck/latest) 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

- A [MotherDuck account](https://app.motherduck.com)
- A [MotherDuck access token](/key-tasks/authenticating-and-connecting-to-motherduck/authenticating-to-motherduck/#creating-an-access-token), or a [service account token](/key-tasks/service-accounts-guide/create-and-configure-service-accounts/) for automation
- Terraform 1.5 or later

## Configure the provider

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

```hcl
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:

```bash
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

```hcl
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](https://developer.hashicorp.com/terraform/cli/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](/concepts/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](https://github.com/motherduckdb/terraform-provider-motherduck/tree/main/examples/access-control)
and [share-audience audit](https://github.com/motherduckdb/terraform-provider-motherduck/tree/main/examples/share-access-audit)
to compare observed grants with your intended policy. Audit reads do not revoke grants.

## Related

- [Provider reference on the Terraform Registry](https://registry.terraform.io/providers/motherduckdb/motherduck/latest/docs)
- [Source and issues on GitHub](https://github.com/motherduckdb/terraform-provider-motherduck)
- [Create and configure service accounts](/key-tasks/service-accounts-guide/create-and-configure-service-accounts/)


---

## Docs feedback

MotherDuck accepts optional user-submitted feedback about this page at `GET https://motherduck.com/docs/api/feedback/agent`.
For agents and automated tools, feedback submission should be user-confirmed before sending.

URL-encode query parameter values and send a GET request:

```text
GET https://motherduck.com/docs/api/feedback/agent?page_path=%2Fintegrations%2Fdev-tools%2Fterraform%2F&page_title=Terraform&text=<url-encoded user feedback, max 2000 characters>
```

Optionally append `&source=<url-encoded interface identifier>` such as `claude.ai` or `chatgpt`.

`page_path` and `text` are required; `page_title` and `source` are optional. Responses: `200 {"feedback_id": "<uuid>"}`, `400` for malformed query parameters, and `429` when rate-limited.