Skip to content

Terraform provider

The provider manages NamiDB Cloud databases (including copies and point-in-time restores), the API keys your applications use, IP allowlist entries and management tokens for other tools, through the management API. Terraform 1.5 or later. Apache-2.0.

terraform {
required_providers {
namidb = {
source = "namidb/namidb"
version = "~> 0.1"
}
}
}
provider "namidb" {} # reads NAMIDB_MANAGEMENT_TOKEN

Authentication

The provider uses a management token. Pass it in the environment so it stays out of your configuration:

Terminal window
export NAMIDB_MANAGEMENT_TOKEN=nmdb_mgmt_…
terraform plan
ScopeAllows
readData sources
writeread, plus namidb_database
adminwrite, plus namidb_api_key, namidb_management_token and namidb_ip_allowlist_entry

Provider arguments (both optional): token (sensitive; defaults to NAMIDB_MANAGEMENT_TOKEN) and url (defaults to NAMIDB_MANAGEMENT_URL, then https://app.namidb.com/api/v1). Create the provider’s own token in the console; with an admin token, Terraform can then create narrower, expiring tokens for other tools with namidb_management_token.

namidb_database

resource "namidb_database" "movies" {
name = "movies"
deletion_protection = true
}
# A new database restored from a backup of another one.
resource "namidb_database" "movies_staging" {
name = "movies-staging"
restore_from_backup_id = "0b4c7f2e-5d1a-4c3b-9e8f-1a2b3c4d5e6f"
timeouts = {
create = "45m"
}
}
# A copy of movies taken now, for tests against current data.
resource "namidb_database" "movies_qa" {
name = "movies-qa"
clone_from = {
database = namidb_database.movies.name
source = "fresh_snapshot"
}
}
# movies as it was at a point in time.
resource "namidb_database" "movies_before_migration" {
name = "movies-before-migration"
clone_from = {
database = namidb_database.movies.name
at = "2026-11-03T09:00:00Z"
}
}
output "movies_endpoint" {
value = namidb_database.movies.http_endpoint
}
Argument
name (required)Lowercase letters, numbers, - and _; starts with a letter or number; at most 63 characters. Changing it replaces the database and erases the old one’s data.
deletion_protectionWhen true, Terraform refuses to destroy it. Default false
restore_from_backup_idCreate it by restoring this backup; Terraform waits for the restore. Used only at creation
clone_fromCreate it as a copy of another database: database (required), source (latest_backup, the default; fresh_snapshot; or point_in_time, the default when at is set) and at (RFC 3339). Inside the plan’s restore-point window (Pro 48 hours, Scale 7 days) at is copied exactly; before it, the newest backup at or before then. Terraform waits for the copy. Used only at creation: changing it replaces the database, adding it to an existing or imported one changes nothing
timeouts.createDefault 30m

Read-only attributes: id, status (ready, restoring, failed), read_only, http_endpoint, bolt_uri, created_at, restored_from_backup, and recovery_point (for clone_from: the moment the data is from; later changes to the source are not included).

Import by name: terraform import namidb_database.movies movies.

namidb_api_key

resource "time_rotating" "every_90_days" {
rotation_days = 90
}
resource "namidb_api_key" "movies_reader" {
name = "movies-reader"
role = "read-only"
databases = [namidb_database.movies.name]
rotation_triggers = {
rotated = time_rotating.every_90_days.id
}
lifecycle {
create_before_destroy = true # the new key exists before the old one is revoked
}
}
output "movies_reader_key" {
value = namidb_api_key.movies_reader.token
sensitive = true
}
Argument
name (required)1–64 characters
roleread-write (default) or read-only
databasesDatabase names; omit for every database, including future ones
expires_atRFC 3339; within 2 years and the organization’s key lifetime policy
rotation_triggersAny values; changing one creates a new key and revokes this one

Read-only attributes: id, prefix, last4, status, created_at, and token (sensitive; known only for keys Terraform created). Every argument change replaces the key. Import by id; an imported key’s token stays null.

namidb_management_token

A narrower, expiring token for a CI job or another tool.

resource "time_rotating" "monthly" {
rotation_days = 30
}
resource "namidb_management_token" "deploy" {
name = "github-actions-deploy"
scope = "write"
expires_at = timeadd(time_rotating.monthly.rfc3339, "840h") # 35 days: a few days of overlap
rotation_triggers = {
rotated = time_rotating.monthly.id
}
lifecycle {
create_before_destroy = true # the new token exists before the old one is revoked
}
}
output "deploy_token" {
value = namidb_management_token.deploy.token
sensitive = true
}
Argument
name (required)1–64 characters
scoperead (default), write or admin; at most the provider token’s scope
expires_atRFC 3339; within 2 years, the organization’s key lifetime policy and, when the provider’s token expires, no later than it
rotation_triggersAny values; changing one creates a new token and revokes this one

The new token acts for the same person as the provider’s token, can’t be broader and can’t outlive it; that person needs two-factor authentication on their account. Read-only attributes: id, prefix, last4, status, created_by, created_at, and token (sensitive; known only for tokens Terraform created). Every argument change replaces the token. Import by id. Don’t manage the provider’s own token with this resource: destroying it would revoke the credential Terraform is using.

namidb_ip_allowlist_entry

An entry of the organization’s IP allowlist, or of one API key’s own list.

resource "namidb_ip_allowlist_entry" "office" {
cidr = "203.0.113.0/24"
label = "office"
}
resource "namidb_ip_allowlist_entry" "batch_host" {
api_key_id = namidb_api_key.movies_reader.id # this key only works from here
cidr = "198.51.100.17"
label = "batch runner"
}
Argument
cidr (required)An IPv4 or IPv6 address or range. The API stores the network address, so 203.0.113.7/24 and 203.0.113.0/24 are the same entry
labelA note shown in the console. Changing it replaces the entry
api_key_idPut the entry on this API key’s own list instead of the organization’s

A list with entries admits data API requests (HTTP, Bolt, MCP) only from its addresses; when both the organization and the key have entries, a request must match both. Add your own addresses before the first entry applies, or your applications lose access. Entries per list depend on the plan. Import by id, or <api-key-id>/<entry-id> for a key’s list. See IP allowlists.

Data sources

data "namidb_organization" "this" {}
data "namidb_databases" "tenants" {
name_prefix = "tenant-"
}
data "namidb_database" "analytics" {
name = "analytics" # created in the console
}
output "plan" { value = data.namidb_organization.this.plan }
output "tenants" { value = data.namidb_databases.tenants.names }
  • namidb_organization: id, slug, name, plan, status, spend_cap, require_mfa, created_at, and limits (databases, api_keys, members; null for no limit).
  • namidb_databases: every database (optionally filtered by name_prefix), newest first, as databases (with id, name, status, read_only, http_endpoint, bolt_uri, created_at) and names.
  • namidb_database: one database by name, for databases Terraform does not manage, with id, status, read_only, http_endpoint, bolt_uri, created_at and restored_from_backup.

Behaviour to know

  • Secrets in state. namidb_api_key.token and namidb_management_token.token are full credentials, kept in the state and marked sensitive. Use an encrypted state backend with restricted access.
  • Drift. A database deleted outside Terraform, or replaced by one with the same name, is dropped from the state and planned again. A key or token revoked outside Terraform is dropped and planned again, with a warning. Expired ones stay in the state with status = "expired".
  • Retries. 429 (honouring Retry-After up to 60 s), 503 and connection errors are retried up to 4 times; every create keeps its Idempotency-Key, so a retry never creates twice.
  • Errors carry the API’s message, code, status and request id; quote the request id to support.