|
| 1 | +<!-- generated-by: sqlbuild skills --> |
| 2 | + |
| 3 | +# Refactoring |
| 4 | + |
| 5 | +> Rename and move models and columns, keep their warehouse history, and keep old names working. |
| 6 | +
|
| 7 | +Online: https://sqlbuild.com/docs/concepts/refactoring/ |
| 8 | + |
| 9 | +## Contents |
| 10 | + |
| 11 | +- Rename a model |
| 12 | +- Rename a column |
| 13 | +- Old names keep working |
| 14 | +- Check the impact first |
| 15 | +- When a rename is refused |
| 16 | + |
| 17 | +SQLBuild lets you rename a model, move it to another folder, or rename one of its columns as a single |
| 18 | +verified change. The compiler finds every reference, the edited project is compiled before anything is |
| 19 | +written, and the next build keeps the existing table's history instead of rebuilding it. |
| 20 | + |
| 21 | +## Rename a model |
| 22 | + |
| 23 | +```bash |
| 24 | +sqb rename hourly_order_activity order_activity_by_hour |
| 25 | +``` |
| 26 | + |
| 27 | +```text |
| 28 | +Rename model hourly_order_activity -> order_activity_by_hour |
| 29 | +├── models/marts/daily_activity_rollup.sql |
| 30 | +│ ├── 10:5 header hourly_order_activity -> order_activity_by_hour |
| 31 | +│ └── 34:13 reference __ref("hourly_order_activity") -> __ref("order_activity_by_hour") |
| 32 | +├── models/marts/hourly_activity_with_daily_context.sql |
| 33 | +│ ├── 10:5 header hourly_order_activity -> order_activity_by_hour |
| 34 | +│ └── 36:15 reference __ref("hourly_order_activity") -> __ref("order_activity_by_hour") |
| 35 | +└── models/marts/order_activity_by_hour.sql (moved from models/marts/hourly_order_activity.sql) |
| 36 | + └── 1:8 migration + migrate_from hourly_order_activity |
| 37 | +Compiled: ok, 3 files changed |
| 38 | +``` |
| 39 | + |
| 40 | +The plan then shows a migration instead of a first run: |
| 41 | + |
| 42 | +```bash |
| 43 | +sqb plan |
| 44 | +``` |
| 45 | + |
| 46 | +```text |
| 47 | +Migrations (1) |
| 48 | +└── order_activity_by_hour migrate dev.hourly_order_activity -> dev.order_activity_by_hour |
| 49 | + ├── compatibility compatible |
| 50 | + ├── transfer physical copy, promote by transactional rename |
| 51 | + └── old name dev.hourly_order_activity |
| 52 | + ├── view until 2026-11-06 |
| 53 | + └── old table archived |
| 54 | +``` |
| 55 | + |
| 56 | +On the next `sqb build`, the incremental model's existing data moves to the new name and the model |
| 57 | +carries on from where it was. Nothing is backfilled. |
| 58 | + |
| 59 | +`sqb mv` does the same for a move to another folder, optionally with a new name: |
| 60 | + |
| 61 | +```bash |
| 62 | +sqb mv fact_orders models/reporting/ |
| 63 | +sqb mv fact_orders models/reporting/order_facts.sql |
| 64 | +``` |
| 65 | + |
| 66 | +A move also takes the model's private macros, enums, constants and other scoped declarations with it, |
| 67 | +following the same placement rules as `sqb compile`. See [Declarations and scopes](declaration-scopes.md). |
| 68 | + |
| 69 | +## Rename a column |
| 70 | + |
| 71 | +```bash |
| 72 | +sqb rename stg_customers.email email_address --dry-run |
| 73 | +``` |
| 74 | + |
| 75 | +```text |
| 76 | +Rename column stg_customers.email -> email_address |
| 77 | +├── models/marts/dim_customers.sql |
| 78 | +│ ├── 16:5 column email -> email_address |
| 79 | +│ ├── 16:10 column + AS email |
| 80 | +│ └── 23:54 column email -> email_address |
| 81 | +└── models/staging/stg_customers.sql |
| 82 | + ├── 7:5 header email -> email_address |
| 83 | + └── 15:8 column + AS email_address |
| 84 | +Dry run: compiles, 2 files would change; nothing written |
| 85 | +``` |
| 86 | + |
| 87 | +Edits follow the columns each query actually binds, so a same-named column of another table is left |
| 88 | +alone. Downstream models keep their own output names unless you pass `--cascade`. An incremental or |
| 89 | +snapshot model renames the column in place on the next build. See |
| 90 | +[Column migrations](models/column-migrations.md). |
| 91 | + |
| 92 | +## Old names keep working |
| 93 | + |
| 94 | +After a model moves to a new name, the old name becomes a view over the new relation for 30 days by |
| 95 | +default, with the old relation's grants copied to it. Queries, dashboards and other tools that read |
| 96 | +the old name keep working while you update them. After that, [`sqb janitor`](../cli/janitor.md) drops |
| 97 | +the view. See [Model migrations](models/migrations.md#old-names) for the settings. |
| 98 | + |
| 99 | +## Check the impact first |
| 100 | + |
| 101 | +- [`sqb lineage`](../cli/lineage.md) shows which models and columns depend on what you are changing. |
| 102 | +- [`sqb scope`](../cli/scope.md) shows which declarations a model uses and what a move would break. |
| 103 | +- `--dry-run` on `sqb rename` and `sqb mv` prints every edit and checks the edited project compiles, |
| 104 | + without writing files. |
| 105 | + |
| 106 | +## When a rename is refused |
| 107 | + |
| 108 | +If any location cannot be rewritten safely, the command lists it and writes nothing: |
| 109 | + |
| 110 | +```text |
| 111 | +Rename column stg_payments.amount_cents -> amount_minor |
| 112 | +Cannot rename column:stg_payments.amount_cents automatically |
| 113 | +└── models/marts/daily_revenue.sql:21:3 column amount_cents is referenced in SQL a macro generates; update the macro call by hand |
| 114 | +Edit the listed locations, then run the command again. |
| 115 | +Refused; no files changed |
| 116 | +``` |
| 117 | + |
| 118 | +The full list of refusals and every flag is in the [`sqb rename` and `sqb mv` reference](../cli/rename.md). |
0 commit comments