Skip to main content

Migrate between dbt platform tenancy types

Back to guides
Migration
Tenancy
dbt platform
Advanced
Menu
    Contract change required

    Migrating between tenancy types requires a contract change.

    Make sure you contact your account manager before starting this process to confirm eligibility, timeline, and initiate the necessary contract updates. Do not begin migration steps until a contract change is confirmed.

    Overview​

    This guide walks you through a self-serve migration between dbt platform tenancy types — for example, moving from multi-tenant to single-tenant.

    It's meant for accounts that have been assessed by the dbt Labs team as low complexity. Your dbt Labs contact will provide a migration window before you begin — do not start until you've received it.

    Use the following table to confirm this guide is the right path for your account. If your account crosses the high-complexity threshold for even one signal, we recommend a Professional Services-led migration instead.

    SignalLow complexity (self-serve)High complexity (PS-led)
    Active jobs (run in last 30 days)Fewer than 1010 or more
    ProjectsFewer than 33 or more
    EnvironmentsFewer than 55 or more
    How to proceedIf all signals are low complexity, follow this guide or contact Professional Services migration for helpIf one or more signals are high complexity, contact your account manager to scope a Professional Services migration

    The following factors add coordination overhead regardless of account size — flag these to your account manager if they apply:

    • CI or webhook-triggered jobs
    • SSO or SCIM provisioning
    • Privatelink endpoints
    • Multiple warehouse connection types

    What doesn't migrate automatically​

    The migration tool automates most configuration, but some things require manual setup after you apply the Terraform configuration.

    Credentials and secrets — these must be recreated manually:

    • SSH keys and repository credentials
    • Service account tokens
    • Environment variables containing secrets
    • Warehouse connections and environment-level credentials
    • dbt platform profiles

    Project data — not transferred:

    • Job run history, artifacts, and logs

    User management — requires manual verification:

    • Users must already exist in the target account
    • Permissions must be manually verified after migration
    • SSO, keypairs, and warehouse authentication credentials must be reconfigured

    Unsupported resources:

    • PrivateLink endpoints require assistance from the dbt Labs infrastructure team — open a support ticket

    Prerequisites​

    Before starting your migration, confirm the following:

    • A contract change has been initiated and confirmed with your account manager
    • You have received a migration window from the dbt Labs Support team
    • You have admin access to both the source and target dbt platform accounts
    • The target account is provisioned in the new environment
    • You have a service token with Account Admin permissions on the source account

    Migration steps​

    This migration uses two open-source tools:

    info

    Credentials, secrets, and some other items don't migrate automatically — plan to recreate them manually. Refer to What doesn't migrate automatically for the full list.

    Step 1: Install prerequisites​

    You need Python, Terraform, and dbtcloud-terraforming. Install them using any method you prefer — we use Homebrew as an example here.

    Create and activate a Python virtual environment:

    python3 -m venv tf_acct_migrator_env
    source tf_acct_migrator_env/bin/activate

    Install Terraform:

    brew tap hashicorp/tap && brew install hashicorp/tap/terraform

    Install dbtcloud-terraforming:

    brew install dbt-labs/dbt-cli/dbtcloud-terraforming

    Step 2: Set up the migration tool​

    Clone the migration tool repo and navigate into it:

    git clone https://github.com/dpguthrie/dbt-cloud-migration-tool
    cd dbt-cloud-migration-tool

    Set environment variables for your source dbt platform account:

    export DBT_CLOUD_HOST_URL="https://YOUR_SOURCE_REGION.getdbt.com/api"
    export DBT_CLOUD_TOKEN="your_source_service_token"
    export DBT_CLOUD_ACCOUNT_ID="your_source_account_id"

    Step 3: Generate and apply Terraform configuration​

    Run the migration tool to generate a resources.tf file with your source account's resources:

    sh migrate.sh

    Copy the example vars file and add your target account's details:

    cp terraform.tfvars.example terraform.tfvars
    # Edit terraform.tfvars with your target account details

    Apply the configuration to your target account:

    terraform init
    terraform plan
    terraform apply

    Terraform will output the newly created resources and any warnings or errors. You may need to re-run migrate.sh multiple times to catch all required resource types.

    Post-migration checklist​

    • Verify all connections, permissions, and secrets in the target account
    • Run test jobs to confirm end-to-end functionality
    • Confirm IP allowlist and network settings are updated for the new tenant
    • Update internal bookmarks, SSO configurations, and API integrations to the new account URL

    Was this page helpful?

    This site is protected by reCAPTCHA and the Google Privacy Policy and Terms of Service apply.

    0