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.
| Kind | Name | What it manages |
|---|---|---|
| Resource | databasezy_project | A project (name, slug, owning team) |
| Resource | databasezy_instance | A database instance of any engine: size, version, storage, placement, allow-list, maintenance window, deletion protection |
| Resource | databasezy_member | An invitation, then the membership and its role |
| Resource | databasezy_api_key | An org API key (role, scopes, expiry) |
| Resource | databasezy_storage_bucket | A storage bucket of a project |
| Data source | databasezy_org, databasezy_engines, databasezy_sizes, databasezy_regions, databasezy_instance | Read-only lookups |
| Ephemeral resource | databasezy_instance_credentials | Instance credentials for one run, never stored |
Quick start
Section titled “Quick start”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.
export DATABASEZY_TOKEN="zb_..."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}"}terraform initterraform applyapply 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.
Provider settings
Section titled “Provider settings”| Argument | Environment variable | Default |
|---|---|---|
token (sensitive) | DATABASEZY_TOKEN (then DATABASEZY_API_KEY) | required |
org_id | DATABASEZY_ORG_ID | the token’s organization |
base_url | DATABASEZY_BASE_URL | https://api.databasezy.com |
max_retries | 5 |
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.
Credentials stay out of state
Section titled “Credentials stay out of state”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".
Deletion protection
Section titled “Deletion protection”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:
terraform apply -var deletion_protection=false # or edit the attributeterraform destroySome 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.
Importing existing resources
Section titled “Importing existing resources”Every resource can be imported:
terraform import databasezy_project.app prj_...terraform import databasezy_instance.orders inst_...terraform import databasezy_api_key.ci key_... # imported keys have no secretterraform import databasezy_storage_bucket.avatars prj_.../avatarsterraform plan reads the real state of every resource. Something deleted outside Terraform
is dropped from state and planned again.
Members
Section titled “Members”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.
Errors and rate limits
Section titled “Errors and rate limits”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.
Reference
Section titled “Reference”The registry documentation lists every argument and attribute: registry.terraform.io/providers/databasezy/databasezy.