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_TOKENAuthentication
The provider uses a management token. Pass it in the environment so it stays out of your configuration:
export NAMIDB_MANAGEMENT_TOKEN=nmdb_mgmt_…terraform plan| Scope | Allows |
|---|---|
read | Data sources |
write | read, plus namidb_database |
admin | write, 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_protection | When true, Terraform refuses to destroy it. Default false |
restore_from_backup_id | Create it by restoring this backup; Terraform waits for the restore. Used only at creation |
clone_from | Create 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.create | Default 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 |
role | read-write (default) or read-only |
databases | Database names; omit for every database, including future ones |
expires_at | RFC 3339; within 2 years and the organization’s key lifetime policy |
rotation_triggers | Any 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 |
scope | read (default), write or admin; at most the provider token’s scope |
expires_at | RFC 3339; within 2 years, the organization’s key lifetime policy and, when the provider’s token expires, no later than it |
rotation_triggers | Any 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 |
label | A note shown in the console. Changing it replaces the entry |
api_key_id | Put 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, andlimits(databases,api_keys,members; null for no limit).namidb_databases: every database (optionally filtered byname_prefix), newest first, asdatabases(withid,name,status,read_only,http_endpoint,bolt_uri,created_at) andnames.namidb_database: one database byname, for databases Terraform does not manage, withid,status,read_only,http_endpoint,bolt_uri,created_atandrestored_from_backup.
Behaviour to know
- Secrets in state.
namidb_api_key.tokenandnamidb_management_token.tokenare 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(honouringRetry-Afterup to 60 s),503and connection errors are retried up to 4 times; every create keeps itsIdempotency-Key, so a retry never creates twice. - Errors carry the API’s message, code, status and request id; quote the request id to support.