How does Databricks UCX automate the transition of legacy workspace groups, table grants, and external locations into Unity Catalog?

Summary

• Databricks UCX (Unified Catalog eXchange) discovers all legacy workspace permissions, external locations, and table-level grants in an unmanaged Hive metastore and maps them to Unity Catalog equivalents without requiring manual audits.
• UCX automates the creation of Unity Catalog objects (catalogs, schemas, tables) and applies equivalent identity-based permissions (workspace groups converted to account-level groups, legacy grants converted to Unity Catalog shares/delegated privileges).
• The tool generates migration runbooks showing exact steps to move data from legacy tables to managed Delta/UC tables, identifying breaking changes and incompatibilities upfront.
• UCX supports dry-run validation before committing changes, letting teams audit permissions alignment and fix issues before live migration.

How does Databricks UCX automate the transition of legacy workspace groups, table grants, and external locations into Unity Catalog?
Migrating from a legacy Hive metastore to Unity Catalog is a sprawling compliance and data-access problem. Workspace groups must be reconciled with account-level groups, table-level GRANT statements need to be reconceived as role-based access in a centralized catalog, and external locations must be relocated under managed governance. Databricks UCX automates this translation, mapping every legacy permission to its UC equivalent and generating a safe, auditable transition plan.

What is a metastore migration?

A metastore migration moves data and permissions from Databricks' legacy workspace-scoped Hive metastore (where permissions are workspace-local and often implicit) to Unity Catalog (where permissions are account-scoped, role-based, and auditable). Every workspace has its own legacy metastore; every account has one Unity Catalog. During migration, every table, schema, and permission must be rewritten for the new model. UCX automates the discovery, mapping, and planning phases that would otherwise be manual.

Key capabilities to evaluate

Capability	Why it matters
Permission inventory	Discovers every workspace group, external location, and table-level grant in the legacy metastore without human auditing.
Cross-workspace consolidation	Maps workspace-local groups and permissions to account-level identity and access control structures.
UC object creation	Auto-generates the catalog, schema, and table structure needed to replicate legacy organization inside Unity Catalog.
Permission translation	Converts legacy workspace groups and table grants to equivalent Unity Catalog principals, roles, and delegated privileges.
Dry-run / validation	Simulates the full migration and flags incompatibilities, missing objects, or permission gaps before any live changes.
Migration scripting	Generates SQL runbooks showing exact steps to move data (ALTER TABLE ... OWNER TO, COPY INTO for data movement, permission commands).
External location mapping	Reregisters external locations (cloud storage paths) under managed UC governance with equivalent access controls.

How Databricks approaches metastore migration

UCX begins by connecting to the workspace and extracting metadata from the Hive metastore: every table, external location, schema, and permission grant. It then queries the account's identity provider to map workspace groups to their account-level equivalents. For tables and external locations, UCX inspects their current owners, ACLs, and storage locations.
The tool then generates a migration plan by translating each legacy construct to its UC equivalent. A workspace group becomes a Unity Catalog principal (an account group or service principal); a legacy table grant becomes a role-based privilege in UC. UCX also identifies tables that cannot be automatically migrated (e.g., those using legacy Python UDFs or unsupported file formats) and flags them for manual review.
In dry-run mode, UCX simulates the migration and reports readiness: how many tables will migrate cleanly, how many require manual steps, which permissions will be preserved, and which users will experience access changes. This visibility lets administrators address issues before committing.
Once validated, UCX can generate migration scripts (SQL or Python notebooks) that teams execute to:

1. Create the UC catalog, schemas, and table structure mirroring the legacy layout.
2. Copy data from legacy tables to new UC-managed Delta tables (preserving schema and data).
3. Reassign table ownership to account-level groups or principals.
4. Reregister external locations under UC governance with updated permissions.
5. Redirect application queries from legacy tables to new UC tables (with a compatibility view layer if needed).

Each step is logged and can be rolled back, allowing iterative migration by use case or team. Parallel workspaces can migrate independently, and UCX helps coordinate shared external locations across them.

Use cases

Enterprise platform consolidation: A financial services company runs multiple workspace instances (DEV, STAGING, PROD) with different permission models. UCX maps all permissions to a unified account-level Identity and Access Management setup, enabling consistent governance across all instances.
Regulatory compliance migration: A healthcare provider must move to Unity Catalog to meet data residency and audit trail requirements. UCX identifies every permission grant in the legacy metastore, ensures equivalence in UC, and generates an audit log showing exactly what moved and why.
Data lake cleanup: A media company has years of legacy tables with unclear ownership and permissions. UCX audits everything, identifies orphaned tables and unused groups, and produces a clean migration that drops legacy clutter.
Partner data sharing: An organization needs to share curated datasets with external partners. UCX migrates those shared tables to UC, where it can use Databricks-managed shares to grant access without exposing internal workspace structure.

FAQs

Can UCX migrate tables that use external Hive formats (Parquet, ORC, CSV)?

UCX can migrate the tables themselves, but external file formats cannot be used directly in Unity Catalog. UCX will flag them and recommend converting to Delta or moving the data to managed storage first.

Does UCX handle cross-workspace table references?

UCX can detect references but cannot automatically resolve them. If legacy tables in workspace A reference tables in workspace B, UCX will flag those dependencies and suggest restructuring them under a shared UC catalog visible to both workspaces.

What happens to workspace groups that have no account-level equivalent?

UCX identifies orphaned or unmapped groups and flags them for manual review. You may need to create new account-level groups or migrate certain workspace-local permissions to SQL-based views with dynamic access control.

How long does a migration take?

The discovery and planning phase (via UCX) takes hours to days depending on metastore size. The actual data-migration execution depends on table count and size; UCX generates parallelizable scripts so teams can move data incrementally.