## Contributing
If you want to help develop the Materialize provider, check out the [contribution guidelines](https://github.com/MaterializeInc/terraform-provider-materialize/blob/main/CONTRIBUTING.md).
---
## Appendix: External secret stores
Materialize does not directly integrate with external secret stores, but it's possible to manage this integration via Terraform.
The [secret stores demo](https://github.com/MaterializeInc/demos/tree/main/integrations/terraform/secret-stores) shows how to handle [secrets](/sql/create-secret) and sensitive data with some popular secret stores. By utilizing Terraform's infrastructure-as-code model, you can automate and simplify both the initial setup and ongoing management of secret stores with Materialize.
A popular secret store is [HashiCorp Vault](https://www.vaultproject.io/). To use Vault with Materialize, you'll need to install the Terraform Vault provider:
```hcl
terraform {
required_providers {
vault = {
source = "hashicorp/vault"
version = "~> 3.15"
}
}
}
provider "vault" {
address = "https://vault.example.com"
token = "your-vault-token"
}
```
Next, fetch a secret from Vault and use it to create a new Materialize secret:
```hcl
data "vault_generic_secret" "materialize_password" {
path = "secret/materialize"
}
resource "materialize_secret" "example_secret" {
name = "pgpass"
value = data.vault_generic_secret.materialize_password.data["pgpass"]
}
```
In this example, the `vault_generic_secret` data source retrieves a secret from Vault, which is then used as the value for a new `materialize_secret` resource.
You can find examples of using other popular secret stores providers in the
[secret stores
demo](https://github.com/MaterializeInc/demos/tree/main/integrations/terraform/secret-stores).
---
## Get started with the Materialize provider
The following guide provides an introduction to the Materialize Terraform
provider and setup.
## Terraform provider
The Materialize provider is hosted on the [Terraform provider registry](https://registry.terraform.io/providers/MaterializeInc/materialize/latest).
To use the Materialize provider, you create a new `main.tf` file and add the
required providers:
```hcl
terraform {
required_providers {
materialize = {
source = "MaterializeInc/materialize"
}
}
}
```
## Authentication and Configuration
The provider auto-detects your deployment type based on the configuration you
provide:
- **Materialize Cloud**: Use `password` and `default_region`
- **Self-managed**: Use `host`, `username`, `password`, and other connection parameters
> **Warning:** Switching between Materialize Cloud and self-managed configuration **breaks your
> Terraform state file**. Ensure that your initial configuration
> matches your intended deployment type, and do not switch to a
> different deployment type afterward.
**Materialize Cloud:**
### Materialize Cloud
Configure the provider with your [app password](/security/cloud/users-service-accounts/create-service-accounts/)
and region. This provides access to all provider resources, including
organization-level resources (users, SSO, SCIM) and database resources.
To avoid checking secrets into source control, use environment variables for authentication. You have two options:
**Option 1: Using provider environment variables (recommended)**
The provider automatically reads the `MZ_PASSWORD` environment variable:
```shell
export MZ_PASSWORD=