Skip to content

Commit 3f13bc3

Browse files
authored
docs: add a Refactoring section for renames, moves and migrations (#996)
1 parent e89dafd commit 3f13bc3

8 files changed

Lines changed: 256 additions & 10 deletions

File tree

‎src/sqlbuild/.agents/skills/sqlbuild/references/docs/CONTENTS.md‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -23,6 +23,9 @@ Bundled copies of every page on the SQLBuild documentation site, matching the in
2323
- [Project Configuration](concepts/project-configuration.md) (`concepts/project-configuration`) - Configure your SQLBuild project with sqlbuild_project.toml and sqlbuild_local.toml.
2424
- [Resource Identities](concepts/resource-identities.md) (`concepts/resource-identities`) - Canonical names for SQLBuild resources, selectors, state, and integrations.
2525
- [Semantic Compilation](concepts/semantic-compilation.md) (`concepts/semantic-compilation`) - Offline reference, semantic and type checks that sqb compile runs before any warehouse work.
26+
- [Refactoring](concepts/refactoring.md) (`concepts/refactoring`) - Rename and move models and columns, keep their warehouse history, and keep old names working.
27+
- [Model migrations](concepts/models/migrations.md) (`concepts/models/migrations`) - Keep a renamed model's history, and keep its old name working for a while.
28+
- [Column migrations](concepts/models/column-migrations.md) (`concepts/models/column-migrations`) - Keep a column's history when you rename it in an incremental or snapshot model.
2629
- [Overview](concepts/adapters.md) (`concepts/adapters`) - Supported database engines and their connection configuration.
2730
- [Snowflake](concepts/adapters/snowflake.md) (`concepts/adapters/snowflake`) - Snowflake adapter configuration for SQLBuild.
2831
- [DuckDB](concepts/adapters/duckdb.md) (`concepts/adapters/duckdb`) - DuckDB adapter configuration for SQLBuild.
@@ -38,8 +41,6 @@ Bundled copies of every page on the SQLBuild documentation site, matching the in
3841
- [Schemas](concepts/models/schemas.md) (`concepts/models/schemas`) - Declare model columns inline or reuse canonical inherited schemas.
3942
- [Type Enforcement](concepts/models/type-enforcement.md) (`concepts/models/type-enforcement`) - Understand declared model types, static checks, and runtime casting.
4043
- [Contracts](concepts/models/contracts.md) (`concepts/models/contracts`) - Validate required or exact model output schemas.
41-
- [Model migrations](concepts/models/migrations.md) (`concepts/models/migrations`) - Keep a renamed model's history, and keep its old name working for a while.
42-
- [Column migrations](concepts/models/column-migrations.md) (`concepts/models/column-migrations`) - Keep a column's history when you rename it in an incremental or snapshot model.
4344
- [Hooks](concepts/models/hooks.md) (`concepts/models/hooks`) - Run SQL or Python lifecycle hooks around model materialization.
4445
- [SQL Hooks](concepts/models/hooks/sql.md) (`concepts/models/hooks/sql`) - Define, parameterize, compile, and invoke reusable or inline SQL lifecycle hooks.
4546
- [Python Hooks](concepts/models/hooks/python.md) (`concepts/models/hooks/python`) - Define Python lifecycle hooks with runtime context, providers, SQL access, and skips.
Lines changed: 118 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,118 @@
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).

‎src/sqlbuild/.agents/skills/sqlbuild/references/docs/index.md‎

Lines changed: 4 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -33,9 +33,10 @@ real model graph against test data, then replay it locally on DuckDB in CI.
3333

3434
[`sqb plan`](concepts/planning.md) shows why each model will run and how much it will rebuild.
3535
[`sqb diff`](concepts/diff.md) compares real data between targets before a change ships. When you
36-
rename a model, a [migration](concepts/models/migrations.md) moves its table instead of rebuilding
37-
its history, and the [janitor](cli/janitor.md) archives tables the project no longer builds before
38-
it deletes them.
36+
rename or move a model with [`sqb rename` and `sqb mv`](concepts/refactoring.md), every reference is
37+
updated, a [migration](concepts/models/migrations.md) moves its table instead of rebuilding its
38+
history, and the old name keeps working as a view. Columns can be renamed the same way. The
39+
[janitor](cli/janitor.md) archives tables the project no longer builds before it deletes them.
3940

4041
## How it fits together
4142

‎src/sqlbuild/.agents/skills/sqlbuild/references/docs/quickstart.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -215,6 +215,10 @@ sqb audit
215215
# Inspect lineage
216216
sqb lineage fact_orders --direction both
217217

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

‎website/src/content/docs/docs/index.mdx‎

Lines changed: 4 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -33,9 +33,10 @@ real model graph against test data, then replay it locally on DuckDB in CI.
3333

3434
[`sqb plan`](/docs/concepts/planning) shows why each model will run and how much it will rebuild.
3535
[`sqb diff`](/docs/concepts/diff) compares real data between targets before a change ships. When you
36-
rename a model, a [migration](/docs/concepts/models/migrations) moves its table instead of rebuilding
37-
its history, and the [janitor](/docs/cli/janitor) archives tables the project no longer builds before
38-
it deletes them.
36+
rename or move a model with [`sqb rename` and `sqb mv`](/docs/concepts/refactoring), every reference is
37+
updated, a [migration](/docs/concepts/models/migrations) moves its table instead of rebuilding its
38+
history, and the old name keeps working as a view. Columns can be renamed the same way. The
39+
[janitor](/docs/cli/janitor) archives tables the project no longer builds before it deletes them.
3940

4041
## How it fits together
4142

‎website/src/content/docs/docs/quickstart.mdx‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -201,6 +201,10 @@ sqb audit
201201
# Inspect lineage
202202
sqb lineage fact_orders --direction both
203203

204+
# Rename a model or a column, updating every reference (see Refactoring)
205+
sqb rename fact_orders order_facts
206+
sqb rename stg_customers.email email_address
207+
204208
# Compile and check contracts
205209
sqb compile
206210
```

‎website/src/sidebar.json‎

Lines changed: 12 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -23,6 +23,18 @@
2323
"docs/concepts/project-configuration",
2424
"docs/concepts/resource-identities",
2525
"docs/concepts/semantic-compilation",
26+
{
27+
"label": "Refactoring",
28+
"collapsed": false,
29+
"items": [
30+
{
31+
"label": "Overview",
32+
"slug": "docs/concepts/refactoring"
33+
},
34+
"docs/concepts/models/migrations",
35+
"docs/concepts/models/column-migrations"
36+
]
37+
},
2638
{
2739
"label": "Adapters",
2840
"collapsed": true,
@@ -48,8 +60,6 @@
4860
"docs/concepts/models/schemas",
4961
"docs/concepts/models/type-enforcement",
5062
"docs/concepts/models/contracts",
51-
"docs/concepts/models/migrations",
52-
"docs/concepts/models/column-migrations",
5363
{
5464
"label": "Hooks",
5565
"collapsed": true,

0 commit comments

Comments
 (0)