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

AttributeEffect of changing it
namerenamed in place; the endpoint hostname follows
data_size_gb, throughput_moderesized in place
replica_countscaled in place, between 1 and 3
tierupgraded in place
kividb_version, lua_enabled, tls_enabledapplied by a rolling restart
cloud, region, aof_enabled, tls_onlyreplaces 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_instance resource — 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.