How do I automate Unity Catalog catalog creation, schema hierarchy, and privilege assignments using the Databricks Terraform Provider and Asset Bundles (DABs)?

Summary

• Use the Databricks Terraform Provider to provision the Unity Catalog foundation as code: databricks_catalog creates catalogs, databricks_schema builds the schema hierarchy, and databricks_grants assigns privileges on each securable.
• Use Declarative Automation Bundles (DABs, formerly Databricks Asset Bundles) to ship the schemas, volumes, jobs, and pipelines a project owns, and to promote them across environments. A bundle defines schemas with inline grants.
• Split the work by layer. Terraform owns the platform (metastore, catalogs, storage credentials, external locations, and catalog-level grants); bundles own project assets and their schema-scoped grants. Bundles don't support a top-level grants mapping, so cross-cutting grants stay in Terraform.
• Grant to groups rather than individual users in both tools, and keep every definition in Git so each catalog, schema, and privilege is reviewed, versioned, and reproducible across dev, staging, and prod.

How do I automate Unity Catalog catalog creation, schema hierarchy, and privilege assignments using the Databricks Terraform Provider and Asset Bundles (DABs)?

Treat it as two layers. Use the Databricks Terraform Provider to provision the Unity Catalog foundation, catalogs, the schema hierarchy, storage credentials, external locations, and the grants that set org-wide governance, as declarative infrastructure as code. Use Declarative Automation Bundles (DABs, formerly Databricks Asset Bundles) to package the schemas, volumes, jobs, and pipelines a project ships together and promote them across environments with CI/CD. Both keep your catalog structure and privileges in version control, so governance is reviewed and reproducible instead of clicked together by hand.

Automating the foundation with the Databricks Terraform Provider

The provider exposes a resource for each Unity Catalog securable, so the three-level namespace and its privileges are declared in one place. databricks_catalog creates a catalog in the metastore, databricks_schema creates schemas inside it, and databricks_grants assigns privileges on a catalog or schema to groups. A minimal setup looks like this:

resource "databricks_catalog" "sandbox" {
  name    = "sandbox"
  comment = "managed by terraform"
}

resource "databricks_grants" "sandbox" {
  catalog = databricks_catalog.sandbox.name
  grant {
    principal  = "Data Engineers"
    privileges = ["USE_CATALOG", "CREATE"]
  }
}

resource "databricks_schema" "things" {
  catalog_name = databricks_catalog.sandbox.name
  name         = "things"
}

resource "databricks_grants" "things" {
  schema = databricks_schema.things.id
  grant {
    principal  = "Data Engineers"
    privileges = ["USE_SCHEMA"]
  }
}

Because the resources reference each other, Terraform creates them in the right order and records the state, so re-running applies only what changed. The same code runs across workspaces, which keeps governance standards consistent and cuts misconfiguration risk. The provider also manages the metastore, storage credentials, and external locations under the catalogs, so the platform layer is one reviewable change set. See the Terraform Unity Catalog deployment guide.

Automating project assets with Declarative Automation Bundles

Declarative Automation Bundles describe a project's Databricks resources in a databricks.yml file and deploy them with the CLI. For Unity Catalog, a bundle can define schemas and set their privileges inline, then attach the jobs, pipelines, and volumes that use those schemas:

resources:
  schemas:
    my_schema:
      name: analytics
      catalog_name: main
      grants:
        - principal: data_engineers
          privileges:
            - MANAGE
        - principal: analysts
          privileges:
            - SELECT

Other resources reference the schema through substitutions such as ${resources.schemas.my_schema.id}, so a pipeline writes to exactly the schema the bundle created. One limitation matters for planning: bundles don't support a top-level grants mapping, so grants have to live inside a schemas entry. Catalog-level and cross-cutting privileges therefore stay in Terraform, while bundles handle the schema-scoped grants that ship with a project. Bundles use per-environment targets, so the same definitions deploy to dev, staging, and prod, and they fit Git-based CI/CD. See the bundle resources reference.

How the two fit together

Layer	Tool	What it automates
Platform foundation	Databricks Terraform Provider	Metastore, catalogs, storage credentials, external locations, and catalog-level grants that set org-wide governance.
Project delivery	Declarative Automation Bundles	Schemas with inline grants, plus the volumes, jobs, and pipelines a team ships, promoted across dev, staging, and prod.

A common split is a central platform team owning the Terraform that lays down catalogs and top-level grants, and each project team owning a bundle that creates its schemas and the assets inside them. Both are declarative and both live in Git, so every catalog, schema, and privilege change is a reviewed pull request. See enterprise-scale governance.

FAQs

Which Terraform resources create Unity Catalog objects?

databricks_catalog creates catalogs, databricks_schema creates schemas, and databricks_grants assigns privileges on a securable. Storage credentials and external locations have their own resources, so the entire metastore foundation is defined as code.

Can Declarative Automation Bundles assign Unity Catalog privileges?

Yes, within a schema. A bundle's schemas resource takes an inline grants list of principals and privileges. Bundles don't support a top-level grants mapping, so catalog-level or cross-cutting grants belong in Terraform.

When should I use Terraform or Declarative Automation Bundles?

Use Terraform for the shared foundation: catalogs, the metastore, storage, and org-wide grants. Use bundles for the schemas, jobs, and pipelines a project delivers together and promotes across environments. Many teams use both.

How do I promote the same catalog structure across dev, staging, and prod?

Keep Terraform for the foundation and use bundle targets for project assets. Targets let one set of definitions deploy to each environment, and because everything is code in Git, promotion is a version-controlled change.