clover's git

the-knife

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/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.