TL;DR
A Unity Catalog migration moves your Databricks tables, permissions, users, compute, and code from the old per-workspace Hive metastore to one account-level governance layer. It is more than copying tables. Start with a UCX assessment so you know every table, group, cluster, and mount you have. Move identities and permissions first, then upgrade tables with federation, SYNC, DEEP CLONE, or CREATE TABLE AS SELECT depending on the table type. Update jobs to three-part names, replace DBFS mounts with volumes, and move clusters to a Unity Catalog access mode. Switch off legacy Hive metastore access last, because after 30 days that change cannot be undone.
Key Takeaways A Unity Catalog migration covers identities, permissions, storage, compute, code, and ML assets, and tables are only one part of the work. Databricks started switching off direct Hive metastore access for workspaces with no Hive activity in July 2026, and a workspace becomes Unity Catalog-only for good after 30 days with legacy access disabled. The UCX toolkit from Databricks Labs runs the assessment, group migration, and table migration workflows, but it is not covered by a Databricks support SLA. The right upgrade command depends on the table type, with federation plus SET MANAGED keeping history, SYNC registering external tables in place, and DEEP CLONE copying DBFS-root managed tables. Standard access mode blocks RDD APIs, Hive UDFs, R, and DBFS FUSE paths, so compute changes need their own test cycle. Cut over one domain at a time, and only after data, permission, and workload parity checks pass with a rollback path documented. Watch on YouTube
Databricks Migration: Moving Enterprise Data Off Legacy ETL
Kanerika walks through how enterprises move data and pipelines off legacy ETL onto Databricks, and what to plan before the first workload moves. It is a useful primer before you scope the governance side of the same move.
The Monday Morning After Legacy Access Goes Dark A platform lead opens the job dashboard at seven in the morning and sees a column of red. The nightly pipeline that reads from a finance mount failed on a path error. Two Power BI reports return “table or view not found,” and a data scientist’s notebook refuses to run an RDD call on the new shared cluster.
Nobody deleted anything over the weekend. The workspace simply stopped letting code reach around Unity Catalog, and every shortcut the team had built over five years surfaced at once.
That scene is avoidable. Planning a Unity Catalog migration as a program, with an inventory, a target design, a table-by-table method, and a cutover gate, turns that Monday into a non-event. The rest of this playbook walks through each phase in the order that keeps production running.
What a Unity Catalog Migration Actually Moves Unity Catalog migration is the process of moving a Databricks workspace from the legacy, workspace-scoped Hive metastore to account-level governance in Unity Catalog. If you need the fundamentals first, the guide to Databricks Unity Catalog explains the three-level namespace and core capabilities, and the Databricks metastore explainer covers how a metastore attaches to workspaces. A governed catalog is also a foundation of a sound enterprise AI architecture , because models and agents inherit its access rules.
Enabling Unity Catalog and migrating to it are two different events. Enabling means attaching a workspace to a metastore, which takes minutes.
Migrating means that everything in the Hive metastore, the workspace groups, and the DBFS mounts now lives under Unity Catalog governance. Nothing in production still depends on the old paths.
In practice, six things move together.
Identities. Users, groups, and service principals move from workspace-level provisioning to the Databricks account.Permissions. Legacy table ACLs become Unity Catalog grants on catalogs, schemas, tables, views, and volumes.Tables and views. You upgrade or re-create every object from hive_metastore in a Unity Catalog catalog.Storage access. Mount points and cluster-level credentials give way to storage credentials, external locations, and volumes.Compute. Clusters and jobs move to a Unity Catalog access mode on a supported Databricks Runtime.Code and ML assets. Queries, notebooks, jobs, BI connections, and registered models switch to three-part names and governed paths.Treating any one of these as optional is how migrations stall halfway. A team that upgrades tables but leaves groups workspace-local ends up granting access to objects nobody can actually reach.
Why Enterprises Are Moving to Unity Catalog Now The Hive metastore and its table access control model are now legacy features. Databricks labels the per-workspace Hive metastore as legacy and recommends upgrading every table it manages to Unity Catalog.
The timeline also got sharper this year. According to the Databricks page on disabling legacy Hive metastore access , Databricks began progressively disabling direct Hive metastore access for workspaces with no Hive metastore activity starting in July 2026. The same page says that after 30 days with legacy access disabled, a workspace permanently becomes Unity Catalog-only.
That second point matters more than the first. A workspace that still runs a few forgotten jobs against hive_metastore is not affected by the automatic switch. Once an admin turns legacy access off and the 30-day window closes, though, there is no path back for those jobs.
The upside is just as concrete. Many newer platform features assume Unity Catalog governance.
They include column and row-level controls, automated data lineage in Databricks , volumes for files, models registered in Unity Catalog, and managed-table predictive optimization. The Databricks Unity AI Gateway and Delta Sharing also only work on objects that Unity Catalog governs.
Staying on the Hive metastore means staying outside all of it. For most platform teams, that turns the migration from a compliance chore into a prerequisite for the roadmap the business is already asking for.
Before and After: The Metastore Architecture Shift The architecture change is the reason migration touches so much. In the legacy model, every workspace carries its own Hive metastore, its own table ACLs, its own local groups, and its own DBFS mounts. Two workspaces reading the same data lake have two separate permission models that can drift apart without anyone noticing.
Cluster-level credentials make the gap wider. An instance profile or service principal attached to a cluster can read storage directly, so anyone who can run code on that cluster can often reach data that no table ACL ever mentioned.
In the target model, identities live at the Databricks account level and one Unity Catalog metastore serves every workspace in a region. Storage access runs through storage credentials and external locations, so a table’s permissions follow it into any workspace attached to that metastore.
This also explains why the order of work never changes. Account groups have to exist before grants can reference them, and external locations have to exist before Unity Catalog can register tables that live in your cloud account. The nine phases below follow that dependency chain.
Phase 1: Assess the Estate With UCX Every Unity Catalog migration should start with an inventory, and for most enterprises that inventory comes from UCX. UCX is a Databricks Labs toolkit that assesses a workspace, migrates groups and permissions, and upgrades tables from the Hive metastore to Unity Catalog.
One caveat belongs in the project charter. The Databricks UCX documentation states that Databricks provides UCX as-is, without a formal support SLA, so you file issues on GitHub rather than through a support ticket. Plan for that in your risk register.
What UCX Needs Before It Runs The installer has a short but strict list of prerequisites. Missing any one of them is the most common reason a first UCX run fails.
Databricks CLI v0.213 or above and Python 3.10 or above on the machine running the install. A configuration profile for both the workspace and the parent Databricks account. A user who is both account admin and workspace admin, because the installation cannot run as a service principal. A Unity Catalog metastore in every region that hosts a workspace you plan to upgrade, with those workspaces attached. A Pro or Serverless SQL warehouse to render the assessment report. Installation is one command, databricks labs install ucx, and the assessment runs with databricks labs ucx ensure-assessment-run. The output lands in Delta tables in an inventory schema, which you can query like any other data. Keep that schema after the migration, since it doubles as the baseline for later parity checks.
What the Assessment Tells You The assessment workflow checks group identities, storage locations, storage credentials, access controls, and tables for Unity Catalog compatibility. Read it as a work breakdown, not a pass or fail score.
The useful outputs are the lists. Tables that sit in DBFS root, clusters in no-isolation shared mode, workspace-local groups that carry permissions, and storage paths shared by several tables all become line items in the migration plan.
Run the assessment more than once, because Databricks recommends repeating it until the report accounts for every incompatible entity.
Checklist
Enterprise Databricks Readiness Checklist
A step-by-step checklist for confirming your Databricks environment, governance model, and teams are ready before a platform change such as a Unity Catalog migration.
Get the Checklist → Finding the Dependencies UCX Cannot See UCX inventories objects well, but code is harder. The UCX documentation notes that its code migration workflow is still under development, so treat code discovery as a separate workstream.
Search your repositories, notebooks, and job definitions for a small set of patterns.
Two-part names such as sales.orders, explicit hive_metastore. prefixes, saveAsTable calls without a catalog, dbutils.fs.mount, and paths that start with /mnt/ or dbfs:/ each point to work in Phase 6. Also list BI tools and external applications that connect over JDBC or ODBC, since their connection strings often hardcode a schema.
For compute, the Databricks upgrade guide shows how to query system.compute.clusters for clusters below Databricks Runtime 13.3 LTS or in no-isolation shared mode. If you have not used them before, the guide to Databricks system tables explains how to query them and grant access.
Phase 2: Design the Target Catalog and Storage Model Resist the urge to recreate the Hive metastore one-for-one inside Unity Catalog. A migration is the cheapest moment you will ever get to fix naming, ownership, and environment boundaries, because the team touches every object anyway.
One Metastore per Region Unity Catalog uses one metastore per region, and every workspace in that region attaches to it. Practitioners who have run multiple migrations warn against creating two metastores in the same region, since it splits governance you are trying to unify.
Keep environment separation at the catalog level instead. A common pattern uses catalogs such as dev, test, and prod, or domain catalogs with environment suffixes, and binds each catalog to the workspaces that should see it.
Catalogs, Schemas, and Ownership Map old Hive databases to Unity Catalog schemas, but decide which catalog each one belongs in based on who owns the data and who consumes it. Teams running a medallion architecture often place bronze, silver, and gold as schemas inside a domain catalog, which keeps grants simple.
Assign ownership of catalogs and schemas to groups, not individual users. Databricks generally recommends group ownership, and it stops a migration from stalling the day one engineer changes teams.
Datasheet
Build a Modern Data and AI Foundation With Databricks
How Kanerika designs Databricks platforms, from lakehouse architecture and governance to AI-ready pipelines, so the target you migrate into is built to last.
View the Datasheet → Storage Credentials, External Locations, and Managed Storage Every cloud path that holds table data or files needs a storage credential and an external location before Unity Catalog can govern it. UCX can generate these from its assessment, which is the fastest route for large estates.
Decide early which tables become managed and which stay external. Managed tables get predictive optimization and simpler lifecycle management, while external tables suit data that other engines or teams read directly from cloud storage. Our guide to Databricks CREATE TABLE options covers the practical differences, and the pillar post has more on catalog hierarchy design .
Phase 3: Move Identities and Rebuild Permissions Identity work comes before table work because Unity Catalog grants only apply to account-level principals. The Databricks guide to workspace-local groups is direct about it, stating that you cannot grant these legacy groups access to data in a Unity Catalog metastore.
Converting Workspace-Local Groups to Account Groups Databricks describes a four-step conversion, and the order is what prevents lockouts.
Move SCIM provisioning from the workspace to the account, and turn off the workspace-level provisioner so it stops recreating local groups. Rename each workspace-local group, for example by adding “(workspace)” to its name, so the account group can take the original name. Assign the account groups to the workspace, grant the same entitlements, and migrate their permissions on workspace objects, which the UCX group migration workflow automates. Delete the renamed workspace-local groups once nothing depends on them. Update any Terraform or other automation that manages users and groups so it calls account endpoints instead of workspace endpoints. Teams that manage Databricks through code should review their Terraform setup on Azure or equivalent before the switch.
How the Permission Model Changes Legacy table ACLs do not translate one-for-one into Unity Catalog grants. The Databricks comparison of the two models lists several behavior changes that will surprise users on day one if nobody plans for them.
Table 1: How Hive Metastore Concepts Map to Unity Catalog
Legacy Hive Metastore Unity Catalog Equivalent What Changes During Migration Workspace-scoped metastore Account-level metastore, one per region Every workspace in the region shares one set of objects and grants Database Schema inside a catalog Names gain a catalog prefix, so sales.orders becomes prod.sales.orders Workspace-local groups Account groups Grants must reference account groups, local groups cannot be granted data access USAGE on the root catalog USE CATALOG and USE SCHEMA A table grant alone is not enough, the parent catalog and schema need their own grants DENY statements No DENY, anything not granted is denied Rewrite deny-based rules as narrower grants or row and column filters ANY FILE and ANONYMOUS FUNCTION Not supported File access moves to external locations and volumes with READ FILES grants View owner must own base tables View owner needs SELECT on base tables Views become easier to delegate to analytics teams DBFS mounts under /mnt External locations and volumes Paths change to /Volumes/catalog/schema/volume/ and access is audited
Where Users Feel the Change First Two rows cause the most support tickets. Users who could read a table yesterday get a permission error because nobody granted USE CATALOG on the new parent. Teams that relied on DENY to hide a sensitive table find nothing to translate it into.
Build a grant matrix per domain before the table moves, and test it with a user the grants should refuse as well as one they should let through.
Governance at this step is about more than tooling. Teams that want a broader framing can read our take on data migration governance , and those comparing catalogs across tools can see how Unity Catalog, Purview, and Collibra divide the work.
Phase 4: Upgrade Tables by Type Table upgrades are where most guides start, and they are genuinely the most technical phase. The trap is treating every table the same way, because the right command depends on where the table stores its data and whether it is managed or external.
Before running anything in bulk, classify tables using the assessment output. The decision usually comes down to four questions about federation, table type, storage location, and format.
Option 1: Federate the Hive Metastore, Then Upgrade in Place Databricks now recommends federation as the first option. You federate the Hive metastore as a foreign catalog in Unity Catalog, which lets workloads read and write the same tables through Unity Catalog while legacy jobs keep running.
Once a foreign table is ready, you upgrade it in place without moving data. The Databricks upgrade guide says this workflow preserves table history, configuration, permissions, and views.
-- Convert a federated table to a Unity Catalog managed table
ALTER TABLE hms_foreign.sales.orders SET MANAGED MOVE;
-- Or keep it as a Unity Catalog external table
ALTER TABLE hms_foreign.sales.orders SET EXTERNAL;
-- When nothing depends on federation any more
ALTER CATALOG hms_foreign DROP CONNECTION;Federation also lowers coordination cost. Each workload can move on its own schedule, because the data is reachable from both the Hive metastore and Unity Catalog during the transition.
Option 2: SYNC External Tables SYNC registers an external Hive table as a Unity Catalog external table without copying data. It also works for Hive managed tables stored outside DBFS root when you add AS EXTERNAL.
-- Preview first
SYNC SCHEMA prod.sales FROM hive_metastore.sales DRY RUN;
-- Then run it and hand ownership to a group
SYNC SCHEMA prod.sales FROM hive_metastore.sales SET OWNER `data-platform-admins`;According to the SYNC command reference , SYNC writes bookkeeping properties to each source table, including a pointer to its target. SYNC can also run on a schedule to pick up source changes, which makes it useful while Hive and Unity Catalog run side by side.
Always run the DRY RUN first. If SYNC returns anything other than a success code for a table, read the status code before retrying, because each common code points to a specific fix covered later in this guide.
Option 3: DEEP CLONE Managed Tables in DBFS Root Unity Catalog cannot register managed tables that store data in DBFS root in place, so you have to copy their data. A deep clone copies data and metadata into a Unity Catalog managed table.
CREATE TABLE prod.sales.orders
DEEP CLONE hive_metastore.sales.orders;Plan for one side effect. The Microsoft Learn guide to upgrading Hive tables to Unity Catalog notes that table history is not migrated by CLONE, so time travel to pre-migration versions stops working on the new table.
Option 4: CREATE TABLE AS SELECT for Everything Else CTAS is the fallback for tables that fail the other paths. Typical cases are Hive SerDe tables, non-Delta formats you want to convert, and tables you want to reshape during the move. It gives full control over the target but requires you to restate partitioning, format, and constraints.
Microsoft’s guidance is that CLONE is almost always preferred over CTAS when both work, because clone carries metadata across automatically. Use CTAS deliberately, not as a default.
Views, Non-Delta Tables, and the Upgrade Wizard You recreate views in Unity Catalog after their base tables move, pointing at the new three-part names. Migrate them in dependency order, starting with views over base tables and finishing with views built on other views.
Non-Delta external tables in supported formats, such as Parquet, CSV, or JSON, can move over as external tables through SYNC. The Catalog Explorer upgrade wizard runs SYNC under a visual interface and can schedule repeat syncs, which suits smaller estates or teams that prefer not to script.
Comparing the Upgrade Methods Each method trades speed against control. The table below summarizes what each one produces and what it keeps.
Table 2: Unity Catalog Table Upgrade Methods Compared
Method Source Table Result in Unity Catalog Data Copied History Kept Federation, then SET MANAGED MOVE or SET EXTERNAL Tables in a federated Hive metastore or AWS Glue catalog Managed or external No Yes SYNC External tables, or managed tables outside DBFS root with AS EXTERNAL External No Data stays in place CREATE TABLE DEEP CLONE Managed Delta tables, including those in DBFS root Managed Yes No, starts fresh CREATE TABLE AS SELECT Any readable table, including formats you want to convert Managed Yes No UCX table migration workflow Whole workspaces, driven by a reviewed mapping file External via SYNC, managed via DEEP CLONE for DBFS-root tables Only for DBFS-root tables Depends on the path used
Automating Table Upgrades With UCX For a whole workspace, the UCX table migration workflow automates this choice. Its preparatory command create-table-mapping writes a CSV that maps each Hive table to a target catalog, schema, and table. Another command, create-uber-principal, creates a read-only service principal for the migration jobs.
Review the mapping file with data owners before running anything, and deprovision the uber principal when the upgrade is done.
On-Demand Webinar
Modernize Your Data Stack With Intelligent Migration Accelerators
An on-demand Kanerika session on using automation to cut the manual effort in platform migrations, from code conversion to validation.
Watch the Webinar → Phase 5: Move Compute to Unity Catalog Access Modes Compute is the phase most migration plans underestimate. A cluster that is not in a Unity Catalog access mode cannot read Unity Catalog tables, and some code that ran fine on legacy clusters will not run on the recommended mode.
Databricks compute configuration docs define two access modes. Many users can share a standard-mode cluster, with data isolation between them, and it supports Python, SQL, and Scala. Dedicated mode belongs to a single user or group and also supports R.
What Standard Mode Blocks Databricks recommends standard mode unless a workload needs something it does not support. The standard compute limitations page is the checklist to run every legacy job against.
RDD APIs and Spark Context calls such as sc.parallelize are not supported, so move that logic to DataFrame or Spark SQL APIs. Hive UDFs are not supported, and the replacement is UDFs registered in Unity Catalog. R is not supported, so R notebooks need dedicated compute. Spark-submit job tasks are not supported, and JAR tasks are the replacement. DBFS root and mounts do not support FUSE, and standard mode blocks POSIX-style DBFS paths. Instance profiles for streaming sources such as Kafka or Kinesis are not supported, and service credentials take their place. Databricks Runtime for Machine Learning and GPU instances are not supported on standard mode. Runtime Floor, Policies, and Cost Set a runtime floor as well. The upgrade guide recommends moving all compute and jobs to Databricks Runtime 13.3 LTS or above, where init scripts and libraries are supported in every access mode. Cluster policies help enforce the new modes, and Databricks serverless compute removes much of this decision for SQL and notebook workloads.
Check cost at the same time. Moving from a few large shared clusters to per-team dedicated clusters can change spend, so review your Databricks cost optimization guardrails and SQL warehouse sizing before the switch.
Phase 6: Refactor Code, Jobs, and Paths Code refactoring is where a migration becomes visible to every engineer. The goal is simple to state and slow to finish, with no two-part names, no mount paths, and no hidden dependence on hive_metastore as the default catalog.
Three-Part Names and the Default Catalog Every table reference should become a three-part name in the form catalog, schema, and table, which is the three-level namespace Unity Catalog uses. During the transition, the default catalog setting buys time.
The Databricks default catalog docs explain that you can keep hive_metastore as the workspace default while migrating, so existing code that uses two-part names keeps resolving to the old tables. Once a domain is cut over, flip the default or set it per cluster with spark.databricks.sql.initial.catalog.namespace. Databricks warns that changing the default catalog can break existing operations, so change it one workspace at a time.
Parameterize Catalog Names Hardcoding prod.sales.orders in a notebook just replaces one brittle reference with another. Pass the catalog name as a job or notebook parameter so the same code runs against dev, test, and prod. It also makes rollback cheaper, because pointing a job back at the old tables becomes a parameter change rather than a code change.
catalog = dbutils.widgets.get("catalog") # set per job or environment
df = spark.table(f"{catalog}.sales.orders")
df.write.mode("overwrite").saveAsTable(f"{catalog}.sales.orders_daily")Orchestration then sets the parameter per environment. If you run pipelines through Databricks Workflows or Lakeflow , set the catalog at the job level rather than inside each task.
Replace Mounts With Volumes and External Locations DBFS mounts were a convenient shortcut that bypassed governance. In Unity Catalog, files live in volumes, and code reaches cloud paths through external locations with audited grants.
# Before
df = spark.read.csv("/mnt/finance/raw/2026-09-01.csv", header=True)
# After
df = spark.read.csv("/Volumes/prod/finance/raw_files/2026-09-01.csv", header=True)The upgrade guide also points to Databricks Labs DBFS scanner scripts that list current DBFS usage. Use the output to decide, asset by asset, whether to register it in place, migrate it, or archive it. Move job scripts and notebooks stored on DBFS into workspace files or Git folders, and move JARs, wheels, and cluster-scoped init scripts into volumes.
Datasheet
FLIP Migration Accelerators
Kanerika’s FLIP accelerators automate code and pipeline conversion from tools such as Informatica, SSIS, Talend, DataStage, and Azure Synapse to Databricks.
View the Datasheet → BI Tools, JDBC Clients, and Deprecation Comments Dashboards and external applications often connect with a default schema in the connection string. Update Power BI, Tableau, and JDBC or ODBC clients to point at Unity Catalog objects, and test refreshes against a SQL warehouse before the old tables are dropped.
One small trick speeds up the long tail. Microsoft’s migration guide describes adding a comment to each migrated Hive table, in the form “This table is deprecated. Please use catalog.schema.table instead of hive_metastore.schema.table.” Notebooks then show the old name struck through with a quick fix that Genie Code can apply.
Phase 7: Bring ML Models and Feature Tables Along Machine learning assets are the part of a migration that data engineering plans tend to skip. Models registered in the workspace model registry, feature tables, and serving endpoints all need a Unity Catalog path.
The Databricks guide to upgrading ML workflows to models in Unity Catalog recommends an incremental approach. Clone the training, deployment, and batch inference workflows, point the clones at Unity Catalog, and switch consumers over once results match.
For model serving, you do not need a new endpoint. Databricks suggests using traffic split to route a small share of requests to the Unity Catalog model version, then increasing it as results hold up. Grant CREATE MODEL and EXECUTE privileges to the right groups first, and use aliases rather than stages to manage which version is in production.
Feature tables follow the same logic as other tables, since they are Delta tables that move into Unity Catalog schemas. The Databricks feature store guide and our post on Databricks MLOps cover the surrounding pipeline changes.
Watch on YouTube
Databricks Summit 2026 Recap: LTAP, Genie Ontology & Unity AI Gateway
Kanerika recaps the Data + AI Summit 2026 announcements, including the Unity AI Gateway and new governance features, most of which assume your models and data already live in Unity Catalog.
Phase 8: Validate, Cut Over, and Keep a Rollback Path A migration ends when production runs on Unity Catalog and nobody noticed the switch. Getting there needs three kinds of parity, each with its own evidence.
Data Parity Compare row counts, schemas, and checksums or hash aggregates between each Hive table and its Unity Catalog counterpart. Sample records for tables where a CTAS changed types or partitioning. For tables still receiving writes, compare over the same time window so late-arriving data does not look like a defect.
Permission Parity Test access with real users and service principals. Each domain should have an allowed test, where a user who needs a table can read it, and a denied test, where access fails for a user who should not have it. Check ownership too, because whoever runs a migration job owns the tables it creates unless SET OWNER assigns a group.
Workload Parity and Parallel Runs Run the new pipelines alongside the old ones for at least one full business cycle, whether that is a day, a week, or a month-end close. Jobs, dashboards, and downstream extracts should produce matching results before consumers move. The data migration testing guide has test patterns you can reuse.
Rollback Planning Keep the Hive metastore tables readable until a domain has run clean on Unity Catalog. While legacy access stays enabled, rollback means pointing jobs back at the old names, which is why the default catalog setting and parameterized catalog names matter.
Write the rollback steps down per domain, with an owner and a trigger condition. The one step you cannot roll back is the last one in this playbook.
Phase 9: Switch Off Legacy Access Retiring legacy access is what makes the migration stick. Without it, a forgotten job or a new hire can keep writing to hive_metastore indefinitely.
Databricks gives workspace admins three switches. Disable legacy Hive metastore access so users cannot bypass Unity Catalog, disable DBFS root and mounts once file workflows have moved, and block new no-isolation shared clusters. Once an admin disables legacy Hive access, the hive_metastore catalog disappears from Catalog Explorer and clusters need an initial Unity Catalog catalog.
Two details belong on the go-live checklist. No-isolation shared clusters do not respect the Hive metastore disable setting, so enforce user isolation for the workspace first. And after 30 days with legacy access disabled, the workspace permanently becomes Unity Catalog-only, so only flip the switch once every cutover gate is green.
A Phased Unity Catalog Migration Plan With Owners A workable plan runs domain by domain rather than as one big weekend. Pick a pilot domain with real consumers but modest blast radius, migrate it end to end, and use what breaks to refine the runbook for everyone else.
Stages, Owners, and Exit Criteria Table 3: Unity Catalog Migration Phases, Owners, and Exit Criteria
Stage Main Work Primary Owner Exit Criterion Assess UCX install and assessment, code search, BI and JDBC inventory Platform admin Every table, group, cluster, and mount has a planned action Design Catalog layout, storage credentials, external locations, managed vs external decisions Data architect Reviewed table mapping file and grant matrix Identity Account-level SCIM, group conversion, permission migration Identity and security team No workspace-local group holds data permissions Pilot domain Table upgrade, compute change, code refactor, parallel run for one domain Domain data engineering lead All five cutover gates green for the pilot Domain waves Repeat the pilot runbook per domain, including ML assets and BI Domain leads with platform support Consumers switched, old tables marked deprecated Retire legacy Disable Hive metastore, DBFS root and mounts, no-isolation shared compute Platform admin No Hive metastore activity, legacy access disabled
Timelines and Change Management Durations vary too widely by estate size to promise a number, and any vendor that quotes one before an assessment is guessing. What reliably shortens the timeline is doing identity work early, since it blocks every domain, and keeping the pilot small enough to finish in one iteration.
Case Study
Zero-Downtime Databricks Migration for Retail Analytics
Kanerika moved a large US retailer’s business-critical applications from on-premise PostgreSQL and Cassandra into Delta Lake tables under Unity Catalog-managed schemas, using phased cutover and parallel availability so production never went down.
Read the Case Study → Change management matters as much as commands. Tell users which names change, when the default catalog flips, and where to ask for access, and publish the grant matrix so requests go to the right owner. Our data migration checklist and our look at common data migration challenges cover the people side in more depth.
Common Unity Catalog Migration Errors and How to Fix Them Migration errors tend to fall into a handful of patterns, and each has a known fix. When a SYNC run fails, start with its output, because every table returns a status code that names the problem.
SYNC Status Codes and Their Fixes DBFS_ROOT_LOCATION. The table stores data in DBFS root, which Unity Catalog cannot register in place, so copy it with DEEP CLONE.NOT_EXTERNAL. Someone pointed SYNC at a managed table, so use DEEP CLONE or add AS EXTERNAL if the data lives outside DBFS root.HIVE_SERDE. Hive SerDe tables are not supported, so convert the table to Delta, then run SYNC.LOCATION_OVERLAP. The table path overlaps another external table, so give each table its own storage path.MULTIPLE_TARGET_TABLE. The source was already synced to a different target, so remove the upgraded_to table property or drop the old target.Runtime Errors After Cutover Outside SYNC, a few runtime errors show up in almost every migration.
Table or view not found after the move. Code is still using a two-part name that resolves to the wrong catalog, so use the three-part name or set the right default catalog.Permission denied on a table the user can see. The user has SELECT but lacks USE CATALOG or USE SCHEMA on the parents.Path errors on /mnt or dbfs:/ locations. The job depends on a mount that no longer resolves, so move it to a volume or external location.Jobs that fail only on shared clusters. The code uses something standard mode blocks, such as RDDs or Hive UDFs, so rewrite it or move it to dedicated compute.Hive tables still visible after cutover. A no-isolation shared cluster is bypassing the disable setting, so enforce user isolation.For platform issues beyond migration, the Databricks troubleshooting guide and our notes on Databricks performance optimization help once workloads are running on the new catalogs.
Kanerika Service
Databricks Consulting and Implementation
Kanerika plans and delivers Databricks programs end to end, from Unity Catalog migration and governance design to pipeline modernization and AI workloads.
Explore Databricks Services How Kanerika Runs Unity Catalog Migrations Kanerika is a Databricks consulting partner that treats a Unity Catalog migration as a platform program, not a script run. Our teams work through five stages, and each one produces something a client can review before the next begins.
A Five-Stage Delivery Approach Assess. We run the UCX assessment alongside our own code and dependency scans, then turn the output into a per-domain work plan with named owners.Design. We agree the catalog layout, storage model, and grant matrix with data owners before any table moves.Migrate. We move identities first, then upgrade tables by type, refactor code to parameterized three-part names, and move compute to the right access mode.Validate. We run data, permission, and workload parity checks in parallel with production and hold each cutover until every gate passes.Enable. We hand over runbooks, train platform teams on the new permission model, and retire legacy access only when the client signs off.Accelerators and Results Migrations rarely stop at the metastore. Clients moving legacy ETL onto Databricks at the same time can use Kanerika’s FLIP migration accelerators . They automate conversion from tools such as Informatica, SSIS, Talend, DataStage, and Azure Synapse to Databricks, so the new pipelines land directly in Unity Catalog-governed schemas.
That approach has held up in production. In one engagement for one of the largest retail corporations in the United States, Kanerika migrated business-critical applications from on-premise PostgreSQL and Cassandra into Delta Lake tables under Unity Catalog-managed schemas. The migration ran in three phases with parallel availability and per-application cutover, so the business saw zero downtime, and the team decommissioned the legacy infrastructure only after validating every application.
In another, a healthcare provider moved Informatica workflows to Azure Databricks using Kanerika’s migration accelerator. The client reported 71% higher reporting accuracy, a 38% reduction in data handling costs, and 64% faster decision-making.
Case Study
71% Higher Reporting Accuracy With Informatica to Databricks
A healthcare provider moved Informatica workflows to Azure Databricks with Kanerika’s migration accelerator and reported 71% higher reporting accuracy, 38% lower data handling costs, and 64% faster decision-making.
Read the Case Study → What Our Teams Watch For The pitfalls our teams watch for are consistent across clients. Grants that reference workspace-local groups, managed tables hiding in DBFS root, jobs on no-isolation shared clusters, and dashboards with hardcoded schemas cause most of the late surprises.
Catching them in the assessment is far cheaper than finding them on cutover day. If you are also weighing wider platform moves, our guides to data platform migration and Hadoop to Databricks migration cover the steps before this one.
Wrapping Up A Unity Catalog migration succeeds when teams run it as a sequence rather than a single command. Assess with UCX, design the target, move identities before tables, pick the upgrade method per table type, and give compute and code their own test cycles. Validate with real users and parallel runs, keep a rollback path, and switch off legacy access only when every gate is green.
With Databricks already disabling Hive metastore access on inactive workspaces, the cheapest time to plan that sequence is before your own deadline arrives. Talk to Kanerika about scoping yours.
Frequently Asked Questions
What is a Unity Catalog migration in Databricks? A Unity Catalog migration moves a Databricks workspace from the legacy per-workspace Hive metastore to account-level governance in Unity Catalog. It covers identities, permissions, tables, storage access, compute, code, and ML models. Tables are only one part, so plan it as a program with an assessment, a target design, phased cutovers, and a final switch-off of legacy access.
How do I migrate from the Hive metastore to Unity Catalog? Start with a UCX assessment, then move identities to the account and convert workspace-local groups. Attach each workspace to a regional metastore, create storage credentials and external locations, and upgrade tables with federation, SYNC, DEEP CLONE, or CREATE TABLE AS SELECT. Refactor code to three-part names, move compute to Unity Catalog access modes, validate, and disable legacy access last.
Is UCX required for a Unity Catalog migration? UCX is not required, but Databricks recommends it for most workspace upgrades, especially large ones. It runs the assessment, group migration, and table migration workflows. Smaller estates can use SYNC, CLONE, or the Catalog Explorer upgrade wizard directly. UCX is a Databricks Labs project provided as-is, so it has no Databricks support SLA.
Should I use SYNC or DEEP CLONE to upgrade tables? Use SYNC for external tables, and for managed tables stored outside DBFS root with AS EXTERNAL, because it registers data in place without copying it. Use DEEP CLONE for managed Delta tables in DBFS root, since that data must be copied into Unity Catalog storage. Remember that CLONE does not carry table history, so pre-migration time travel stops working.
What happens to Hive metastore tables after migration? The original Hive tables stay in the hive_metastore catalog until you drop them or disable legacy access. SYNC adds bookkeeping properties that point to the new target. Many teams add a deprecation comment so notebooks flag the old name. Dropping an external Hive table does not delete its data files in cloud storage.
Can the Hive metastore and Unity Catalog run side by side during migration? Yes. A Unity Catalog workspace can still query the hive_metastore catalog, and you can keep it as the default catalog so existing two-part names keep working. Hive metastore federation goes further by exposing Hive tables through Unity Catalog while legacy jobs keep running. Coexistence ends when you disable legacy access for the workspace.
Is Unity Catalog owned by Databricks? Databricks created Unity Catalog and runs the managed version inside the Databricks platform, where your migration lands. There is also an open-source Unity Catalog project, which its GitHub repository describes as a sandbox project with the LF AI and Data Foundation, part of the Linux Foundation. The open-source version supports multiple formats and engines.
Are a catalog and Unity Catalog the same thing? No. Unity Catalog is the governance layer and metastore for a Databricks account. A catalog is the top level of its three-level namespace, catalog, schema, and table, and one metastore can hold many catalogs, such as dev, test, and prod. The legacy hive_metastore also shows up as a catalog in Unity Catalog workspaces.
How do permissions change after moving to Unity Catalog? Grants move from workspace-local groups to account groups, and access needs USE CATALOG and USE SCHEMA on parent objects, not just a table grant. Unity Catalog has no DENY statement, no ANY FILE privilege, and no READ_METADATA privilege. View owners only need SELECT on base tables rather than owning them, which makes delegation easier.
What breaks when clusters move to standard access mode? Standard access mode blocks RDD APIs and Spark Context calls, Hive UDFs, R, spark-submit tasks, DBFS FUSE paths, and instance profiles for streaming sources. Databricks Runtime for Machine Learning and GPU compute are also unsupported there. Rewrite that code with DataFrame APIs and Unity Catalog UDFs, or run those workloads on dedicated access mode instead.
How do I migrate DBFS mounts to Unity Catalog? Create a storage credential and an external location for each cloud path behind a mount, then create volumes for file data. Copy anything stored in DBFS root into the new location. Update code from /mnt paths to /Volumes paths, move scripts and init scripts out of DBFS, and unmount the old mount points once reads are verified.
How do I migrate MLflow models to Unity Catalog? Databricks recommends cloning your training, deployment, and batch inference workflows so the clones register and load models in Unity Catalog. Grant CREATE MODEL and EXECUTE to the right groups, and use aliases to manage production versions. For model serving, use traffic split to shift requests gradually to the Unity Catalog model version.
What happens when Databricks disables Hive metastore access? Users can no longer bypass Unity Catalog to reach Hive metastore tables, and the hive_metastore catalog disappears from Catalog Explorer. Clusters need an initial Unity Catalog catalog. Databricks began disabling access automatically for workspaces with no Hive activity in July 2026, and after 30 days of disabled access a workspace permanently becomes Unity Catalog-only.
How long does a Unity Catalog migration take? Duration depends on the number of tables, jobs, groups, and consuming applications, so it should be estimated from a UCX assessment rather than guessed. Small workspaces with mostly external tables can move quickly. Estates with DBFS-root managed tables, legacy compute code, and many BI connections take longer because of data copies, code rewrites, and parallel runs.
