The best way to control Claude Code, Codex and more from any computer or phone

main
mdx 148 lines 7.42 KB
Raw
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.