What an OpenMetadata migration involves
An OpenMetadata migration is one of two different jobs, and each carries different risks. The first moves catalog metadata (assets, owners, glossary terms, domains and lineage references) from another catalog or from spreadsheets into OpenMetadata. The second upgrades an existing 1.x installation to 2.0 and clears its breaking changes before cutover. Common triggers for the first path are retiring a legacy catalog or consolidating spreadsheet inventories that no longer match how data is owned. The second is usually triggered by moving onto a supported major version.
For the catalog move, the first task is to confirm what the source actually holds and in what form. Ask whether owners are recorded as people or as team names, whether glossary terms link to assets or only sit in a list, and whether lineage exists as stored relationships or only as diagrams. Each of these needs a mapping decision before any data is loaded, and spreadsheet inventories often hide gaps where an asset has no owner or two domains claim the same table.
The 2.0 upgrade is different because it changes the platform itself. OpenMetadata 2.0.0 was released on August 24, 2026. Breaking changes that need work before cutover include moving embedding credentials into an llmConfiguration block, a new Databricks authentication format, rebuilding custom ingestion images for Python 3.12, and migrating Great Expectations to 1.3 before the upgrade. Confirm which of these apply to your connectors and custom images, because they can block the upgrade if left until the production window.
In-house delivery is workable when your team already owns the source exports, can write mapping scripts against the REST APIs or Python SDK, and has time to test in a non-production copy. A partner is worth weighing when the migration has a fixed deadline, several source catalogs or large spreadsheet estates, or custom ingestion that must be rebuilt. DeployOpen works to a fixed scope agreed in writing before work starts, so ask any provider for the written scope, the named deliverables and the exit criteria, and compare the quote against that scope.
What the work includes
Migrations into OpenMetadata follow the same sequence whether the source is another catalog or spreadsheets. Clients receive a mapping specification, import scripts or SDK jobs, reconciliation reports, and a rollback plan with a runbook.
Source inventory and mapping
Every source catalog, spreadsheet and glossary export is listed with its owners, object counts and fields. Each field is mapped to an OpenMetadata entity, custom property or glossary term, and unmapped fields are logged with a recorded decision. The mapping specification becomes the document that the import is built and checked against.
Entity, glossary and ownership import
Services, databases, tables, glossary terms and domains are loaded through the REST APIs or the Python SDK in dependency order, so parent entities exist before their children. Owners and teams are resolved against users and groups already present in the instance. Missing owners are reported for a decision before each load runs.
Validation and reconciliation
Object counts and identifiers from each source are compared with what OpenMetadata holds after every load. Reconciliation reports list missing entities, duplicate fully qualified names, orphaned glossary links and ownership mismatches. Each exception gets a named owner and is closed or formally accepted before cutover.
Cutover and rollback runbook
The runbook sets the freeze window for source catalogs, the final incremental load, the sign-off points and who makes the go or no-go call. The rollback plan states how the previous catalog stays readable and how loads are reversed or replayed if reconciliation fails after switchover.
2.0 breaking-change review
For 1.x installs, each OpenMetadata 2.0 breaking change is traced to the configuration it affects. Embedding credentials move into an llmConfiguration block, Databricks connections need the new auth format, and affected pipelines are updated and tested on a non-production instance first. The output is a change list tied to each pipeline.
Ingestion image rebuilds and checks
Custom ingestion images are rebuilt for Python 3.12, which 2.0 ingestion images use alongside Apache Airflow 3.3.0. Custom connector code and plugins are tested against that runtime. Great Expectations is migrated to 1.3 before the upgrade so that data quality checks run correctly during the cutover window.
What drives cost and duration
The table lists the factors that move migration effort for an OpenMetadata move, why each one matters and how to keep it under control before cutover.
| Driver | Why it moves effort | How to keep it down |
|---|---|---|
| Volume of assets and columns | Every table, column, dashboard and pipeline must be mapped, validated and re-ingested, so effort grows with the catalog size and the number of fields carried over. | Agree which asset types and schemas are in scope for the first cutover, and archive stale objects before export. |
| Number of source systems and export quality | Each source needs its own export format, mapping and validation, and inconsistent or incomplete exports create rework that is hard to spot until lineage and ownership look wrong. | Clean and deduplicate sources before export, standardize naming, and check a sample of each export against the source catalog. |
| Ownership and glossary data reconciled by hand | Owners, teams, glossary terms and their relationships often live in spreadsheets or in people's heads, and matching them to OpenMetadata domains and roles needs human review. | Name one accountable owner per domain, freeze the glossary before migration, and record decisions in a reconciliation log. |
| Custom ingestion images and connectors from 1.x | Custom ingestion images built on 1.x must be rebuilt for Python 3.12 and the 2.0 ingestion stack, and each custom connector needs regression testing against its source. | Inventory every custom image and connector first, retire unused ones, and rebuild only what the first cutover needs. |
| Deployment target and its prerequisites | Kubernetes and bare metal installs each require their own setup, and bare metal depends on Java 21, a supported database version and Elasticsearch 9.x or OpenSearch 3.x being in place. | Confirm the target platform and its prerequisite versions with the vendor documentation before planning, and size the server, database and search services against the published minimums. |
| Number of environments kept in step | Development, test and production instances each need the same schema changes, connector configuration and evidence, so every extra environment multiplies testing and drift checks. | Limit the number of environments that receive the migration, promote changes through one pipeline, and compare configuration across environments before each step. |
| Compliance evidence needed for cutover | Assessors may ask for records of who approved the cutover, what changed, how data was validated and how access was restored, which adds documentation and sign-off steps. | Agree the evidence list with your compliance lead before work starts, and capture screenshots, logs and approvals as each step is completed. |
Project phases and outputs
The sequence moves catalog metadata into OpenMetadata or upgrades a 1.x install to 2.0, with each change tested before it reaches production.
Discover sources and inventory metadata
Your team and the DeployOpen engineers list every source catalog, spreadsheet, connector and owner, then record which assets, glossary terms and ownership records must move. Output: a signed-off source inventory with volumes, owners and the OpenMetadata version the work is based on.
Design target model and field mapping
Define domains, glossary structure, ownership roles and the mapping from each source field to an OpenMetadata entity, including how spreadsheet columns become classifications or custom properties. Check: data owners approve the mapping document, and every unmapped field is either assigned a destination or formally dropped.
Load and reconcile in non-production
Load the inventory into a non-production OpenMetadata environment using scripted or API-driven imports, then compare entity counts, ownership assignments and glossary links against the source. Output: a reconciliation report listing each mismatch, its cause and its disposition, approved by data owners before the production load.
Remediate breaking changes and rehearse upgrade
For installs moving to 2.0, address the documented breaking changes before cutover: move embedding credentials into the llmConfiguration block, adopt the new Databricks auth format, rebuild custom ingestion images for Python 3.12 and migrate Great Expectations to 1.3. Rehearse the full upgrade on a copy of production data. Output: a tested runbook and a rehearsal log with remaining fixes closed.
Cut over and run hypercare
Freeze source edits, run the final incremental load, switch users and ingestion schedules to the production instance, then monitor connectors, search indexing and sign-in through an agreed hypercare period. Output: a cutover record with the final reconciliation, a documented rollback point and a closeout report listing open issues and their owners.
What teams keep and what they outsource
This table splits the OpenMetadata migration into work most teams keep in-house and work often outsourced, with the skills each part needs, so you can see where your own people are required.
| Work part | Who usually owns it | Skills needed | Notes for the decision |
|---|---|---|---|
| Metadata ownership decisions | In-house | Data governance, domain knowledge | Deciding which team owns each asset must come from your organization, since no partner can make those calls for you. |
| Business definitions and glossary sign-off | In-house | Data stewardship, business domain expertise | Stewards approve term wording and links to assets; a partner can draft the structure but not the approvals. |
| Final acceptance and cutover approval | In-house | Data platform leadership, stewardship | Acceptance criteria should be written before the migration starts so sign-off is a check, not a debate. |
| Mapping design from the source catalog | Often outsourced | Metadata modeling, familiarity with the source catalog and OpenMetadata entities | Covers how source objects, tags and owners map to OpenMetadata entities. Ask the partner to show the mapping document before import code is written. |
| Scripted import through the APIs | Often outsourced | Python SDK or REST API work, JSON handling, error and retry design | Scripts should be repeatable and idempotent so a failed run can be rerun without duplicates. Confirm the SDK version against your target release. |
| Upgrade rehearsal from 1.x to 2.0 | Often outsourced | Kubernetes or bare metal operations, database administration, release notes review | Rehearse on a copy of production data. Breaking changes such as the llmConfiguration move and the Databricks auth format must be handled before cutover. |
| Custom ingestion image rebuilds | Often outsourced | Docker, Python 3.12 packaging, Apache Airflow 3.3.0 compatibility | Custom connector images must be rebuilt for Python 3.12. Confirm every connector dependency installs on the new base before scheduling the upgrade. |
| Reconciliation tooling | Often outsourced | Python or Java SDK work, SQL, data quality checks | Compares counts, owners, glossary links and lineage edges between the source and OpenMetadata. Agree the pass criteria in writing first. |
What usually goes wrong
Most OpenMetadata migrations stall at a small number of predictable points. Each card names the failure and the check that prevents it before cutover.
Breaking changes found after cutover
Teams often start the upgrade and treat 2.0 as a normal patch, then discover breaking changes in production. Review the OpenMetadata 2.0 release notes against your installed version before cutover, covering embedding credentials moving into an llmConfiguration block, the new Databricks auth format and Great Expectations 1.3 migration. Record each change as a pass or fix item.
Duplicate owners and glossary terms
Importing from a spreadsheet or a previous catalog often creates two owner records for one team and two glossary terms for one concept. Before loading, reconcile team names, user identities and term definitions against a single approved list. Then run a duplicate report after the first import and assign one steward per term.
Lost lineage and orphaned references
Spreadsheet-based lineage usually names tables that were renamed or deleted, so the imported links point nowhere. Map every source reference to a fully qualified asset name in the target service, and load lineage only after the referenced assets exist. Flag any reference that does not resolve so an owner can decide whether to fix or retire it.
Ingestion failures after the Python 3.12 move
Ingestion images in 2.0 run Python 3.12 with Apache Airflow 3.3.0, so custom connector images built for older runtimes can fail at startup or during extraction. Rebuild every custom ingestion image, then run each connector against a non-production source and compare record counts with the previous run. Confirm the Airflow version your scheduler uses before scheduling the first run.
Authentication cutover conflicts
OpenMetadata does not run multiple authentication mechanisms at once, so enabling SSO while basic authentication accounts still exist can lock users out or leave an unmanaged login path open. Agree on a single identity mechanism, map existing accounts to the identity provider, and set a dated switch-off for basic logins. Test an administrator recovery path before the switch.
Unrehearsed rollback
A rollback plan that has never been run usually fails when the database has already accepted new metadata. Take a verified database backup and search index snapshot before the upgrade, restore both into a separate environment, and time the restore against your change window. Decide in advance which edits made after cutover are kept and which are discarded.
How the work differs by starting point
When the source is another data catalog, the work is mainly mapping. Your team and the implementation partner decide which entities, owners, glossary terms, classifications and lineage links move, and which are rebuilt by connectors after cutover.
- Scope: mapping the old model to OpenMetadata domains, glossary terms, tags and ownership, then loading records through exports, the REST APIs or the Python SDK.
- Extra risk: duplicate assets when imported records and connector-created entities describe the same table under different names.
- Confirm: which source catalog version and export formats are available, who owns each domain, and whether historical lineage must be kept or can be regenerated from query logs and pipelines.
Spreadsheets usually hold definitions and ownership but little structured technical metadata, so the work starts with cleaning the data before any load. The sheets become the input to a controlled import rather than the source of record going forward.
- Scope: normalizing columns, removing duplicate terms, assigning owners and loading records through the APIs or the Python SDK.
- Extra risk: conflicting definitions for the same term across sheets, and owners who have left the organization or changed roles.
- Confirm: which sheet is the approved source for each definition, who signs off on glossary terms, and which technical assets will come from connectors and which need manual entry.
An upgrade changes an existing running install, so the work centers on the breaking changes in 2.0 being handled before the cutover. Several changes affect configuration and custom code, not only the core application.
- Scope: moving embedding credentials into the llmConfiguration block, updating Databricks connections to the new auth format, rebuilding custom ingestion images for Python 3.12 and migrating Great Expectations to 1.3 first.
- Extra risk: the profiler now defaults to Dynamic Sampling, which can change data quality results, and MCP is enabled by default, so access settings need review.
- Confirm: your current 1.x version, whether Great Expectations is in use, which custom code references the Knowledge Center (now the Context Center), and which 2.0 maintenance release the target will be.
The deployment target changes the dependency and sizing work, while the metadata itself is the same. Each option moves operational responsibility to a different team.
- Kubernetes: charts or manifests, secrets, persistent volumes for the database and search service, ingress and TLS. OpenMetadata documents production use on EKS, AKS, GKE and on-premises clusters.
- Bare metal: Java 21, MySQL 8.0.42 or later or PostgreSQL 15 or later, and Elasticsearch 9.x or OpenSearch 3.x. The documented minimum server is 2 vCPUs, 4 GB RAM and 20 GB storage, with the database and search services each needing at least 2 vCPUs, 2 GB RAM and 30 GB storage.
- Extra risk: bare metal leaves OS patching, service restarts and database backups with your team, while Kubernetes adds cluster version and storage class dependencies.
- Confirm: the target distribution and version, whether a managed database or search service is allowed, and sizing based on expected catalog size and connector count.
What the client needs to provide
Migration starts with access and decisions, not installation. Provide exports of the source catalog or spreadsheets in a form we can read, read-only credentials for the systems those catalogs describe, and admin rights on the target OpenMetadata environment and at least one non-production environment for rehearsals. Each data domain also needs a named owner who can answer questions about its assets, owners and definitions during mapping and acceptance.
Several decisions must be made before the mapping is built. Decide the owner model (who owns a table, a dashboard or a glossary term, and whether ownership is individual or team-based), who has final authority over glossary terms when two sources disagree, the cutover window in which the old catalog becomes read-only, and the acceptance criteria that will mark the migration complete. Written criteria, such as which domains and asset types must reconcile and who signs off, prevent the project from drifting after cutover.
Confirm the infrastructure against OpenMetadata's bare metal prerequisites before scoping: Java 21 on the application hosts, MySQL 8.0.42 or later or PostgreSQL 15 or later for the database, and Elasticsearch 9.x or OpenSearch 3.x for search. Check the exact versions your organization can support, because the database and search choices affect upgrade paths. Compare planned capacity with the documented minimums of 2 vCPUs, 4 GB RAM and 20 GB storage for the server, and at least 2 vCPUs, 2 GB RAM and 30 GB storage for each of the database and search services. Treat these as floors, and size higher for the number of assets being loaded.
If you are upgrading an existing 1.x install to 2.0, also confirm the custom ingestion images you run, the Python version they use, the Great Expectations version in use and any embedding credentials, since these are breaking-change areas. Name the person who can approve a maintenance window and rollback plan. Ask the implementation partner to confirm which of these items apply to your environment before the written scope is agreed.
Frequently asked questions
What makes an OpenMetadata catalog move cost more or less?
Scope drives cost more than any single factor. Discovery and mapping cost more when the source catalog has many entity types, custom fields or inconsistent ownership. Data cleanup costs more when the source is spreadsheets. Ingestion rework grows with the number of pipelines, and upgrade work rises for 1.x installs with custom ingestion images, Great Expectations tests or Databricks connections. Recurring costs, such as infrastructure and support, sit outside the migration itself. Ask for a quote that separates discovery, build, testing, cutover and documentation, and that states which items are one-time.
How long does a migration take before cutover?
The schedule depends on the source, the target and how many test cycles the cutover needs. No duration has been fixed for this topic, so ask for a timeline in the written scope rather than relying on a general estimate. The main schedule drivers are the volume of metadata to move, the number of connectors to rebuild, the number of validation rounds with data owners and the length of the cutover window. Upgrades add a dependency: OpenMetadata 2.0.0 was released on August 24, 2026, with maintenance releases following about every one to two weeks, so confirm which version the plan targets and when it will be frozen.
What does our team need to provide before a migration starts?
Expect to supply access, inventories and an environment. Before work starts, the team should prepare:
- Source export: access to the existing catalog or spreadsheets, plus any API or database access needed for extraction.
- Connector inventory: each source system, its owner and the credentials to be rotated or reissued.
- Target platform: bare metal needs Java 21, MySQL 8.0.42 or later or PostgreSQL 15 or later, and Elasticsearch 9.x or OpenSearch 3.x. Kubernetes and Docker are also documented options. The minimum server is 2 vCPUs, 4 GB RAM and 20 GB storage, with the database and search services each needing at least 2 vCPUs, 2 GB RAM and 30 GB storage.
- Decision makers: named data owners who can approve mappings and sign off on validation.
Can an internal team complete the migration without a partner?
Yes, if the team has the skills and time for the work. OpenMetadata is released under the Apache License 2.0, so self-hosting does not require a commercial agreement. The team needs capacity in four areas: database and search operations, Python or Java ingestion work, metadata mapping and cross-team testing. The 2.0 breaking changes, including the llmConfiguration block, the new Databricks auth format, Python 3.12 ingestion images and the Great Expectations 1.3 migration, must be handled before cutover. Confirm with Collate which commercial features your plan depends on, since they are separate from the open-source release.
What happens to existing lineage and ownership during the move?
Lineage and ownership move in different ways, so confirm each one in scope. Ownership, glossary terms and domains need to be mapped to users and teams in OpenMetadata, which depends on how identity is set up, including any SSO plan. Lineage can be carried only where the source data maps cleanly. Table and column lineage that is missing after the move can be rebuilt from pipeline connectors, query logs and OpenLineage events. The scope should list which objects are carried over, which are rebuilt and how gaps are reported to data owners.
How does a partner migration differ from following the release notes?
Release notes describe what changed in the software. A migration plan applies those changes to your environment. A partner typically inventories your custom ingestion images, connectors, custom properties and API scripts against the breaking changes listed for 2.0. It then tests the upgrade on a non-production copy, sets a backup and rollback path, runs the cutover and documents the result. DeployOpen plans, implements, backs up, upgrades and documents self-hosted platforms inside the client's own infrastructure, and most engagements are fixed-scope with deliverables and timelines agreed in writing before work starts.
How DeployOpen works on this
DeployOpen plans and runs OpenMetadata migrations inside your own infrastructure, moving catalog metadata from another catalog or spreadsheets and handling 1.x to 2.0 breaking changes before cutover. Engagements are fixed-scope, with scope, deliverables and timelines agreed in writing before work starts.
How we scope
- We inventory the source catalog or spreadsheets, including entity types, owners, glossary terms and classifications to be carried over
- We record the current OpenMetadata version and list 2.0 breaking changes that touch your custom ingestion images and credentials
- We agree in writing which connectors, domains and ownership records are in the migration and which are retired or deferred
How we build
- We map source fields to OpenMetadata entities, then load a sample set into a non-production instance for review by data owners
- We rebuild custom ingestion images for Python 3.12 and move embedding credentials into the llmConfiguration block before upgrading
- We run reconciliation checks comparing entity counts, owners and lineage edges between the source and the migrated catalog
How we hand over
- We deliver the mapping specification, migration scripts, reconciliation reports and a cutover runbook with rollback steps
- We document the upgrade path from 1.x to 2.0 for your team, including the Great Expectations 1.3 migration and Databricks auth format change
- We walk your platform and data stewardship teams through operations, then transfer ownership of the scripts and configuration
How we support
- Post-cutover support is available as a retainer covering patch releases, which arrive roughly every one to two weeks after 2.0.0
- Retainers can include connector regression testing and ingestion image rebuilds when new OpenMetadata releases ship
- Support scope, response expectations and fees are agreed in writing before the retainer starts, and no prices are published
