Skip to content

Reference

Terraform provider

Tested with:Terraform 1.10-1.16 · provider 0.1.0 · Databasezy API 1.0.0

The Databasezy Terraform provider (databasezy/databasezy) manages your organization through the REST API. It is built on the Go SDK and needs Terraform 1.10 or later.

KindNameWhat it manages
Resourcedatabasezy_projectA project (name, slug, owning team)
Resourcedatabasezy_instanceA database instance of any engine: size, version, storage, placement, allow-list, maintenance window, deletion protection
Resourcedatabasezy_memberAn invitation, then the membership and its role
Resourcedatabasezy_api_keyAn org API key (role, scopes, expiry)
Resourcedatabasezy_storage_bucketA storage bucket of a project
Data sourcedatabasezy_org, databasezy_engines, databasezy_sizes, databasezy_regions, databasezy_instanceRead-only lookups
Ephemeral resourcedatabasezy_instance_credentialsInstance credentials for one run, never stored

Create an org API key in the portal (Organization > Access & settings > API keys) or with zb api-keys create, and export it. Give it the least role and scopes your configuration needs: developer with projects:* and instances:* covers projects and instances. To terraform destroy a project, use an owner or admin key whose scopes name projects:delete (or projects:*); a key scoped only * cannot delete projects. Resources that send data out (log drains, pipelines, public egress on secure placement) also need the explicit data:egress scope.

Terminal window
export DATABASEZY_TOKEN="zb_..."
main.tf
terraform {
required_version = ">= 1.10"
required_providers {
databasezy = {
source = "databasezy/databasezy"
version = "~> 0.1"
}
}
}
provider "databasezy" {}
resource "databasezy_project" "app" {
name = "Production"
}
resource "databasezy_instance" "orders" {
project_id = databasezy_project.app.id
name = "orders-db"
engine = "postgres"
engine_version = "17"
size = "s1"
allow_cidrs = ["203.0.113.0/24"]
}
output "orders_endpoint" {
value = "${databasezy_instance.orders.host}:${databasezy_instance.orders.port}"
}
Terminal window
terraform init
terraform apply

apply waits until the instance is ready (30 minutes by default; set timeouts { create = "45m" } to change it). Engine, size and region ids come from the engine and size catalogues, or from the databasezy_engines, databasezy_sizes and databasezy_regions data sources.

ArgumentEnvironment variableDefault
token (sensitive)DATABASEZY_TOKEN (then DATABASEZY_API_KEY)required
org_idDATABASEZY_ORG_IDthe token’s organization
base_urlDATABASEZY_BASE_URLhttps://api.databasezy.com
max_retries5

Keep the token in the environment or your CI’s secret store, not in .tf files. The provider only talks HTTPS and never writes the token to state, plans or logs.

Instance credentials are never stored in state. Read them with the databasezy_instance_credentials ephemeral resource, which uses the audited one-time reveal and exists only while Terraform runs. Pass the values to another provider or to a write-only argument:

ephemeral "databasezy_instance_credentials" "orders" {
instance_id = databasezy_instance.orders.id
}
provider "postgresql" {
host = ephemeral.databasezy_instance_credentials.orders.host
port = ephemeral.databasezy_instance_credentials.orders.port
username = ephemeral.databasezy_instance_credentials.orders.username
password = ephemeral.databasezy_instance_credentials.orders.password
sslmode = "require"
}

Revealing needs credentials:reveal and a second factor, which an API key cannot provide on its own. Use a service-account key with the credentials:reveal:integration scope and set purpose = "integration_env_sync".

databasezy_instance.deletion_protection defaults to true. While it is on, Terraform refuses to destroy or replace the instance, and so does the API. To delete an instance, turn protection off first:

Terminal window
terraform apply -var deletion_protection=false # or edit the attribute
terraform destroy

Some attributes can only be set when an instance is created (engine, region, ha, replicas, pooler_enabled, tags, cost_centre). Changing one of them plans a replacement, which deletion protection blocks. size, storage_gb (grows only), engine_version (upgrades only), placement, name, allow_cidrs and maintenance_window change in place.

Every resource can be imported:

Terminal window
terraform import databasezy_project.app prj_...
terraform import databasezy_instance.orders inst_...
terraform import databasezy_member.dev [email protected] # email, user id or invite id
terraform import databasezy_api_key.ci key_... # imported keys have no secret
terraform import databasezy_storage_bucket.avatars prj_.../avatars

terraform plan reads the real state of every resource. Something deleted outside Terraform is dropped from state and planned again.

databasezy_member sends an invitation (status = "invited"). Once the person accepts, the resource tracks the membership (status = "active"). Changing role updates the membership, or replaces a pending invitation. Managing members needs the admin role, and a role can never exceed the token’s.

API errors show the problem type, message, field errors and request id, for example 422 validation: size: unknown size xxl (request id req_...). Quote the request id when you contact support. The provider retries 429 and 503 answers after their Retry-After (up to max_retries times). If you hit rate limits on large configurations, lower terraform apply -parallelism.

The registry documentation lists every argument and attribute: registry.terraform.io/providers/databasezy/databasezy.