> ## Documentation Index
> Fetch the complete documentation index at: https://docs.paradime.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Migration Playbook

> A six-phase playbook for migrating hundreds of dbt Cloud™ jobs to Paradime Bolt over 5–10 days, covering audit, cutover, validation, and decommission.

This guide lays out a repeatable, low-risk process for moving a production dbt Cloud™ setup onto Paradime - from first audit through full cutover and decommission. It is written for teams with a **medium to large, multi-workspace footprint** (hundreds of jobs across several dbt Cloud™ projects) and factors in the real orchestration edge cases you are likely to hit at that scale like separate environment variables, CI checks, external orchestrator triggers, API-driven downstream apps, SSO, and rollback.

The plan is organised into six phases mapped onto a **5–10 working-day** window. Smaller instances compress toward five days or less; larger or more integrated instances run toward ten. Nothing in Phase 4 is irreversible until you consciously decommission in Phase 6.

**Before you start - it’s worth remembering the following:**\
A **dbt Cloud™ project maps to a Paradime workspace**, and each **dbt Cloud™ job becomes a paused Bolt schedule**. You migrate *one project into one workspace at a time*, validate, then enable. You are never flipping the whole instance at once.

***

## Phase 0 - Pre-migration review (Day 1)

Everything downstream depends on knowing exactly what you have. Do not skip the inventory.

**Audit every dbt Cloud™ environment.** Walk dev, staging, and production. Note connection settings, target names, dbt™ version, and any environment-specific configuration. You need this to reproduce the same warehouse connection in Paradime.

**List all environment variables.** Check both the dbt Cloud™ environment-variable UI *and* every `env_var()` call in the project. This matters because Paradime keeps **Bolt schedule variables** and **Code IDE variables** in two separate places - a variable your production jobs rely on and a variable your developers rely on are configured independently.

**Inventory all jobs.** For each job capture: type (deployment, CI, on-merge, on-completion), cron, full command list, and any cross-job dependencies. This inventory becomes your validation checklist after import - you will cross-check imported schedule counts against it per workspace.

**Pick your pilots.** Choose a small set of jobs that run at least daily and that between them exercise the *different mechanics* in your instance. A representative pilot set usually covers:

* a job(s) with dbt™ runs and also dbt™ tests
* a job that has run-operation to validate external dependencies
* a **Python model** job (if applicable)
* a job **triggered by an external orchestrator** (e.g. a data-pipeline/ELT tool)
* a **CI job**

**Review the key-term mappings** so the whole team speaks one language:

| dbt Cloud™                          | Paradime               |
| :---------------------------------- | :--------------------- |
| Job                                 | Bolt Schedule          |
| Orchestration                       | Bolt                   |
| CI Job / Slim CI                    | Turbo CI               |
| Studio IDE                          | Code IDE               |
| dbt Cloud™ Project                  | Paradime Workspace     |
| Run / Run History                   | Bolt Run / Run History |
| Deployment / Production Environment | Production Environment |

***

## Phase 1 - Paradime setup (Days 1–2)

**Connect the data warehouse.** Match the exact connection your dbt Cloud™ **production** environment uses. If you have separate dev and prod accounts, connect dev first, validate, then switch to prod.

**Configure Bolt schedule environment variables.** Go to `Settings → Workspaces → Env Variables → Bolt Schedules`. For a large variable set, use the bulk CSV upload rather than entering them by hand, and override per-schedule only where a job genuinely needs a different value.

**Configure Code IDE environment variables** separately, under the Code IDE section of the same settings page. These power interactive development; skipping them leaves developers unable to reproduce production behaviour in the IDE.

**Verify the IDE with `dbt debug`.** This will confirm warehouse auth, profiles, and env vars are wired up correctly *before* you import a single job. Fix any failure here - it is much cheaper than debugging it inside a schedule later.

**Complete SSO configuration.** Loop in IT early to set up your identity provider (e.g. Okta) integration and share the details with the Paradime team. SSO is rarely a hard blocker for the technical migration, but it gates broad user rollout, so start it in parallel on day one.

> **Tip.** Treat Phase 1 as "make one model build correctly by hand." If a developer can open the Code IDE, run `dbt debug`, and build a model against the right warehouse, your foundation is sound and the dbt Cloud™ importer will work without issues.

***

## Phase 2 - Run the importer (Days 2–3)

The importer itself is three clicks. The bulk of the work goes into scoping and validation.

**Create a dbt Cloud™ service token.** In dbt Cloud™: `⚙️ Account Settings → Service Tokens → New Token`. Name it `paradime`, set permission to **Account Admin**, and scope the **Project** to the dbt Cloud™ project that matches the workspace you're importing into. Save the token immediately - you cannot view it again.

> **Scope the token to one project.** The import pulls every job the token can access into your **current** Paradime workspace. Scoping the token to the matching project stops another project's jobs from getting imported in the wrong workspace. To migrate several projects, repeat this connection from each corresponding workspace.

**Connect the integration in Paradime.** `Account Settings → Integrations → dbt Cloud™ → Connect`. Enter your dbt Cloud™ host name (including the account ID) and the service token, then click **Test Connection**.

**Run the import and review Bolt schedules.** Click **View imported jobs** in Bolt. **Every schedule imported will be paused - nothing will run yet.** Cross-check the imported count against your Phase 0 inventory for that workspace.

**Validate each schedule's configuration.** Confirm cron, commands, environment-variable overrides, and trigger types (schedule, on-merge, on-completion, API). Pay attention to how configuration carries across:

| dbt Cloud™ job   | Bolt schedule    | Note                                             |
| :--------------- | :--------------- | :----------------------------------------------- |
| Name             | Display name     | Internal slug is generated                       |
| Commands / steps | Commands         | Copied exactly                                   |
| Cron             | Cron             | Trigger-only jobs import with schedule OFF       |
| Custom branch    | Git branch       | Otherwise uses workspace default                 |
| -                | Status           | Always **paused**                                |
| -                | Threads / target | Taken from the Paradime environment, not the job |
| -                | Timezone         | Schedules run in **UTC**                         |

**Known caveats to plan around.**

>

> * **Re-importing creates duplicates** - the importer does not match against prior imports. Delete previously-imported schedules before re-running.
> * **`state:modified+` commands need a deferral target.** Environment-level deferral is not imported, so set the deferred schedule manually before enabling, or the run selects nothing.
> * **On-completion chains only resolve within a single import.** If a parent job lives in another project that wasn't part of this import, the child imports paused with no trigger - wire it up after both are in.
> * **Timezone is UTC.** Re-check any cron that assumed a local timezone.

***

## Phase 3 - Pilot run (Days 3–5, \~2 days of monitoring)

This is where you validate that the imports and settings are working as expected.

1. **Enable the pilot schedules** you selected in Phase 0. Run them against your **dev warehouse account** first if you have one, then promote to prod. Update cron config where needed.
2. **Disable the same jobs in dbt Cloud™** so nothing double-runs. Leave them *paused, not deleted* so you can rollback instantly if needed.
3. **Monitor for \~2 days.** Compare Bolt run history - durations, row counts, errors - against the previous dbt Cloud™ history for the same jobs.

> **Handling externally-triggered jobs.** If an external orchestrator (ELT tool, ETL pipeline) previously kicked a dbt Cloud™ job by its job ID, update that caller to trigger the corresponding **Bolt schedule via the Paradime API**. Validate the trigger end-to-end in dev before prod cutover.

***

## Phase 4 - Full cutover (Days 5–8)

Cutover **per workspace, in batches** - never the whole instance in one motion. For each workspace:

1. **Enable the remaining Bolt schedules**, starting with independent / upstream jobs. Enable downstream schedules only once their upstream is live, so dependency order is preserved.
2. **Disable the equivalent jobs in dbt Cloud™** at the same time to prevent double-runs. **Do not delete them** - keep them as reference and rollback for 1–2 weeks.
3. **Migrate CI checks.** Re-create your PR/CI checks (branch protection, status checks) so pull requests are validated by Turbo CI instead of dbt Cloud™. Validate on a sample PR before relying on it.
4. **Re-point API-driven and downstream apps.** Anything that invoked the dbt Cloud™ API - like alerting webhooks - must be switched to the Paradime equivalent. Configure Bolt failure webhooks into your existing alert channels so on-call coverage is uninterrupted.

> **Dev vs prod targets.** For development-environment schedules, make the target explicit in each step (e.g. `dbt build --select <selector> --target dev`). Otherwise Bolt defaults to the workspace's production environment and dev models land in prod.

***

## Phase 5 - Hypercare monitoring (Days 8–10 and the following 1–2 weeks)

Run both systems in a watch-and-verify posture through at least **one full schedule cycle** - every daily, weekly, and monthly cron must fire at least once on Paradime under observation. Weekly and monthly jobs are the ones most likely to surprise you, precisely because they don't run during the pilot. For monthly jobs, run them on a non-prod target to verify that they run.

For each workspace, per cycle, confirm:

* schedules run on time with expected durations
* CI triggers fire on a test PR and produce the right checks
* failure alerts reach the correct channel
* the Paradime Catalog reflects the latest model status from production runs

Keep the **rollback path warm** the entire time: if any schedule misbehaves, re-enable that single job in dbt Cloud™, disable it in Paradime, log it, and fix forward.

***

## Phase 6 - Decommission

Only after a clean full cycle with no open rollbacks:

* delete the migrated jobs in dbt Cloud™
* revoke the `paradime` service token
* wind down the dbt Cloud™ subscription

***

## At-a-glance timeline

| Phase                    | Days              | Outcome                                                  |
| :----------------------- | :---------------- | :------------------------------------------------------- |
| 0 - Pre-migration review | 1                 | Complete inventory + pilots chosen                       |
| 1 - Paradime setup       | 1–2               | Warehouse, env vars, IDE, SSO in place                   |
| 2 - Run the importer     | 2–3               | Jobs imported as paused Bolt schedules, validated        |
| 3 - Pilot run            | 3–5               | 4 job types proven over \~2 days                         |
| 4 - Full cutover         | 5–8               | Per-workspace batch enablement + integrations re-pointed |
| 5 - Hypercare            | 8–10 (+1–2 wks)   | One full schedule cycle verified                         |
| 6 - Decommission         | after clean cycle | dbt Cloud™ retired                                       |

***

## Migration checklist

**Phase 0 - Pre-migration review**

* [ ] Audit dev / staging / prod environments and connection settings
* [ ] List all env vars (UI + every `env_var()` call)
* [ ] Inventory all jobs (type, cron, commands, dependencies)
* [ ] Pick 3–4 representative pilot jobs
* [ ] Review key-term mappings with the team

**Phase 1 - Paradime setup**

* [ ] Connect the data warehouse (dev → prod)
* [ ] Configure Bolt schedule env vars (bulk CSV)
* [ ] Configure Code IDE env vars
* [ ] Verify IDE with `dbt debug`
* [ ] Kick off SSO / Okta configuration with IT

**Phase 2 - Run the importer**

* [ ] Create scoped `paradime` service token (Account Admin, one project)
* [ ] Connect dbt Cloud™ integration + Test Connection
* [ ] Run import, review paused Bolt schedules
* [ ] Validate cron, commands, overrides, triggers per schedule
* [ ] Resolve `state:modified+` deferral targets and cross-project chains

**Phase 3 - Pilot run**

* [ ] Enable pilot schedules (dev, then prod)
* [ ] Disable the same jobs in dbt Cloud™ (paused, not deleted)
* [ ] Monitor \~2 days vs dbt Cloud™ history
* [ ] Re-point externally-triggered pilot jobs to the Bolt API

**Phase 4 - Full cutover**

* [ ] Enable remaining schedules per workspace, upstream first
* [ ] Disable equivalent dbt Cloud™ jobs (keep 1–2 weeks)
* [ ] Migrate CI checks to Turbo CI, validate on a sample PR
* [ ] Re-point API apps, monitoring, and alert webhooks
* [ ] Add `--target dev` to dev-environment schedule steps

**Phase 5 - Hypercare**

* [ ] Monitor one full schedule cycle (daily/weekly/monthly)
* [ ] Verify CI triggers, alerts, and Catalog freshness
* [ ] Keep rollback path warm

**Phase 6 - Decommission**

* [ ] Delete migrated dbt Cloud™ jobs
* [ ] Revoke service token
* [ ] Cancel dbt Cloud™ subscription

***

### Reference docs

* dbt Cloud™ → Paradime importer: `https://docs.paradime.io/app-help/guides-new/migrations/dbt-cloud-tm-importer`
* Transferring dbt™ jobs: `https://docs.paradime.io/app-help/guides-new/migrations/dbt-cloud-tm-importer/transferring-dbt-tm-jobs`
* Translation of key terms: `https://docs.paradime.io/app-help/guides-new/migrations/dbt-cloud-tm-importer/translation-of-key-terms`
* Environment variables: `https://docs.paradime.io/app-help/documentation/settings/environment-variables`
* Okta SSO: `https://docs.paradime.io/app-help/products/single-sign-on/okta-sso`


## Related topics

- [Changelog](/changelog/overview.md)
- [Migrations](/guides/migrations/index.md)
- [Migration Checklist](/guides/migrations/dbt-cloud-tm-importer/migration-checklist.md)
- [Translating Key Terms](/guides/migrations/dbt-cloud-tm-importer/translation-of-key-terms.md)
- [Github Actions to Paradime Bolt](/guides/migrations/migrating-dbt-tm-jobs-from-github-actions-to-paradime-bolt.md)