Supabase Terraform Provider

https://github.com/supabase/terraform-provider-supabase
Admin
Supabase Terraform Provider enables Terraform users to manage and version control Supabase...
Tokens:11,293
Snippets:87
Trust Score:10
License:MPL-2.0
Update:2 weeks ago
Show doc for...
Tokens:
Raw
### Build the Provider with go install

Source: https://github.com/supabase/terraform-provider-supabase/blob/main/CONTRIBUTING.md

Builds the provider and places the binary in the $GOPATH/bin directory. Run from the repository directory after cloning.

```shell
go install
```

--------------------------------

### Example Usage: Configure Supabase project settings

Source: https://github.com/supabase/terraform-provider-supabase/blob/main/docs/resources/settings.md

Terraform configuration that sets database, network, API, auth, and storage settings for a Supabase project. The project_ref is required, and each setting is provided as serialised JSON. Note that storage fileSizeLimit is expressed in bytes.

```terraform
resource "supabase_settings" "production" {
  project_ref = "mayuaycdtijbctgqbycg"

  database = jsonencode({
    statement_timeout = "10s"
  })

  network = jsonencode({
    restrictions = [
      "0.0.0.0/0",
      "::/0"
    ]
  })

  api = jsonencode({
    db_schema            = "public,storage,graphql_public"
    db_extra_search_path = "public,extensions"
    max_rows             = 1000
  })

  auth = jsonencode({
    site_url             = "http://localhost:3000"
    mailer_otp_exp       = 3600
    mfa_phone_otp_length = 6
    sms_otp_length       = 6
  })

  storage = jsonencode({
    # fileSizeLimit is expressed in bytes (e.g., 50MB = 50 * 1024 * 1024)
    fileSizeLimit = 52428800
    features = {
      imageTransformation = {
        enabled = true
      }
      s3Protocol = {
        enabled = false
      }
    }
  })
}
```

--------------------------------

### Import existing Supabase project and configure API settings

Source: https://github.com/supabase/terraform-provider-supabase/blob/main/README.md

This HCL example imports an existing Supabase project using the `import` block and configures its API settings with the `supabase_settings` resource. It requires a Supabase access token, either via the `access_token` argument or the `SUPABASE_ACCESS_TOKEN` environment variable. The `organization_id` must be the organization slug from the Supabase Dashboard.

```hcl
terraform {
  required_providers {
    supabase = {
      source  = "supabase/supabase"
      version = "~> 1.0"
    }
  }
}

# Alternatively, you can set the env var for SUPABASE_ACCESS_TOKEN
provider "supabase" {
  access_token = file("${path.module}/access-token")
}

# Define a linked project variable as user input
variable "linked_project" {
  type = string
}

# Import the linked project resource
import {
  to = supabase_project.production
  id = var.linked_project
}

resource "supabase_project" "production" {
  # organization_id is your organization's slug (it can be found in the Supabase Dashboard under Organization Settings > Organization Details > Organization slug)
  organization_id   = "nknnyrtlhxudbsbuazsu"
  name              = "tf-project"
  database_password = "tf-example"
  region            = "ap-southeast-1"
}

# Configure api settings for the linked project
resource "supabase_settings" "production" {
  project_ref = var.linked_project

  api = jsonencode({
    db_schema            = "public,storage,graphql_public"
    db_extra_search_path = "public,extensions"
    max_rows             = 1000
  })
}
```

--------------------------------

### Example Usage: supabase_branch data source

Source: https://github.com/supabase/terraform-provider-supabase/blob/main/docs/data-sources/branch.md

Retrieves all branch databases for the specified parent project reference. The parent_project_ref is required and should be set to the project reference of the parent project.

```terraform
data "supabase_branch" "all" {
  parent_project_ref = "mayuaycdtijbctgqbycg"
}

```

--------------------------------

### Import an API key using terraform import

Source: https://github.com/supabase/terraform-provider-supabase/blob/main/docs/resources/apikey.md

Shows how to import an existing API key using the terraform import command. The import syntax uses the project reference and the key's name, optionally including the key type or UUID. The example includes comments explaining the required parameters.

```shell
# API keys can be imported using the project reference and the key's name,
# separated by a '/'.
#
# - project_ref: Found in the Supabase dashboard under Project Settings -> General,
#   or in the project's URL: https://supabase.com/dashboard/project/<project_ref>
# - api_key_name: Found in the Supabase dashboard under Project Settings -> API Keys.
terraform import supabase_apikey.example <project_ref>/<api_key_name>

# If multiple keys in the project share the same name, a type must also be provided.
#
# - api_key_type: The `type` of the target key (publishable or secret).
terraform import supabase_apikey.example <project_ref>/<api_key_name>/<api_key_type>

# Alternatively, the key's UUID can be used instead of its name.
#
# - api_key_id: The `id` field of the target key from the JSON output of:
#     supabase projects api-keys --output json --project-ref <project_ref>
terraform import supabase_apikey.example <project_ref>/<api_key_id>
```

--------------------------------

### Example Usage: supabase_edge_function_secrets

Source: https://github.com/supabase/terraform-provider-supabase/blob/main/docs/resources/edge_function_secrets.md

Creates a supabase_edge_function_secrets resource with a project reference and a set of secrets. Each secret requires a name and a sensitive value. Secret names must not start with the SUPABASE_ prefix.

```terraform
resource "supabase_edge_function_secrets" "example" {
  project_ref = "mayuaycdtijbctgqbycg"

  secrets = [
    {
      name  = "API_KEY"
      value = "your-api-key-here"
    },
    {
      name  = "DATABASE_URL"
      value = "postgresql://user:pass@localhost:5432/db"
    },
    {
      name  = "STRIPE_SECRET_KEY"
      value = "sk_test_..."
    }
  ]
}
```

--------------------------------

### Add a Go Module Dependency with go get and go mod tidy

Source: https://github.com/supabase/terraform-provider-supabase/blob/main/CONTRIBUTING.md

Adds a new dependency to the provider's Go modules. Run both commands, then commit the changes to go.mod and go.sum.

```shell
go get github.com/author/dependency
go mod tidy
```

--------------------------------

### Create a Supabase branch with Terraform

Source: https://github.com/supabase/terraform-provider-supabase/blob/main/docs/resources/branch.md

Creates a new Supabase branch resource. The example sets the parent project ref and git branch; the persistent and region attributes are optional. The database connection details are exposed as read-only attributes after creation.

```terraform
resource "supabase_branch" "new" {
  parent_project_ref = "mayuaycdtijbctgqbycg"
  git_branch         = "main"
}
```

--------------------------------

### Example Usage: supabase_network_bans data source

Source: https://github.com/supabase/terraform-provider-supabase/blob/main/docs/data-sources/network_bans.md

Use this Terraform configuration to fetch the network bans for a Supabase project. The project_ref is required and must be set to the project's reference ID. The data source exposes banned_ipv4_addresses as a read-only set of strings.

```terraform
data "supabase_network_bans" "test" {
  project_ref = "mayuaycdtijbctgqbycg"
}

```

--------------------------------

### Retrieve pooler connection strings with supabase_pooler

Source: https://github.com/supabase/terraform-provider-supabase/blob/main/docs/data-sources/pooler.md

Use this data source to get the pooler connection strings for a Supabase project. The project_ref is required, and the url attribute returns a map of pooler mode to connection string.

```terraform
data "supabase_pooler" "production" {
  project_ref = "mayuaycdtijbctgqbycg"
}

```

--------------------------------

### Create supabase_third_party_auth resources for OIDC, JWKS URL, and custom JWKS

Source: https://github.com/supabase/terraform-provider-supabase/blob/main/docs/resources/third_party_auth.md

Shows three separate resource declarations for supabase_third_party_auth: one using oidc_issuer_url, one using jwks_url, and one using custom_jwks. The custom_jwks example includes a comment noting that custom_jwks must contain public JWKS material only.

```terraform
resource "supabase_third_party_auth" "oidc" {
  project_ref     = "mayuaycdtijbctgqbycg"
  oidc_issuer_url = "https://issuer.example.com"
}

resource "supabase_third_party_auth" "jwks_url" {
  project_ref = "mayuaycdtijbctgqbycg"
  jwks_url    = "https://issuer.example.com/.well-known/jwks.json"
}

resource "supabase_third_party_auth" "custom_jwks" {
  project_ref = "mayuaycdtijbctgqbycg"

  # custom_jwks must contain public JWKS material only.
  custom_jwks = jsonencode({
    keys = [
      {
        kty = "RSA"
        kid = "example-key"
        n   = "example-modulus"
        e   = 
```

--------------------------------

### Import: Import supabase_settings using project reference

Source: https://github.com/supabase/terraform-provider-supabase/blob/main/docs/resources/settings.md

Shell command to import the supabase_settings resource using the project reference. On import, all setting categories are fetched from the API, allowing selective management of specific settings.

```shell
# Settings can be imported using the project reference.
#
# - project_ref: Found in the Supabase dashboard under Project Settings -> General,
#   or in the project's URL: https://supabase.com/dashboard/project/<project_ref>
#
# On import, all setting categories (API, auth, etc.) are fetched from the API.
# You can then selectively manage specific settings in your Terraform configuration.
terraform import supabase_settings.production <project_ref>
```

--------------------------------

### Create a Draft Release with gh release create

Source: https://github.com/supabase/terraform-provider-supabase/blob/main/CONTRIBUTING.md

Creates a draft release with a new semantic version tag and auto-generated release notes. Edit the notes as needed via the printed link or gh release edit.

```shell
gh release create v1.10.0 --draft --generate-notes
```

--------------------------------

### Run Acceptance Tests with make testacc

Source: https://github.com/supabase/terraform-provider-supabase/blob/main/CONTRIBUTING.md

Runs the full suite of Acceptance tests. Note that acceptance tests create real resources and often cost money to run.

```shell
make testacc
```

--------------------------------

### Create a Supabase project resource and retrieve API keys

Source: https://github.com/supabase/terraform-provider-supabase/blob/main/docs/tutorial.md

Defines a `supabase_project` resource and a `supabase_apikeys` data source in Terraform. The data source reads the project's API keys using the project reference from the resource, and the output exposes the anon key. Sensitive data is involved, so handle the API key output carefully.

```tf
# Create a project resource
resource "supabase_project" "production" {
  organization_id   = "<your-org-id>"
  name              = "tf-example"
  database_password = "<your-password>"
  region            = "ap-southeast-1"
}

# Retrieve project API keys (careful with sensitive data!)
data "supabase_apikeys" "production" {
  project_ref = supabase_project.production.id
}

output "anon_key" {
  value = data.supabase_apikeys.production.anon_key
}

```

--------------------------------

### Import a Supabase project using terraform import

Source: https://github.com/supabase/terraform-provider-supabase/blob/main/docs/resources/project.md

Shows how to import an existing Supabase project using the terraform import command. The project reference is found in the Supabase dashboard under Project Settings -> General or in the project's URL.

```shell
# Projects can be imported using the project reference.
#
# - project_ref: Found in the Supabase dashboard under Project Settings -> General,
#   or in the project's URL: https://supabase.com/dashboard/project/<project_ref>
terraform import supabase_project.production <project_ref>

```

--------------------------------

### Configure branch databases with for_each in module/branches.tf

Source: https://github.com/supabase/terraform-provider-supabase/blob/main/docs/tutorial.md

Mirrors production project settings to branch databases using the `for_each` meta-argument. Create this file as `module/branches.tf` to fan out configs to multiple branch resources.

```tf
# Fetch all branches of a linked project
resource "supabase_branch" "production" {
  for_each = var.branches

  project_ref = var.linked_project
  branch_ref  = each.value
}

```

--------------------------------

### Tag and Push the Release Version

Source: https://github.com/supabase/terraform-provider-supabase/blob/main/CONTRIBUTING.md

Creates and pushes the git tag for the draft release. Pushing the tag triggers the release workflow, which builds and signs binaries via GoReleaser.

```shell
git tag v1.10.0
git push origin v1.10.0
```

--------------------------------

### Import an Edge Function with terraform import

Source: https://github.com/supabase/terraform-provider-supabase/blob/main/docs/resources/edge_function.md

Shows how to import an existing Edge Function using the `terraform import` command. The import syntax is `supabase_edge_function.example <project_ref>/<slug>`. Note that local-only fields (entrypoint, import_map, static_files, local_checksum) may not be populated by import and must be configured manually.

```shell
# Edge functions can be imported using the project reference and the function slug,
# separated by a '/'.
#
# - project_ref: Found in the Supabase dashboard under Project Settings -> General,
#   or in the project's URL: https://supabase.com/dashboard/project/<project_ref>
# - slug: Found in the Supabase dashboard under Edge Functions,
#   or in the function's URL: https://supabase.com/dashboard/project/<project_ref>/functions/<slug>
#
# Note: Local-only fields (entrypoint, import_map, static_files, local_checksum)
# may not be populated by import and must be configured manually in your Terraform configuration.
terraform import supabase_edge_function.example <project_ref>/<slug>
```

--------------------------------

### Configure api settings with supabase_settings resource

Source: https://github.com/supabase/terraform-provider-supabase/blob/main/docs/tutorial.md

Creates a supabase_settings resource for the linked project. The api field is JSON-encoded with db_schema, db_extra_search_path, and max_rows settings. Settings are created and destroyed with the referenced project, so create and update are identical and deletion is always a no-op.

```tf
# Configure api settings for the linked project
resource "supabase_settings" "production" {
  project_ref = var.linked_project

  api = jsonencode({
    db_schema            = "public,storage,graphql_public"
    db_extra_search_path = "public,extensions"
    max_rows             = 1000
  })
}
```

--------------------------------

### Create a Supabase project with Terraform

Source: https://github.com/supabase/terraform-provider-supabase/blob/main/docs/resources/project.md

Defines a supabase_project resource with required attributes: organization_id, name, database_password, and region. Optional attributes include instance_size and legacy_api_keys_enabled. The legacy_api_keys_enabled attribute is deprecated.

```terraform
resource "supabase_project" "test" {
  organization_id         = "continued-brown-smelt"
  name                    = "foo"
  database_password       = "barbaz"
  region                  = "us-east-1"
  instance_size           = "micro"
  legacy_api_keys_enabled = false
}

```

--------------------------------

### Create an API key with supabase_apikey

Source: https://github.com/supabase/terraform-provider-supabase/blob/main/docs/resources/apikey.md

Defines a new API key for a Supabase project. The required attributes are project_ref and name. The resource is created with the specified project reference and name.

```terraform
resource "supabase_apikey" "new" {
  project_ref = "mayuaycdtijbctgqbycg"
  name        = "test"
}
```

--------------------------------

### Import supabase_edge_function_secrets with terraform import

Source: https://github.com/supabase/terraform-provider-supabase/blob/main/docs/resources/edge_function_secrets.md

Use this command to import an existing edge function secrets resource into Terraform state. The project reference is found in the Supabase dashboard under Project Settings -> General or in the project URL. After import, the API returns only SHA-256 digests, so `secret_digests` is populated and `secrets[*].value` is null; SUPABASE_ prefixed secrets are not imported. Supply plaintext values in your configuration and run `terraform plan` to reconcile state.

```shell
# Edge function secrets can be imported using the project reference.
#
# - project_ref: Found in the Supabase dashboard under Project Settings -> General,
#   or in the project's URL: https://supabase.com/dashboard/project/<project_ref>
#
# IMPORTANT: The Supabase management API only returns SHA-256 digests of secret
# values, never the plaintext. After import:
#   - `secret_digests` is populated with the digests returned by the API.
#   - `secrets[*].value` is null for every imported secret.
#   - Secrets with a SUPABASE_ prefix are not imported (they are reserved).
#
# After running this command, supply the plaintext secret values in your Terraform
# configuration and run `terraform plan` to reconcile state. Terraform will show
# a plan to update the secrets to match the values in your config.
#
# Note: Secret values are sensitive. Always use a remote state backend with
# encryption to protect sensitive values stored in Terraform state.
terraform import supabase_edge_function_secrets.example mayuaycdtijbctgqbycg
```

--------------------------------

### Retrieve API keys with supabase_apikeys data source

Source: https://github.com/supabase/terraform-provider-supabase/blob/main/docs/data-sources/apikeys.md

Use this Terraform configuration to fetch API keys for a Supabase project. The `project_ref` argument is required and must be set to the project's reference ID. The data source returns sensitive keys such as `anon_key`, `publishable_key`, `service_role_key`, and `secret_keys`.

```terraform
data "supabase_apikeys" "production" {
  project_ref = "mayuaycdtijbctgqbycg"
}

```

--------------------------------

### Terraform provider configuration for Supabase

Source: https://github.com/supabase/terraform-provider-supabase/blob/main/docs/tutorial.md

Defines the required provider block for Supabase Terraform provider version ~> 1.0 and configures the provider with an access token read from a local file. Save the access token to the access-token file before running terraform -chdir=module apply.

```hcl
terraform {
  required_providers {
    supabase = {
      source  = "supabase/supabase"
      version = "~> 1.0"
    }
  }
}

provider "supabase" {
  access_token = file("${path.cwd}/access-token")
}
```

--------------------------------

### Create an Edge Function with supabase_edge_function

Source: https://github.com/supabase/terraform-provider-supabase/blob/main/docs/resources/edge_function.md

Defines a Terraform resource for a Supabase Edge Function. Required attributes are `project_ref`, `slug`, and `entrypoint`. Optional attributes include `import_map`, `name`, and `static_files`.

```terraform
resource "supabase_edge_function" "foo" {
  project_ref = "mayuaycdtijbctgqbycg"
  slug        = "foo"
  entrypoint  = "supabase/functions/foo/index.ts"
}
```

--------------------------------

### Configure Supabase Provider

Source: https://github.com/supabase/terraform-provider-supabase/blob/main/docs/index.md

Basic Terraform configuration for the Supabase provider. The access token can be set via the SUPABASE_ACCESS_TOKEN environment variable or directly in the configuration. The endpoint can be set via SUPABASE_API_ENDPOINT, defaulting to https://api.supabase.com.

```terraform
# Configure the Supabase Provider
provider "supabase" {
  # Recommended: Use environment variable SUPABASE_ACCESS_TOKEN
  # Or specify directly (not recommended for production)
  # access_token = "your-access-token"
}
```
Tokens:
Raw