📊 Microsoft Fabric KQL Database Terraform Module

Manages a Fabric KQL Database (fabric_kql_database), typically attached to (created inside) a Fabric Eventhouse. Targets microsoft/fabric ~> 1.12.0.

• 🗄️ Creates a single fabric_kql_database.this keystone item inside an existing workspace (and, optionally, an existing folder), always attached to a parent Eventhouse.
• 🔗 The parent-Eventhouse cross-reference is configuration.eventhouse_id — a required field nested inside the resource's own configuration object, confirmed against the live v1.12.0 schema via the terraform-registry MCP. It is not a bare top-level eventhouse_id scalar.
• 🔀 Supports both database_type = "ReadWrite" (a genuine read/write child database) and database_type = "Shortcut" (a read-only shortcut following a source database in the same or a different Eventhouse/Azure Data Explorer cluster/tenant).
• 🔐 Supports Shortcut invitation tokens via the provider's write-only invitation_token_wo / invitation_token_wo_version pair — the older, deprecated, state-persisting invitation_token argument is deliberately not exposed by this module.
• 📦 Optionally bootstraps schema/DDL content via a definition Attributes Map.
• 🏷️ Optionally attaches pre-existing fabric_tag GUIDs via tags.

💡 Why it matters: getting the parent-Eventhouse cross-reference field name right matters more than it might look — the provider does not expose a flat eventhouse_id argument, and a module that guessed wrong would fail every plan for this resource. This module mirrors the provider's real nested shape exactly.

If these Terraform modules have been helpful to you or your organization, I'd appreciate your support in any of the following ways:

• ⭐ Star this repository to help others discover this Terraform module.
• 🤝 Connect with me on LinkedIn: linkedin.com/in/microsoftexpert
• ☕ Buy me a coffee: buymeacoffee.com/microsoftexpert

Whether it's a star, a professional connection, or a coffee, every gesture helps keep these modules actively maintained and continually improving. Thank you for being part of the community!

flowchart TD
 workspace["terraform-fabric-workspace"]:::neutral
 folder["terraform-fabric-folder"]:::neutral
 eventhouse["terraform-fabric-eventhouse"]:::keystone
 kqldb["terraform-fabric-kql-database"]:::this
 queryset["terraform-fabric-kql-queryset"]:::neutral

 workspace -->|"workspace_id"| kqldb
 folder -->|"folder_id (optional)"| kqldb
 eventhouse -->|"configuration.eventhouse_id"| kqldb
 kqldb -->|"database reference (illustrative)"| queryset

 classDef this fill:#0F6CBD,color:#FFFFFF,stroke:#0F6CBD
 classDef keystone fill:#143551,color:#FFFFFF,stroke:#143551
 classDef neutral fill:#E6E6E6,color:#111111,stroke:#999999

(Validated via the Mermaid Chart MCP. terraform-fabric-eventhouse is the direct parent keystone — the Consumes/Emits tables below show configuration.eventhouse_id prominently, since it is this module's one distinguishing input beyond the universal workspace_id/folder_id shape.)

flowchart LR
 subgraph Inputs
 display_name["display_name"]
 workspace_id["workspace_id"]
 folder_id["folder_id — optional"]
 configuration["configuration — REQUIRED (database_type, eventhouse_id, source_cluster_uri, source_database_name)"]
 invitation["invitation_token_wo / _version — optional, sensitive"]
 definition["definition — optional map"]
 tags["tags — optional"]
 timeouts["timeouts — optional"]
 end

 this(["fabric_kql_database.this"]):::this

 subgraph Outputs
 id["id"]
 ehid["eventhouse_id"]
 dbtype["database_type"]
 ingestion["ingestion_service_uri"]
 query["query_service_uri"]
 end

 display_name --> this
 workspace_id --> this
 folder_id --> this
 configuration --> this
 invitation --> this
 definition --> this
 tags --> this
 timeouts --> this

 this --> id
 this --> ehid
 this --> dbtype
 this --> ingestion
 this --> query

 classDef this fill:#0F6CBD,color:#FFFFFF,stroke:#0F6CBD

(Validated via the Mermaid Chart MCP.)

Resource inventory: one keystone resource, fabric_kql_database.this — no owned children (standalone).

Schema notes that bite:

• Parent-Eventhouse reference confirmed: the live v1.12.0 schema does not expose a top-level eventhouse_id argument on fabric_kql_database. The parent Eventhouse reference is configuration.eventhouse_id — required inside the resource's own configuration Attributes object, alongside database_type (required: "ReadWrite" | "Shortcut") and, for Shortcut databases only, source_cluster_uri / source_database_name / invitation-token fields. This module models configuration as a required variable (no default) with the identical nesting, per this module suite's code-standard convention's "mirror the provider's own block structure" rule.
• configuration is force-new: any change — including database_type or eventhouse_id — recreates the KQL Database.
• The sibling fabric_eventhouse resource's docs explicitly state that its configuration and definition cannot be used together; fabric_kql_database's docs do not repeat that sentence, but share the identical two-mode creation architecture. This module's own example library deliberately combines a populated configuration with a non-empty definition DDL-bootstrap part — see § Architecture Notes for the reasoning and the explicit caveat that this is an unconfirmed-safe assumption pending a live-tenant reconfirmation.
• Write-only invitation token: configuration.invitation_token_wo / invitation_token_wo_version are Terraform 1.11+ write-only arguments — never persisted to state. The older configuration.invitation_token argument is sensitive but not write-only (deprecated, persists to state/plan) and is deliberately not exposed by this module — see § Design Principles.
• format accepts only "Default" today — modeled as its own variable with a validation{} block.
• configuration/definition/timeouts are Terraform Plugin Framework nested Attributes, not classic SDKv2 Blocks — main.tf assigns all three directly with =, never a dynamic block.
• tags is a genuine live attribute (Set of String of fabric_tag GUIDs) — this module exposes it directly as tags, matching the provider's own argument name; it is a closed reference-set of pre-existing fabric_tag GUIDs, not an azurerm-style free-form key/value map.
• This resource supports Service Principal authentication per the provider's own docs — it is not one of the documented delegated-auth-only surfaces. Reconfirm against the live provider changelog before treating this as permanent.

• Fabric: Workspace Contributor (or higher) on the target workspace — the workspace that owns both the parent Eventhouse and this KQL Database. Fabric RBAC in the current model is workspace-scoped, not item-scoped; there is no separate "Eventhouse Contributor" role.
• Entra: the calling Service Principal (or Managed Identity) must be covered by the tenant's "Service principals can use Fabric APIs" setting.
• For database_type = "Shortcut" sourcing an external Azure Data Explorer cluster, the calling principal (or the invitation-token flow) additionally needs read access on that source cluster/database — not a Fabric-workspace-scoped permission, and not independently confirmed against a specific ADX RBAC role this session.
• If tags is populated, the calling principal needs read access to the referenced fabric_tag resources.

⚠️ Not independently verified against a live tenant this session — confirm against current Fabric RBAC documentation before relying on this as a complete permission list for a production rollout.

• The capacity backing the target workspace must be in Active state (not paused) for KQL Database create/read operations — this item type is squarely in the capacity-hosted-state-can-appear-to-drift category this module suite's region/instance/scope-model-warns-about convention.
• The parent Eventhouse must already exist and be reachable — this module has no visibility into whether the Eventhouse ID it is given is actually valid/active beyond what a normal Terraform reference and apply-ordering gives it.
• The tenant's "Service principals can use Fabric APIs" setting must already be enabled in the Fabric Admin Portal before any SPN/MSI auth call succeeds at all.

Delegated-auth exception: KQL Database create/read/update/delete is not among the documented delegated-auth-only surfaces in this module suite's conventions § Authentication model — SPN/MSI auth is expected to work for this resource. Reconfirm against the live provider changelog before treating this as permanent.

terraform-fabric-kql-database/
├── providers.tf # required_providers block, version floor ~> 1.12.0, no provider {} block
├── variables.tf # display_name, workspace_id, folder_id, format, configuration (REQUIRED),...
├── main.tf # fabric_kql_database.this — the sole keystone, a thin total renderer
├── outputs.tf # id, display_name, eventhouse_id, database_type, ingestion/query URIs
├── README.md # this file
├── SCOPE.md # lightweight cross-module contract
└── examples/
 ├── basic/ # ReadWrite KQL Database attached to a parent Eventhouse, no definition
 └── complete/ # ReadWrite KQL Database with a DDL definition part, explicit folder_id, tags

module "kql_database" {
  source = "git::https://github.com/microsoftexpert/terraform-fabric-kql-database.git?ref=v1.0.0"

  display_name = "kdb-telemetry-raw-prod"
  workspace_id = module.workspace.id

  configuration = {
    database_type = "ReadWrite"
    eventhouse_id = module.eventhouse.id
  }
}

The caller configures the fabric provider (Service Principal or Managed Identity, tenant ID) once at the root of the real Terraform configuration — never inside this module.

Consumes

Emits

module "kql_database" {
  source = "../.."

  display_name = "kdb-telemetry-raw-dev"
  workspace_id = var.workspace_id

  configuration = {
    database_type = "ReadWrite"
    eventhouse_id = var.eventhouse_id
  }
}

module "kql_database" {
  source = "../.."

  display_name = "kdb-telemetry-raw-dev"
  description  = "Raw telemetry KQL Database (dev). Owner: Data Engineering."
  workspace_id = var.workspace_id

  configuration = {
    database_type = "ReadWrite"
    eventhouse_id = var.eventhouse_id
  }
}

module "kql_database" {
  source = "../.."

  display_name = "kdb-telemetry-raw-prod"
  workspace_id = var.workspace_id
  folder_id    = module.folder_real_time.id

  configuration = {
    database_type = "ReadWrite"
    eventhouse_id = module.eventhouse.id
  }
}

module "kql_database" {
  source = "../.."

  display_name = "kdb-shortcut-adx-prod"
  workspace_id = var.workspace_id

  configuration = {
    database_type        = "Shortcut"
    eventhouse_id        = module.eventhouse.id
    source_cluster_uri   = "https://clustername.westus.kusto.windows.net"
    source_database_name = "MyDatabase"
  }
}

module "kql_database" {
  source = "../.."

  display_name = "kdb-shortcut-cross-tenant-prod"
  workspace_id = var.workspace_id

  configuration = {
    database_type        = "Shortcut"
    eventhouse_id        = module.eventhouse.id
    source_cluster_uri   = "https://clustername.westus.kusto.windows.net"
    source_database_name = "MyDatabase"
  }

  invitation_token_wo         = var.shortcut_invitation_token # sourced from Key Vault / pipeline secret
  invitation_token_wo_version = 1
}

module "kql_database" {
  source = "../.."

  display_name = "kdb-shortcut-sibling-prod"
  workspace_id = var.workspace_id

  configuration = {
    database_type        = "Shortcut"
    eventhouse_id        = module.eventhouse.id
    source_database_name = "MyDatabase"
  }
}

module "kql_database" {
  source = "../.."

  display_name = "kdb-telemetry-raw-prod"
  workspace_id = var.workspace_id

  configuration = {
    database_type = "ReadWrite"
    eventhouse_id = module.eventhouse.id
  }

  definition = {
    "DatabaseProperties.json" = {
      source = "${path.module}/files/DatabaseProperties.json.tmpl"
    }
  }
}

module "kql_database" {
  source = "../.."

  display_name = "kdb-telemetry-raw-prod"
  workspace_id = var.workspace_id

  configuration = {
    database_type = "ReadWrite"
    eventhouse_id = module.eventhouse.id
  }

  definition = {
    "DatabaseSchema.kql" = {
      source = "${path.module}/files/DatabaseSchema.kql.tmpl"
    }
  }
}

module "kql_database" {
  source = "../.."

  display_name = "kdb-telemetry-raw-prod"
  workspace_id = var.workspace_id

  configuration = {
    database_type = "ReadWrite"
    eventhouse_id = module.eventhouse.id
  }

  definition = {
    "DatabaseProperties.json" = {
      source          = "${path.module}/files/DatabaseProperties.json.tmpl"
      processing_mode = "Parameters"
      parameters = [
        {
          type  = "JsonPathReplace"
          find  = "$.properties.databaseType"
          value = "ReadWrite"
        }
      ]
    }
  }
}

module "kql_database" {
  source = "../.."

  display_name              = "kdb-telemetry-raw-prod"
  workspace_id              = var.workspace_id
  definition_update_enabled = false

  configuration = {
    database_type = "ReadWrite"
    eventhouse_id = module.eventhouse.id
  }

  definition = {
    "DatabaseSchema.kql" = {
      source = "${path.module}/files/DatabaseSchema.kql.tmpl"
    }
  }
}

module "kql_database" {
  source = "../.."

  display_name = "kdb-telemetry-raw-prod"
  workspace_id = var.workspace_id

  configuration = {
    database_type = "ReadWrite"
    eventhouse_id = module.eventhouse.id
  }

  tags = [module.tag_pii.id]
}

module "kql_database" {
  source = "../.."

  display_name = "kdb-telemetry-raw-prod"
  workspace_id = var.workspace_id

  configuration = {
    database_type = "ReadWrite"
    eventhouse_id = module.eventhouse.id
  }

  timeouts = {
    create = "30m"
  }
}

locals {
  kql_databases = {
    "raw"     = "kdb-telemetry-raw-prod"
    "curated" = "kdb-telemetry-curated-prod"
  }
}

module "kql_database" {
  source   = "../.."
  for_each = local.kql_databases

  display_name = each.value
  workspace_id = var.workspace_id

  configuration = {
    database_type = "ReadWrite"
    eventhouse_id = module.eventhouse.id
  }
}

module "kql_database" {
  source = "../.."

  display_name = "kdb-telemetry-raw-prod"
  description  = "Raw telemetry KQL Database, real-time intelligence domain — prod. Owner: Data Engineering."
  workspace_id = var.workspace_id
  folder_id    = module.folder_real_time.id

  configuration = {
    database_type = "ReadWrite"
    eventhouse_id = module.eventhouse.id
  }

  definition = {
    "DatabaseSchema.kql" = {
      source = "${path.module}/files/DatabaseSchema.kql.tmpl"
    }
  }

  tags = [module.tag_pii.id]

  timeouts = {
    create = "30m"
  }
}

module "workspace" {
  source = "git::https://github.com/microsoftexpert/terraform-fabric-workspace.git?ref=v1.0.0"

  display_name = "ws-realtime-core-prod"
  capacity_id  = data.fabric_capacity.shared.id
}

module "folder_real_time" {
  source = "git::https://github.com/microsoftexpert/terraform-fabric-folder.git?ref=v1.0.0"

  display_name = "real-time"
  workspace_id = module.workspace.id
}

module "eventhouse" {
  source = "git::https://github.com/microsoftexpert/terraform-fabric-eventhouse.git?ref=v1.0.0"

  display_name = "eh-telemetry-core-prod"
  description  = "Core telemetry Eventhouse, real-time intelligence domain — prod. Owner: Data Engineering."
  workspace_id = module.workspace.id
  folder_id    = module.folder_real_time.id

  configuration = {
    minimum_consumption_units = 2.25
  }
}

module "kql_database" {
  source = "git::https://github.com/microsoftexpert/terraform-fabric-kql-database.git?ref=v1.0.0"

  display_name = "kdb-telemetry-raw-prod"
  description  = "Raw telemetry KQL Database, real-time intelligence domain — prod. Owner: Data Engineering."
  workspace_id = module.workspace.id
  folder_id    = module.folder_real_time.id

  configuration = {
    database_type = "ReadWrite"
    eventhouse_id = module.eventhouse.id # <-- the confirmed cross-module reference
  }

  definition = {
    "DatabaseSchema.kql" = {
      source = "${path.module}/files/DatabaseSchema.kql.tmpl"
    }
  }
}

Required: display_name, workspace_id, configuration (object — database_type + eventhouse_id required within it). Optional (secure defaults): description, folder_id (workspace root), format ("Default"), invitation_token_wo / invitation_token_wo_version (null), definition ({}), definition_update_enabled (true), tags ([]), timeouts (null).

variable "configuration" {
  type = object({
    database_type        = string
    eventhouse_id        = string
    source_cluster_uri   = optional(string)
    source_database_name = optional(string)
  })
  # REQUIRED — no default
}

variable "invitation_token_wo" {
  type      = string
  default   = null
  sensitive = true
}

variable "invitation_token_wo_version" {
  type    = number
  default = null
}

variable "definition" {
  type = map(object({
    source           = string
    tokens_delimiter = optional(string, "{{}}")
    tokens           = optional(map(string), {})
    processing_mode  = optional(string, "None")
    parameters = optional(set(object({
      type  = string
      find  = string
      value = string
    })), [])
  }))
  default = {}
}

variable "timeouts" {
  type = object({
    create = optional(string)
    read   = optional(string)
    update = optional(string)
    delete = optional(string)
  })
  default = null
}

No output is marked sensitive — the invitation token is never echoed back by the provider's properties block, so there is nothing credential-shaped to surface.

• The parent-Eventhouse field name is the one fact this module cannot afford to get wrong. The live v1.12.0 schema nests it as configuration.eventhouse_id, not a bare top-level eventhouse_id — this was confirmed directly against the provider's own Argument Reference via the terraform-registry MCP (the live provider schema, provider_doc_id 12766477), not assumed from the sibling fabric_eventhouse resource's shape or guessed from naming convention.
• configuration is modeled as a required module variable (no default) — a deliberate, opinionated design choice distinguishing this module from fabric_eventhouse's optional configuration. This module's entire purpose is a KQL Database that is always attached to a parent Eventhouse via cross-module reference; purely definition-driven bootstrap with no Eventhouse attachment (which the provider itself technically supports) is out of scope here.
• invitation_token_wo / invitation_token_wo_version are kept as separate top-level variables (rather than nested inside the configuration object variable) specifically so they can be marked sensitive = true individually, without redacting the non-secret database_type/eventhouse_id fields from plan output — marking the whole configuration object sensitive would have hidden useful, non-secret plan diffs.
• The deprecated configuration.invitation_token argument (sensitive but not write-only) is deliberately not exposed by this module, since the provider persists it to Terraform state and plan files — a direct conflict with this module suite's secure-by-default convention's "secrets are always out of band" rule. Callers who genuinely need that deprecated variant (e.g. running Terraform below 1.11) must manage it outside this module directly against the fabric_kql_database resource.
• definition is rendered with = length(var.definition) > 0 ? {...}: null (never an unconditional map literal), matching every other definition-carrying module in this library. Unlike fabric_eventhouse, where configuration+definition are confirmed mutually exclusive, this module's own examples deliberately combine a populated configuration with a non-empty definition DDL-bootstrap part — a reasoned inference (the two arguments govern non-overlapping concerns for this resource: attachment vs. schema content) rather than an independently confirmed fact. Reconfirm via a live plan/apply in a non-prod tenant before relying on this combination in production.

cd C:\GitHubCode\newfabricmodules\terraform-fabric-kql-database
terraform init -backend=false
terraform validate
terraform fmt -check

Pin ?ref=v1.0.0 in every real composition — never a branch. This module is plan-only; a human applies from a reviewed, approved CI pipeline.

• terraform validate / terraform fmt -check catch: a missing/malformed configuration object (missing database_type or eventhouse_id, invalid database_type enum value), Shortcut-only fields supplied when database_type = "ReadWrite", malformed definition object shapes, and invalid enum values (format, processing_mode, tokens_delimiter, parameters[].type).
• Only a live terraform plan against a real tenant can exercise: whether the target capacity is Active, whether the parent Eventhouse ID actually exists and is reachable, whether the calling principal has sufficient Fabric RBAC (and, for Shortcut sourcing, permission on the external ADX cluster), whether the tenant's SPN/MSI API-access switch is enabled, and whether configuration + definition truly do not conflict for this resource as this module's documentation assumes.

Outputs:

kql_database_id = "7a6b5c4d-3e2f-1a0b-9c8d-7e6f5a4b3c2d"
eventhouse_id = "3f2b1a4c-9d8e-4f7a-b6c5-1e2d3f4a5b6c"
database_type = "ReadWrite"
ingestion_service_uri = "https://telemetry.eh.z1.fabric.microsoft.com"
query_service_uri = "https://telemetry.z1.kusto.fabric.microsoft.com"

• fabric_kql_database provider docs
• Sibling modules: terraform-fabric-workspace, terraform-fabric-folder, terraform-fabric-eventhouse (required parent), terraform-fabric-kql-queryset, terraform-fabric-tag
• This module's SCOPE.md

💙 "Infrastructure as Code should be standardized, consistent, and secure."