clover's git

the-knife

1	---
2	title: Renaming Resources
3	description: Migrate a resource's state across a logical ID change instead of replacing it.
4	---
5
6	Changing a [logical ID](/infrastructure-as-code/resource#logical-id)
7	normally plans a
8	[**replacement**](/infrastructure-as-code/resource-lifecycle#replace):
9	a new resource is created under the new ID and the old one —
10	including its physical resource, data, and
11	attachments — is deleted. When you actually just renamed the
12	resource, declare the rename with `Alchemy.renamedFrom` and alchemy
13	migrates the state row instead:
14
15	```diff lang="typescript"
16	-const bucket = yield* Cloudflare.R2.Bucket("Bucket");
17	+const bucket = yield* Cloudflare.R2.Bucket("Assets").pipe(
18	+ Alchemy.renamedFrom("Bucket"),
19	+);
20	```
21
22	The next deploy finds the state persisted under `Bucket`, moves it to
23	`Assets`, and plans a single re-branding **update** — same
24	[instance ID](/infrastructure-as-code/resource#physical-name), same
25	physical name, nothing created or deleted in the cloud. The
26	plan shows what's happening:
27
28	```text
29	Plan: 1 to update
30	[Assets] update (renamed from Bucket)
31	```
32
33	Keep the decoration around; once no state row exists under the old
34	ID it does nothing.
35
36	## Namespaces
37
38	A bare-string former id behaves exactly like the `id` argument: it
39	resolves against the surrounding namespace (`Namespace.push`).
40	Declared inside `Namespace.push("Site")`, `renamedFrom("Worker")`
41	claims the former FQN `Site/Worker` — write the former id exactly
42	as you would have written the `id` in the same position:
43
44	```typescript
45	// this Worker's FQN used to be `<id>/Worker`; now it is `<id>`
46	// (what Cloudflare.Website.StaticSite does internally)
47	yield* Worker(id, props).pipe(Alchemy.renamedFrom(`${id}/Worker`));
48	```
49
50	When a resource moved **between** namespaces, a relative id can't
51	express the old location — pass the absolute form, the full FQN
52	exactly as it appears in state:
53
54	```typescript
55	yield* Cloudflare.R2.Bucket("Assets").pipe(
56	Alchemy.renamedFrom({ fqn: "LegacySite/Assets" }),
57	Namespace.push("NewSite"),
58	);
59	```
60
61	## Renamed more than once
62
63	List every former id, **most recent first** — alchemy checks them in
64	order and migrates from the first matching row:
65
66	```typescript
67	yield* Cloudflare.R2.Bucket("Assets").pipe(
68	Alchemy.renamedFrom("StaticAssets", "Bucket"),
69	);
70	```
71
72	## Reusing the old ID
73
74	The old ID can be reused by a **new** resource in the same deploy.
75	The rename claim wins the state row — it's an explicit statement
76	that the row was the renamed resource's — and the reusing resource
77	is created fresh:
78
79	```typescript
80	// `Assets` keeps the physical resource previously known as
81	// `Bucket`; this `Bucket` is a brand-new one.
82	const assets = yield* Cloudflare.R2.Bucket("Assets").pipe(
83	Alchemy.renamedFrom("Bucket"),
84	);
85	const bucket = yield* Cloudflare.R2.Bucket("Bucket");
86	```
87
88	The migration deploy plans one **update** for the renamed resource
89	(not a noop) — the reconcile re-brands the physical resource's
90	ownership tags under the new logical ID, so the reused ID can never
91	accidentally adopt the wrong cloud resource.
92
93	## Safety semantics
94
95	The migration is deliberately conservative.
96
97	**Identity is proven, not assumed.** Only a migration ever copies an
98	instance ID, so a leftover row from an interrupted move is provably
99	a copy — it's dropped state-only, the physical resource untouched:
100
101	```diff lang="typescript"
102	-const bucket = yield* Cloudflare.R2.Bucket("Bucket");
103	+// a crashed deploy left rows at BOTH ids with the SAME instance id;
104	+// re-deploying drops the leftover copy — the cloud is never touched
105	+const bucket = yield* Cloudflare.R2.Bucket("Assets").pipe(
106	+ Alchemy.renamedFrom("Bucket"),
107	+);
108	```
109
110	A former row with a *different* instance ID is someone else's — the
111	old name was reused after the rename shipped — so the alias is
112	ignored and the row follows normal lifecycle rules:
113
114	```diff lang="typescript"
115	// deployed long after the rename: `Bucket` is its own resource now,
116	// with its own instance id — `renamedFrom` never adopts it
117	const assets = yield* Cloudflare.R2.Bucket("Assets").pipe(
118	Alchemy.renamedFrom("Bucket"),
119	);
120	const bucket = yield* Cloudflare.R2.Bucket("Bucket");
121	```
122
123	**Types must match.** A former row written by a different resource
124	type can't be this resource's state, whatever its FQN says — nothing
125	migrates, and the orphaned row follows its own lifecycle:
126
127	```diff lang="typescript"
128	-const cache = yield* Cloudflare.KV.Namespace("Store");
129	+// the row at `Store` belongs to a KV.Namespace — it is never adopted;
130	+// `Assets` is created fresh and `Store` is a normal orphan delete
131	+const assets = yield* Cloudflare.R2.Bucket("Assets").pipe(
132	+ Alchemy.renamedFrom("Store"),
133	+);
134	```
135
136	And a different-typed row sitting at the *new* ID fails the plan —
137	migrating over it would silently abandon its cloud resource:
138
139	```diff lang="typescript"
140	-const cache = yield* Cloudflare.KV.Namespace("Assets");
141	-const bucket = yield* Cloudflare.R2.Bucket("Bucket");
142	+// ✗ a state row of a different type already occupies 'Assets' —
143	+// delete or rename the KV namespace first, then re-deploy
144	+const bucket = yield* Cloudflare.R2.Bucket("Assets").pipe(
145	+ Alchemy.renamedFrom("Bucket"),
146	+);
147	```
148
149	**Ambiguity fails loudly.** Two resources claiming the same former
150	ID fail instead of racing for the row:
151
152	```typescript
153	yield* Cloudflare.R2.Bucket("Assets").pipe(Alchemy.renamedFrom("Bucket"));
154	yield* Cloudflare.R2.Bucket("Files").pipe(Alchemy.renamedFrom("Bucket"));
155	// ✗ 'Assets' and 'Files' both claim former FQN 'Bucket'
156	```
157
158	**Shifts work.** Renames may pass through each other in one deploy —
159	each row follows its resource, and pending replacement cleanup rides
160	along:
161
162	```typescript
163	yield* Cloudflare.R2.Bucket("B").pipe(Alchemy.renamedFrom("A")); // row at A → B
164	yield* Cloudflare.R2.Bucket("C").pipe(Alchemy.renamedFrom("B")); // row at B → C
165	```
166
167	**Swaps fail.** Exchanging two live IDs is a rename cycle — the two
168	migrations would overwrite each other's rows — so the plan fails;
169	rename through a temporary ID across two deploys instead:
170
171	```typescript
172	yield* Cloudflare.R2.Bucket("A").pipe(Alchemy.renamedFrom("B"));
173	yield* Cloudflare.R2.Bucket("B").pipe(Alchemy.renamedFrom("A"));
174	// ✗ rename cycle detected among ['A', 'B']
175	```
176
177	## Where next
178
179	- [Providers](/infrastructure-as-code/provider) — the object that
180	implements a resource type's lifecycle. Next page.
181	- [Resource Lifecycle](/infrastructure-as-code/resource-lifecycle) — the
182	replacement this decoration avoids.
183	- [Resources](/infrastructure-as-code/resource) — logical IDs, instance
184	IDs, and physical names.