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

main
mdx 148 lines 6.87 KB
Raw
1 ---
2 title: Private networking
3 description: Prepare AWS PrivateLink endpoints, register them with Neon, enable private DNS, and verify database access.
4 ---
5
6 Neon Private Networking routes database connections through AWS PrivateLink.
7 Alchemy's `OrganizationVPCEndpoint` and `ProjectVPCEndpoint` manage Neon
8 registrations and associations; they do not provision AWS endpoints, change DNS,
9 or block public connections. Complete [Setup](/neon/setup) and review
10 [governance ownership](/neon/governance) before changing a shared network.
11
12 ## Obtain access and choose the region
13
14 Use an existing Neon organization with Private Networking entitlement and an
15 organization-admin deployment identity. Confirm the current plan requirements in
16 [Neon's Private Networking guide](https://neon.com/docs/guides/neon-private-networking).
17 If the feature is unavailable, use the project's **Settings → Network Security**
18 page to request a trial where offered, or contact Neon. An API key does not grant
19 plan entitlement.
20
21 The AWS client application, VPC endpoint, and Neon project must use the same
22 supported AWS region. Copy the organization ID from Organization Settings and
23 verify the project's region before creating endpoints. This guide concerns
24 Postgres traffic, not a private network for Function, Auth, storage, or AI URLs.
25 Check each service's network limitations before combining it with a restricted
26 database; [Neon Auth](https://neon.com/docs/auth/overview) currently documents
27 Private Networking restrictions.
28
29 ## Create the AWS endpoints
30
31 Open **AWS VPC → Endpoints → Create endpoint** in the client's region. Follow
32 Neon's [endpoint creation instructions](https://neon.com/docs/guides/neon-private-networking#create-an-aws-vpc-endpoint):
33
34 1. Use the VPC where the database client runs.
35 2. Copy the current endpoint service names for that region from Neon's guide and
36 verify each service in AWS. Regions can require multiple endpoints; use the
37 complete current list rather than copying an old service ID from an example.
38 3. Select the intended subnets and security groups. Allow the database traffic
39 required by your client under your organization's network policy.
40 4. Leave private DNS disabled until the endpoint is registered with Neon.
41 5. Create the endpoints and retain their `vpce-...` IDs. These are endpoint IDs,
42 not the `vpc-...` ID of the network.
43
44 AWS endpoint charges are separate from Neon. Obtain approval before provisioning
45 and retain the AWS resource ownership information for later cleanup.
46
47 ## Register each endpoint with Neon
48
49 Inside your stack, register an endpoint that you created in AWS:
50
51 ```typescript
52 import * as Neon from "@alchemy.run/neon";
53
54 const network = yield* Neon.OrganizationVPCEndpoint("PrivateNetwork", {
55 orgId: "org-example",
56 regionId: "aws-us-east-2",
57 vpcEndpointId: "vpce-0123456789abcdef0",
58 label: "Application network",
59 });
60 ```
61
62 Repeat for each endpoint required by the region. Let Alchemy create the Neon
63 registration; registering it manually first creates an existing resource that
64 requires explicit adoption. For an already registered endpoint, review its
65 ownership and use resource-scoped `Alchemy.adopt(true)` only when intentionally
66 taking over label management. Adopted registrations are preserved on destroy.
67
68 :::caution[Unregistration is irreversible for this endpoint ID]
69 Destroying a newly owned Neon registration unregisters the endpoint. Neon prevents
70 that endpoint from being registered again in the same organization. A replacement
71 requires a new AWS endpoint. Use a disposable endpoint for lifecycle experiments,
72 not an existing production endpoint.
73 :::
74
75 ## Enable private DNS in AWS
76
77 After the Neon registration succeeds, select each AWS endpoint and choose
78 **Modify private DNS name → Enable for this endpoint**. Confirm the VPC and
79 client resolver use the intended private DNS configuration. The order matters:
80 Neon must recognize the endpoint before private DNS is enabled.
81
82 ## Associate the project
83
84 Use the project and organization registration in the same organization and region:
85
86 ```typescript
87 const access = yield* Neon.ProjectVPCEndpoint("PrivateAccess", {
88 project,
89 endpoint: network,
90 label: "Application access",
91 });
92 ```
93
94 Repeat the association for all applicable regional endpoints. This manages the
95 project's endpoint restriction, not its public-connectivity setting. Existing
96 associations require intentional scoped adoption; other associations remain
97 untouched. The database connection string does not change.
98
99 ## Verify from inside the VPC
100
101 From the actual client host inside the VPC, resolve the database hostname copied
102 from the Neon connection string:
103
104 ```sh
105 nslookup "$NEON_DATABASE_HOST"
106 ```
107
108 Confirm the result is the private address of the intended endpoint, not merely
109 that DNS returned an address. Then connect with the normal database URL and run
110 a small query using your existing SQL client. Test every client subnet that must
111 work. A connection from your laptop over the public internet does not verify
112 PrivateLink.
113
114 If resolution or connection fails, check region, endpoint registration, private
115 DNS, VPC DNS settings, security groups, and the regional endpoint-service list
116 before changing database credentials.
117
118 ## Decide whether to block public connections
119
120 Private connectivity does not automatically disable the public database path.
121 If policy requires it, first verify the private path and arrange a recovery path
122 with the network administrator. Then follow Neon's
123 [public-access restriction procedure](https://neon.com/docs/guides/neon-private-networking#restrict-public-internet-access).
124
125 `Neon.Project` does not currently expose `block_public_connections`; this is a
126 separate, deliberate Console/API/CLI setting rather than a property of either
127 endpoint resource. Confirm its effect on Auth and other integrations before
128 changing it. Test that private clients still connect and that a client outside
129 the permitted network is denied. Record who owns this setting so another tool
130 does not silently reverse it.
131
132 ## Remove or restore the configuration safely
133
134 Agree on the desired network posture before removing a restriction. Removing the
135 last project association can broaden connectivity; unregistering the organization
136 endpoint can prevent clients from reconnecting.
137
138 Remove dependent project associations before an owned organization registration.
139 Alchemy restores adopted labels and preserves adopted registrations/associations;
140 it removes newly owned ones. AWS endpoints and private DNS remain separately
141 managed and must be retired by their owner only after traffic has moved. Retain
142 state until both access checks and intended cleanup are confirmed.
143
144 ## Related guides
145
146 - [Organization governance](/neon/governance) — IDs, permissions, adoption, and restoration.
147 - [State and recovery](/neon/guides/state-recovery) — interrupted operations and retained state.
148 - [Neon Private Networking](https://neon.com/docs/guides/neon-private-networking) — current service names and entitlement requirements.