KiviDB with Terraform
The KiviDB provider manages databases as configuration: you describe the database you want, Terraform works out the difference, and the plan tells you what…
The KiviDB provider manages databases as configuration: you describe the database you want, Terraform works out the difference, and the plan tells you what it is about to do before it does it.
terraform {
required_providers {
kividb = {
source = "kividbio/kividb"
version = "~> 0.5"
}
}
}
provider "kividb" {}
resource "kividb_instance" "cache" {
name = "orders-cache"
tier = "essentials"
cloud = "aws"
region = "us-east-1"
data_size_gb = 8
}
$ export KIVIDB_API_KEY=kvdb_live_…
$ terraform apply
The provider is published at registry.terraform.io/providers/kividbio/kividb.
Authentication
Mint an API key in the console under Dashboard → API keys and put it in
KIVIDB_API_KEY. The key carries both the organization and the role, so there
is nothing else to configure — no account id, no region, no endpoint.
Prefer the environment variable over api_key in a provider block. A key
written into a .tf file ends up in version control, and a key passed as a
variable ends up in state, where it is stored in plain text.
A member or admin key can create, change and delete databases. A viewer key can only read: any change it attempts is refused, and it cannot read database passwords. Use a viewer key for monitoring and reporting, so a pipeline that should only look cannot change anything.
A key can also be limited to chosen databases when you create it (Databases → Only these databases). A limited key reaches those databases and their snapshots and nothing else: other databases look as if they do not exist, and it cannot create databases or read cloud accounts. Give each environment's configuration its own limited key, so a mistake in one cannot reach another.
The key is checked once, when the provider is configured. A key that has been
revoked fails at terraform plan with a message saying so, rather than partway
through an apply with half a database built.
The mental model
KiviDB has no general "update the database" endpoint, and the provider does not pretend otherwise. What the API has is a rename, a resize, a replica scale, a tier upgrade and an engine upgrade, each with its own rules about when it is allowed. The provider routes each changed attribute to the operation that owns it.
This is worth knowing because it explains the two things that surprise people.
Some attributes cannot change at all, because no operation exists to change them. Those are marked as forcing replacement, and Terraform will plan a destroy and create — which destroys the data. The plan says so plainly:
# kividb_instance.cache must be replaced
~ region = "us-east-1" -> "eu-west-1" # forces replacement
Plan: 1 to add, 0 to change, 1 to destroy.
Changing several things at once takes longer than changing one. Most of these operations refuse a database that is still busy with the previous one, so the provider waits for each step to finish before starting the next. An apply that changes one attribute is as quick as it ever was; an apply that changes three is roughly the sum of the three.
What changes in place, and what replaces the database
| Attribute | Effect of changing it |
|---|---|
name | renamed in place; the endpoint hostname follows |
data_size_gb, throughput_mode | resized in place |
replica_count | scaled in place, between 1 and 3 |
tier | upgraded in place |
kividb_version, lua_enabled, tls_enabled | applied by a rolling restart |
cloud, region, aof_enabled, tls_only | replaces the database |
The last row is the one to read carefully. Nothing moves a database between clouds or regions, and append-only persistence is chosen when the volume is laid out rather than afterwards. Terraform will do exactly what you asked — destroy the old database and create a new, empty one — so read a plan that mentions replacement before approving it.
Waiting
By default an apply waits for the database to be ready, because anything that
refers to endpoint needs one that answers. Set wait_for_ready = false to
return as soon as the work is accepted, which is occasionally useful when
creating many databases at once and nothing downstream depends on them.
An update waits for the change itself, not merely for the status to settle. If a change is accepted and then does not take effect, the apply fails saying which attribute is still wrong and what it is — rather than reporting success over a database that did not change.
Where to go next
- The
kividb_instanceresource — every attribute, the refusals you can meet, and what each one means. - Snapshots — point-in-time copies as configuration.
- Recipes — multi-cloud, high availability, environments, importing what already exists, and running in CI.