clover's git

the-knife

1	---
2	title: State and recovery
3	description: Preserve Neon ownership and reveal-once secrets, recover interrupted deployments, and clean up without discarding state.
4	---
5
6	Alchemy state records resource ownership, physical IDs, secrets, and the original
7	values needed to restore governance controls. It is part of the deployment, not
8	a disposable build cache. Complete [Setup](/neon/setup) and choose a durable
9	[state store](/state-store) before deploying production resources.
10
11	## Record the deployment identity
12
13	Keep a deployment record with the stack name, stage, source revision, working
14	directory/config file, profile or CI identity, and state-store location. Record
15	public Neon project/branch IDs alongside it. A matching cloud resource name alone
16	does not prove Alchemy ownership.
17
18	The tutorial uses local `.alchemy` state; other applications may configure a
19	remote store. Switching machines, directories, stages, or state backends without
20	migrating the correct state can leave the original resources behind.
21
22	## Protect state and backups
23
24	Use the chosen backend's access controls, encryption, and backup facilities.
25	Capture a consistent backup with deployments paused or through the backend's
26	supported snapshot mechanism. Keep the exact state, including resource and
27	replacement records, rather than exporting only stack outputs.
28
29	`Redacted` prevents accidental display in normal application output, but its
30	underlying value is serialized for recovery. It is not encryption by itself.
31	Treat state and its backups as secrets: exclude local state from source control,
32	restrict access, and never attach raw state to an issue or support request.
33
34	Before changing infrastructure, verify you can locate and restore a backup through
35	the state backend's documented procedure. A backup of source code alone does not
36	recover a reveal-once credential or a role's original value.
37
38	## Recover an interrupted operation with retained state
39
40	Pause concurrent deployments first. Confirm the credentials target the original
41	account and use the original stack, stage, config, and state backend. Inspect the
42	failure and current cloud state without mutating them before deciding whether to
43	continue deployment or clean up.
44
45	For a default `alchemy.run.ts` stack previously deployed to `dev` with the
46	`testing` profile, the normal continuation is:
47
48	```sh
49	pnpm exec alchemy deploy --profile testing --stage dev
50	```
51
52	Use your actual profile and stage, and the same `--config` if deployment used a
53	non-default file. For cleanup, use the corresponding normal lifecycle:
54
55	```sh
56	pnpm exec alchemy destroy --profile testing --stage dev
57	```
58
59	A retry can reconcile resources whose ownership and recovery information remain
60	known. It cannot reconstruct missing secrets or safely guess who owns a resource.
61	Keep a recovery failure visible rather than changing names, removing rows, or
62	using stack-wide adoption to force success.
63
64	## Resolve ownership or restoration conflicts
65
66	An ownership refusal means Alchemy cannot safely claim the observed resource.
67	Inspect its ID, owning stack/stage, inherited branch lineage, and retained state.
68	If another stack owns it, change the reference or coordinate with that owner.
69	Resource-scoped `Alchemy.adopt(true)` is an intentional takeover mechanism only
70	where the resource supports it; it is not a generic interrupted-deploy repair.
71
72	Governance controls also retain original roles, direct grants, spending thresholds,
73	and labels. External changes can make restoration unsafe. Compare the recorded
74	baseline with the administrator's intended configuration before proceeding, and
75	serialize changes to that control. Never invent a baseline from the desired
76	properties: it would erase the distinction between original and managed state.
77
78	For role and spending controls, restore/remove the old control before declaring
79	one targeting another member, project, or organization. See
80	[Organization governance](/neon/governance).
81
82	## Handle missing state or reveal-once secrets
83
84	When the original state cannot be recovered:
85
86	1. Stop further deploy/destroy attempts for the affected scope.
87	2. Inventory exact project, branch, resource, and credential IDs using read-only
88	Console/API access. Establish the owner and affected applications.
89	3. Search approved backups and the original deployment machine or CI state
90	backend. Restore an authentic consistent backup before retrying, if available.
91	4. If no recovery record exists, agree on an explicit recovery or retirement plan
92	with the resource owner. Preserve the inventory and approval record.
93
94	`OrganizationApiKey.key` is revealed only at creation. Listing a same-named key
95	cannot recover it, and the provider refuses silent rotation. If both the state
96	and approved secret backup are unavailable, the organization admin must explicitly
97	plan replacement/revocation and update consumers. Coordinate any exceptional
98	manual action with the Alchemy state owner before resuming automation; this guide
99	does not prescribe fabricating resource state or bypassing ownership checks.
100
101	The same caution applies to an interrupted credential creation whose cloud result
102	was never persisted. Broad account deletion, guessed adoption, and deleting state
103	are not substitutes for establishing ownership.
104
105	## Preserve Auth user data
106
107	Disabling Managed Auth preserves its `neon_auth` schema. Neon can refuse to enable
108	Auth again while that schema exists; Alchemy intentionally does not drop user and
109	session data to recreate an externally disabled integration. Preserve a database
110	backup and involve the application owner and Neon Support in restoration. Do not
111	treat deleting the schema as a routine retry step.
112
113	## Plan normal teardown
114
115	Clean up previews before their parent application and retain referenced parent
116	IDs while destroying a preview stack. Review destructive settings such as bucket
117	`forceDestroy` before running teardown; they deliberately remove application data.
118
119	Special external dependencies need their own ordering:
120
121	- Remove custom-domain DNS records and allow them to expire before releasing the
122	registration; see [Custom domains](/neon/guides/custom-domains#retire-the-hostname).
123	- Remove project endpoint associations before an owned organization endpoint
124	registration. Unregistration prevents re-registering that endpoint in the same
125	organization; see [Private networking](/neon/guides/private-networking).
126	- Preserve governance records until original settings have been restored.
127	- Keep the deployment identity authorized until cleanup completes. Plan retirement
128	of a deployment key separately from a stack that needs that key to destroy.
129
130	## Verify cleanup independently
131
132	After a successful destroy, use the Neon Console or read-only SDK calls to check
133	that the stack's owned resources are absent. Check that referenced/shared parents
134	still exist and work, adopted governance values are restored, and external DNS or
135	AWS resources have the intended state. A successful command alone is not an
136	inventory check.
137
138	Retain protected recovery evidence until verification finishes. Avoid publishing
139	connection strings, API tokens, SMTP passwords, private application data, or raw
140	state when reporting an error. Include sanitized error tags, request IDs, resource
141	types, and the relevant stack/stage instead.
142
143	## Related guides
144
145	- [State stores](/state-store) — backend selection.
146	- [Organization governance](/neon/governance) — restoration and adoption rules.
147	- [Preview cleanup](/neon/tutorial/previews) — tutorial-specific destruction commands.
148	- [Setup](/neon/setup) — profiles and environment credential precedence.