So you’re considering moving from dbt Core to dbt Cloud (or to use dbt Lab’s updated terminology, from self-hosted dbt to dbt platform*).

While the terminology may have evolved, the migration considerations remain just as important.

Your dbt project already exists. Your models are in Git. Your warehouse is running.

In theory, you connect the pieces to dbt Cloud, recreate your jobs and carry on.

However, in practice, a successful migration needs more care.

Over time, a dbt Core implementation can accumulate dependencies that aren’t immediately obvious such as environment variables, orchestration logic, service accounts, scripts, package dependencies, CI processes, notifications and conventions that might exist only in someone’s head.

That’s why we recommend treating a move to dbt Cloud as a migration rather than a lift-and-shift exercise.

The goal is to move to dbt Cloud in a controlled way, while taking the opportunity to simplify your setup, strengthen governance and make the platform easier to operate.

Here’s the approach we’d recommend.

Plan Your dbt Cloud Migration: Assess Your Existing dbt Core Setup

Start with discovery

Before creating projects or jobs in dbt Cloud, establish exactly what you’re migrating.

Start by documenting your current dbt Core estate. Depending on your setup, that should include:

• dbt projects and repositories

• dbt and adapter versions

• packages and dependencies

• targets and environments

• warehouse connections

• users and service accounts

• environment variables and secrets

• scheduled jobs

• dbt commands associated with each job

• upstream and downstream dependencies

• CI/CD processes

• external orchestration

• alerts and notifications

• custom scripts, hooks and macros

Pay particular attention to processes outside the dbt repository. A scheduled dbt run might look straightforward in the codebase while actually relying on an orchestrator to load data, set variables, invoke dbt and then trigger another downstream process.

Those dependencies need to be understood before anything is switched off.

If your dbt codebase hasn’t been updated for some time, this is also the point to decide which dbt version you want to migrate to.

We recommend targeting the latest available version supported by your dbt Cloud environment where practical, so you can take advantage of the latest platform features and improvements rather than carrying legacy constraints into your new setup.

Depending on the age of your existing project, this may require some syntax and configuration updates, so make sure these are factored into your migration plan rather than discovered during cutover.

dbt provides dbt-autofix, a tool that can help identify and automatically remediate deprecated syntax and other upgrade-related changes, reducing some of the manual effort involved. As with any automated code changes, review and test the resulting updates thoroughly before progressing with the migration.

Tip: Build a migration inventory

1. Give every existing job, integration and dependency an owner and migration status. This then becomes your control document throughout the migration. If something isn’t in the inventory, there’s a good chance it won’t be considered during testing.
2. Identify opportunities of current custom logic in dbt core that can be replaced by native features in dbt cloud. Flag features we can migrate to or new dbt cloud features we can implement in the future

Define Your Target Architecture Before Migrating to dbt Cloud

Decide what the target state should look like

A migration is a perfect opportunity to ask a question that often gets overlooked:

Would we design our dbt estate this way if we were starting today?

Don’t automatically reproduce every existing Core configuration in Cloud.

Consider whether projects should be consolidated or separated, how development and production environments should work, who needs access to each project and which workloads should remain externally orchestrated.

Project boundaries, in particular, deserve careful thought. Too many projects can introduce unnecessary administration and make collaboration harder. Too few can create ownership, security and deployment challenges.

The right structure depends on your organisation, teams, data domains and governance requirements.

Note: Don’t combine migration and redesign indiscriminately

There’s value in improving your architecture during migration, but changing everything at once also increases risk.

Separate necessary migration changes from optional improvements. Make intentional improvements where the benefit is clear, but avoid turning the migration into an open-ended transformation programme.

Configure Identity, Access and Security for dbt Cloud

Configure Identity, Access and Security for dbt Cloud

Establish identity, access and security early

Before developers start moving onto the new platform, define how authentication, user provisioning and permissions will work.

For enterprise environments, this may involve integrating dbt Cloud with your identity provider and mapping access to appropriate groups. Apply least-privilege principles and distinguish clearly between account-level administration and project-level responsibilities.

You should also decide who can:

• administer the dbt account
• administer individual projects
• configure Git integrations
• manage environments and credentials
• create or change production jobs
• develop and approve code
• view production runs and artifacts
• licence requirements by user/persona*

* Consider which users genuinely require a dbt Cloud Developer licence and where lower-cost licence types may be more appropriate. Developer licences represent a more significant investment, so allocating them according to the activities each persona needs to perform can help optimise both cost and ROI. For example, IT or read-only users may be covered by alternative licence types that are available at little or no additional cost, depending on your dbt contract. Review your specific licensing agreement and map each user persona to the appropriate licence type before provisioning access.

This is also a good point to review service accounts. Production workloads shouldn’t depend on an individual developer’s credentials.

Tip: Test access with real personas

Don’t validate security using an administrator account alone.

Test the experience as a developer, reviewer, job operator and read-only stakeholder. Confirm that each persona can do what they need to do, and equally importantly, can’t do what they shouldn’t.

Connect Git and Source Control as Part of Your dbt Cloud Migration

Connect source control and protect the development workflow

Your Git repository remains central to the development lifecycle, so configure the source control integration carefully.

Confirm the appropriate repository is connected to each dbt project and review:

• repository permissions
• branch strategy
• pull request requirements
• branch protection
• code review processes
• CI checks
• deployment branches

The migration shouldn’t weaken controls that already exist around production code.

In many cases, it provides an opportunity to strengthen them.

For example, if developers have historically been able to commit directly to the production branch, moving to dbt Cloud may be the right point to introduce protected branches and mandatory pull requests.

This is also a good point to evaluate whether you need a custom CI/CD workflow as part of your dbt Cloud migration. dbt Cloud provides native integrations with supported Git providers that can automatically trigger CI jobs in response to actions such as opening or updating a pull request.

If your Git provider isn’t natively integrated with dbt Cloud, a custom CI/CD workflow can be used to replace this native integration and trigger the appropriate dbt Cloud jobs from your existing Git or CI/CD platform.

This allows you to retain your existing source control platform while still incorporating dbt Cloud into your development and deployment process. Identifying this requirement early gives you time to build and test the workflow alongside the wider migration, rather than discovering an integration gap close to cutover.

Note: Check more than the default branch

Repositories sometimes contain release branches, long-lived development branches, submodules or automation tied to particular branch names.

Inventory these before changing the Git workflow. A seemingly harmless branch change can break an external deployment or integration.

Set Up dbt Cloud Development Environments

Configure developer environments

Essential step: Use Infrastructure as code on the dbt cloud resource setup

Once projects and source control are connected, focus on the developer experience.

Developers need isolated environments where they can build and test changes without affecting production datasets or one another.

That typically means reviewing:

• development credentials
• developer-specific schemas
• warehouse access
• database and schema naming conventions
• environment variables
• targets
• package installation
• dbt version compatibility

The objective should be simple: a developer should be able to pick up a branch, work safely and reproduce expected dbt behaviour without relying on undocumented local configuration.

This is an important point in the migration because dbt Core implementations often contain assumptions inherited from individual developers’ machines or profiles.yml configurations.

Those assumptions need to become explicit.

Tip: Use a representative project as your proving ground

Don’t migrate every project simultaneously.

Choose a project that is complex enough to expose genuine migration issues, but not so business-critical that every problem becomes an incident. Use what you learn to refine the migration pattern before scaling it.

Migrate dbt Core Environments and Configuration to dbt Cloud

Recreate environments carefully

Your existing Core targets don’t necessarily translate directly into your desired dbt Cloud environment structure.

Map the current state first:

Core target → Cloud environment → credentials → database/warehouse → schema behaviour

Pay particular attention to custom logic that changes database names, schemas or aliases based on the target or environment.

Macros such as custom generate_schema_name logic can produce unexpected results when assumptions about the execution environment change.

Environment variables also deserve a specific review. Identify which variables exist, where their values currently come from, whether they contain sensitive information and where they should live after migration.

Note: Never assume a successful run means a correct migration

A job can finish successfully and still write data to the wrong database or schema.

Validate the location and contents of the output, not simply the dbt exit status.

Migrate dbt Core Environments and Configuration to dbt Cloud

Migrate production credentials separately from development

Production deserves a different security model from development.

Scheduled production jobs should run using controlled deployment credentials or service accounts rather than credentials belonging to individual users.

Review:

• warehouse roles
• database permissions
• service account ownership
• secret management
• credential rotation
• authentication method
• audit requirements

Where an existing dbt Core service account meets your organisation’s security standards, it may be reusable. But migration is still a sensible point to review whether its permissions are broader than necessary.

Tip: Don’t copy credentials blindly

A migration is one of the few times you get a complete view of how an application authenticates.

Use it to remove stale credentials, reduce excessive privileges and document who owns each production identity.

Migrate dbt Core Jobs and Orchestration to dbt Cloud

Rebuild job orchestration deliberately

This is often where the migration becomes most interesting.

dbt Core may currently be invoked through Airflow, Azure Data Factory, Dagster, Prefect, Control-M, shell scripts, CI/CD pipelines or another orchestration platform.

Ask: “Where should this workflow be orchestrated after the migration?”

For straightforward dbt workloads, moving scheduling and monitoring into dbt Cloud may reduce operational overhead.

For more complex pipelines, external orchestration may still make sense, particularly when a dbt job is only one step in a larger workflow involving ingestion, machine learning, application processes or other dependencies.

Classify your jobs before migrating them:

Note: Preserve sequencing

A schedule doesn’t tell you the whole story.

If a dbt job runs at 02:00 because ingestion normally completes at 01:45, the real dependency is data availability, not the clock.

Make those dependencies explicit before replacing the existing orchestration.

Set Up dbt Cloud Monitoring, Alerts and Operational Ownership

Rebuild job orchestration deliberately

This is often where the migration becomes most interesting.

dbt Core may currently be invoked through Airflow, Azure Data Factory, Dagster, Prefect, Control-M, shell scripts, CI/CD pipelines or another orchestration platform.

Ask: “Where should this workflow be orchestrated after the migration?”

For straightforward dbt workloads, moving scheduling and monitoring into dbt Cloud may reduce operational overhead.

For more complex pipelines, external orchestration may still make sense, particularly when a dbt job is only one step in a larger workflow involving ingestion, machine learning, application processes or other dependencies.

Classify your jobs before migrating them:

Note: Preserve sequencing

A schedule doesn’t tell you the whole story.

If a dbt job runs at 02:00 because ingestion normally completes at 01:45, the real dependency is data availability, not the clock.

Make those dependencies explicit before replacing the existing orchestration.

Test and Validate Your dbt Cloud Migration Before Cutover

Validate before cutting over

Avoid a big-bang switch wherever possible.

Run controlled comparisons between Core and Cloud so you can establish that the new environment produces the expected outcome.

Validation should cover several layers:

• project compilation
• package installation
• model execution
• tests
• row counts
• important business measures
• database and schema destinations
• incremental model behaviour
• snapshots
• seeds
• hooks and macros
• permissions
• execution times
• alerts
• downstream dependencies

For critical workloads, consider running Core and Cloud in parallel against isolated targets for an agreed validation period.

You don’t necessarily need byte-for-byte comparisons across every table. Validation should be proportionate to the importance and complexity of the workload.

Note: Define acceptance criteria before testing

Decide what “success” means before you see the results.

For example: all critical tests pass, agreed reconciliation checks are within tolerance, downstream processes complete successfully and run times remain within an acceptable range.

This prevents the cutover decision becoming subjective.

Create a dbt Cloud Migration Cutover and Rollback Plan

Plan the cutover and rollback together

Every cutover plan should have a corresponding rollback plan.

For each workload, document:

1. What is being switched?
2. When will it happen?
3. Who owns the change?
4. How will success be confirmed?
5. What would trigger rollback?
6. How will Core execution be restored if required?

Don’t dismantle the old environment immediately after the first successful Cloud run.

Keep the previous route available for a defined stabilisation period, where practical, while preventing duplicate production writes.

Tip: Make rollback boring

Rollback shouldn’t require an emergency design meeting.

The team should already know the trigger, decision-maker and exact steps required to return to the previous execution path.

Optimise dbt Cloud After Migration

Stabilise before you optimise

Once production workloads are running reliably in dbt Cloud, resist the urge to declare the migration finished immediately.

Monitor the platform through a stabilisation period.

Look at:

• job success rates
• run durations
• warehouse consumption
• queueing or concurrency
• developer feedback
• CI performance
• alert volumes
• support requests
• unexpected permissions issues

Once you’re confident the new operating model is stable, you can start optimising it.

This is also a good opportunity to evaluate model build patterns alongside actual user usage, helping you identify models that are being built more frequently than necessary, models with limited or no downstream consumption, and opportunities to better align build schedules with how and when data is actually used.

These insights can help reduce unnecessary compute, improve job performance and ensure your dbt Cloud environment is delivering value efficiently.

That may mean simplifying jobs, improving CI, reducing unnecessary runs, refining access, consolidating environments or taking advantage of dbt platform capabilities that weren’t part of the original Core setup.

Note: Migration and optimisation have different success criteria

Migration asks: Is the new platform producing the right results reliably?

Optimisation asks: Can we now make it faster, cheaper or easier to operate?

Keeping those questions separate makes both easier to answer.

Decommission dbt Core After a Successful dbt Cloud Migration

Decommission dbt Core carefully

Only retire the old Core setup once you’ve confirmed that nothing still depends on it.

Return to the migration inventory you created at the beginning.

Check that:

• all production jobs have migrated
• external orchestrators no longer invoke old Core processes
• legacy schedules are disabled
• obsolete service accounts can be retired
• old secrets can be revoked
• redundant infrastructure can be removed
• monitoring has moved to the new operating model
• documentation and runbooks have been updated
• ownership is clear

This final reconciliation is easy to skip, but it’s what prevents a migration from leaving behind a shadow platform that quietly costs money and creates security risk.

Tip: Finish with the same inventory you started with

Every item should have a clear outcome: migrated, replaced, intentionally retained or retired.

Nothing should simply disappear from the list

dbt Cloud Migration Best Practices

A prudent migration beats a fast migration

Moving from dbt Core to dbt Cloud doesn’t need to be disruptive. Much of the underlying dbt project can remain familiar to developers.

The risk sits around it: credentials, environments, orchestration, permissions, integrations, dependencies and operational processes.

That’s why we’d favour a staged migration over a rushed lift-and-shift.

Discover first. Design the target state. Migrate incrementally. Validate the outputs. Keep rollback available. Then optimise.

Done properly, the result isn’t simply dbt Core running somewhere new. It’s a dbt environment that’s easier to govern, easier to operate and better positioned to scale with the organisation.

A Final Migration Checklist

Before signing off the migration, confirm that you can answer “yes” to the following:

• Have we inventoried every project, job, dependency and integration?
• Have we agreed the target project and environment structure?
• Are identity, permissions and production credentials appropriately controlled?
• Have we tested the developer workflow?
• Have all required environment variables and secrets been migrated securely?
• Have we reviewed rather than simply copied existing orchestration?
• Have we validated actual data outputs, not just successful job completion?
• Have we tested monitoring and failure notifications?
• Have critical workloads been reconciled against the existing implementation?
• Are cutover criteria documented?
• Is there a tested rollback path?
• Has the new platform completed an appropriate stabilisation period?
• Have legacy Core jobs, credentials and infrastructure been safely retired?
• Have documentation, ownership and support processes been updated?

If any of those answers is “not sure”, that’s usually a good reason to resolve it before calling the migration complete.

“Data Army consistently delivered exceptional value at Lendi, quickly absorbing context, integrating seamlessly with our squads, and contributing meaningful outcomes from day one.  Their contribution continues to position us strongly in delivering on our AI-native vision and the increasing pace of innovation across the business.”

See how we’ve helped others make the move, or talk to our experts about your own migration.

*dbt Labs now refers to what many teams know as dbt Core as self-hosted dbt, while dbt Cloud is now the dbt platform.

You can read more about the distinction between self-hosted dbt and the dbt platform here.